<<<
: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 NEORV32.

The NEORV32 project features three minimalistic 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 Files
[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 file-list files that list all required HDL files in
their recommended compilation order (see https://stnolting.github.io/neorv32/#_file_list_files).

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

[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>
  MEM_INT_IMEM_SIZE : natural := 16*1024;   <2>
  MEM_INT_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 you want to or if your FPGA does not provide sufficient resources you can modify the
_memory sizes_ (`MEM_INT_IMEM_SIZE` and `MEM_INT_DMEM_SIZE`).
. There is one generic that has to be set according to your FPGA board setup: the actual clock frequency
of the top's clock input signal (`clk_i`). Use the `CLOCK_FREQUENCY` generic to specify your clock source's
frequency in Hertz (Hz).

.Memory Layout
[NOTE]
If you have changed the default memory configuration (`MEM_INT_IMEM_SIZE` and `MEM_INT_DMEM_SIZE` generics)
keep those new sizes in mind - these values are required for setting up the software framework in the next
section <<_general_software_framework_setup>>.

[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
[NOTE]
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.
. Done! The LED(s) connected to `gpio_o` should be flashing now.
