Device Registers#

Register Type#

Device registers can be separated into two types:

  • Raw registers: Those that correspond 1:1 to the physical register space of an external electrical component (e.g., the register map in the manufacturer datasheet of a sensor IC).

  • Managed registers: Those designed to interface exclusively with an ONI system, usually implemented in firmware and described in a ONI Device Datasheet.

Raw registers provide a direct window to the underlying hardware. On the other hand, managed registers provide flexibility and abstract control over device state. For instance, managed registers may provide access to abstract properties that require access to multiple physical registers in hardware, which can all be completed in a single register read or write cycle. Thus the firmware can manage low-level raw access to the hardware, while exposing only high-level abstract registers in order to simplify the interface to user applications.

Register Access and Update#

Registers, independently of their type, can be defined as Read/Write, Read-Only or Write-Only. All registers MUST have a valid value at power-on. Whenever a device receives a soft reset request generated by the controller, registers might either be reset to their power-on value or keep their current value. This can be defined independently for each register. A hard hard reset MUST always reset them to their power-on value.

All register writes, regardless of reset behavior, MUST be immediate (i.e., for a Read/Write register, reading a register after being written must reflect the new value). However, the effects of a register might not occur until the next soft reset. An example of this type of behavior is registers that operate on the device descriptor. The descriptor must be static during runtime, but registers affecting it might take action after a soft reset, providing an updated descriptor to the controller.

Devices SHOULD inform the Controller of the time when a register access has been acknowledged. For read accesses, this is the time at which the value is retrieved by the device. For write accesses, its meaning depends on the register effect timing:

  • For registers with an immediate effect, the acknowledge time SHOULD be as close as possible to the time the effect occurs (e.g.: when the communication with the underlying hardware is finished)

  • For other register types, when the value is written to the device

The time reported by the devices MUST use the same counter source and format as the hubclk_cnt field of their data samples. If a device does not provide the time of a register access, the time MUST be of value 0xFFFFFFFFFFFFFFFF. Access time reporting MAY be implemented in all or some of the registers of any device.

Register access, bit-field definitions, reset behavior time of effect and access time reporting description MUST all be specified in the hardware datasheet for raw registers or the ONI Device Datasheet for managed registers.

Register Map#

A device MAY implement raw registers and MUST implement at least one managed register, ENABLE. This register’s behavior MUST conform the following rules:

  • Bits 31 down to 1 of the ENABLE are reserved.

  • For devices that produce data through the Read Channel, ENABLE is a Read/Write register that takes effect after soft reset. When ENABLE is set to 0x00000000, the device MUST NOT produce any data on the Read Channel. When ENABLE is set to 0x00000001, the device MUST produce data on the Read Channel in accordance with behavior documented on its Device Datasheet.

  • For devices that do not produce data through the Read Channel, ENABLE is a Read-Only register with value 0. Attempting to write to the register results in CONFIGWNACK on the Signal Channel.

The location of the managed registers depends on the existence of raw registers. If the device implements raw registers, those are mapped to addresses 0x00000000 to 0x00007FFF, corresponding to the same address map of the underlying hardware, and managed registers start from 0x00008000. If no raw registers are present, managed registers start from 0x00000000 instead.

The ENABLE register MUST be the first of the managed registers, at 0x00000000 if no raw registers are present, 0x00008000 if raw registers are implemented.

Note

A Null Device is an explicit exception to these rules.