FPGA Build
==========

This section corresponds to ``3.miniac/3.build``.

The current build documentation was inherited from the Wireguard-FPGA project
and still needs uberClock-specific adaptation. It nonetheless describes the
existing CSR, software, and co-simulation build flow.

Build Stages
------------

The documented flow consists of three stages:

- Compilation of CSR definitions from SystemRDL into RTL and a software HAL.
- Compilation of the RISC-V software application.
- Compilation of SystemVerilog designs into a target bitstream.

CSR HAL Compilation
-------------------

The CSR RTL and HAL are generated from SystemRDL using ``peakrdl``. For
co-simulation, a second HAL layer is generated using
``systemrdl-compiler``-compatible inputs.

Example command:

.. code-block:: bash

   peakrdl c-header csr_cosim.rdl -b ltoh -o csr.h

The wrapper HAL headers are generated with ``sysrdl_cosim.py``. Its documented
options include:

.. code-block:: text

   usage: sysrdl_cosim.py [-h] [-r RDLFILE] [-o OUTFILE] [-c] [-v VPNODE] [-d DELAY] [-C CLKPERIOD]

Running ``make -f MakefileCSR`` produces generated files in
``3.build/csr_build/generated-files`` including:

- ``csr_cosim.rdl``
- ``csr.sv``
- ``csr_pkg.sv``
- ``csr.h``
- ``csr_hw.h``
- ``csr_cosim.h``

The hardware and co-simulation headers expose the same API and can be selected
at compile time:

.. code-block:: c

   ifdef VPROC
   #include "csr_cosim.h"
   #else
   #include "csr_hw.h"
   #endif

Software Compilation
--------------------

Running ``make -f MakefileSW`` produces outputs in ``3.build/sw_build``,
including:

- ``main.lds``
- ``main.map``
- ``main.elf``
- ``main.hex``
- ``main.bin``
- ``main.dump``
- ``imem.INIT.vh``

Hardware Compilation
--------------------

- TODO in the current source README.

Co-simulation HAL
-----------------

The HAL provides hierarchical register access that mirrors the RDL layout.
Example usage:

.. code-block:: c

   #include "wireguard_regs.h"

   csr_vp_t* csr = new csr_vp_t();
   csr->ip_lookup_engine->table[0]->allowed_ip[0]->address(0x12345678);
   printf("address = 0x%08lx\n\n", csr->ip_lookup_engine->table[0]->allowed_ip[0]->address());

   csr->ip_lookup_engine->table[3]->endpoint->full(0x5555555555555555ULL);
   csr->ip_lookup_engine->table[3]->endpoint->interface(0x7);
   printf("interface = 0x%1lx\n\n", csr->ip_lookup_engine->table[3]->endpoint->interface());

For co-simulation, the autogenerated header also remaps the application entry
point through ``WGMAIN`` so the same source can build either for hardware or
for a VProc simulation node.