Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

feat: Make it easier to specify target architecture #869

Merged
merged 8 commits into from
Oct 31, 2024
Merged

feat: Make it easier to specify target architecture #869

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
7554d41
feat: Make it easier to specify target architecture
winksaville Oct 26, 2024
9155290
feat: Document the aliases in README.me
winksaville Oct 28, 2024
c61b023
fix: Adding reviewers suggestions
winksaville Oct 29, 2024
ab44340
fix: More clean up
winksaville Oct 29, 2024
416cdc7
fix: Apply review suggestions from theJPster
winksaville Oct 30, 2024
033e5aa
Update rp235x-hal-examples/README.md
thejpster Oct 30, 2024
7fc0d6a
Apply suggestions from code review
thejpster Oct 30, 2024
8ebc0ab
Update rp235x-hal-examples/README.md
thejpster Oct 30, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions rp235x-hal-examples/.cargo/config.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,21 @@
# writing programs for Raspberry Silicon microcontrollers.
#

# Add aliases for building and running for the ARM and RISC-V targets.
[alias]

# Build arm or riscv
build-arm = "build --target=thumbv8m.main-none-eabihf"
build-riscv = "build --target=riscv32imac-unknown-none-elf"

# Run arm or riscv
run-arm = "run --target=thumbv8m.main-none-eabihf"
run-riscv = "run --target=riscv32imac-unknown-none-elf"

# Add other custom aliases here, `rrr-blinky` which
# runs in release mode a riscv version of blinky.
rrr-blinky = "run-riscv --release --bin=blinky"

[build]
# Set the default target to match the Cortex-M33 in the RP2350
target = "thumbv8m.main-none-eabihf"
Expand Down
195 changes: 169 additions & 26 deletions rp235x-hal-examples/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,44 +56,128 @@ https://github.com/rp-rs/rp-hal-boards/ for more details.
<!-- GETTING STARTED -->
## Getting Started

To build all the examples, first grab a copy of the source code:
To build the examples, first grab a copy of the source code:

```console
$ git clone https://github.com/rp-rs/rp-hal.git
```

Then use `rustup` to grab the Rust Standard Library for the appropriate targets. There are two targets because the RP2350 has both an Arm mode and a RISC-V mode.
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 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
```

To build all the examples for Arm mode, run:
**Note: all examples assume the current directory is `<repo root>/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 --target=thumbv8m.main-none-eabihf
Compiling rp235x-hal-examples v0.1.0 (/home/user/rp-hal/rp235x-hal-examples)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 4.53s
$ cargo build --bin blinky
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.06s
Compiling proc-macro2 v1.0.89
Compiling unicode-ident v1.0.13
Compiling syn v1.0.109
...
Compiling pio-parser v0.2.2
Compiling rp235x-hal v0.2.0
Compiling pio-proc v0.2.2
Finished `dev` profile [unoptimized + debuginfo] target(s) in 14.97s
```

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
```

You can also 'run' an example, which thanks to our supplied
[`.cargo/config.toml`](./.cargo/config.toml) will invoke Raspberry Pi's
`picotool` to copy it to an RP235x in USB Bootloader mode. You should install
that if you don't have it already, from
<https://github.com/raspberrypi/pico-sdk-tools/releases>.
If you want to build a binary that runs in RISC-V mode, then you must specify the RISC-V target to override the default:

