diff --git a/.scaffold.toml b/.scaffold.toml new file mode 100644 index 0000000000000000000000000000000000000000..d7db7f46b86d5bacf578f4aba4e3ceb7897ee84f --- /dev/null +++ b/.scaffold.toml @@ -0,0 +1,28 @@ +# Basic template informations +[template] +name = "troll-template" +author = "Michael Hauspie <michael.hauspie@univ-lille.fr>" +version = "0.1.0" + +# Exclude paths you do not want copy/pasted in the generated project +exclude = [ +] + +# Notes to display at the end of the generation +notes = """ +Run 'make flash' to build the binary image and to flash it to your device +""" + +[hooks] +# Commands to be executed before scaffolding, from within the generated project +pre = [ +] +# Commands to be executed after scaffolding, from within the generated project +post = [ +] + +# Parameters are basically all the variables needed to generate your template using templating. +# It will be displayed as prompt to interact with user (thanks to the message subfield). +# All the parameters will be available in your templates as variables (example: `{{description}}`). +#[parameters] +# [parameters.name] is already reserved diff --git a/Makefile b/Makefile index 58e8d7fa182d556702f228e0f523f9d77669e5cb..a4c742b131a99c3beafc70bb6fd01c525acdf59e 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ OBJCOPY=arm-none-eabi-objcopy OBJCOPY_FLAGS=--input-format=elf32-littlearm --output-format=binary -RELOC_TOOL=cargo-pip +RELOC_TOOL=troll-rs CRT0=crt0 diff --git a/README.md b/README.md index f484ced3395808ec1ac6a36f563e140e565279c6..8504960f223e9403d95fe34ee61237e5238c61c4 100644 --- a/README.md +++ b/README.md @@ -1,27 +1,38 @@ -# Lightweight relocatable format for ARM Thumb rust code +# Troll : Tiny Relocatable Object file format -This repository allows the creation of a lightweight relocatable binary -that can be executed on an ARM Thumb board from any address. +This repository allows the creation of a Troll relocatable binary that can be executed on an ARM +Thumb board from any address. This file format is a binary image that can be directly executed from +any address. -It consists in three crates: +The Troll file format is not a bootloader itself. It cannot be directly flashed at address +`0x00000000` because it does not contain the needed interrupt vector. + +However, a bootloader can setup a simple structure and use it as a parameter for the Troll file +entrypoint function. This entrypoint is simply located at offset `0` in the Troll binary format. + +The file format is explained in details in the [README.md](crt0/README.md) file of the `crt0` crate. + +# What's included in this project + +This repository consists in three crates: - `crt0` : this holds the bootstrap code that will perform the actual - needed step for relocating the binary of the `user_code`. You will + needed step for relocating the Troll binary of the `user_code`. You will not have to modify this crate, - `user_code` : a template that you can modify to develop your own application - `simple-bootloader` : a example of a bootloader that sets up the - minimum needed things to start a lightweigth relocatable binary + minimum needed things to start an Troll binary The first two crates builds into two elf files that are needed -to generate the final relocatable binary file +to generate the final Troll binary file - `crt0/target/thumbv7em-none-eabihf/<profile>/crt0` - `user_code/target/thumbv7em-none-eabihf/<profile>/root` These binaries are elf files, ready to be processed by our tool to -generate the binary file that can be flashed/loaded on the board at +generate the Troll binary file that can be flashed/loaded on the board at any address for execution. @@ -29,10 +40,11 @@ The `simple-bootloader` crate produces - `simple-bootloader/target/thumbv7em-none-eabihf/<profile>/simple-bootloader` -This is also an elf file, but this one is not relocatable. You can produce the binary -to flash using a standard `arm-none-eabi-objcopy`. This binary includes the vector table -suitable for starting the bootloader (see arm thumb documentation if you want to know more -one the boot process of ARM Thumb CPUs) +This is also an elf file, but this one is not relocatable. You can produce the binary to flash using +a standard `arm-none-eabi-objcopy`. This binary includes the vector table suitable for starting the +bootloader (see arm thumb documentation if you want to know more one the boot process of ARM Thumb +CPUs). By default, this bootloader considers that the Troll file it needs to start is located +immediatly after its own image in the flash memory. # Getting started @@ -43,27 +55,26 @@ To create your own project based on this template, you need: - A working [rust](https://rust-lang.org) toolchain for the target `thumbv7em-none-eabihf` (Last tested version: 1.81.0-nightly) - Our dedicated tool that will produce generate the template for you and the binary files for the - firmware from the ELF files - You can install it using `cargo install cargo-pip` + firmware from the ELF files. You can install it using `cargo install troll-rs` - [OpenOCD](https://openocd.sourceforge.io/) to flash and debug your code on your platform ## Create your own project -To create your project, use `cargo-pip` with the `new` subcommand +To create your project, use `troll-rs` with the `new` subcommand ``` -$ cargo-pip new --help -Generate a new pip partition project +$ troll-rs new --help +Generate a new project -Usage: cargo-pip new [OPTIONS] <CRATE_PATH> +Usage: troll-rs new [OPTIONS] <PROJECT_PATH> Arguments: - <CRATE_PATH> The path where to generate your crate + <PROJECT_PATH> The path where to generate your project Options: - -c, --crate-name <CRATE_NAME> The name of the generated project. If omitted, deduced from the crate_path parameter - -h, --help Print help + -p, --project-name <PROJECT_NAME> The name of the generated project. If omitted, deduced from the PROJECT_PATH parameter + -h, --help Print help ``` You can now modify the rust source code under the `user_code/src/` folder. Do not modify `crt0` and