Skip to content

F
FPGA Device ID
Commit dbe8ecef authored by Federico Vaga's avatar Federico Vaga
Browse files
Options

add main document 

Signed-off-by: Federico Vaga's avatarFederico Vaga <federico.vaga@cern.ch>
parent c993c1c9
Hide whitespace changes
Inline Side-by-side
Showing with 258 additions and 0 deletions
device-structure.rst 0 → 100644
View file @ dbe8ecef
.. _device-structure:
FPGA Device Structure |version|
===============================
The aim of this set of rules is to help the low-level software to perform
a sanity check on an FPGA device, to ease debugging and to provide support
for low-level software auto-configuration for byte-order and optional
components.
Device Stability
----------------
Every design change requires a new release. It is impossible to handle
different designs with the same software without being aware of
the fact that they are different. It is really important that a device
does not change its nature without formalizing a new release.
This is the key ingredient for a simpler software administration and design.
Rule 01.01.00
Any change requires a new release. It must be versioned using the
`semantic versioning`_ schema
Device Grouping
---------------
It is important to identify FPGA devices that we want to drive and clearly
*draw* their borders. For example, all our FMC designs have a clear set
of IP-cores which are used to drive carrier components, or offer services
to the mezzanines/applications; for those, it is necessary a clear and
fixed memory map that uniquely identify the device as such. Otherwise it will
be impossible for the driver to correctly handle them, especially after a
number of versions.
Rule 02.01.00
A set of IP-cores or devices which are used together to offer a service must
be grouped together in a device.
Observation 02.01.01
A device could be composed by a single IP-core.
Observation 02.01.02
A device can be made of other devices.
Observation 02.01.03
Internal components (IP-cores, devices) offsets are fixed. Within the same
release they do not change.
Rule 02.02.00
The device must have all *metadata* registers described by this document.
Observation 02.02.01
This concept is evident for carrier boards, but it is not limited to that.
User FPGA applications may use different IP-core to create a new
functionality, that functionality must be embedded in a device.
.. _`rule 02.03.00`:
Rule 02.03.00
Any change to the device behavior, its interface or its composition must
be done in a new device release.
Device Metadata
---------------
========== ========== ===============
Offset Size (bit) Name
0x00000000 32 Vendor ID
0x00000004 32 Device ID
0x00000008 32 Version
0x0000000C 32 Byte Order Mark
0x00000010 128 Source ID
0x00000020 32 Capability Mask
0x00000030 128 Vendor UUID
========== ========== ===============
Vendor ID and Device ID
'''''''''''''''''''''''
The ``vendor ID`` and the ``device ID`` are used to identify a device. It will
be used by the driver for sanity checking incorrectly built FPGA code and ease
of debugging.
The device driver at ``probe()`` time will read these registers and refuse to
drive the device if it does not recognize it.
Rule 03.01.00
A device must export at offset ``0x00`` a 32 bit register containing the
vendor ID.
Rule 03.02.00
The vendor ID format must be one of the following:
- ``0x0000`` followed by a valid 16 bit PCI vendor ID (e.g.``0x000010DC``)
- ``0x01`` followed by a valid 24 bit MA-L vendor ID (e.g. ``0x0180D336``)
- ``0xFF000000`` for an auto-generated UUID (RFC4122_) that will be
accessible at offset ``0x30``
Rule 03.03.00
A device can export at offset ``0x30`` a 128 bit register containing an
auto-generated vendor UUID (RFC4122_).
Observation 03.03.01
The vendor UUID (RFC4122_) is meaningful only if the vendor ID is
``0xFF000000``
Rule 03.04.00
A device must export at offset ``0x04`` a 32 bit register containing the
device ID.
Observation 03.04.01
The device ID content is vendor specific
Observation 03.04.02
The device ID is meaningful only in combination with the vendor ID
Observation 03.04.03
The vendor must put in place a database of device ID in order to avoid
internal conflicts
.. _`Observation 03.05.01`:
Observation 03.05.01
The registers ``vendor ID`` and ``device ID`` are used for identification.
Today (June 2019), it does not exists a proper auto-discovery bus for FPGA,
and this document does not aim to fill that gap. For this reason the device
identification is mainly used for sanity check to validate any external
description (e.g. device-tree, ACPI, or any other custom hardware
description format) at driver probing time.
Observation 03.05.02
Despite `Observation 03.05.01`_, it is possible to use ``vendor ID`` and
``device ID`` to describe hardware. This requires the FPGA design to be
properly structured as a set of hierarchical devices. This implies that it
must exist a top level device (as described by this document) that uniquely
identifies the full design.
Version
'''''''
FPGA-based applications are evolutionary by nature, be it through bug
fixes or feature requests. This implies that both FPGA code and drivers must
be versioned to enable users to choose versions. The immediate consequence
is that both driver and FPGA code must explicitly exhibit a version tag.
The driver can use this information to automatically handle interface
differences.
Rule 04.01.00
A device must export at offset ``0x08`` a 32 bit register containing the
version number according to the `semantic versioning`_ schema where:
- bits 31-24: major number
- bits 23-16: minor number
- bits 15-00: patch number
Observation 04.01.01
Any development effort should be versioned according to the release version
in which it will be officially included. For example, if the current release
is 4.1, and there is an on going development that will add new
functionalists; then, any development version should be *distributed* as
version 4.2.0 without increasing the patch number until it become an
official release. This does not apply for the patch number.
Byte Order Mark
'''''''''''''''
FPGA devices can be used on different buses, where endianess can be different.
On the software side, drivers, must be able to dynamically identify endianess
*before* driving the device. This is achievable with a ``BOM``
(``Byte Order Mark``) register in each device at a known offset.
Rule 05.01.00
A device must export the ``BOM`` register at offset ``0x0C`` and it must
contain the constant value ``0xFFFExxxx`` with little endian byte order.
Observation 05.01.01
If the software reads the value ``0xFFFExxxx`` from the ``BOM`` register it
means that the access is little-endian.
Observation 05.01.02
If the software reads the value ``0xxxxxFEFF`` from the ``BOM`` register it
means that the access is big-endian.
Rule 05.02.00
The 16 least significant bits are used to identify the version of this
convention. The value for this version (|version|) is: ``0x0000``.
.. note::
The value ``0xFFFE0000`` comes from UTF-32-LE.
Source ID
'''''''''
The ``source ID`` field identifies the sources from which the correspondent
FPGA bitstream has been synthesized. The content depends on how the source
code is managed (e.g. it could the git commit ID of a git repository).
Rule 06.01.00
A device must export at offset ``0x10`` a 128 bit register containing a
source identifier.
Rule 06.02.00
The source identifier must be able to identify the source code from which
the FPGA device has been synthesized.
Observation 06.02.01
The source identifier is project dependent.
Capability Mask
'''''''''''''''
Like for physical hardware devices, FPGA devices could be made of different
IP-core or devices with the difference that on an FPGA design sometimes those
components may be there or not (without precluding the system from working).
For this reason it is important to inform drivers about what optional
components are present in the device and what are not.
Rule 07.01.00
A device must export at offset ``0x20`` a 32 bit register containing the
capability mask.
Rule 07.02.00
The capability mask is device specific. Each bit represents the presence
of an *optional* IP-core or device: a bit set to 1 means that the
correspondent component is present, otherwise it is not.
Each bit represents a specific component release with a specific
configuration.
Observation 07.02.01
The capability mask describes **only** optional capabilities. The device must
work in any case, even if all optional capabilities are missing.
Observation 07.02.02
For any component modification it will be necessary to produce a new device
release because its behavior changed (`rule 02.03.00`_).
Observation 07.02.03
Since this field is device specific, its interpretation must be described
in the device manual.
Rule 07.03.00
All components described by the capability mask are at fixed offset within
the device memory map.
Observation 07.03.01
A device that does not have optional components must have a capability mask
on 0x0.
Observation 07.03.02
A component offset change it is an interface change and for this reason it
need a new release (`rule 02.03.00`_).
.. links
.. _`semantic versioning`: https://semver.org/
.. _RFC4122: https://tools.ietf.org/html/rfc4122
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment