Device Datasheet#
All ONI-compliant devices MUST have a corresponding datasheet that provides information on register programming and data IO. The datasheet must be served publicly. It can be a text file, PDF, or website. The required datasheet sections and information are described below.
Preamble#
The following information is required in the preamble:
Informal Device Name: Name of the device. This field MUST contain only alphanumeric characters and punctuation marks (i.e.,
?!*+-_~.()). Other characters, including special characters MUST NOT be used (e.g., ChipXYX, Chip XYX, and My~Chip-12ab!, are all valid).Author(s): Device firmware or chip creator(s). Can be a person/people, or a company, group, or organization.
Device Version: The device version that this datasheet corresponds to.
Device ID: The device ID that this datasheet corresponds to.
Description#
A textual description of the functionality of the device. This can be simple or detailed and is meant to be useful for upstream hardware and software developers for understanding the nature of the device during their work.
Register Map#
Raw Registers#
If the device uses raw registers, then a link to the manufacturer’s datasheet is all that is required so long as it contains the register documentation equivalent to that required by managed registers. However, the register map can also be reproduced for clarity or if the manufacturer’s datasheet is missing required information.
Managed Registers#
If the device uses managed registers, a table that describes the managed register map is required. There are no formatting requirements for this table, but it MUST contain the following columns:
Address: Register address within the register map.
Name: Human readable name for the register. Only capital ASCII letters and underscores are allowed, with no spaces or special characters (e.g.
VALIDandALSO_VALIDvs.NotValidandALSO-NOT-VALID).Access: Read-only, Write-only, or Read/Write.
Time of Effect: When does a register write affect hardware state? Immediately or following soft reset?
POR Value: Power-on or hard reset default value.
Reset Action: Upon a soft reset, what happens to the register? Does it maintain its previous state or get reset to some value? If the latter, then what value?
Description: Word description of the register’s function.
Additional columns are permitted so long as their information does not conflict with that in the required columns.
Read Frame Format#
If the device produces samples, a bitfield diagram describing the frame structure is required. Bits can be grouped into words as is convenient. If no frames are produced, then a statement of such is required.
Write Frame Format#
If the device accepts samples, a bitfield diagram describing the frame structure is required. Bits can be grouped into words as is convenient. If no frames are accepted, then a statement of such is required.
In addition to a description of the frame format, this section MUST specify if write frames are consumed immediately or buffered. If write frames are buffered, this section MUST specify if there is any possibility of dropping frames (e.g: receiving a frame while one is being processed).
A device MAY implement a mechanism to inform the host about its internal state, for instance to synchronize the production of data on the host synchronize with the device’s consumption of data. If implemented, this mechanism should be detailed in this section.
Bandwidth information#
A device datasheet MUST specify the expected periodicity and bandwidth for both its read and write channels, when available.
For streams with periodic data production or consumption, the datasheet must specify the frequency or possible configurable frequencies at which frames are being transmitted.
For streams with event-based, non-periodic data, the datasheet must specify the minimum and maximum rates at which data might be produced or can be consumed. Minimum rates of 0 are acceptable.
In both cases, the datasheet SHOULD specify one or more typical cases.