Hardware Interfaces
###################

Hardware Interfaces 
===================

SLAVE_CONTROLLER_INTERFACE
--------------------------

The ``SLAVE_CONTROLLER`` module facilitates communication between the host CPU and multiple engine cores through 6 registers. 
These registers are used to send commands to the engine cores, with a specific format for handling operations and context data.

The lgoic signals and registers are influenced by the following generics:

.. list-table:: 
   :header-rows: 1

   * - Name
     - Type
     - Default
     - Description
   * - ``AXI_DATA_WIDTH``
     - ``integer``
     - ``32``
     - Specifies the width of the data bus, which is the size of each register.
   * - ``NUMBER_OF_CORES``
     - ``integer``
     - ``1``
     - Defines the number of engine cores connected to the SLAVE_CONTROLLER.

The following ports allow communication with the engine cores:

.. list-table:: 
   :header-rows: 1

   * - Signal Name
     - Direction
     - Width
     - Description
   * - ``head_reg_2_out``
     - ``out``
     - ``AXI_DATA_WIDTH``
     - Register used for sending operation codes (op-codes).
   * - ``payload_3_out``
     - ``out``
     - ``AXI_DATA_WIDTH``
     - Register used for context-specific information.
   * - ``payload_4_out``
     - ``out``
     - ``AXI_DATA_WIDTH``
     - Register used for context-specific information.
   * - ``payload_5_out``
     - ``out``
     - ``AXI_DATA_WIDTH``
     - Register used for context-specific information.
   * - ``payload_6_out``
     - ``out``
     - ``AXI_DATA_WIDTH``
     - Register used for context-specific information.
   * - ``payload_7_out``
     - ``out``
     - ``AXI_DATA_WIDTH``
     - Register used for context-specific information.

Signals for communication status:

.. list-table::
   :header-rows: 1

   * - Signal Name
     - Direction
     - Width
     - Description
   * - ``c_new_command``
     - ``out``
     - ``NUMBER_OF_CORES``
     - Indicates a new command for the cores.
   * - ``c_command_complete``
     - ``in``
     - ``NUMBER_OF_CORES``
     - Signals when a core has completed executing a command.

The ``SLAVE_CONTROLLER`` targets more than only one engine core. The number is determined
by the generic ``NUMBER_OF_CORES``. Each bit of ``c_new_command`` and ``c_command_complete`` 
corresponds to one engine core.


MASTER_CONTROLLER_INTEFACE
--------------------------

The ``MASTER_CONTROLLER`` module interfaces between multiple engine cores and external DDR memory, 
handling simultaneous memory transaction requests (read and write) from different cores. It 
prioritizes requests based on two main rules:

1. **Core priority**: The core with the lowest index has the highest priority.
2. **Request priority**: Write requests are prioritized over read requests within a core.

The module has three configurable parameters to adjust for various system requirements:

.. list-table::
   :header-rows: 1

   * - Name
     - Type
     - Default
     - Description
   * - ``AXI_DATA_WIDTH``
     - ``integer``
     - ``32``
     - Specifies the width of the data bus between the cores and the memory.
   * - ``AXI_ADDR_WIDTH``
     - ``integer``
     - ``32``
     - Defines the address width of the memory being accessed.
   * - ``NUMBER_OF_CORES``
     - ``integer``
     - ``1``
     - Determines the number of cores that will interface with the memory controller.

The following ports connect to the engine cores, enabling read and write transactions:

.. list-table::
   :header-rows: 1

   * - Signal Name
     - Direction
     - Width
     - Description
   * - ``c_rd_req``
     - ``in``
     - ``NUMBER_OF_CORES``
     - Read request signals from each core.
   * - ``c_wr_req``
     - ``in``
     - ``NUMBER_OF_CORES``
     - Write request signals from each core.
   * - ``raddr``
     - ``in``
     - ``NUMBER_OF_CORES * AXI_ADDR_WIDTH``
     - Read addresses from each core.
   * - ``waddr``
     - ``in``
     - ``NUMBER_OF_CORES * AXI_ADDR_WIDTH``
     - Write addresses from each core.
   * - ``out_data``
     - ``out``
     - ``AXI_DATA_WIDTH``
     - Data output from the core to the memory.
   * - ``in_data``
     - ``in``
     - ``NUMBER_OF_CORES * AXI_DATA_WIDTH``
     - Data input from the memory to each core.
   * - ``c_wxfer_length``
     - ``in``
     - ``NUMBER_OF_CORES * 12``
     - Transfer byte lengths for write operations for each core.
   * - ``c_rxfer_length``
     - ``in``
     - ``NUMBER_OF_CORES * 12``
     - Transfer byte lengths for read operations for each core.
   * - ``c_next_wdata``
     - ``out``
     - ``NUMBER_OF_CORES``
     - Indicates when a core should provide the next word for a write operation.
   * - ``c_next_rdata``
     - ``out``
     - ``NUMBER_OF_CORES``
     - Indicates when memory should provide the next word for a read operation.
   * - ``c_done``
     - ``out``
     - ``1``
     - Indicates completion of the current transaction.
  
