From e273324bf61e01d0ae7c9a57d974f576ed6bcc44 Mon Sep 17 00:00:00 2001 From: Peter McGoron Date: Mon, 12 Jun 2023 13:09:45 -0400 Subject: [PATCH] this has to be almost entirely rewritten --- doc/maintenance_manual.md | 79 +++++++++++++-------------------------- 1 file changed, 25 insertions(+), 54 deletions(-) diff --git a/doc/maintenance_manual.md b/doc/maintenance_manual.md index e09418a..4afb7e4 100644 --- a/doc/maintenance_manual.md +++ b/doc/maintenance_manual.md @@ -14,9 +14,9 @@ section you need without having to read the entire thing. ## 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 -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 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 before because it is running "freestanding." -The kernel uses Zephyr as the real-time operating system running the -code. Zephyr has very good documentation and a very readable code base, -go read it. +You do not need to know about Linux kernel development. You will need +to know the basics of ssh, vi, and how to use Unix as a user. Tests are written in C++ and verilog. You will not have to write C++ 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 (e.g. adding more software-accessable ports). -Python is used for the bytecode assembler, the bytecode itself, and -the SoC generator. The SoC generator uses a library called LiteX, -which in turn uses migen. -You do not need to know a lot about migen, but LiteX's documentation -is poor so you will need to know some migen in order to read the -code and understand how some modules work. +Python is used the SoC generator. The SoC generator uses a library called +LiteX, which in turn uses migen. You do not need to know a lot about migen, +but LiteX's documentation is poor so you will need to know some migen in order +to read the code and understand how some modules work. # Compile Process @@ -81,29 +78,6 @@ compile things on any computer with an internet connection. 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 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 [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 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 -The software build system uses files that are generated by the FPGA compile -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. +It is recommended to use the [docker files][docker]. -This requires at least CMake 3.20.0 (you can install this using `conda`). -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. +[docker]: https://software.mcgoron.com/peter/upsilon-docker # Loading the Software and Firmware