```console
winksaville marked this conversation as resolved.
Show resolved Hide resolved
$ cargo build --target=riscv32imac-unknown-none-elf --bin blinky
Compiling nb v1.1.0
Compiling byteorder v1.5.0
Compiling stable_deref_trait v1.2.0
..
Compiling futures v0.3.31
Compiling frunk v0.4.3
Compiling rp235x-hal v0.2.0
Finished `dev` profile [unoptimized + debuginfo] target(s) in 6.23s```
```

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 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. Note: be sure the RP235x is in BOOTSEL mode before using the `run` command because we use `picotool` to flash and run the binary:

```console
$ cargo run --bin blinky --target=thumbv8m.main-none-eabihf
Compiling rp235x-hal v0.10.0 (/home/user/rp-hal/rp235x-hal)
Compiling rp235x-hal-examples v0.1.0 (/home/user/rp-hal/rp235x-hal-examples)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 1.62s
Running `picotool load -u -v -x -t elf target/thumbv8m.main-none-eabihf/debug/blinky`
Family id 'rp2350-arm-s' can be downloaded in absolute space:
$ cargo run --target thumbv8m.main-none-eabihf --bin blinky
$ cargo run --target riscv32imac-unknown-none-elf --bin blinky
```

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 mode target all of the examples are built if no `--bin` is specified:

```console
$ cargo clean
Removed 1488 files, 398.6MiB total
$ cargo build --target thumbv8m.main-none-eabihf
Compiling proc-macro2 v1.0.89
Compiling unicode-ident v1.0.13
..
Compiling rp235x-hal v0.2.0
Compiling pio-proc v0.2.2
Finished `dev` profile [unoptimized + debuginfo] target(s) in 16.08s
$ find target/thumbv8m.main-none-eabihf/debug/ -maxdepth 1 -type f -executable | sort
target/thumbv8m.main-none-eabihf/debug/adc
target/thumbv8m.main-none-eabihf/debug/adc_fifo_dma
..
target/thumbv8m.main-none-eabihf/debug/blinky
..
target/thumbv8m.main-none-eabihf/debug/vector_table
target/thumbv8m.main-none-eabihf/debug/watchdog
```

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 using the default dev profile, emulating the development cycle **Note:** be sure
the RP235x is in BOOTSEL mode before using the `run` command because we use `picotool` to flash and run the binary:

```console
$ cargo build --bin blinky --target=riscv32imac-unknown-none-elf
Compiling rp235x-hal-examples v0.1.0
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.15s
$ cargo run --bin blinky --target=riscv32imac-unknown-none-elf
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.07s
Running `picotool load -u -v -x -t elf target/riscv32imac-unknown-none-elf/debug/blinky`
Family id 'rp2350-riscv' can be downloaded in absolute space:
00000000->02000000
Loading into Flash: [==============================] 100%
Verifying Flash: [==============================] 100%
Expand All @@ -102,18 +186,61 @@ Verifying Flash: [==============================] 100%
The device was rebooted to start the application.
```

It is currently possible to build *some* of the examples in RISC-V mode. See
[`riscv_examples.txt`](./riscv_examples.txt) for a list of the examples known to
work. The missing ones probably rely on interrupts, or some other thing we
haven't ported to work in RISC-V mode yet.
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 generated a RISC-V mode ELF file:

```console
$ cargo build --bin blinky --target=riscv32imac-unknown-none-elf
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.06s
$ 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
$ cargo run --bin blinky --target=riscv32imac-unknown-none-elf
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.06s
```

Next we'll build and run it using the release profile for "final" testing,
again be sure the RP235x is in BOOTSEL mode:

```console
$ cargo run --bin blinky --target=riscv32imac-unknown-none-elf --release
Compiling proc-macro2 v1.0.89
Compiling unicode-ident v1.0.13
..
Compiling pio-parser v0.2.2
Compiling pio-proc v0.2.2
Finished `release` profile [optimized] target(s) in 17.05s
Running `picotool load -u -v -x -t elf target/riscv32imac-unknown-none-elf/release/blinky`
Family id 'rp2350-riscv' can be downloaded in absolute space:
00000000->02000000
Loading into Flash: [==============================] 100%
Verifying Flash: [==============================] 100%
OK

The device was rebooted to start the application.
```

The LED should be blinking and looking at `blinky`
thejpster marked this conversation as resolved.
Show resolved Hide resolved
thejpster marked this conversation as resolved.
Show resolved Hide resolved

```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
```

The above commands work well, but the commands are somewhat verbose.
To make building and running commands more succinct an `[alias]` section
has been added to [.cargo/config.toml](../.cargo/config.toml) that define:
| Command Alias | Description |
|---|---|
| build-arm | build for ARM |
| build-riscv | build for RISC-V |
| run-arm | run on ARM |
| run-riscv | run on RISC-V |
| rrr-blinky | run release on RISC-V blinky |

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
$ cargo run-riscv --bin blinky
Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.05s
Running `picotool load -u -v -x -t elf target/riscv32imac-unknown-none-elf/debug/blinky`
Family id 'rp2350-riscv' can be downloaded in absolute space:
00000000->02000000
Expand All @@ -124,6 +251,22 @@ Verifying Flash: [==============================] 100%
The device was rebooted to start the application.
```

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
Running `picotool load -u -v -x -t elf target/riscv32imac-unknown-none-elf/release/blinky`
Family id 'rp2350-riscv' can be downloaded in absolute space:
00000000->02000000
Loading into Flash: [==============================] 100%
Verifying Flash: [==============================] 100%
OK

The device was rebooted to start the application.
```

<!-- ROADMAP -->
## Roadmap

Expand Down