Skip to content

Commit e552a69

Browse files
rodrigomelo9rodrigomelo9
committed
docs: rewritten (WIP) advanced usage
1 parent 0103506 commit e552a69

File tree

1 file changed

+42
-142
lines changed

1 file changed

+42
-142
lines changed

‎docs/advanced.rst‎

Lines changed: 42 additions & 142 deletions
Original file line numberDiff line numberDiff line change
@@ -1,161 +1,61 @@
11
Advanced usage
22
==============
33

4-
.. ATTENTION::
5-
6-
(2024-05-31) To be updated.
7-
8-
Multi project managment
9-
-----------------------
10-
11-
.. code-block:: python
4+
PyFPGA offers advanced features for more customized and flexible control over FPGA project management.
5+
This section covers two key advanced features:
126

13-
PROJECTS = {
14-
'<NAME1>': Project(
15-
'<TOOLNAME>',
16-
'<PROJECTNAME>',
17-
{
18-
'outdir': '<DIRNAME>',
19-
'part': '<PARTNAME>'
20-
'paths': [
21-
'<PATHNAME1>',
22-
...
23-
'<PATHNAMEn>'
24-
],
25-
'vhdl': [
26-
['<FILENAME1>', '<LIBRARYNAME1>'],
27-
'<FILENAME2>',
28-
...
29-
'<FILENAMEn>'
30-
],
31-
'verilog': [
32-
'<FILENAME1>',
33-
...
34-
'<FILENAMEn>'
35-
],
36-
'constraint': [
37-
'<FILENAME1>',
38-
...
39-
'<FILENAMEn>'
40-
],
41-
'params': {
42-
'<PARAMNAME1>': '<VALUE1>',
43-
...
44-
'<PARAMNAMEn>': '<VALUEn>'
45-
},
46-
'top': '<TOPNAME>'
47-
}
48-
)
49-
'<NAME2>': Project(
50-
...
51-
)
52-
}
7+
1. **Hooks**: These are points in the code where you can insert custom code to extend or modify the behavior of the tool.
8+
Hooks provide a way to integrate additional functionality or perform specific actions at predefined stages of the project lifecycle.
539

54-
.. _hooks:
10+
2. **Options**: This feature allows you to specify additional options to fine-tune the tool's behavior.
11+
Options provide greater control over the tool's operation and enable you to customize the processing according to your specific requirements.
5512

5613
Hooks
5714
-----
5815