Every core takes a specific portion of the signals. Each engine core connected to a port with the standard logic vector ..

* (NUMBER_OF_CORES - 1 downto 0) takes 1 bit.
* (NUMBER_OF_CORES * AXI_ADDR_WIDTH - 1 downto 0) takes AXI_ADDR_WIDTH bits.
* (NUMBER_OF_CORES * AXI_DATA_WIDTH - 1 downto 0) takes AXI_DATA_WIDTH bits.

.. note: The lower the index of the engine core, the more it is prioritzed when sending data request.

The transaction has essentially 3 states 

* **IDLE:** The ``MASTER_CONTROLLER`` waits for a read or write request 
* **START_TXN:** The ``MASTER_CONTROLLER`` prioritizes the engine core and write over read requests
* **TXN:** The ``MASTER_CONTROLLER`` performs the transaction

For the engine core the following aspects need to be taken care of 

**Sart a write request**:
Set the following singals until the write request has started

* set ``c_wr_req`` to '1' to indicate a write request
* set ``c_wxfer_length`` which is the number of bytes to be send to the memory. It ranges from 4 * 2^3 to 4 * 2^15, where 4 is the 4 bytes of a 32 bit word.  
* set ``waddr`` which is the write target address of the external memory
* set ``in_data`` which is the first data word to send to external memory 

**Write transaction**:
wait until the core asks for new data when ``c_next_wdata`` is '1'. This means the ``MASTER_CONTROLLER`` has accepted the request and starts the transaction

* ``c_wxfer_length`` is irrelevant 
* ``waddr`` is irrelevant 
* ``c_wr_req`` can be set to '0' to not start a new request after the transaction has finished
* ``c_next_wdata`` on high indicates whenever in the next clock cycle a new word is written. Make sure to provide the next data word at ``in_data``
* ``c_done`` on high indicates that a write or read transaction has been completed. Since ``c_next_wdata`` was triggered before you know its a write transaction. 

**Sart a read request**:
Set the following singals until the read request has started

* set ``c_rd_req`` to '1' to indicate a read request 
* set ``c_rxfer_length`` which is the number of bytes to be send to the memory. It ranges from 4 * 2^3 to 4* 2^15, where 4 is the 4 bytes of a 32 bit word. 
* set ``waddr`` which is the read target address of the external memory

**Read transaction**:
wait until the core asks for new data when ``c_next_wdata`` is '1'. This means the ``MASTER_CONTROLLER`` has accepted the request and starts the transaction

* ``c_wxfer_length`` is irrelevant 
* ``waddr`` is irrelevant 
* ``c_wr_req`` can be set to '0' to not start a new request after the transaction has finished
* ``c_next_wdata`` on high indicates whenever in the next clock cycle a new word is written. Make sure to provide the next data word at ``in_data``
* ``c_done`` on high indicates that a write or read transaction has been completed. Since ``c_next_wdata`` was triggered before you know its a write transaction. 

.. note: Read and write request can be send in parallel, but only one of them can be processed at a time, so the other request needs to wait until ``MASTER_CONTROLLER`` reacts.

A diagramm demonstrating a write request 

.. image:: ../source/figs/MASTER_CONTROLLER_WriteTiming.svg
  :width: 800
  :alt: Overview of the write timing diagramm

  Overview of the write timing diagramm. The grey and white blocks at the bus indicates alternating data.
  In the case of the in_data it means that new data words are send to the MASTER_CONTROLLER.

A diagramm demonstrating a read request 

.. image:: ../source/figs/MASTER_CONTROLLER_ReadTiming.svg
  :width: 800
  :alt: Overview of the read timing diagramm

  Overview of the read timing diagramm. The grey and white blocks at the bus indicates alternating data.
  In the case of the out_data it means that new data words are send from the MASTER_CONTROLLER.


Software Interfaces 
===================

SLAVE_CONTROLLER_INTERFACE
---------------------------

**Send a command to an engine core:**

The following code examples how the SLAVE_CONTROLLER receives a new command.
Besides the command send logic, there are 6 more register that provide command context.
For example context look into the ``AXI_TEST_ENGINE_CORE_INTERFACE``.

Here the following two signals matter: 

* ``control_command_reg_0_in`` (reg_data[0]) : 
  A write only register 
  Each bit belongs to one engine core. 
  Be aware that there are often more bits provided than engine cores are connected.
  When the bit targeting the engine core is set to '1' the corresponding engine core receives a new command. 
  Make sure to set the bit afterwards to 0. A new command can only be send if the bit has been 0 before.
* ``control_status_1_out`` (reg_data[1]): 
  A read only register
  Each bit belongs to one engine core. 
  Be aware that there are often more bits provided than engine cores are connected.
  The ``SLAVE_CONTROLLER`` sets a bit to '1' after a command has been send to the corresponding engine core. 
  It indicates that the engine core is busy and wont process new requests

