Skip to content

Commit 5ff0d5d

Browse files
acomodiacomodi
committed
docs: added/modified equivalent sites documentation
added tutorial for using equivalent sites. Signed-off-by: Alessandro Comodi <[email protected]>
1 parent 6f3d2dd commit 5ff0d5d

File tree

3 files changed

+268
-20
lines changed

3 files changed

+268
-20
lines changed

‎doc/src/arch/reference.rst

Lines changed: 33 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -799,7 +799,7 @@ Tile
799799
~~~~
800800
.. arch:tag:: <tile name="string" capacity="int" width="int" height="int" area="float"/>
801801
802-
A tile refers to a placeable element within an FPGA architecture.
802+
A tile refers to a placeable element within an FPGA architecture and describes its physical compositions on the grid.
803803
The following attributes are applicable to each tile.
804804
The only required one is the name of the tile.
805805
@@ -1179,33 +1179,46 @@ The following tags are common to all ``<tile>`` tags:
11791179
11801180
.. arch:tag:: <equivalent_sites>
11811181
1182-
Describes the Complex Blocks that can be placed within this tile.
1182+
.. seealso:: For a step-by-step walkthrough on describing equivalent sites see :ref:`equivalent_sites_tutorial`.
11831183
1184-
.. arch:tag:: <site pb_type="string"/>
1184+
Describes the Complex Blocks that can be placed within a tile.
1185+
Each physical tile can comprehend a number from 1 to N of possible Complex Blocks, or ``sites``.
1186+
A ``site`` corresponds to a top-level Complex Block that must be placeable in at least 1 physical tile locations.
11851187
1186-
Each instance of site must also specify the direct connections between the physical
1187-
tile pins and the logical block pins.
1188+
.. arch:tag:: <site pb_type="string" pin_mapping="string"/>
11881189
1189-
.. arch:tag:: <direct from="string" to="string">
1190+
:req_param pb_type: Name of the corresponding pb_type.
11901191
1191-
Attributes:
1192-
- ``from`` is relative to the physical tile pins
1193-
- ``to`` is relative to the logical block pins
1192+
:opt_param pin_mapping: Specifies whether the pin mapping between physical tile and logical pb_type:
11941193
1195-
:req_param pb_type: Name of the corresponding pb_type.
1194+
* ``direct``: the pin mapping does not need to be specified as the tile pin definition is equal to the corresponding pb_type one;
1195+
* ``custom``: the pin mapping is user-defined.
11961196
1197-
**Example: Equivalent Sites**
11981197
1199-
.. code-block:: xml
1198+
**Default:** ``direct``
12001199
1201-
<equivalent_sites>
1202-
<site pb_type="MLAB_SITE">
1203-
<direct from="MLAB_TILE.AX" to="MLAB_SITE.AX"/>
1204-
<direct from="MLAB_TILE.CX" to="MLAB_SITE.BX"/>
1205-
<direct from="MLAB_TILE.DX" to="MLAB_SITE.GX"/>
1206-
...
1207-
</site>
1208-
</equivalent_sites>
1200+
**Example: Equivalent Sites**
1201+
1202+
.. code-block:: xml
1203+
1204+
<equivalent_sites>
1205+
<site pb_type="MLAB_SITE" pin_mapping="direct"/>
1206+
</equivalent_sites>
1207+
1208+
.. arch:tag:: <direct from="string" to="string">
1209+
1210+
Desctibes the mapping of a physical tile's port on the logical block's (pb_type) port.
1211+
``direct`` is an option sub-tag of ``site``.
1212+
1213+
.. note:: This tag is need only if the pin_mapping of the ``site`` is defined as ``custom``
1214+
1215+
Attributes:
1216+
- ``from`` is relative to the physical tile pins
1217+
- ``to`` is relative to the logical block pins
1218+
1219+
.. code-block:: xml
1220+
1221+
<direct from="MLAB_TILE.CX" to="MLAB_SITE.BX"/>
12091222
12101223
.. _arch_complex_blocks:
12111224

