axi2ahb - AXI4 to AHB2 Bridge
=============================
Overview
--------
The AXI4 to AHB2 bridge enables the usage of AXI4 masters in an AHB system.
It has an AXI4 slave port as an input and an AHB master port as output.
The IP also provides static endianess inversion to help integrating little endian
components into a big endian system.

┌─────────────┐      ┌─────────────────────┐      ┌────────────┐
│             ├─────►│                     ├─────►│            │
│ AXI4 Master │      │ AXI4 to AHB2 Bridge │      │ AHB2 Slave │
│             │◄─────┤                     │◄─────┤            │
└─────────────┘      └─────────────────────┘      └────────────┘
Figure: Usage example

AXI4 Limitations
----------------
The AXI4 to AHB2 bridge currently does not support all AXI4 features.

Incremental transfers are the only transfer type supported.
This means that the bridge will not function as intended for the
fixed and wrapping transfer types.

The following AXI4 signals are ignored by the bridge:
 * AxCACHE
 * AxREGION
 * AxQOS
 * AxLOCK
 * AxPROT
 * AxUSER
 * xUSER
This means that the functions in the AXI4 protocol relying on these
signals are not supported. It also means that there is no matching
of features relying on these signals between the AXI4 and AHB2 protocols.

Response reporting only provides two possible response codes:
OKAY and SLVERR. Any response from the AHB bus which is not OKAY are
translated to SLVERR.

AHB2 Details
------------
Due to the differences in the protocols, some AHB2 features can not
be fully expressed.

The HPROT signals is fixed to "0011", which translates into:
not cachable, not bufferable, privileged data accesses.

Operation
---------
There are no runtime control signals to the bridge. Thus the only way
to operate the bridge is using the AXI4 slave interface. Please refer
the the AXI4 protocol standard document from Arm for AXI4 details.
Also please do observe the limitations of the bridge, described by the
AXI4 Limitations sections of this documentation.
The AXI4 to AHB2 bridge is limited to having matching data bus sizes of
the AXI4 and AHB2 buses. If the AXI4 data bus size is greater than the
AHB2 data bus size, the AXI4 resizer IP can be used to reduce the data bus
size; before connecting it to the AXI4 to AHB2 bridge IP.

Implementation
--------------
Reset
~~~~~
The AXI4 to AHB2 bridge resets all its registers using an active low
reset. The registers are reset synchronously.

Endianness
~~~~~~~~~~
The endianess of the bridge is controlled using two different sources.
The slave port endianess is controlled via the axi_endian configuration option,
while the master port endianess is controlled via the abhmi.endian signal.
The signal is expected to be static after reset. The AXI4 to AHB2 bridge will
convert between the different endianesses with the goal to keep the data consistent
in regard to the transaction size.

Configuration Options
---------------------
The AXI4 to AHB2 bridge can be configured at elaboration time using
the generics described in this section.

memtech
~~~~~~~
Controls the memory technology used to implement the write data buffer.
Please refer to the technology mapping library documentation for more information.

hindex
~~~~~~
The master index for the AHB master. Used to select which HGRANT to observe.

dbuffer
~~~~~~~
Controls the depth of the data buffer. Expressed as the number
of words to buffer. Recommended to be a power of two.

wordsize
~~~~~~~~
The wordsize of the data words, in the number of bytes. The AXI to AHB2 bridge
will consider the bus to only be as wide as expressed by this generic.

axi_endian
~~~~~~~~~
Controls the endianess expected from the AXI4 interface.
0: Big endian
1: Little endian

sub_bus_width_address_inversion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In some cases it might be desirable to align narrow accesses to the width
of the bus.
E.g. a 16-bit access on a 32-bit bus. The address provided via the AXI interface
is 0x0. The resulting address would in this case become 0x2.

mask
~~~~
The 12 most significant bits of the address will be XORed with the
provided mask. The mask must thus be within the range of [0, 4095].

vendorid
~~~~~~~~
The AHB2 vendor ID to be used by the AHB2 master interface.

deviceid
~~~~~~~~
The AHB2 device ID to be used by the AHB2 master interface.

scantest
~~~~~~~~
Enable scan for the memory used in the read data FIFO.

memory_ft
~~~~~~~~~
Use a fault tolerant memory variant for the read data FIFO.

Signal Descriptions
-------------------
resetn
~~~~~~
Active low synchronous reset.

clk
~~~
AHB and AXI clock.

axisi
~~~~~
AXI4 slave input signals. Not all signals are included,
please refer to the AXI4 limitations section for more information.

axiso
~~~~~
AXI4 slave output signals.

ahbmi
~~~~~
AHB2 master input signals.

ahbmo
~~~~~
AHB2 master output signals.

custom*
~~~~~~~
MBIST related signals.

Library Dependencies
--------------------
GRLIB
~~~~~
amba: AHB2 and AXI4 composite type definitions.
stdlib: Utility functions, such as log2.
devices: AHB2 vendor definitions.

TECHMAP
~~~~~~~
gencomp: Synchronous FIFO component.

GAISLER
~~~~~~~
axi: AXI4 related helper functions.

Instantiation
-------------
The following code snippet is intended to show how the core is instantiated.

library ieee;
use ieee.std_logic_1164.all;

library grlib;
use grlib.amba.all; -- For types and AXIDW

library gaisler;
use gaisler.axi.all; -- AXI4 to AHB2 bridge component

entity axi2ahb_example is
  port (
    clk : in std_logic;
    rstn : in std_logic;

    -- AXI4 slave signals
    s_axi4_awaddr : in std_logic_vector(31 downto 0);
    -- ... Rest of slave port declarations omitted.

    -- AHB2 master signals
    m_ahb2_haddr : out std_logic_vector(31 downto 0);
    -- ... Rest of master port declartions omitted.
    m_ahb2_hgrant : in std_logic
  );
end entity;

architecture ex of axi2ahb_example is
  constant hgrant_index : natural := 2;

  signal axisi : axi4_mosi_type;
  signal axiso : axi_somi_type;
  signal ahbmi : ahb_mst_in_type;
  signal ahbmo : ahb_mst_out_type;
begin
  -- Assign slave inputs to record.
  axisi.aw.addr <= s_axi4_awaddr;
  -- ... Rest of AXI4 assignments omitted.

  -- Assign master inputs to record.
  ahbmi.hgrant <= (hgrant_index => m_ahb2_hgrant, others => '0');
  -- ... Rest of input assignments omitted.

  -- Assign master outputs to ports.
  m_ahb2_haddr <= ahbmo.haddr;
  -- ... Rest of output assignments omitted.

  axi2ahb_0 : axi2ahb
    generic map(
      memtech => 0, -- Generic memory implementation
      hindex => hgrant_index,
      dbuffer  => 64, -- Data buffer capable of storing 64 data words
      wordsize => AXIDW, -- To match record type width
      axi_endian => 1, -- Little endian AXI4 interface
      sub_bus_width_address_inversion => 0, -- Do not modify addresses
      mask => 16#000#, -- Do not mask the address
      vendorid => YOUR_VENDOR_ID,
      deviceid => YOUR_DEVICE_ID,
      scantest => 0, -- No SCAN support
      memory_ft => 0 -- Use a regular memory
    )
    port map(
      clk               => clk,
      resetn            => rstn,
      ahbmi             => ahbmi,
      ahbmo             => ahbmo,
      axisi             => aximo,
      axiso             => aximi
    );
end architecture;

