.. _dev-register: Device Registers ================== .. _reg-type: 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 :ref:`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 :ref:`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 :ref:`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 :ref:`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 :ref:`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. Register access, bit-field definitions, reset behavior, and time of effect MUST be specified in the hardware datasheet for raw registers or the :ref:`ONI Device Datasheet ` for managed registers. .. _dev-reg-map: Register Map ------------- A device can optionally 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 :ref:`data-rd-chan`, ``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 :ref:`data-rd-chan`. When ``ENABLE`` is set to 0x00000001, the device MUST produce data on the :ref:`data-rd-chan` in accordance with behavior documented on its :ref:`dev-datasheet`. - For devices that do not produce data through the :ref:`data-rd-chan`, ``ENABLE`` is a Read-Only register with value 0. Attempting to write to the register results in ``CONFIGWNACK`` on the :ref:`sig-chan`. 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 :ref:`null-device` is an explicit exception to these rules.