In vhdl:

.. code-block:: vhdl

    -- <<Here is place to set the other register for command context>>
    -- Send a command to the first engine core with the index 0
    control_command_reg_0_in(0) <= '1'; 
    -- Wait for a clock cycle using the THANNA_TEST_UTILS package
    run_cycle(clk);
    -- Set the send command bit for the engine core 0 back to 0
    control_command_reg_0_in(0) <= '0';
    -- Wait until the status register at index 0 is '0' which indicates that 
    -- the engine core has completed the command and is not busy anymore
    while control_status_1_out(0) = '0' loop run_cycle(clk); end loop;

In C:

.. code-block:: C

    // <<Here is place to set the other register for command context>>
    // Send a command to the first engine core with the index 0
    reg_data[0] = 1;                  
    // Set the send command bit for the engine core 0 back to 0
    reg_data[0] = 0;
    // Wait until the status register at index 0 is '0' which indicates that 
    // the engine core has completed the command and is not busy anymore
    printf("WAIT: \n\r");
    while ((reg_data[1] & 1) != 1)
    {   // Looping = waiting
        for(size_t i = 0; i < 1000000; i++);
    }
    printf("Read complete");

AXI_TEST_ENGINE_CORE_INTERFACE
------------------------------

The following examples show how to provide the command context for the ``AXI_TEST`` engine core.
To send the command append the send command logic from the ``SLAVE_CONTROLLER_INTERFACE``.

The following ``AXI_DATA_WIDTH`` generic defines the size of the register, which depend on the devices
data bus. In the case of the Zybo Z-720 it is 32 Bit. In the case of ``AXI_TEST`` the register are used 
as follows: 

.. list-table:: 
   :header-rows: 1

   * - Register
     - Write/Read
     - Width
     - Description
   * - ``head_reg_2_out`` (reg[2])
     - ``write``
     - ``AXI_DATA_WIDTH``
     - Register used for sending operation codes (op-codes).
   * - ``payload_3_out`` (reg[3])
     - ``write``
     - ``AXI_DATA_WIDTH``
     - Register containing the write or read address for a memory transaction.
   * - ``payload_5_out`` (reg[5])
     - ``write``
     - ``AXI_DATA_WIDTH``
     - Start index of the burst register in the AXI_TEST module. Only relevant for memory transactions.
   * - ``payload_6_out`` (reg[6])
     - ``write``
     - ``AXI_DATA_WIDTH``
     - Number of burst bytes transferred in a memory transaction. It can range from 4 * 2^2 to 4 * 2^15.

**Read command:**

In vhdl:

.. code-block:: vhdl 

    head_reg_2_in <= std_logic_vector(to_unsigned(2, AXI_DATA_WIDTH)); --  Op code for the read command
    payload_3_in  <= (others => '0'); -- Address initialized with a pointer pointing to free space in the DDR                                 
    payload_5_in  <= (others => '0'); -- Start index of the burst register in the AXI_TEST module                           
    payload_6_in  <= std_logic_vector(to_unsigned(4 * 8, AXI_DATA_WIDTH)); -- Number of burst bytes. It can range from 4 * 2^2 to 4 * 2^15

In C:

.. code-block:: C

    reg_data[2] = 2;                  // Op code for the read command
    reg_data[3] = (uint32_t)ddr_data; // Address initialized with a pointer pointing to free space in the DDR
    reg_data[5] = 0;                  // Start index of the burst register in the AXI_TEST module
    reg_data[6] = 8;                  // Number of burst bytes. It can range from 4 * 2^2 to 4 * 2^15

**Write command:**

In vhdl:

.. code-block:: vhdl

    head_reg_2_in <= std_logic_vector(to_unsigned(1, AXI_DATA_WIDTH)); -- Op code for the write command
    payload_3_in  <= (others => '0'); -- Address initialized with a pointer pointing to free space in the DDR
    payload_5_in  <= (others => '0'); -- Start index of the burst register in the AXI_TEST module 
    payload_6_in  <= std_logic_vector(to_unsigned(4 * 8, AXI_DATA_WIDTH)); -- Number of burst bytes. It can range from 4 * 2^2 to 4 * 2^15.

In C:

.. code-block:: C

    reg_data[2] = 1;                  // Op code for the write command
    reg_data[3] = (uint32_t)ddr_data; // Address initialized with a pointer pointing to free space in the DDR
    reg_data[5] = 0;                  // Start index of the burst register in the AXI_TEST module
    reg_data[6] = 8;                  // Number of burst bytes. It can range from 4 * 2^2 to 4 * 2^15.

**Increment command:**

In vhdl:

.. code-block:: vhdl

    head_reg_2_in <= std_logic_vector(to_unsigned(16, AXI_DATA_WIDTH)); -- Op code for the increment command

In C:

.. code-block:: C

    reg_data[2] = 16;                 // Op code for the increment command