neorv32/docs/userguide/adding_custom_hw_modules.adoc

<<<
:sectnums:
== Adding Custom Hardware Modules

In resemblance to the RISC-V ISA, the NEORV32 processor was designed to ease customization and _extensibility_.
The processor provides several predefined options to add application-specific custom hardware modules and accelerators.
A <<_comparative_summary>> is given at the end of this section.

.Debugging/Testing Custom Hardware Modules
[TIP]
Custom hardware IP modules connected via the external bus interface or integrated as CFU can be debugged "in-system" using the
"bus explorer" example program (`sw/example_bus_explorer`). This program provides an interactive console (via UART0)
that allows to perform arbitrary read and write access from/to any memory-mapped register.


=== Standard (_External_) Interfaces

The processor already provides a set of standard interfaces that are intended to connect _chip-external_ devices.
However, these interfaces can also be used chip-internally. The most suitable interfaces are
https://stnolting.github.io/neorv32/#_general_purpose_input_and_output_port_gpio[GPIO],
https://stnolting.github.io/neorv32/#_primary_universal_asynchronous_receiver_and_transmitter_uart0[UART],
https://stnolting.github.io/neorv32/#_serial_peripheral_interface_controller_spi[SPI] and
https://stnolting.github.io/neorv32/#_two_wire_serial_interface_controller_twi[TWI].

The SPI and especially the GPIO interfaces might be the most straightforward approaches since they
have a minimal  protocol overhead. Device-specific interrupt capabilities could be added using the
https://stnolting.github.io/neorv32/#_external_interrupt_controller_xirq[External Interrupt Controller (XIRQ)].

Beyond simplicity, these interface only provide a very limited bandwidth and require more sophisticated
software handling ("bit-banging" for the GPIO). Hence, it is not recommend to use them for _chip-internal_ communication.


=== External Bus Interface

The https://stnolting.github.io/neorv32/#_processor_external_memory_interface_wishbone[External Bus Interface]
provides the classic approach for attaching custom IP. By default, the bus interface implements the widely adopted
Wishbone interface standard. This project also includes wrappers to convert to other protocol standards like ARM's
AXI4-Lite or Intel's Avalon protocols. By using a full-featured bus protocol, complex SoC designs can be implemented
including several modules and even multi-core architectures. Many FPGA EDA tools provide graphical editors to build
and customize whole SoC architectures and even include pre-defined IP libraries.

.Example AXI SoC using Xilinx Vivado
image::neorv32_axi_soc.png[]

Custom hardware modules attached to the processor's bus interface have no limitations regarding their functionality.
User-defined interfaces (like DDR memory access) can be implemented and the hardware module can operate completely
independent of the CPU.

The bus interface uses a memory-mapped approach. All data transfers are handled by simple load/store operations since the
external bus interface is mapped into the processor's https://stnolting.github.io/neorv32/#_address_space[address space].
This allows a very simple still high-bandwidth communications. However, high bus traffic may increase access latencies.


=== Custom Functions Subsystem

The https://stnolting.github.io/neorv32/#_custom_functions_subsystem_cfs[Custom Functions Subsystem (CFS)] is
an "empty" template for a memory-mapped, processor-internal module.

The basic idea of this subsystem is to provide a convenient, simple and flexible platform, where the user can
concentrate on implementing the actual design logic rather than taking care of the communication between the
CPU/software and the design logic. Note that the CFS does not have direct access to memory. All data (and control
instruction) have to be send by the CPU.

The use-cases for the CFS include medium-scale hardware accelerators that need to be tightly-coupled to the CPU.
Potential use cases could be DSP modules like CORDIC, cryptographic accelerators or custom interfaces (like IIS).


=== Custom Functions Unit

The https://stnolting.github.io/neorv32/#_custom_functions_unit_cfu[Custom Functions Unit (CFU)] is a functional
unit that is integrated right into the CPU's pipeline. It allows to implement custom RISC-V instructions.
This extension option is intended for rather small logic that implements operations, which cannot be emulated
in pure software in an efficient way. Since the CFU has direct access to the core's register file it can operate
with minimal data latency.


=== Comparative Summary

The following table gives a comparative summary of the most important factors when choosing one of the
chip-internal extension options:

* https://stnolting.github.io/neorv32/#_custom_functions_unit_cfu[Custom Functions Unit (CFU)] for CPU-internal custom RISC-V instructions
* https://stnolting.github.io/neorv32/#_custom_functions_subsystem_cfs[Custom Functions Subsystem (CFS)] for tightly-coupled processor-internal co-processors
* https://stnolting.github.io/neorv32/#_processor_external_memory_interface_wishbone[External Bus Interface (WISHBONE)] for processor-external memory-mapped modules

.Comparison of On-Chip Extension Options
[cols="<1,^1,^1,^1"]
[options="header",grid="rows"]
|=======================
|                                | Custom Functions Unit (CFU) | Custom Functions Subsystem (CFS) | External Bus Interface
| **RTL location**               | CPU-internal                | processor-internal               | processor-external
| **HW complexity/size**         | small                       | medium                           | large
| **CPU-independent operation**  | no                          | yes                              | yes
| **CPU interface**              | register file access        | memory-mapped                    | memory-mapped
| **Low-level access mechanism** | custom instructions         | load/store                       | load/store
| **Access latency**             | minimal                     | low                              | medium to high
| **External IO interfaces**     | not supported               | yes, but limited                 | yes, user-defined
| **Exception capability**       | yes                         | no                               | no
| **Interrupt capability**       | no                          | yes                              | user-defined
|=======================