From 5844f5ce2d704058312ea607eb976e438ad990cb Mon Sep 17 00:00:00 2001 From: Adin Ackerman Date: Mon, 27 Nov 2023 10:23:42 -0800 Subject: [PATCH 1/4] Update faq.adoc --- docs/modules/ROOT/pages/faq.adoc | 125 +++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) diff --git a/docs/modules/ROOT/pages/faq.adoc b/docs/modules/ROOT/pages/faq.adoc index 6032985fc..2d49b68a6 100644 --- a/docs/modules/ROOT/pages/faq.adoc +++ b/docs/modules/ROOT/pages/faq.adoc @@ -4,6 +4,87 @@ These are a list of unsorted, commonly asked questions and answers. Please feel free to add items to link:https://github.com/embassy-rs/embassy/edit/main/docs/modules/ROOT/pages/faq.adoc[this page], especially if someone in the chat answered a question for you! +== How do I even start? + +There are many ways to configure embassy and it's components for your exact application. The link:https://github.com/embassy-rs/embassy/tree/main/examples[examples] directory for each chipset demonstrate how your project structure should look. Let's break it down: + +The toplevel file structure of your project should look like this: +[source,plain] +---- +{} = Maybe + +my-project +|- .cargo +| |- config.toml +|- src +| |- main.rs +|- build.rs +|- Cargo.toml +|- {memory.x} +|- rust-toolchain.toml +---- + +=== .cargo/config.toml + +This directory/file describes what platform you're on, and configures link:https://github.com/probe-rs/probe-rs[probe-rs] to deploy to your device. + +Here is a minimal example: + +[source,toml] +---- +[target.thumbv6m-none-eabi] # <-change for your platform +runner = 'probe-rs run --chip STM32F031K6Tx' # <- change for your chip + +[build] +target = "thumbv6m-none-eabi" # <-change for your platform + +[env] +DEFMT_LOG = "trace" # <- can change to info, warn, or error +---- + +=== build.rs + +This is the build script for your project. It links defmt (what is defmt?) and the `memory.x` file if need be. This file is pretty specific for each chipset, just copy and paste from the corresponding link:https://github.com/embassy-rs/embassy/tree/main/examples[example]. + +=== Cargo.toml + +This is your manifest file, where you can configure all of the embassy components to use the features you need. + +TODO: someone should exhaustively describe every feature for every component! + +=== memory.x + +This file outlines the flash/ram usage of your program. It is especially useful when using link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] on an nRF5x. + +Here is an example for using S140 with an nRF52840: + +[source,x] +---- +MEMORY +{ + /* NOTE 1 K = 1 KiBi = 1024 bytes */ + /* These values correspond to the NRF52840 with Softdevices S140 7.0.1 */ + FLASH : ORIGIN = 0x00027000, LENGTH = 868K + RAM : ORIGIN = 0x20020000, LENGTH = 128K +} +---- + +=== rust-toolchain.toml + +This file configures the rust version and configuration to use. + +A minimal example: + +[source,toml] +---- +[toolchain] +channel = "nightly-2023-08-19" # <- as of writing, this is the exact rust version embassy uses +components = [ "rust-src", "rustfmt" ] # <- optionally add "llvm-tools-preview" for some extra features like "cargo size" +targets = [ + "thumbv6m-none-eabi" # <-change for your platform +] +---- + == How to deploy to RP2040 without a debugging probe. Install link:https://github.com/JoNil/elf2uf2-rs[elf2uf2-rs] for converting the generated elf binary into a uf2 file. @@ -36,3 +117,47 @@ For Cortex-M targets, consider making sure that ALL of the following features ar * `nightly` For Xtensa ESP32, consider using the executors and `#[main]` macro provided by your appropriate link:https://crates.io/crates/esp-hal-common[HAL crate]. + +== Why is my binary so big? + +The first step to managing your binary size is to set up your link:https://doc.rust-lang.org/cargo/reference/profiles.html[profiles]. + +[source,toml] +---- +[profile.release] +debug = false +lto = true +opt-level = "s" +incremental = true +---- + +All of these flags are elaborated on in the Rust Book page linked above. + +=== My binary is still big... filled with `std::fmt` stuff! + +This means your code is sufficiently complex that `panic!` invocation's formatting requirements could not be optimized out, despite your usage of `panic-halt` or `panic-reset`. + +You can remedy this by adding the following to your `.cargo/config.toml`: + +[source,toml] +---- +[unstable] +build-std = ["core"] +build-std-features = ["panic_immediate_abort"] +---- + +This replaces all panics with a `UDF` (undefined) instruction. + +Depending on your chipset, this will exhibit different behavior. + +Refer to the spec for your chipset, but for `thumbv6m`, it results in a hardfault. Which can be configured like so: + +[source,rust] +---- +#[exception] +unsafe fn HardFault(_frame: &ExceptionFrame) -> ! { + SCB::sys_reset() // <- you could do something other than reset +} +---- + +Refer to cortex-m's link:https://docs.rs/cortex-m-rt/latest/cortex_m_rt/attr.exception.html[exception handling] for more info. From 142f42fe90caf8edddb34ba1fe6119dbd80a67e6 Mon Sep 17 00:00:00 2001 From: Adin Ackerman Date: Mon, 27 Nov 2023 10:44:47 -0800 Subject: [PATCH 2/4] ... --- docs/modules/ROOT/nav.adoc | 1 + docs/modules/ROOT/pages/faq.adoc | 81 ------------------- .../modules/ROOT/pages/project_structure.adoc | 80 ++++++++++++++++++ 3 files changed, 81 insertions(+), 81 deletions(-) create mode 100644 docs/modules/ROOT/pages/project_structure.adoc diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 7e178df62..13459099f 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,5 +1,6 @@ * xref:getting_started.adoc[Getting started] ** xref:basic_application.adoc[Basic application] +** xref:project_structure.adoc[Project Structure] * xref:layer_by_layer.adoc[Bare metal to async] * xref:runtime.adoc[Executor] * xref:hal.adoc[HAL] diff --git a/docs/modules/ROOT/pages/faq.adoc b/docs/modules/ROOT/pages/faq.adoc index 2d49b68a6..2994c6278 100644 --- a/docs/modules/ROOT/pages/faq.adoc +++ b/docs/modules/ROOT/pages/faq.adoc @@ -4,87 +4,6 @@ These are a list of unsorted, commonly asked questions and answers. Please feel free to add items to link:https://github.com/embassy-rs/embassy/edit/main/docs/modules/ROOT/pages/faq.adoc[this page], especially if someone in the chat answered a question for you! -== How do I even start? - -There are many ways to configure embassy and it's components for your exact application. The link:https://github.com/embassy-rs/embassy/tree/main/examples[examples] directory for each chipset demonstrate how your project structure should look. Let's break it down: - -The toplevel file structure of your project should look like this: -[source,plain] ----- -{} = Maybe - -my-project -|- .cargo -| |- config.toml -|- src -| |- main.rs -|- build.rs -|- Cargo.toml -|- {memory.x} -|- rust-toolchain.toml ----- - -=== .cargo/config.toml - -This directory/file describes what platform you're on, and configures link:https://github.com/probe-rs/probe-rs[probe-rs] to deploy to your device. - -Here is a minimal example: - -[source,toml] ----- -[target.thumbv6m-none-eabi] # <-change for your platform -runner = 'probe-rs run --chip STM32F031K6Tx' # <- change for your chip - -[build] -target = "thumbv6m-none-eabi" # <-change for your platform - -[env] -DEFMT_LOG = "trace" # <- can change to info, warn, or error ----- - -=== build.rs - -This is the build script for your project. It links defmt (what is defmt?) and the `memory.x` file if need be. This file is pretty specific for each chipset, just copy and paste from the corresponding link:https://github.com/embassy-rs/embassy/tree/main/examples[example]. - -=== Cargo.toml - -This is your manifest file, where you can configure all of the embassy components to use the features you need. - -TODO: someone should exhaustively describe every feature for every component! - -=== memory.x - -This file outlines the flash/ram usage of your program. It is especially useful when using link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] on an nRF5x. - -Here is an example for using S140 with an nRF52840: - -[source,x] ----- -MEMORY -{ - /* NOTE 1 K = 1 KiBi = 1024 bytes */ - /* These values correspond to the NRF52840 with Softdevices S140 7.0.1 */ - FLASH : ORIGIN = 0x00027000, LENGTH = 868K - RAM : ORIGIN = 0x20020000, LENGTH = 128K -} ----- - -=== rust-toolchain.toml - -This file configures the rust version and configuration to use. - -A minimal example: - -[source,toml] ----- -[toolchain] -channel = "nightly-2023-08-19" # <- as of writing, this is the exact rust version embassy uses -components = [ "rust-src", "rustfmt" ] # <- optionally add "llvm-tools-preview" for some extra features like "cargo size" -targets = [ - "thumbv6m-none-eabi" # <-change for your platform -] ----- - == How to deploy to RP2040 without a debugging probe. Install link:https://github.com/JoNil/elf2uf2-rs[elf2uf2-rs] for converting the generated elf binary into a uf2 file. diff --git a/docs/modules/ROOT/pages/project_structure.adoc b/docs/modules/ROOT/pages/project_structure.adoc new file mode 100644 index 000000000..31417d09c --- /dev/null +++ b/docs/modules/ROOT/pages/project_structure.adoc @@ -0,0 +1,80 @@ += Project Structure + +There are many ways to configure embassy and it's components for your exact application. The link:https://github.com/embassy-rs/embassy/tree/main/examples[examples] directory for each chipset demonstrate how your project structure should look. Let's break it down: + +The toplevel file structure of your project should look like this: +[source,plain] +---- +{} = Maybe + +my-project +|- .cargo +| |- config.toml +|- src +| |- main.rs +|- build.rs +|- Cargo.toml +|- {memory.x} +|- rust-toolchain.toml +---- + +=== .cargo/config.toml + +This directory/file describes what platform you're on, and configures link:https://github.com/probe-rs/probe-rs[probe-rs] to deploy to your device. + +Here is a minimal example: + +[source,toml] +---- +[target.thumbv6m-none-eabi] # <-change for your platform +runner = 'probe-rs run --chip STM32F031K6Tx' # <- change for your chip + +[build] +target = "thumbv6m-none-eabi" # <-change for your platform + +[env] +DEFMT_LOG = "trace" # <- can change to info, warn, or error +---- + +=== build.rs + +This is the build script for your project. It links defmt (what is defmt?) and the `memory.x` file if need be. This file is pretty specific for each chipset, just copy and paste from the corresponding link:https://github.com/embassy-rs/embassy/tree/main/examples[example]. + +=== Cargo.toml + +This is your manifest file, where you can configure all of the embassy components to use the features you need. + +TODO: someone should exhaustively describe every feature for every component! + +=== memory.x + +This file outlines the flash/ram usage of your program. It is especially useful when using link:https://github.com/embassy-rs/nrf-softdevice[nrf-softdevice] on an nRF5x. + +Here is an example for using S140 with an nRF52840: + +[source,x] +---- +MEMORY +{ + /* NOTE 1 K = 1 KiBi = 1024 bytes */ + /* These values correspond to the NRF52840 with Softdevices S140 7.0.1 */ + FLASH : ORIGIN = 0x00027000, LENGTH = 868K + RAM : ORIGIN = 0x20020000, LENGTH = 128K +} +---- + +=== rust-toolchain.toml + +This file configures the rust version and configuration to use. + +A minimal example: + +[source,toml] +---- +[toolchain] +channel = "nightly-2023-08-19" # <- as of writing, this is the exact rust version embassy uses +components = [ "rust-src", "rustfmt" ] # <- optionally add "llvm-tools-preview" for some extra features like "cargo size" +targets = [ + "thumbv6m-none-eabi" # <-change for your platform +] +---- From a42aef7759a2f2b1da5bb9a62bb83006c4e856e0 Mon Sep 17 00:00:00 2001 From: AdinAck Date: Mon, 27 Nov 2023 10:51:05 -0800 Subject: [PATCH 3/4] it's -> its MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Dániel Buga --- docs/modules/ROOT/pages/project_structure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/project_structure.adoc b/docs/modules/ROOT/pages/project_structure.adoc index 31417d09c..ac992f8bd 100644 --- a/docs/modules/ROOT/pages/project_structure.adoc +++ b/docs/modules/ROOT/pages/project_structure.adoc @@ -1,6 +1,6 @@ = Project Structure -There are many ways to configure embassy and it's components for your exact application. The link:https://github.com/embassy-rs/embassy/tree/main/examples[examples] directory for each chipset demonstrate how your project structure should look. Let's break it down: +There are many ways to configure embassy and its components for your exact application. The link:https://github.com/embassy-rs/embassy/tree/main/examples[examples] directory for each chipset demonstrates how your project structure should look. Let's break it down: The toplevel file structure of your project should look like this: [source,plain] From 02305451b1893924effa8d036a0d379ed485a364 Mon Sep 17 00:00:00 2001 From: AdinAck Date: Mon, 27 Nov 2023 10:51:20 -0800 Subject: [PATCH 4/4] need be -> needed MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Dániel Buga --- docs/modules/ROOT/pages/project_structure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/modules/ROOT/pages/project_structure.adoc b/docs/modules/ROOT/pages/project_structure.adoc index ac992f8bd..3e6008ec4 100644 --- a/docs/modules/ROOT/pages/project_structure.adoc +++ b/docs/modules/ROOT/pages/project_structure.adoc @@ -38,7 +38,7 @@ DEFMT_LOG = "trace" # <- can change to info, warn, or error === build.rs -This is the build script for your project. It links defmt (what is defmt?) and the `memory.x` file if need be. This file is pretty specific for each chipset, just copy and paste from the corresponding link:https://github.com/embassy-rs/embassy/tree/main/examples[example]. +This is the build script for your project. It links defmt (what is defmt?) and the `memory.x` file if needed. This file is pretty specific for each chipset, just copy and paste from the corresponding link:https://github.com/embassy-rs/embassy/tree/main/examples[example]. === Cargo.toml