99 lines
3.5 KiB
ReStructuredText
99 lines
3.5 KiB
ReStructuredText
.. _file_formats_io_naming_file:
|
|
|
|
Fabric I/O Naming (.xml)
|
|
------------------------
|
|
|
|
The XML-based description language is used to describe
|
|
|
|
- I/O names for an FPGA fabric when creating a top-level wrapper
|
|
- I/O connections between the fabric and top-level wrappers
|
|
|
|
Using the description language, users can customize the I/O names for each pin/port of an FPGA fabric, including dummy pins (not from an FPGA fabric but required for system integration).
|
|
|
|
Under the root node ``<ports>``, naming rules can be defined line-by-line through syntax ``<port>``.
|
|
|
|
.. code-block:: xml
|
|
|
|
<ports>
|
|
<port top_name="<string>" core_name="<string>" is_dummy="<bool>" direction="<string>"/>
|
|
</ports>
|
|
|
|
.. note:: If you do not need to rename a port of an FPGA fabric, there is no need to define it explicitly in the naming rules. OpenFPGA can infer it.
|
|
|
|
Please be aware of the following restrictions:
|
|
|
|
.. note:: Please note that when naming rules should be applied to a port at its full size. For example, given a port of ``in[0:31]``, naming rules should cover all the 32 bits.
|
|
|
|
.. note:: Please note that we currently only supports port splitting at the top-level wrapper. For example, there is a port ``a[0:9]`` from the FPGA fabric, it can be split to ``a0[0:4]`` and ``a1[0:4]`` at the top-level wrapper.
|
|
|
|
.. warning:: Port grouping is **NOT** supported yet. For example, there are ports ``b[0:7]`` and ``c[0:7]`` from the FPGA fabric, it can **NOT** be grouped to a port ``bnc[0:15]`` at the top-level wrapper.
|
|
|
|
Syntax
|
|
``````
|
|
|
|
Detailed syntax are presented as follows.
|
|
|
|
.. option:: top_name="<string>"
|
|
|
|
Define the port name and width which will appear in the top-level wrapper. For example,
|
|
|
|
.. code-block:: xml
|
|
|
|
top_name="a[0:2]"
|
|
|
|
.. option:: core_name="<string>"
|
|
|
|
Define the port name and width which exists in the current FPGA fabric. For example,
|
|
|
|
.. note:: You can find the available ports in the current top-level module of FPGA netlists. See details in :ref:`fabric_netlists`.
|
|
|
|
.. code-block:: xml
|
|
|
|
core_name="gfpga_pad_GPIO_PAD[0:2]"
|
|
|
|
.. option:: is_dummy="<bool>"
|
|
|
|
Define if the port is a dummy one in the top-level wrapper, which does not connect to any pin/port of the current FPGA fabric. For example,
|
|
|
|
.. note:: When a dummy port is defined. ``core_name`` is not required.
|
|
|
|
.. code-block:: xml
|
|
|
|
is_dummy="true"
|
|
|
|
.. option:: direction="<string>"
|
|
|
|
Direction can be ``input`` | ``output`` | ``inout``. Only applicable to dummy ports. For example,
|
|
|
|
.. code-block:: xml
|
|
|
|
direction="input"
|
|
|
|
Example
|
|
```````
|
|
|
|
:numref:`fig_fpga_core_wrapper` shows an example of a top-level wrapper with naming rules, which is built on top of an existing FPGA core fabric.
|
|
There is a dummy input port at the top-level wrapper.
|
|
|
|
.. _fig_fpga_core_wrapper:
|
|
|
|
.. figure:: figures/fpga_core_wrapper.png
|
|
:width: 100%
|
|
:alt: Illustration of a top-level wrapper on an existing FPGA core fabric
|
|
|
|
Example of a top-level wrapper: how it interfaces between SoC and an existing FPGA core fabric
|
|
|
|
The I/O naming in the :numref:`fig_fpga_core_wrapper` can be described in the following XML:
|
|
|
|
.. code-block:: xml
|
|
|
|
<ports>
|
|
<port top_name="pclk0[0:3]" core_name="prog_clk[0:3]"/>
|
|
<port top_name="pclk1[0:3]" core_name="prog_clk[4:7]"/>
|
|
<port top_name="right_io[0:23]" core_name="pad[0:23]"/>
|
|
<port top_name="bottom_io[0:7]" core_name="pad[24:31]"/>
|
|
<port top_name="pvt_sense[0:0]" is_dummy="true" direction="input"/>
|
|
</ports>
|
|
|
|
Note that since port ``reset[0:0]`` require no name changes, it is not required to be defined in the XML.
|