projekte
/
Neopixelar
28
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Documentation included now

Browse Source
master
kaqu 2 years ago
parent 4015caedc8
commit d4948f201e
4 changed files with 69 additions and 39 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 79
      README.md
  2. 11
      firmware/README.md
  3. 10
      helpers/README.md
  4. 8
      software/README.md

79
README.md
Unescape View File

@ -1,38 +1,45 @@
## Neopixelar - the FPGA project ##
# Neopixelar - the FPGA project #
This project demonstrates the use of LiteX & migen to create a Neopixel driving FPGA based h/w unit,
called NPE ('neopixel engine'). The project requires a colorlight-5a-75b board (sells at ~18€ currently). A RISC-V CPU (RV32I) is incorporated as well as network RAM loading (2 banks!) & separate application flashing capability (MUCH faster, bringing flashboot
called NPE ('neopixel engine'). The project requires a colorlight-5a-75b board (sells at ~18€ as of 10/2020). A RISC-V CPU (RV32I) is incorporated as well as network RAM loading (2 banks!) & separate application flashing capability (MUCH faster, bringing flashboot
to life!).
To use this project effectively, you will have to install LiteX, see https://github.com/enjoy-digital/litex for details.
Also, it is recommended to install the board support, see https://github.com/litex-hub/litex-boards.
To communicate with your board via network, install the wishbone tools, see https://github.com/litex-hub/wishbone-utils.
For board specific details see https://github.com/enjoy-digital/colorlite/blob/master.
(Hint: project has been tested on Linux Mint 20 only, but should run on other Linux versions as well ...)
Also, a JTAG programmer will be required for successful device programming. Thanx to Wolfgang, I'm using the Versaloon (s/w for blue-pill STM32), see https://github.com/zoobab/versaloon. To use this device, you also will have to install openocd:
## Installation ##
apt install openocd
### 1. Software ###
Other helpful links to board data:
https://github.com/q3k/chubby75/blob/master/5a-75b/hardware_V7.0.md
https://saturn.ffzg.hr/rot13/index.cgi?colorlight_5a_75b
https://github.com/trabucayre/litexOnColorlightLab004/
https://blog.pcbxprt.com/index.php/2020/07/19/running-risc-v-core-on-small-fpga-board/
To use this project effectively, you will have to install LiteX, see https://github.com/enjoy-digital/litex for details. Project Trellis, NextPNR & YoSys shall also be installed.
Also, it is recommended to install the board support, see https://github.com/litex-hub/litex-boards.
To communicate with your board via network, install the wishbone tools, see https://github.com/litex-hub/wishbone-utils.
To use the automatic documentation feature, you will have to install sphinx, see https://www.sphinx-doc.org/en/master.
To use the automatic documentation feature, you will have to install sphinx, see https://www.sphinx-doc.org/en/master. Also its wavedrom extension has to be installed, see https://pypi.org/project/wavedrom.
Some helpful links for RST docstring formats:
http://daouzli.com/blog/docstring.html
http://daouzli.com/blog/docstring.html &
https://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html
### 2. Hardware ###
A JTAG programmer will be required for successful device programming. Thanx to Wolfgang, I'm using the Versaloon (s/w for blue-pill STM32), see https://github.com/zoobab/versaloon. To use this device, you also will have to install openocd via 'apt install openocd'. See https://git.hacknology.de/wolfgang/colorlight#user-content-class-hub75sender for details, on how to connect the JTAG adapter.
For board specific details see
https://github.com/enjoy-digital/colorlite/blob/master.
Other helpful links to board data:
https://github.com/q3k/chubby75/blob/master/5a-75b/hardware_V7.0.md
https://saturn.ffzg.hr/rot13/index.cgi?colorlight_5a_75b
https://github.com/trabucayre/litexOnColorlightLab004/
https://blog.pcbxprt.com/index.php/2020/07/19/running-risc-v-core-on-small-fpga-board/
## Program structure: ##
*Neopixelar.py - this is the main FPGA building source
*neopixelengine.py - this is the actual NeoPixel driving engine
*helpers dir - contains python helpers for load & flash etc.
*firmware dir - contains some modified BIOS files (relative to the original version)
*software dir - contains a separate build, load & flash logic for separate (RV32i) application code
the rest is of minor importance ...
1. Neopixelar.py - this is the main FPGA building source
2. neopixelengine.py - this is the actual NeoPixel driving engine
3. helpers subdir - contains python helpers for load & flash etc.
4. firmware subdir - contains some modified BIOS files (relative to the original version)
5. software subdir - contains a separate build, load & flash logic for separate (RV32i) application code
(the rest is of minor importance ...)
## QUICKSTART ##
## Quickstart ##
After installation of the relevant toolchains:
1. Open the project in VSC (or use your favourite IDE & maybe adjust some settings ;), adjust local paths if nec. ...
@ -48,27 +55,31 @@ After installation of the relevant toolchains:
8. This time it will take even longer ...
9. And hopefully complete without errors. If successful, the basic ROM s/w is now in place & operating. In case of errors try again - rule out EMI disturbances if nec.
10. Create the actual documentation for html via: 'sphinx-build -b html build/documentation build/documentation/html'
11. Use your favourite browser to access the 'npe' units documentation via 'file://<projectpath>/build/documentation build/documentation/html/index.html'
11. Use your favourite browser to access the 'npe' units documentation via 'file://your_projectpath/build/documentation build/documentation/html/index.html'
## Individual (separate) applications ##
1. This time, open up a terminal & cd to the project local software subdirectory
2. You can load an application to RAM bank 1:
1. This time, open up a terminal & cd to the project local 'software' subdirectory
2. You can load an application to RAM bank 1:
./ramcreate.sh main illumination 1
3. To run the (now) RAM based application, type 'cd ..' within terminal
4. Connect the Litex-Terminal to the board via: wishbone-tool --ethernet-host 192.168.1.20 --server terminal --csr-csv build/csr.csv
4. Connect the Litex-Terminal to the board via:
wishbone-tool --ethernet-host 192.168.1.20 --server terminal --csr-csv build/csr.csv
5. Type 'ramboot' into terminal, the RAM based application should come up now
6. Press 's' (Speedup) to speed up the lights, 'w' (sloWdown) to slow them down
7. Press 'x' (eXit) to abort the application, you should see the LiteX prompt now
6. You can load an application to RAM bank 2:
8. You can load an application to RAM bank 2:
./ramcreate.sh main illumination 2
7. Now, use 'ramboot' again! The system should swap to RAM bank #2 and boot the application right away
8. This is the testing loop, once your happy w/ your application, it needs to be flashed
9. !CAREFULL NOW! The application shouldn't contain any errors as it will be booted right after the BIOS
9. Now, use 'ramboot' again! The system should swap to RAM bank #2 and boot the application right away
10. This is the testing loop, once your happy w/ your application, it needs to be flashed
11. !CAREFULL NOW! The application shouldn't contain any errors as it will be booted right after the BIOS
automatically
10. Make sure, your JTAG adapter is in place!
11. Run: ./ramcreate.sh main illumination 1
and then: ./flashcreate.sh main illumination
12. This flashes the application permanently to the boot address, where it will be verified by the BIOS
12. Make sure, your JTAG adapter is in place!
13. Run:
./ramcreate.sh main illumination 1
and then:
./flashcreate.sh main illumination
14. This flashes the application permanently to the boot address, where it will be verified by the BIOS
and started automatically (the good news: the 64kBytes of the sample application only take some 18 s ...)
15. You probably want to modify the application now ...
Have fun!

11
firmware/README.md
Unescape View File

@ -1,8 +1,9 @@
# FIRMWARE #
This directory contains the modified versions of several BIOS related files.
The modifications are:
boot.c - doRAMBoot introduced
cmd_mem.c - dumpregs & ramboot introduced (mx, mhsig no longer used)
console.c - set_console, kbhit introduced, putchar modified
main.c - BIOS starter, modified for non-blocking operation
1. boot.c - doRAMBoot introduced (permitting RAM boot - automatically selecting the currently inactive RAM bank)
2. cmd_mem.c - additional commands dumpregs & ramboot introduced (mx, mhsig no longer used)
3. console.c - non-blocking feature implemented (set_console, kbhit introduced, putchar modified)
4. main.c - BIOS starter, modified for non-blocking operation

10
helpers/README.md
Unescape View File

@ -0,0 +1,10 @@
# HELPERS #
This directory contains helper & test routines.
1. bit_to_flash.py - Used by main build for the conversion of bitstream to flash file format
2. imageflasher.py - Used to flash the application image separately to flash boot address
3. load_to_flash.py - Used by main build to flash the FPGA data (includes 'ROM' software BIOS)
also may be called directly, then (currently) uses eraser.svf to clear all flash data (reset!)
4. prepare_firmware.py - Used by main build to integrate modified BIOS routines into main LiteX build
5. remotetest.py - Test drive the LED driver remotely via wishbone bus (i.e. network)

8
software/README.md
Unescape View File

@ -1,2 +1,10 @@
# SOFTWARE #
This directory contains the actual application & the loading/flashing tools.
1. ramcreate.sh - Create & load a startable binary to either RAM bank 1 or 2 (will be lost on power cycles ...)
usage: ./ramcreate.sh <<main_app_w/o_extension>> <<additional_lib_w/o_extension>> <<ram_bank_no>>
example: ./ramcreate.sh main illumination 1
2. flashcreate.sh - Create & flash an application image (for permanent action across power losses)
usage: ./flashcreate.sh

Write Preview
Loading…
Cancel
Save