Register tree access protocol
=============================

This documentation provides an overview and description of the VHDL module that implements the HotRIO register tree access protocol. The module is meant to grant access to an internal register tree through a SPI interface with 8-bit transmission units, but if needed it can also be used in combination with any other interfaces that send and receive bytes.

.. note::
  The module is configured to accept addresses and data in the "Little-Endian" format. They are however converted to Big-Endian internally.

The module
----------

.. vhdlentity::
   :file: ../Firmware/Source/modules/register_tree/hdl/regtree_access.vhd
   :entity: regtree_access

The protocol
------------

The communication protocol is straightforward and consists of three fundamental commands:

.. list-table::
    :widths: 12 5
    :header-rows: 1

    * - Command
      - Default value

    * - Set address
      - "00100000"
    
    * - Read
      - "01000000"

    * - Write
      - "10000000"

    * - Read without increment
      - "01010000"

    * - Write without increment
      - "10010000"
  
The commands are defined by the generics ``addr_cmd_g``, ``read_cmd_g``, ``write_cmd_g``, ``rni_cmd_g`` and ``wni_cmd_g`` and they can be changed if needed. This is especially useful is more than one register tree needs to be instantiated in the same firmware.

The process begins with the microcontroller sending a command, which is 8 bits long. This is followed by data transmitted in 16-bit packets, using little-endian format. Sequential reads and writes are also supported. After completing an operation, the internal address automatically increments, allowing subsequent registers to be read or written without restarting the communication process.

A register tree transaction consists of a 'set address' operation followed by a 'read' or 'write' operation which can be prolonged as needed to read or write several registers in a row, or to read/write the same register multiple times if the 'rni' and 'wni' commands are used instead of 'read' and 'write'. The interface connected to "regtree_access" must assert ``rstn_i`` whenever a transaction is not ongoing, and at least for three cycles of the system clock between two transactions.

The following waveform diagrams illustrate the expected stimuli from the interface that drives the module and the corresponding expected responses. The examples show how to read or write two consecutive 16-bit registers. If the ``rni`` and ``wni`` commands had been used in place of the ``read`` and ``write`` commands, the two read/write operations would have been executed at the same address instead.

.. figure:: ../Resources/cfg_spi_set_address_wave.svg

  Set address operation waveform

.. figure:: ../Resources/cfg_spi_write_wave.svg

  Write operation waveform

.. figure:: ../Resources/cfg_spi_read_wave.svg

  Read operation waveform