diff --git a/rp235x-hal-examples/README.md b/rp235x-hal-examples/README.md index 687ffc406..9fc8bbb50 100644 --- a/rp235x-hal-examples/README.md +++ b/rp235x-hal-examples/README.md @@ -63,20 +63,22 @@ $ git clone https://github.com/rp-rs/rp-hal.git ``` Then use `rustup` to grab the Rust Standard Library for the appropriate targets. -RP2350 has two possible targets: thumbv8m.main-none-eabihf for the ARM cpu, and -riscv32imac-unknown-none-elf for the RISC-V cpu. +RP2350 has two possible targets: `thumbv8m.main-none-eabihf` for the Arm mode, and +`riscv32imac-unknown-none-elf` for the RISC-V mode. + ```console $ rustup target add thumbv8m.main-none-eabihf $ rustup target add riscv32imac-unknown-none-elf ``` -**Note: all examples assume the current directory is /rp235x-hal-examples.** +**Note: all examples assume the current directory is `/rp235x-hal-examples`.** ``` cd rp235x-hal-examples ``` The most basic method is to use `cargo build` with the `--bin` flag to specify the example you want to build. For example, to build the `blinky` example: + ```console $ cargo build --bin blinky Compiling proc-macro2 v1.0.89 @@ -89,14 +91,16 @@ $ cargo build --bin blinky Finished `dev` profile [unoptimized + debuginfo] target(s) in 14.97s ``` -This builds the default target, which is the for the ARM and the elf file +This builds the default target, which is Arm mode and the ELF file is located at `./target/thumbv8m.main-none-eabihf/debug/blinky`: + ```console $ file ./target/thumbv8m.main-none-eabihf/debug/blinky ./target/thumbv8m.main-none-eabihf/debug/blinky: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), statically linked, with debug_info, not stripped ``` -If you want to build the RISC-V you specify the target directly to override the default: +If you want to build the RISC-V mode you specify the target directly to override the default: + ```console $ cargo build --target=riscv32imac-unknown-none-elf --bin blinky Compiling nb v1.1.0 @@ -109,30 +113,34 @@ $ cargo build --target=riscv32imac-unknown-none-elf --bin blinky Finished `dev` profile [unoptimized + debuginfo] target(s) in 6.23s``` ``` -And we see that the RISC-V elf file is now present at `./target/riscv32imac-unknown-none-elf/debug/blinky`: +And we see that the RISC-V mode ELF file is now present at `./target/riscv32imac-unknown-none-elf/debug/blinky`: + ```console $ file ./target/riscv32imac-unknown-none-elf/debug/blinky ./target/riscv32imac-unknown-none-elf/debug/blinky: ELF 32-bit LSB executable, UCB RISC-V, RVC, soft-float ABI, version 1 (SYSV), statically linked, with debug_info, not stripped ``` -You can also specify the ARM target directly by using +You can also specify the Arm mode target directly by using `--target thumbv8m.main-none-eabihf` instead of `--target riscv32imac-unknown-none-elf`. To build, flash and start the application on the RP235x you use `cargo run` with one of the following commands: + ```console $ cargo run --target thumbv8m.main-none-eabihf --bin blinky $ cargo run --target riscv32imac-unknown-none-elf --bin blinky ``` -For a release build pass `--release` to the `cargo build` +For the release profile build pass `--release` to the `cargo build` or `cargo run` commands. This will build the example with optimizations enabled: + ```console $ cargo run --target thumbv8m.main-none-eabihf --release --bin blinky $ cargo run --target riscv32imac-unknown-none-elf --release --bin blinky ``` -For the ARM target all of the examples are built if no `--bin` is specified: +For the Arm mode target all of the examples are built if no `--bin` is specified: + ```console $ cargo clean Removed 1488 files, 398.6MiB total @@ -153,14 +161,15 @@ target/thumbv8m.main-none-eabihf/debug/vector_table target/thumbv8m.main-none-eabihf/debug/watchdog ``` -For the RISC-V it is currently possible to build only *some* of the examples. See +For the RISC-V mode it is currently possible to build only *some* of the examples. See [`riscv_examples.txt`](./riscv_examples.txt) for a list of known working examples. The missing ones probably rely on interrupts, or some other thing we haven't ported to work in RISC-V mode yet. Here is an example using the `blinky` example in RISC-V mode. We'll build and -run it first in non-release emulating the developement cycle **Note:** be sure +run it first using the default dev profile, emulating the development cycle **Note:** be sure the pico 2 is in BOOTSEL mode before the `run` command: + ```console $ cargo build --bin blinky --target=riscv32imac-unknown-none-elf Compiling rp235x-hal-examples v0.1.0 @@ -178,19 +187,16 @@ The device was rebooted to start the application. ``` At this point the development version is running on the RP2350 and the LED is blinking. -When we look at `blinky` using `file` we see we have an RISC-V ELF file and using `ls` -we see it is quite large, 2.4M: +When we look at `blinky` using `file` we see we have generated a RISC-V mode ELF file: + ```console $ file ./target/riscv32imac-unknown-none-elf/debug/blinky ./target/riscv32imac-unknown-none-elf/debug/blinky: ELF 32-bit LSB executable, UCB RISC-V, RVC, soft-float ABI, version 1 (SYSV), statically linked, with debug_info, not stripped -$ ls -l ./target/riscv32imac-unknown-none-elf/debug/blinky --rwxr-xr-x 2 wink users 2432556 Oct 29 12:59 ./target/riscv32imac-unknown-none-elf/debug/blinky -$ ls -lh ./target/riscv32imac-unknown-none-elf/debug/blinky --rwxr-xr-x 2 wink users 2.4M Oct 29 12:59 ./target/riscv32imac-unknown-none-elf/debug/blinky ``` -Next we'll build and run it in release mode for "final" testing, +Next we'll build and run it using the release profile for "final" testing, again be sure the pico 2 is in BOOTSEL mode: + ```console $ cargo run --bin blinky --target=riscv32imac-unknown-none-elf --release Compiling proc-macro2 v1.0.89 @@ -209,13 +215,11 @@ Verifying Flash: [==============================] 100% The device was rebooted to start the application. ``` -The LED should be blinking and looking at `blinky` we see -it is now much smaller at 87K: +The LED should be blinking and looking at `blinky` + ```console $ file ./target/riscv32imac-unknown-none-elf/release/blinky ./target/riscv32imac-unknown-none-elf/release/blinky: ELF 32-bit LSB executable, UCB RISC-V, RVC, soft-float ABI, version 1 (SYSV), statically linked, not stripped -$ ls -lh ./target/riscv32imac-unknown-none-elf/release/blinky --rwxr-xr-x 2 wink users 87K Oct 29 12:55 ./target/riscv32imac-unknown-none-elf/release/blinky ``` The above commands work well, but the commands are somewhat verbose. @@ -231,6 +235,7 @@ has been added to [.cargo/config.toml](../.cargo/config.toml) that define: When using these aliases your build and run commands are much shorter. Below we see the development cycle using `build-riscv` and `run-riscv`: + ```console $ cargo build-riscv --bin blinky Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.05s @@ -246,8 +251,9 @@ Verifying Flash: [==============================] 100% The device was rebooted to start the application. ``` -And for the `run` command in `--release` mode for the RISC-V we added the `rrr-blinky` alias +And for the `run` command in `--release` profile and a RISC-V mode we added the `rrr-blinky` alias as an example of customization. You might want to add others as you see fit: + ```console $ cargo rrr-blinky Finished `release` profile [optimized] target(s) in 0.05s