Merge #161 161: Cleanup and add a Makefile r=alistair23 a=alistair23 After looking at https://github.com/tock/libtock-rs/issues/160 I think there are some things we can do to make it easier to get started with `libtock-rs`. One of the key things for me with all new projects is how hard is it to build and run this thing. I find the current bundle of scripts confusing and non obvious what I should do/run. This PR moves the linker files out of the main directory (so they don't clutter everything up) and then adds a Tock style Makefile which can be used to build the examples for the boards. This PR also removes some unused files to again reduce clutter. If this is merged the next step is to move the `flash.sh` actions into the Makefile and look at supporting building a single app (instead of all of the examples) and how to handle features. Co-authored-by: Alistair Francis <alistair.francis@wdc.com>
diff --git a/.cargo/config b/.cargo/config index c34fe36..96fe275 100644 --- a/.cargo/config +++ b/.cargo/config
@@ -16,4 +16,4 @@ "-C", "relocation-model=static", "-C", "link-arg=-Tlayout.ld", ] -runner = "./flash.sh" +runner = "./tools/flash.sh"
diff --git a/.gitignore b/.gitignore index 46f3217..e8cecc0 100644 --- a/.gitignore +++ b/.gitignore
@@ -1,5 +1,3 @@ Cargo.lock layout.ld -platform target -.history
diff --git a/.travis.yml b/.travis.yml index 9a91eaa..7b6bf87 100644 --- a/.travis.yml +++ b/.travis.yml
@@ -1,9 +1,8 @@ +# Disable bors on the bors temp branch branches: - only: - # This is where pull requests from "bors r+" are built. - - staging - # This is where pull requests from "bors try" are built. - - trying + except: + - staging.tmp + - trying.tmp language: rust rust: @@ -30,11 +29,7 @@ - popd install: - - rustup target add thumbv7em-none-eabi - - rustup target add riscv32imc-unknown-none-elf - - rustup component add rustfmt - - rustup component add clippy - - cargo install elf2tab --version 0.4.0 + - make setup # Build Tock, it needs to be outside of the libtock-rs source - pushd ../ - git clone https://github.com/tock/tock.git @@ -45,8 +40,8 @@ - popd script: - - ./run_all_checks.sh + - make test # Run a QEMU instance of the HiFive1 app - - PLATFORM=riscv32 cargo rrv32imac --example hello_world - - timeout --foreground 10s qemu-system-riscv32 -M sifive_e -kernel ../tock/boards/hifive1/target/riscv32imac-unknown-none-elf/release/hifive1 -device loader,file=./target/riscv32imac-unknown-none-elf/tab/riscv32/hello_world/rv32imac.tbf,addr=0x20430000 -nographic | tee serial + - make flash-hifive1 EXAMPLE=hello_world + - timeout --foreground 10s qemu-system-riscv32 -M sifive_e -kernel ../tock/boards/hifive1/target/riscv32imac-unknown-none-elf/release/hifive1 -device loader,file=./target/riscv32imac-unknown-none-elf/tab/hifive1/hello_world/rv32imac.tbf,addr=0x20430000 -nographic | tee serial - grep "Hello Tock World" serial
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1caeca5..a992373 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md
@@ -21,12 +21,12 @@ - `riscv32imc-unknown-none-elf` - `thumbv7em-none-eabi` -You can trigger a test build of the library and the examples using the script `build_examples.sh`. +You can trigger a test build of the library and the examples using `make test`. ## Unit Testing and Linting There a a number of tests which run in our travis-ci environment. You can run them -using `cargo test --workspace`. +using `make test`. ## Integration tests @@ -35,7 +35,7 @@ - connect your device to your computer - open a console, e.g. `tockloader listen` -- run the tests: `PLATFORM=nrf52 cargo rtv7em libtock_test --features=alloc` +- run the tests: `make flash-nrf52 EXAMPLE=libtock_test FEATURES=alloc` The expected output on the UART console will be as follows.
diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..d912813 --- /dev/null +++ b/Makefile
@@ -0,0 +1,97 @@ +# By default, let's print out some help +.PHONY: usage +usage: + @echo "$$(tput bold)Welcome to libtock-rs!$$(tput sgr0)" + @echo + @echo "First things first, if you haven't yet, check out Tocks's doc/Getting_Started." + @echo "After that read the README from libtock-rs" + @echo "You'll need to install a few requirements before we get going." + @echo + @echo "The next step is to choose a board to build Tock for. Mainline" + @echo "libtock-rs currently includes support for the following platforms:" + @echo " - hail" + @echo " - nrf52840" + @echo " - opentitan" + @echo " - hifive1" + @echo " - nrf52" + @echo + @echo "Run 'make setup' to setup Rust to build libtock-rs." + @echo "Run 'make <board>' to build libtock-rs for that board" + @echo " Set the DEBUG flag to enable the debug build" + @echo " Set the FEATURES flag to enable features" + @echo "Run 'make flash-<board> EXAMPLE=<>' to flash EXAMPLE to that board" + @echo "Run 'make test' to test any local changes you have made" + +ifdef FEATURES + features=--features=$(FEATURES) +endif + +ifndef DEBUG + release=--release +endif + +.PHONY: setup +setup: + rustup target add thumbv7em-none-eabi + rustup target add riscv32imc-unknown-none-elf + rustup component add rustfmt + rustup component add clippy + cargo install elf2tab --version 0.4.0 + +.PHONY: examples +examples: + PLATFORM=nrf52 cargo build --release --target=thumbv7em-none-eabi --examples + PLATFORM=nrf52 cargo build --release --target=thumbv7em-none-eabi --examples --features=alloc + PLATFORM=opentitan cargo build --release --target=riscv32imc-unknown-none-elf --examples + +.PHONY: test +test: + PLATFORM=nrf52 cargo fmt --all -- --check + PLATFORM=nrf52 cargo clippy --workspace --all-targets + PLATFORM=nrf52 cargo test --workspace + make examples + +.PHONY: hail +hail: + PLATFORM=hail cargo build $(release) --target=thumbv7em-none-eabi --examples $(features) + +.PHONY: flash-hail +flash-hail: + PLATFORM=hail cargo run $(release) --target=thumbv7em-none-eabi --example $(EXAMPLE) $(features) + +.PHONY: nrf52840 +nrf52840: + PLATFORM=nrf52840 cargo build $(release) --target=thumbv7em-none-eabi --examples $(features) + +.PHONY: flash-nrf52840 +flash-nrf52840: + PLATFORM=nrf52840 cargo run $(release) --target=thumbv7em-none-eabi --example $(EXAMPLE) $(features) + +.PHONY: opentitan +opentitan: + PLATFORM=opentitan cargo build $(release) --target=riscv32imc-unknown-none-elf --examples $(features) + +.PHONY: flash-opentitan +flash-opentitan: + PLATFORM=opentitan cargo run $(release) --target=riscv32imac-unknown-none-elf --example $(EXAMPLE) $(features) + +.PHONY: hifive1 +hifive1: + PLATFORM=hifive1 cargo build $(release) --target=riscv32imac-unknown-none-elf --examples $(features) + +.PHONY: flash-hifive1 +flash-hifive1: + PLATFORM=hifive1 cargo run $(release) --target=riscv32imac-unknown-none-elf --example $(EXAMPLE) $(features) + +.PHONY: nrf52 +nrf52: + PLATFORM=nrf52 cargo build $(release) --target=thumbv7em-none-eabi --examples $(features) + +.PHONY: flash-nrf52 +flash-nrf52: + PLATFORM=nrf52 cargo run $(release) --target=thumbv7em-none-eabi --example $(EXAMPLE) $(features) + +.PHONY: clean +clean: + rm -rf target + rm Cargo.lock
diff --git a/README.md b/README.md index 18a04b1..36be4b0 100644 --- a/README.md +++ b/README.md
@@ -14,7 +14,7 @@ and that there can only be one application written in rust at a time and it must be installed as the first application on the board, unless you want to play games with linker scripts. -There are some `layout_*.ld` files provided that allow to run the +There are some `boards/layout_*.ld` files provided that allow to run the examples on common boards. Due to MPU region alignment issues they may not work for applications that use a lot of RAM, in that case you may have to change the SRAM @@ -28,38 +28,32 @@ 1. Clone the repository: - ```bash + ```shell git clone https://github.com/tock/libtock-rs cd libtock-rs ``` -1. Install `elf2tab`: +1. Install the dependencies: - ```bash - cargo install -f elf2tab --version 0.4.0 + ```shell + make setup ``` -1. Add dependencies for cross-compilation. Currently, only few platforms have been configured, e.g.: +1. Use `make` to compile and run an example app. - ```bash - rustup target add thumbv7em-none-eabi # For an nRF52 DK board + ```shell + make nrf52 # Builds all examples for the nrf52 platform ``` ```bash - rustup target add riscv32imc-unknown-none-elf # For an OpenTitan board - ``` - -1. Use `cargo r<arch>` to compile and run an example app. The full command is platform dependent and looks as follows for the `blink` example: - - ```bash - PLATFORM=nrf52 cargo rthumbv7em blink # For an nRF52 DK board + make opentitan # Builds all examples for the OpenTitan platform ``` ```bash - PLATFORM=opentitan cargo rriscv32imc blink # For an OpenTitan board + make opentitan FEATURES=alloc # Builds all examples for the OpenTitan platform, with alloc feature enabled ``` - For an unknown platform, you may have to create your own memory layout definition. Place the layout definition file at `layout_<platform>.ld` and do not forget to enhance the `tockloader_flags` dispatching section in `flash.sh`. You are welcome to create a PR, s.t. the number of supported platforms grows. + For an unknown platform, you may have to create your own memory layout definition. Place the layout definition file at `boards/layout_<platform>.ld` and do not forget to enhance the `tockloader_flags` dispatching section in `tools/flash.sh`. You are welcome to create a PR, s.t. the number of supported platforms grows. ## Using libtock-rs @@ -87,8 +81,14 @@ To run on the code on your board you can use -```bash -PLATFORM=<platform> cargo r<arch> <your_app> [--features=alloc] +```shell +make <platform> [FEATURES=alloc] +``` + +The example can also be flashed to the board by running: + +```shell +make flash-<platform> EXAMPLE=<example> ``` This script does the following steps for you: @@ -97,11 +97,6 @@ - create a TAB (tock application bundle) - if you have a J-Link compatible board connected: flash this TAB to your board (using tockloader) -Instead of specifying an environment variable each time you can permanently configure your platform by writing its name into a file named `platform`, e.g. - -```bash -echo nrf52 > platform -``` ## License
diff --git a/layout_hail.ld b/boards/layout_hail.ld similarity index 100% rename from layout_hail.ld rename to boards/layout_hail.ld
diff --git a/layout_riscv32.ld b/boards/layout_hifive1.ld similarity index 100% rename from layout_riscv32.ld rename to boards/layout_hifive1.ld
diff --git a/layout_nrf52.ld b/boards/layout_nrf52.ld similarity index 100% rename from layout_nrf52.ld rename to boards/layout_nrf52.ld
diff --git a/layout_nrf52840.ld b/boards/layout_nrf52840.ld similarity index 100% rename from layout_nrf52840.ld rename to boards/layout_nrf52840.ld
diff --git a/layout_opentitan.ld b/boards/layout_opentitan.ld similarity index 100% rename from layout_opentitan.ld rename to boards/layout_opentitan.ld
diff --git a/build.rs b/build.rs index 8cdb6ae..7160086 100644 --- a/build.rs +++ b/build.rs
@@ -45,7 +45,7 @@ } fn copy_linker_file(platform_name: &str) { - let linker_file_name = format!("layout_{}.ld", platform_name); + let linker_file_name = format!("boards/layout_{}.ld", platform_name); let path = Path::new(&linker_file_name); if !path.exists() { println!("Cannot find layout file {:?}", path);
diff --git a/build_examples.sh b/build_examples.sh deleted file mode 100755 index fd67b75..0000000 --- a/build_examples.sh +++ /dev/null
@@ -1,7 +0,0 @@ -#!/usr/bin/env bash - -set -eux - -PLATFORM=nrf52 cargo build --release --target=thumbv7em-none-eabi --examples -PLATFORM=nrf52 cargo build --release --target=thumbv7em-none-eabi --examples --features=alloc -PLATFORM=riscv32 cargo build --release --target=riscv32imc-unknown-none-elf --examples # Important for testing: This target does not support atomics
diff --git a/doc/README.md b/doc/README.md deleted file mode 100644 index b8da532..0000000 --- a/doc/README.md +++ /dev/null
@@ -1,7 +0,0 @@ -# Available flash commands - -- `cargo rriscv32imac`/`cargo rrv32imac`: Use the `riscv32imac-unknown-none-elf` target -- `cargo rriscv32imc`/`cargo rrv32imc`: Use the `riscv32imc-unknown-none-elf` target -- `cargo rthumbv7em`/`cargo rtv7em`: Use the `thumbv7em-none-eabi` target - -Before flashing, write your board name to the environment variable `PLATFORM` or to a file named `platform`
diff --git a/run_all_checks.sh b/run_all_checks.sh deleted file mode 100755 index 3dde5ff..0000000 --- a/run_all_checks.sh +++ /dev/null
@@ -1,10 +0,0 @@ -#!/usr/bin/env bash - -set -eux - -export PLATFORM=nrf52 # The specific platform doesn't matter for tests - -cargo fmt --all -- --check -cargo clippy --workspace --all-targets -cargo test --workspace -./build_examples.sh
diff --git a/rustfmt.toml b/rustfmt.toml index d3da3dd..8a1751f 100644 --- a/rustfmt.toml +++ b/rustfmt.toml
@@ -1,3 +1 @@ use_field_init_shorthand = true -use_try_shorthand = true -edition = "2018" \ No newline at end of file
diff --git a/flash.sh b/tools/flash.sh similarity index 98% rename from flash.sh rename to tools/flash.sh index b241a7a..7d20190 100755 --- a/flash.sh +++ b/tools/flash.sh
@@ -16,7 +16,7 @@ binary_name=cortex-m4.elf tockload=y ;; - "riscv32") + "hifive1") tockloader_flags="" binary_name=rv32imac.elf tockload=n