Skip to content

Commit

Permalink
feat: Document the aliases in README.me
Browse files Browse the repository at this point in the history 
Also, tweak the aliases and add dev and release modes with shorter names.
  • Loading branch information
@winksaville
winksaville committed Oct 28, 2024
1 parent 7554d41 commit 9155290
Show file tree
Hide file tree
Showing 2 changed files with 158 additions and 26 deletions.
24 changes: 22 additions & 2 deletions rp235x-hal-examples/.cargo/config.toml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,31 @@

# Add aliases for building and running for the ARM and RISC-V targets.
[alias]
build-arm = "build --target=thumbv8m.main-none-eabihf"

# Build arm or riscv using defaults or other options
bld-arm = "build --target=thumbv8m.main-none-eabihf"
bld-riscv = "build --target=riscv32imac-unknown-none-elf"

# Run arm or riscv using defaults or other options
run-arm = "run --target=thumbv8m.main-none-eabihf"
build-riscv = "build --target=riscv32imac-unknown-none-elf"
run-riscv = "run --target=riscv32imac-unknown-none-elf"

# Build dev and release for arm
bda = "bld-arm"
bra = "bld-arm --release"

# Build dev and release for risc-v
bdr = "bld-riscv"
brr = "bld-riscv --release"

# Run dev and release for arm
rda = "run-arm"
rra = "run-arm --release"

# Run dev and release for risc-v
rdr = "run-riscv"
rrr = "run-riscv --release"

[build]
# Set the default target to match the Cortex-M33 in the RP2350
target = "thumbv8m.main-none-eabihf"
Expand Down
160 changes: 136 additions & 24 deletions rp235x-hal-examples/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -56,43 +56,156 @@ 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. the RP2350
has two possible targets, thumbv8m.main-none-eabihf for the ARM cpu. And riscv32imac-unknown-none-elf
for the RISC-V cpu.

```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 (/home/wink/prgs/rpi-pico/myrepos/rp-hal-clone/rp235x-hal)
Compiling pio-proc v0.2.2
Finished `dev` profile [unoptimized + debuginfo] target(s) in 14.97s
```

This builds the default target, which is the for the ARM 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 the RISC-V you can specify the target directly to override the default:
```console
$ 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 (/home/wink/prgs/rpi-pico/myrepos/rp-hal-clone/rp235x-hal)
Finished `dev` profile [unoptimized + debuginfo] target(s) in 6.23s```
```

And we see the RISC-V 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 just pass
`--target thumbv8m.main-none-eabihf` instead of `--target riscv32imac-unknown-none-elf`.

You can also easily build, flash and start the application on the RP235x
by using the `cargo run` using command:
```console
$ cargo run --target thumbv8m.main-none-eabihf --bin blinky
$ cargo run --target riscv32imac-unknown-none-elf --bin blinky
```

You can also specify a release build by passing `--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
```

The above work well but the commands are somewhat verbose. To make building and running
more succinct we have added some aliases in .carog/config.toml:

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

# Build arm or riscv using defaults or other options
bld-arm = "build --target=thumbv8m.main-none-eabihf"
bld-riscv = "build --target=riscv32imac-unknown-none-elf"

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

# Build dev and release profiles for arm
bda = "bld-arm"
bra = "bld-arm --release"

# Build dev and release for profiles risc-v
bdr = "bld-riscv"
brr = "bld-riscv --release"

# Run dev and release for profiles arm
rda = "run-arm"
rra = "run-arm --release"

# Run dev and release for profiles risc-v
rdr = "run-riscv"
rrr = "run-riscv --release"
```

Using the aliases the commands are much shorter the first is for
running on ARM in rlease mode and the second is for running on RISC-V in release mode:
```console
$ cargo rra --bin blinky
$ cargo rrr --bin blinky
```

These are exactly the same as:
```console
$ cargo run --target thumbv8m.main-none-eabihf --release --bin blinky
$ cargo run --target riscv32imac-unknown-none-elf --release --bin blinky
```

Here is the output of running in release mode the `blinky` example on ARM
after cleaning the build **Note:** have the pico 2 in BOOTSEL mode:
```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`
$ cargo clean
Removed 3565 files, 1.4GiB total
$ cargo rra --bin blinky
Compiling proc-macro2 v1.0.89
Compiling unicode-ident v1.0.13
..
Compiling rp235x-hal v0.2.0 (/home/wink/prgs/rpi-pico/myrepos/rp-hal/rp235x-hal)
Compiling pio-proc v0.2.2
Finished `release` profile [optimized] target(s) in 11.72s
Running `picotool load -u -v -x -t elf target/thumbv8m.main-none-eabihf/release/blinky`
Family id 'rp2350-arm-s' can be downloaded in absolute space:
00000000->02000000
Loading into Flash: [==============================] 100%
Verifying Flash: [==============================] 100%
OK

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

And you can build first and then run, in this case the `blinky` example was already built:
```console
$ cargo bra --bin blinky
Finished `release` profile [optimized] target(s) in 0.05s
$ cargo rra --bin blinky
Finished `release` profile [optimized] target(s) in 0.05s
Running `picotool load -u -v -x -t elf target/thumbv8m.main-none-eabihf/release/blinky`
Family id 'rp2350-arm-s' can be downloaded in absolute space:
00000000->02000000
Loading into Flash: [==============================] 100%
Expand All @@ -107,14 +220,13 @@ It is currently possible to build *some* of the examples in RISC-V mode. See
work. 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:
```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
Running `picotool load -u -v -x -t elf target/riscv32imac-unknown-none-elf/debug/blinky`
$ cargo brr --bin blinky
Finished `release` profile [optimized] target(s) in 0.06s
$ cargo rrr --bin blinky
Finished `release` profile [optimized] target(s) in 0.06s
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%
Expand Down

0 comments on commit 9155290

Please sign in to comment.