<<<
:sectnums:
== General Hardware Setup

This guide shows the basics of setting up a NEORV32 project for simulation or synthesis from scratch.
It uses a simple, exemplary test "SoC" setup of the processor to keep things simple at the beginning.
This simple setup is intended for a first test / evaluation of the processor.

The NEORV32 project features three minimalist pre-configured test setups in
https://github.com/stnolting/neorv32/blob/main/rtl/test_setups[`rtl/test_setups`].
These test setups only implement very basic processor and CPU features and mainly
differ in the actual boot configuration.

.NEORV32 "hello world" Test Setup (`rtl/test_setups/neorv32_test_setup_bootloader.vhd`)
image::neorv32_test_setup.png[align=center]

[start=1]
. Create a new project with your FPGA/ASIC/simulator EDA tool of choice.
. Add all VHDL files from the project's `rtl/core` folder to your project.
Make sure to add all these rtl files to a new library called `neorv32`. If your toolchain does not
provide a field to enter the library name, check out the "properties" menu of the added rtl files.

.Compile Order and File-List File
[TIP]
Some tools (like Lattice Radiant) might require a manual compile order of the VHDL source files to
identify the dependencies. The `rtl` folder features a file-list file that lists all required HDL files in
their recommended compilation order (see https://stnolting.github.io/neorv32/#_file_list_file).

[start=3]
. The `rtl/core/neorv32_top.vhd` VHDL file is the top entity of the NEORV32 processor, which can be
instantiated within a user project. However, in this tutorial we will use one of the pre-defined
test setups from `rtl/test_setups` as top entity.

.NEORV32 VHDL Package
[IMPORTANT]
Make sure to include the `neorv32` package into your design when instantiating the processor: add
`library neorv32;` and `use neorv32.neorv32_package.all;` to your design unit.

[start=4]
. Add the pre-defined test setup of choice to the project, too, and select it as **top entity**.
. The entity of the test setups provides a minimal set of configuration generics, that might have
to be adapted to match your FPGA and board:

.Test setup entity - configuration generics
[source,vhdl]
----
generic (
  -- adapt these for your setup --
  CLOCK_FREQUENCY : natural := 100000000; <1>
  IMEM_SIZE       : natural := 16*1024;   <2>
  DMEM_SIZE       : natural := 8*1024     <3>
);
----
<1> Clock frequency of `clk_i` signal in Hertz
<2> Default size of internal instruction memory: 16kB
<3> Default size of internal data memory: 8kB

[start=6]
. If your FPGA does not provide sufficient resources you can modify the memory sizes (`IMEM_SIZE` and `DMEM_SIZE`).
. The actual clock frequency (Hz) of the top's clock input signal (`clk_i`) needs to be defined using the `CLOCK_FREQUENCY` generic.

[start=8]
. Assign the signals of the test setup top entity to the according pins of your FPGA board.
All the signals can be found in the entity declaration of the corresponding test setup, e.g.:

.Ports of `neorv32_test_setup_bootloader.vhd`
[source,vhdl]
----
port (
  -- Global control --
  clk_i       : in  std_ulogic; -- global clock, rising edge
  rstn_i      : in  std_ulogic; -- global reset, low-active, async
  -- GPIO --
  gpio_o      : out std_ulogic_vector(7 downto 0); -- parallel output
  -- UART0 --
  uart0_txd_o : out std_ulogic; -- UART0 send data
  uart0_rxd_i : in  std_ulogic  -- UART0 receive data
);
----

.Signal Polarity
[IMPORTANT]
If your FPGA board has inverse polarity for certain input/output you need to add inverters. Example: The reset signal
`rstn_i` is low-active by default; the LEDs connected to `gpio_o` are high-active by default.

[start=9]
. Attach the clock input `clk_i` to your clock source and connect the reset line `rstn_i` to a button of
your FPGA board. Check whether it is low-active or high-active - the reset signal of the processor is
**low-active**, so maybe you need to invert the input signal.
. If possible, connected at least bit `0` of the GPIO output port `gpio_o` to a LED (see "Signal Polarity" note above).
. If your are using a UART-based test setup connect the UART communication signals `uart0_txd_o` and `uart0_rxd_i`
to the host interface (e.g. a USB-UART converter).
. If you are using the on-chip debugger setup connect the processor's JTAG signal `jtag_*` to a suitable JTAG adapter.
. Perform the project HDL compilation (synthesis, mapping, placement, routing, bitstream generation).
. Program the generated bitstream into your FPGA and press the button connected to the reset signal.
. The LED(s) connected to `gpio_o` should be flashing now.
