Lab_NHMFL
/
upsilon
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

this has to be almost entirely rewritten

This commit is contained in:
Peter McGoron 2023-06-12 13:09:45 -04:00
parent f8b7571f97
commit e273324bf6
1 changed files with 25 additions and 54 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

79
doc/maintenance_manual.md
View File

@ -14,9 +14,9 @@ section you need without having to read the entire thing.
## Organization of the Project ## Organization of the Project
Upsilon uses LiteX and ZephyrOS for it's FPGA code. LiteX generates HDL Upsilon uses LiteX and Linux for it's FPGA code. LiteX generates HDL
and glues it together. It also forms the build system of the hardware and glues it together. It also forms the build system of the hardware
portion of Upsilon. ZephyrOS is the kernel portion, which deals with portion of Upsilon. Linux is the kernel portion, which deals with
communication between the computer that receives scan data and the communication between the computer that receives scan data and the
hardware that is executing the scan. hardware that is executing the scan.
@ -34,9 +34,8 @@ to write much of it.
The kernel is written in C. This C is different than C you have written The kernel is written in C. This C is different than C you have written
before because it is running "freestanding." before because it is running "freestanding."
The kernel uses Zephyr as the real-time operating system running the You do not need to know about Linux kernel development. You will need
code. Zephyr has very good documentation and a very readable code base, to know the basics of ssh, vi, and how to use Unix as a user.
go read it.
Tests are written in C++ and verilog. You will not have to write C++ Tests are written in C++ and verilog. You will not have to write C++
unless you modify the Verilog files. unless you modify the Verilog files.
@ -45,12 +44,10 @@ The macro processing language GNU m4 is used occasionally. You will
need to know how to use m4 if you modify the main `base.v.m4` file need to know how to use m4 if you modify the main `base.v.m4` file
(e.g. adding more software-accessable ports). (e.g. adding more software-accessable ports).
Python is used for the bytecode assembler, the bytecode itself, and Python is used the SoC generator. The SoC generator uses a library called
the SoC generator. The SoC generator uses a library called LiteX, LiteX, which in turn uses migen. You do not need to know a lot about migen,
which in turn uses migen. but LiteX's documentation is poor so you will need to know some migen in order
You do not need to know a lot about migen, but LiteX's documentation to read the code and understand how some modules work.
is poor so you will need to know some migen in order to read the
code and understand how some modules work.
# Compile Process # Compile Process
@ -81,29 +78,6 @@ compile things on any computer with an internet connection.
All commands should be done in the conda environment. All commands should be done in the conda environment.
### Zephyr OS
These instructions are based on [these][zephyr_getting_started], but the Zephyr
environment should be installed into the F4PGA conda environment,
[zephyr_getting_started]: https://docs.zephyrproject.org/latest/develop/getting_started/index.html
1. Run `pip3 install west`
2. Run
```
west init $ZEPHYR_DIRECTORY/zephyrproject
cd $ZEPHYR_DIRECTORY/zephyrproject
west update
west zephyr-export
pip install -r ~/zephyrproject/zephyr/scripts/requirements.txt
cd $ZEPHYR_DIRECTORY/zephyrproject
wget https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.0/zephyr-sdk-0.16.0_linux-x86_64.tar.xz
wget -O - https://github.com/zephyrproject-rtos/sdk-ng/releases/download/v0.16.0/sha256.sum | shasum --check --ignore-missing
tar xvf zephyr-sdk-0.16.0_linux-x86_64.tar.xz
cd zephyr-sdk-0.16.0
./setup.sh
```
### LiteX ### LiteX
1. Download `litex_setup.py` from the [LiteX repository][litex_repo], Upsilon 1. Download `litex_setup.py` from the [LiteX repository][litex_repo], Upsilon
@ -119,6 +93,21 @@ environment should be installed into the F4PGA conda environment,
[litex_repo]: https://github.com/enjoy-digital/litex [litex_repo]: https://github.com/enjoy-digital/litex
[sifive_gcc]: https://github.com/sifive/freedom-tools/releases [sifive_gcc]: https://github.com/sifive/freedom-tools/releases
### Buildroot
Buildroot builds a Linux system for the FPGA. To build the Images, download a stable
version of Buildroot that the config files support and run
make BR2_EXTERNAL=/upsilon_directory/buildroot litex_vexriscv_defconfig
### OpenSBI
OpenSBI is a platform independent interface between the hardware and the kernel.
Download the latest version of OpenSBI that the config files support. Copy
the files in the `opensbi` directory to the `targets` directory and run
make CROSS_COMPILE=riscv64-linux-gnu- PLATFORM=litex/vexriscv
## FPGA Build System ## FPGA Build System
Make sure F4PGA and a RISC-V GCC compiler are in your path. Then just go into Make sure F4PGA and a RISC-V GCC compiler are in your path. Then just go into
@ -136,27 +125,9 @@ For the Arty A7, the bitstream is `firmware/build/digilent_arty/gateware/digilen
## Software Build System ## Software Build System
The software build system uses files that are generated by the FPGA compile It is recommended to use the [docker files][docker].
process. The number one reason why software won't work when loaded onto the
FPGA is because it is compiled for a different FPGA bitstream. If you have
an issue where software that you know should work does not, run `make clean`
in the FPGA build system and rebuild it from scratch.
This requires at least CMake 3.20.0 (you can install this using `conda`). [docker]: https://software.mcgoron.com/peter/upsilon-docker
Afterwards just run `make` and everything should work. Everything is
managed by the `CMakeLists.txt` and the `prj.conf`, see the Zephyr OS
documentation.
The kernel is `/software/build/zephyr/zephyr.bin`
If you make a change to `CMakeLists.txt` or to `prj.conf`, run `make clean`
before `make`.
Make can run in parallel using `-j${NUMBER_OF_PROCESSORS}`. Add this to the
`buidl/zephyr/zephyr.bin` in `/software/Makefile` to makeyour builds faster.
Remove this argument when you are attemping to fix compile errors and warnings
(it will make the build output easier to read) but put it back when you fix
them.
# Loading the Software and Firmware # Loading the Software and Firmware