From a8748bb4246484eb33b4e6ff287e287584f92a4f Mon Sep 17 00:00:00 2001 From: Aadi Desai <21363892+supleed2@users.noreply.github.com> Date: Mon, 5 Jun 2023 13:53:29 +0100 Subject: [PATCH] Update demo C++ readme with instructions --- demo/README.md | 139 +++++++++++++++++++++++-------------------------- 1 file changed, 64 insertions(+), 75 deletions(-) diff --git a/demo/README.md b/demo/README.md index fe7310f..f3080bd 100644 --- a/demo/README.md +++ b/demo/README.md @@ -1,104 +1,93 @@ # Bare Metal Demo App -This directory provides a minimal bare metal demo app that demonstrates how to easily create a bare metal C application and load it/run it on the CPU of a SoC. +This directory provides a basic bare metal demo app that demonstrates how to communicate / drive the custom logic in this project. ## Build and Load over LiteX-Term -To build a LiteX SoC for the Arty board (available in LiteX-Boards) and build the demo app for it, execute the following commands: +The project is built with: ``BUILD_DIR=`realpath -eL build/gsd_orangecrab/` WITH_CXX=1 make -C demo`` + +The project board does not provide extra interfaces to connect to the board, so serial is used here: `$ litex_term --kernel demo/demo.bin /dev/ttyACMX` (ACM due to the use of `usb_acm` UART) + +You should see the demo app running and should be able to interact with it: ```bash -python3 -m litex_boards.targets.digilent_arty --build --load -litex_bare_metal_demo --build-path=build/digilent_arty -``` +$ litex_term --kernel demo/demo.bin /dev/ttyACM0 + __ _ __ _ __ + / / (_) /____ | |/_/ + / /__/ / __/ -_)> < + /____/_/\__/\__/_/|_| + Build your hardware, easily! -Where `--build-path` is the build path to the Arty build directory. The Arty board is used here but almost any another board supported in LiteX-Boards could be used. When no external RAM is provided directly by the board, `--integrated-main-ram-size` argument could be used to add some integrated RAM in the SoC and be able to execute the demo from it. (ex `--integrated-main-ram-size=0x8000` will add 32KB of integrated RAM). + (c) Copyright 2012-2022 Enjoy-Digital + (c) Copyright 2007-2015 M-Labs -Loading the compiled demo app can be done in different ways as explain in LiteX's [wiki](https://github.com/enjoy-digital/litex/wiki/Load-Application-Code-To-CPU) + BIOS built on Jun 5 2023 13:37:57 + BIOS CRC passed (f2f2af2d) -Since our app is small and for simplicity we'll just load it over serial here: `$ litex_term /dev/ttyUSBX --kernel=demo.bin` + LiteX git sha1: 310bc777 -You should see the minimal demo app running and should be able to interact with it: +--=============== SoC ==================-- +CPU: VexRiscv @ 48MHz +BUS: WISHBONE 32-bit @ 4GiB +CSR: 32-bit data +ROM: 128KiB +SRAM: 8KiB +L2: 8KiB +SDRAM: 131072KiB 16-bit @ 192MT/s (CL-6 CWL-5) + +--========== Initialization ============-- +Initializing SDRAM @0x40000000... +Switching SDRAM to software control. +Read leveling: + m0, b00: |01110000| delays: 02+-01 + m0, b01: |00000000| delays: - + m0, b02: |00000000| delays: - + m0, b03: |00000000| delays: - + best: m0, b00 delays: 02+-01 + m1, b00: |01110000| delays: 02+-01 + m1, b01: |00000000| delays: - + m1, b02: |00000000| delays: - + m1, b03: |00000000| delays: - + best: m1, b00 delays: 02+-01 +Switching SDRAM to hardware control. +Memtest at 0x40000000 (2.0MiB)... + Write: 0x40000000-0x40200000 2.0MiB + Read: 0x40000000-0x40200000 2.0MiB +Memtest OK +Memspeed at 0x40000000 (Sequential, 2.0MiB)... + Write speed: 11.7MiB/s + Read speed: 17.5MiB/s -```shell --============== Boot ==================-- Booting from serial... Press Q or ESC to abort boot completely. sL5DdSMmkekro [LITEX-TERM] Received firmware download request from the device. -[LITEX-TERM] Uploading demo.bin to 0x40000000 (9264 bytes)... -[LITEX-TERM] Upload complete (9.8KB/s). +[LITEX-TERM] Uploading kernel.bin to 0x40000000 (11248 bytes)... +[LITEX-TERM] Upload calibration... (inter-frame: 10.00us, length: 64) +[LITEX-TERM] Upload complete (54.1KB/s). [LITEX-TERM] Booting the device. [LITEX-TERM] Done. Executing booted program at 0x40000000 --============= Liftoff! ===============-- -LiteX minimal demo app built Dec 10 2020 17:13:02 +LiteX custom demo app built Jun 5 2023 13:40:19 Available commands: help - Show this command reboot - Reboot CPU -led - Led demo donut - Spinning Donut demo -litex-demo-app> led -Led demo... -Counter mode... -Shift mode... -Dance mode... -litex-demo-app> donut -Donut demo... - - $$$$$@@@@@ - $##########$$$$$$$$ - ###*!!!!!!!!!***##$$$$$$ - ***!!====;;;;===!!**###$$$$# - **!===;;;:::::;:===!!**####$## - !*!!==;;:~-,,.,-~::;;=!!**#######! - !!!!=;:~-,.......-~::==!!***#####* - !!!!==;~~-.........,-:;==!!***###**! - !**!!=;:~-... ..-:;=!!!********! - ;!*#####*!!;. ~:;==!!!******!!= - :!*###$$$$#*! :;==!!!!!****!!!=; - ~=!*#$$$@@@$$##!!!!!!!!!!!!****!!!!=; - ;=!*#$$$@@@@$$#*******!*!!*!!!!!==;~ - -;!*###$$$$$$$###******!!!!!!!===;~ - -;!!*####$#####******!!!!!!==;;:- - ,:=!!!!**#**#***!!!!!!!====;:~, - -:==!!!*!!*!!!!!!!===;;;:~- - .~:;;========;=;;:::~-, - .--~~::::~:~~--,. -litex-demo-app> +saw - Sawtooth Wave demo +square - Square Wave demo +triangle - Triangle Wave demo +sine - Sine Wave demo +imperial - Imperial March demo +roll - Music demo +can_id - Get / Set CAN ID +can_mask - Get / Set CAN Mask +can_read - Receive CAN Frames and print (delay in s) +can_watch - Watch CAN Frames at 2Hz +can_listen - Play CAN Frames as Audio +StackSynth> ``` - -## Replace the LiteX BIOS with the Demo App - -In some cases, we'll just want to replace the LiteX BIOS with our custom app. This demo can be used as a basis to create a such custom app. - -The demo will be recompiled to target the ROM of the SoC: - -```bash -litex_bare_metal_demo --build-path=build/arty/ --mem=rom -``` - -The SoC can then be re-compiled to integrate the demo app in the ROM with: - -```bash -python3 -m litex_boards.targets.digilent_arty --integrated-rom-init=demo.bin --build --load -``` - -When loading the bitstream, you should then directly see the demo app executed: - -```shell -LiteX minimal demo app built Dec 10 2020 17:13:02 - -Available commands: -help - Show this command -reboot - Reboot CPU -led - Led demo -donut - Spinning Donut demo -litex-demo-app> -``` - -## Going further - -To create more complex apps, feel free to explore the source code of the BIOS or other open source projects build with LiteX on the [GitHub wiki](https://github.com/enjoy-digital/litex/wiki/Projects).