‎doc/src/tutorials/arch/equivalent_sites.rst

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
.. _equivalent_sites_tutorial:
2+
3+
Equivalent Sites tutorial
4+
=========================
5+
6+
This tutorial aims at providing information to the user on how to model the equivalent sites to enable ``equivalent placement`` in VPR.
7+
8+
Equivalent site placement allows the user to define complex logical blocks (top-level pb_types) that can be used in multiple physical location types of the FPGA device grid.
9+
In the same way, the user can define many physical tiles that have different physical attributes that can implement the same logical block.
10+
11+
The first case (multiple physical grid location types for one complex logical block) is explained below.
12+
The device has at disposal two different Configurable Logic Blocks (CLB), SLICEL and SLICEM.
13+
In this case, the SLICEM CLB is a superset that implements additional features w.r.t. the SLICEL CLB.
14+
Therefore, the user can decide to model the architecture to be able to place the SLICEL Complex Block in a SLICEM physical tile, being it a valid grid location.
15+
This behavior can lead to the generation of more accurate and better placement results, given that a Complex Logic Block is not bound to only one physical location type.
16+
17+
Below the user can find the implementation of this situation starting from an example that does not make use of the equivalent site placement:
18+
19+
.. code-block:: xml
20+
21+
<tiles>
22+
<tile name="SLICEL_TILE">
23+
<input name="IN_A" num_pins="6"/>
24+
<input name="AX" num_pins="1"/>
25+
<input name="SR" num_pins="1"/>
26+
<input name="CE" num_pins="1"/>
27+
<input name="CIN" num_pins="1"/>
28+
<clock name="CLK" num_pins="1"/>
29+
<output name="A" num_pins="1"/>
30+
<output name="AMUX" num_pins="1"/>
31+
<output name="AQ" num_pins="1"/>
32+
33+
<equivalent_sites>
34+
<site pb_type="SLICEL_SITE" pin_mapping="direct"/>
35+
</equivalent_sites>
36+
37+
<fc ...>
38+
<pinlocations ...>
39+
</tile>
40+
<tile name="SLICEM_TILE">
41+
<input name="IN_A" num_pins="6"/>
42+
<input name="AX" num_pins="1"/>
43+
<input name="AI" num_pins="1"/>
44+
<input name="SR" num_pins="1"/>
45+
<input name="WE" num_pins="1"/>
46+
<input name="CE" num_pins="1"/>
47+
<input name="CIN" num_pins="1"/>
48+
<clock name="CLK" num_pins="1"/>
49+
<output name="A" num_pins="1"/>
50+
<output name="AMUX" num_pins="1"/>
51+
<output name="AQ" num_pins="1"/>
52+
53+
<equivalent_sites>
54+
<site pb_type="SLICEM_SITE" pin_mapping="direct"/>
55+
</equivalent_sites>
56+
57+
<fc ...>
58+
<pinlocations ...>
59+
</tile>
60+
</tiles>
61+
62+
<complexblocklist>
63+
<pb_type name="SLICEL_SITE"/>
64+
<input name="IN_A" num_pins="6"/>
65+
<input name="AX" num_pins="1"/>
66+
<input name="AI" num_pins="1"/>
67+
<input name="SR" num_pins="1"/>
68+
<input name="CE" num_pins="1"/>
69+
<input name="CIN" num_pins="1"/>
70+
<clock name="CLK" num_pins="1"/>
71+
<output name="A" num_pins="1"/>
72+
<output name="AMUX" num_pins="1"/>
73+
<output name="AQ" num_pins="1"/>
74+
<mode ...>
75+
...
76+
</pb_type>
77+
<pb_type name="SLICEM_SITE"/>
78+
<input name="IN_A" num_pins="6"/>
79+
<input name="AX" num_pins="1"/>
80+
<input name="SR" num_pins="1"/>
81+
<input name="WE" num_pins="1"/>
82+
<input name="CE" num_pins="1"/>
83+
<input name="CIN" num_pins="1"/>
84+
<clock name="CLK" num_pins="1"/>
85+
<output name="A" num_pins="1"/>
86+
<output name="AMUX" num_pins="1"/>
87+
<output name="AQ" num_pins="1"/>
88+
<mode ...>
89+
...
90+
</pb_type>
91+
</complexblocklist>
92+
93+
As the user can see, ``SLICEL`` and ``SLICEM`` are treated as two different entities, even though they seem to be similar one to another.
94+
To have the possibility to make VPR choose a ``SLICEM`` location when placing a ``SLICEL_SITE`` pb_type, the user needs to change the ``SLICEM`` tile accordingly, as shown below:
95+
96+
.. code-block:: xml
97+
98+
<tile name="SLICEM_TILE">
99+
<input name="IN_A" num_pins="6"/>
100+
<input name="AX" num_pins="1"/>
101+
<input name="AI" num_pins="1"/>
102+
<input name="SR" num_pins="1"/>
103+
<input name="WE" num_pins="1"/>
104+
<input name="CE" num_pins="1"/>
105+
<input name="CIN" num_pins="1"/>
106+
<clock name="CLK" num_pins="1"/>
107+
<output name="A" num_pins="1"/>
108+
<output name="AMUX" num_pins="1"/>
109+
<output name="AQ" num_pins="1"/>
110+
111+
<equivalent_sites>
112+
<site pb_type="SLICEM_SITE" pin_mapping="direct"/>
113+
<site pb_type="SLICEL_SITE" pin_mapping="custom">
114+
<direct from="SLICEM_TILE.IN_A" to="SLICEL_SITE.IN_A"/>
115+
<direct from="SLICEM_TILE.AX" to="SLICEL_SITE.AX"/>
116+
<direct from="SLICEM_TILE.SR" to="SLICEL_SITE.SR"/>
117+
<direct from="SLICEM_TILE.CE" to="SLICEL_SITE.CE"/>
118+
<direct from="SLICEM_TILE.CIN" to="SLICEL_SITE.CIN"/>
119+
<direct from="SLICEM_TILE.CLK" to="SLICEL_SITE.CLK"/>
120+
<direct from="SLICEM_TILE.A" to="SLICEL_SITE.A"/>
121+
<direct from="SLICEM_TILE.AMUX" to="SLICEL_SITE.AMUX"/>
122+
<direct from="SLICEM_TILE.AQ" to="SLICEL_SITE.AQ"/>
123+
</site>
124+
</equivalent_sites>
125+
126+
<fc ...>
127+
<pinlocations ...>
128+
</tile>
129+
130+
With the above description of the ``SLICEM`` tile, the user can now have the ``SLICEL`` sites to be placed in ``SLICEM`` physical locations.
131+
One thing to notice is that not all the pins have been mapped for the ``SLICEL_SITE``. For instance, the ``WE`` and ``AI`` port are absent from the ``SLICEL_SITE`` definition, hence they cannot appear in the pin mapping between physical tile and logical block.
132+
133+
The second case described in this tutorial refers to the situation for which there are multiple different physical location types in the device grid that are used by one complex logical blocks.
134+
Imagine the situation for which the device has left and right I/O tile types which have different pinlocations, hence they need to be defined in two different ways.
135+
With equivalent site placement, the user doesn't need to define multiple different pb_types that implement the same functionality.
136+
137+
Below the user can find the implementation of this situation starting from an example that does not make use of the equivalent site placement:
138+
139+
.. code-block:: xml
140+
141+
<tiles>
142+
<tile name="LEFT_IOPAD_TILE">
143+
<input name="INPUT" num_pins="1"/>
144+
<output name="OUTPUT" num_pins="1"/>
145+
146+
<equivalent_sites>
147+
<site pb_type="LEFT_IOPAD_SITE" pin_mapping="direct"/>
148+
</equivalent_sites>
149+
150+
<fc ...>
151+
<pinlocations pattern="custom">
152+
<loc side="left">LEFT_IOPAD_TILE.INPUT</loc>
153+
<loc side="right">LEFT_IOPAD_TILE.OUTPUT</loc>
154+
</pinlocations>
155+
</tile>
156+
<tile name="RIGHT_IOPAD_TILE">
157+
<input name="INPUT" num_pins="1"/>
158+
<output name="OUTPUT" num_pins="1"/>
159+
160+
<equivalent_sites>
161+
<site pb_type="RIGHT_IOPAD_SITE" pin_mapping="direct"/>
162+
</equivalent_sites>
163+
164+
<fc ...>
165+
<pinlocations pattern="custom">
166+
<loc side="right">RIGHT_IOPAD_TILE.INPUT</loc>
167+
<loc side="left">RIGHT_IOPAD_TILE.OUTPUT</loc>
168+
</pinlocations>
169+
</tile>
170+
</tiles>
171+
172+
<complexblocklist>
173+
<pb_type name="LEFT_IOPAD_SITE">
174+
<input name="INPUT" num_pins="1"/>
175+
<output name="OUTPUT" num_pins="1"/>
176+
<mode ...>
177+
...
178+
</pb_type>
179+
<pb_type name="RIGHT_IOPAD_SITE">
180+
<input name="INPUT" num_pins="1"/>
181+
<output name="OUTPUT" num_pins="1"/>
182+
<mode ...>
183+
...
184+
</pb_type>
185+
</complexblocklist>
186+
187+
To avoid duplicating the complex logic blocks in ``LEFT`` and ``RIGHT IOPADS``, the user can describe the pb_type only once and add it to the equivalent sites tag of the two different tiles, as follows:
188+
189+
.. code-block:: xml
190+
191+
<tiles>
192+
<tile name="LEFT_IOPAD_TILE">
193+
<input name="INPUT" num_pins="1"/>
194+
<output name="OUTPUT" num_pins="1"/>
195+
196+
<equivalent_sites>
197+
<site pb_type="IOPAD_SITE" pin_mapping="direct"/>
198+
</equivalent_sites>
199+
200+
<fc ...>
201+
<pinlocations pattern="custom">
202+
<loc side="left">LEFT_IOPAD_TILE.INPUT</loc>
203+
<loc side="right">LEFT_IOPAD_TILE.OUTPUT</loc>
204+
</pinlocations>
205+
</tile>
206+
<tile name="RIGHT_IOPAD_TILE">
207+
<input name="INPUT" num_pins="1"/>
208+
<output name="OUTPUT" num_pins="1"/>
209+
210+
<equivalent_sites>
211+
<site pb_type="IOPAD_SITE" pin_mapping="direct"/>
212+
</equivalent_sites>
213+
214+
<fc ...>
215+
<pinlocations pattern="custom">
216+
<loc side="right">RIGHT_IOPAD_TILE.INPUT</loc>
217+
<loc side="left">RIGHT_IOPAD_TILE.OUTPUT</loc>
218+
</pinlocations>
219+
</tile>
220+
</tiles>
221+
222+
<complexblocklist>
223+
<pb_type name="IOPAD_SITE">
224+
<input name="INPUT" num_pins="1"/>
225+
<output name="OUTPUT" num_pins="1"/>
226+
<mode ...>
227+
...
228+
</pb_type>
229+
</complexblocklist>
230+
231+
With this implementation, the ``IOPAD_SITE`` can be placed both in the ``LEFT`` and ``RIGHT`` physical location types.
232+
Note that the pin_mapping is set as ``direct``, given that the physical tile and the logical block share the same IO pins.
233+
234+
The two different cases can be mixed to have a N to M mapping of physical tiles/logical blocks.

‎doc/src/tutorials/arch/index.rst

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,7 @@ Multiple examples of how this language can be used to describe different types o
3030
fracturable_multiplier
3131
configurable_memory
3232
xilinx_virtex_6_like
33+
equivalent_sites
3334

3435
**Modeling Guides:**
3536

0 commit comments

Comments
 (0)