59-
The following table depicts the parts of the *Project Creation* and the
60-
*Design Flow* internally performed by PyFPGA.
61-
62-
+--------------------------+----------------------+
63-
| Project Creation | Design Flow |
64-
+==========================+======================+
65-
| Part specification | **preflow** hook |
66-
+--------------------------+----------------------+
67-
| **prefile** hook | Synthesis |
68-
+--------------------------+----------------------+
69-
| Files addition | **postsyn** hook |
70-
+--------------------------+----------------------+
71-
| Top specification | Place and Route |
72-
+--------------------------+----------------------+
73-
| Parameters specification | **postpar** hook |
74-
+--------------------------+----------------------+
75-
| **project** hook | Bitstream generation |
76-
+--------------------------+----------------------+
77-
| | **postbit** hook |
78-
+--------------------------+----------------------+
79-
80-
If the provided API if not enough or suitable for your project, you can
81-
specify additional *hooks* in different parts of the flow, using:
82-
83-
.. code-block:: python
84-
85-
prj.add_hook(hook, phase)
86-
87-
.. NOTE::
88-
89-
* Valid vaues for *phase* are ``prefile``, ``project`` (default), ``preflow``,
90-
``postsyn``, ``postpar`` and ``postbit``.
91-
* The *hook* string must be a valid command (supported by the used tool).
92-
* If more than one *hook* is needed in the same *phase*, you can call this
93-
method several times (the commands will be executed in order).
94-
95-
Parameters
96-
----------
97-
98-
The generics/parameters of the project can be optionally changed with:
99-
100-
.. code-block:: python
101-
102-
prj.add_param('param1', value1)
103-
...
104-
prj.add_param('paramN', valueN)
105-
106-
Generate options
107-
----------------
108-
109-
The method ``generate`` (previously seen at the end of
110-
[Basic usage](#basic-usage) section) has optional parameters:
16+
Hooks allow you to insert custom code at specific stages of the project lifecycle. The available hooks are:
17+
18+
+---------+---------------------------------------------------------------------------------------------+
19+
| Stage | Description |
20+
+=========+=============================================================================================+
21+
| precfg | Code inserted after project creation and before files inclusion (e.g., specify HDL version) |
22+
+---------+---------------------------------------------------------------------------------------------+
23+
| postcfg | Code inserted after files inclusion (e.g., additional project configurations) |
24+
+---------+---------------------------------------------------------------------------------------------+
25+
| presyn | Code inserted before synthesis (e.g., synthesis-specific options) |
26+
+---------+---------------------------------------------------------------------------------------------+
27+
| postsyn | Code inserted after synthesis (e.g., report generation) |
28+
+---------+---------------------------------------------------------------------------------------------+
29+
| prepar | Code inserted before place and route (e.g., place-and-route-specific options) |
30+
+---------+---------------------------------------------------------------------------------------------+
31+
| postpar | Code inserted after place and route (e.g., report generation) |
32+
+---------+---------------------------------------------------------------------------------------------+
33+
| prebit | Code inserted before bitstream generation (e.g., bitstream-specific options) |
34+
+---------+---------------------------------------------------------------------------------------------+
35+
| postbit | Code inserted after bitstream generation (e.g., report generation) |
36+
+---------+---------------------------------------------------------------------------------------------+
37+
38+
You can specify hooks for a specific stage either line-by-line:
11139

11240
.. code-block:: python
11341
114-
prj.generate(to_task, from_task, capture)
42+
prj.add_hook('presyn', 'COMMAND1')
43+
prj.add_hook('presyn', 'COMMAND2')
44+
prj.add_hook('presyn', 'COMMAND3')
11545
116-
With *to_task* and *from_taks* (with default values ``bit`` and ``prj``),
117-
you are selecting the first and last task to execute when `generate` is
118-
invoqued. The order and available tasks are ``prj``, ``syn``, ``par`` and ``bit``.
119-
It can be useful in at least two cases:
120-
121-
* Maybe you created a file project with the GUI of the Tool and only want to
122-
run the Design Flow, so you can use: ``generate(to_task='bit', from_task='syn')``
123-
124-
* Despite that a method to insert particular commands is provided, you would
125-
want to perform some processing from Python between tasks, using something
126-
like:
46+
Or in a multi-line format:
12747

12848
.. code-block:: python
12949
130-
prj.generate(to_task='syn', from_task='prj')
131-
#Some other Python commands here
132-
prj.generate(to_task='bit', from_task='syn')
50+
prj.add_hook('presyn', """
51+
COMMAND1
52+
COMMAND2
53+
COMMAND3
54+
""")
13355
134-
In case of *capture*, it is useful to catch execution messages to be
135-
post-processed or saved to a file:
136-
137-
.. code-block:: python
56+
Options
57+
-------
13858

139-
result = prj.generate(capture=True)
140-
print(result)
141-
142-
In case of *capture*, it is useful to catch execution messages to be
143-
post-processed or saved to a file.
144-
145-
Exceptions
146-
----------
147-
148-
Finally, you must run the bitstream generation or its transfer. Both of them
149-
are time-consuming tasks, performed by a backend tool, which could fail.
150-
Exceptions are raised in such cases, that should be ideally caught to avoid
151-
abnormal program termination.
152-
153-
.. code-block:: python
154-
155-
try:
156-
prj.generate()
157-
prj.transfer()
158-
except Exception as e:
159-
print('{} ({})'.format(type(e).__name__, e))
59+
.. ATTENTION::
16060

161-
And wait for the backend Tool to accomplish its task.
61+
WIP feature.

0 commit comments

Comments
 (0)