From 0b0ca62a95cd2dabbc7e160dc5d0fcfc1a7a76e8 Mon Sep 17 00:00:00 2001 From: JuliDi <20155974+JuliDi@users.noreply.github.com> Date: Mon, 4 Dec 2023 20:59:08 +0100 Subject: add speed optimization --- docs/modules/ROOT/pages/faq.adoc | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'docs/modules') diff --git a/docs/modules/ROOT/pages/faq.adoc b/docs/modules/ROOT/pages/faq.adoc index df3f66658..8ac1febc2 100644 --- a/docs/modules/ROOT/pages/faq.adoc +++ b/docs/modules/ROOT/pages/faq.adoc @@ -135,3 +135,19 @@ embassy-time = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd ---- Note that the git revision should match any other embassy patches or git dependencies that you are using! + +== How can I optimize the speed of my embassy-stm32 program? + +* Make sure RCC is set up to go as fast as possible +* Make sure link:https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.SCB.html[flash cache] is enabled +* build with `--release` +* Set the following keys for the release profile in your `Cargo.toml``: + ** `opt-level=s` + ** `lto=fat` + ** `build-std=core` + ** `build-std-features=panic_immediate_abort` +* Enable feature `embassy-time/generic-queue`, disable feature `embassy-executor/integrated-timers` +* When using `InterruptExecutor`: + ** disable `executor-thread` + ** make `main`` spawn everything, then enable link:https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.SCB.html#method.set_sleeponexit[SCB.SLEEPONEXIT] and `loop { cortex_m::asm::wfi() }` + ** *Note:* If you need 2 priority levels, using 2 interrupt executors is better than 1 thread executor + 1 interrupt executor. \ No newline at end of file -- cgit From bf7115cb4425959acd01d3e9a1d640a47948b2f9 Mon Sep 17 00:00:00 2001 From: JuliDi <20155974+JuliDi@users.noreply.github.com> Date: Mon, 4 Dec 2023 21:20:18 +0100 Subject: remove unnecessary backtick --- docs/modules/ROOT/pages/faq.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/modules') diff --git a/docs/modules/ROOT/pages/faq.adoc b/docs/modules/ROOT/pages/faq.adoc index 8ac1febc2..0999b6909 100644 --- a/docs/modules/ROOT/pages/faq.adoc +++ b/docs/modules/ROOT/pages/faq.adoc @@ -141,7 +141,7 @@ Note that the git revision should match any other embassy patches or git depende * Make sure RCC is set up to go as fast as possible * Make sure link:https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.SCB.html[flash cache] is enabled * build with `--release` -* Set the following keys for the release profile in your `Cargo.toml``: +* Set the following keys for the release profile in your `Cargo.toml`: ** `opt-level=s` ** `lto=fat` ** `build-std=core` -- cgit From 1f6ffdcdd2e760d91ed10fa63f6819b71579b2b4 Mon Sep 17 00:00:00 2001 From: JuliDi <20155974+JuliDi@users.noreply.github.com> Date: Tue, 5 Dec 2023 10:10:47 +0100 Subject: fix Cargo.toml and config.toml keys --- docs/modules/ROOT/pages/faq.adoc | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) (limited to 'docs/modules') diff --git a/docs/modules/ROOT/pages/faq.adoc b/docs/modules/ROOT/pages/faq.adoc index 0999b6909..cab9fb9d8 100644 --- a/docs/modules/ROOT/pages/faq.adoc +++ b/docs/modules/ROOT/pages/faq.adoc @@ -142,10 +142,11 @@ Note that the git revision should match any other embassy patches or git depende * Make sure link:https://docs.rs/cortex-m/latest/cortex_m/peripheral/struct.SCB.html[flash cache] is enabled * build with `--release` * Set the following keys for the release profile in your `Cargo.toml`: - ** `opt-level=s` - ** `lto=fat` - ** `build-std=core` - ** `build-std-features=panic_immediate_abort` + ** `opt-level = "s"` + ** `lto = "fat"` +* Set the following keys in the `[unstable]` section of your `.cargo/config.toml` + ** `build-std = ["core"]` + ** `build-std-features = ["panic_immediate_abort"]` * Enable feature `embassy-time/generic-queue`, disable feature `embassy-executor/integrated-timers` * When using `InterruptExecutor`: ** disable `executor-thread` -- cgit From cd62d2cd84176cd7a70ea164e34a3f2245c1fbd1 Mon Sep 17 00:00:00 2001 From: Barnaby Walters Date: Wed, 6 Dec 2023 21:10:16 +0100 Subject: Added embassy in the wild docs page with two projects --- docs/modules/ROOT/nav.adoc | 1 + docs/modules/ROOT/pages/embassy_in_the_wild.adoc | 8 ++++++++ 2 files changed, 9 insertions(+) create mode 100644 docs/modules/ROOT/pages/embassy_in_the_wild.adoc (limited to 'docs/modules') diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 8d7f6f411..f79e1d54a 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -12,4 +12,5 @@ * xref:examples.adoc[Examples] * xref:developer.adoc[Developer] ** xref:developer_stm32.adoc[Developer: STM32] +* xref:embassy_in_the_wild.adoc[Embassy in the wild] * xref:faq.adoc[Frequently Asked Questions] diff --git a/docs/modules/ROOT/pages/embassy_in_the_wild.adoc b/docs/modules/ROOT/pages/embassy_in_the_wild.adoc new file mode 100644 index 000000000..c1c09c38a --- /dev/null +++ b/docs/modules/ROOT/pages/embassy_in_the_wild.adoc @@ -0,0 +1,8 @@ += Embassy in the wild! + +Here are known examples of real-world projects which make use of Embassy. Feel free to link:https://github.com/embassy-rs/embassy/blob/main/docs/modules/ROOT/pages/embassy_in_the_wild.adoc[add more]! + +* link:https://github.com/cbruiz/printhor/[Printhor: The highly reliable but not necessarily functional 3D printer firmware] +** Targets some STM32 MCUs +* link:https://github.com/card-io-ecg/card-io-fw[Card/IO firmware] +** Targets the ESP32-S3 MCU \ No newline at end of file -- cgit From 10c9e2e7238f07665333264afa132736cee09f8d Mon Sep 17 00:00:00 2001 From: Barnaby Walters Date: Wed, 6 Dec 2023 21:11:34 +0100 Subject: Added description for Card/IO --- docs/modules/ROOT/pages/embassy_in_the_wild.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/modules') diff --git a/docs/modules/ROOT/pages/embassy_in_the_wild.adoc b/docs/modules/ROOT/pages/embassy_in_the_wild.adoc index c1c09c38a..a69aa701e 100644 --- a/docs/modules/ROOT/pages/embassy_in_the_wild.adoc +++ b/docs/modules/ROOT/pages/embassy_in_the_wild.adoc @@ -4,5 +4,5 @@ Here are known examples of real-world projects which make use of Embassy. Feel f * link:https://github.com/cbruiz/printhor/[Printhor: The highly reliable but not necessarily functional 3D printer firmware] ** Targets some STM32 MCUs -* link:https://github.com/card-io-ecg/card-io-fw[Card/IO firmware] +* link:https://github.com/card-io-ecg/card-io-fw[Card/IO firmware] - firmware for an open source ECG device ** Targets the ESP32-S3 MCU \ No newline at end of file -- cgit From 195b492158b7db8b81c4cf6bbc436884590d334b Mon Sep 17 00:00:00 2001 From: Barnaby Walters Date: Wed, 6 Dec 2023 21:13:56 +0100 Subject: Update docs/modules/ROOT/pages/embassy_in_the_wild.adoc 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/embassy_in_the_wild.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/modules') diff --git a/docs/modules/ROOT/pages/embassy_in_the_wild.adoc b/docs/modules/ROOT/pages/embassy_in_the_wild.adoc index a69aa701e..5c12227b9 100644 --- a/docs/modules/ROOT/pages/embassy_in_the_wild.adoc +++ b/docs/modules/ROOT/pages/embassy_in_the_wild.adoc @@ -5,4 +5,4 @@ Here are known examples of real-world projects which make use of Embassy. Feel f * link:https://github.com/cbruiz/printhor/[Printhor: The highly reliable but not necessarily functional 3D printer firmware] ** Targets some STM32 MCUs * link:https://github.com/card-io-ecg/card-io-fw[Card/IO firmware] - firmware for an open source ECG device -** Targets the ESP32-S3 MCU \ No newline at end of file +** Targets the ESP32-S3 or ESP32-C6 MCU \ No newline at end of file -- cgit From 7561696a57ce77146078e481dc75dd3ab9e1c76d Mon Sep 17 00:00:00 2001 From: Barnaby Walters Date: Wed, 6 Dec 2023 21:47:52 +0100 Subject: Added lora-rs links --- docs/modules/ROOT/pages/embassy_in_the_wild.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/modules') diff --git a/docs/modules/ROOT/pages/embassy_in_the_wild.adoc b/docs/modules/ROOT/pages/embassy_in_the_wild.adoc index a69aa701e..625bd0b29 100644 --- a/docs/modules/ROOT/pages/embassy_in_the_wild.adoc +++ b/docs/modules/ROOT/pages/embassy_in_the_wild.adoc @@ -5,4 +5,5 @@ Here are known examples of real-world projects which make use of Embassy. Feel f * link:https://github.com/cbruiz/printhor/[Printhor: The highly reliable but not necessarily functional 3D printer firmware] ** Targets some STM32 MCUs * link:https://github.com/card-io-ecg/card-io-fw[Card/IO firmware] - firmware for an open source ECG device -** Targets the ESP32-S3 MCU \ No newline at end of file +** Targets the ESP32-S3 MCU +* The link:https://github.com/lora-rs/lora-rs[lora-rs] project includes link:https://github.com/lora-rs/lora-rs/tree/main/examples/stm32l0/src/bin[various standalone examples] for NRF52840, RP2040, STM32L0 and STM32WL \ No newline at end of file -- cgit From 536e91d263ecfcf684f91598e5ca987ae0acc820 Mon Sep 17 00:00:00 2001 From: Barnaby Walters Date: Wed, 6 Dec 2023 23:51:13 +0100 Subject: Added a step-by-step guide to starting a new embassy project Based off an example, noting what to copy, what to change and why Briefly summarizing how to require embassy crates via github All steps tested and proven working at the time of writing --- docs/modules/ROOT/nav.adoc | 1 + docs/modules/ROOT/pages/new_project.adoc | 179 +++++++++++++++++++++++++++++++ 2 files changed, 180 insertions(+) create mode 100644 docs/modules/ROOT/pages/new_project.adoc (limited to 'docs/modules') diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 8d7f6f411..70a4a4159 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -1,6 +1,7 @@ * xref:getting_started.adoc[Getting started] ** xref:basic_application.adoc[Basic application] ** xref:project_structure.adoc[Project Structure] +** xref:new_project.adoc[Starting a new Embassy project] * xref:layer_by_layer.adoc[Bare metal to async] * xref:runtime.adoc[Executor] * xref:delaying_a_task.adoc[Delaying a Task] diff --git a/docs/modules/ROOT/pages/new_project.adoc b/docs/modules/ROOT/pages/new_project.adoc new file mode 100644 index 000000000..ae819aa83 --- /dev/null +++ b/docs/modules/ROOT/pages/new_project.adoc @@ -0,0 +1,179 @@ += Starting a new Embassy project + +Once you’ve successfully xref:getting_started.adoc[run some example projects], the next step is to make a standalone Embassy project. The easiest way to do this is to adapt an example for a similar chip to the one you’re targeting. + +As an example, let’s create a new embassy project from scratch for a STM32G474. The same instructions are applicable for any supported chip with some minor changes. + +Run: + +[source,bash] +---- +mkdir embassy-stm32g474 +cd embassy-stm32g474 +cargo init +---- + +to create an empty rust project: + +[source] +---- +embassy-stm32g474 +├── Cargo.toml +└── src + └── main.rs +---- + +Looking in link:https://github.com/embassy-rs/embassy/tree/main/examples[the Embassy examples], we can see there’s a `stm32g4` folder. Find `src/blinky.rs` and copy its contents into our `src/main.rs`. + +== .cargo/config.toml + +Currently, we’d need to provide cargo with a target triple every time we run `cargo build` or `cargo run`. Let’s spare ourselves that work by copying `.cargo/config.toml` from `examples/stm32g4` into our project. + +[source] +---- +embassy-stm32g474 +├── .cargo +│   └── config.toml +├── Cargo.toml +└── src + └── main.rs +---- + +In addition to a target triple, `.cargo/config.toml` contains a `runner` key which allows us to conveniently run our project on hardware with `cargo run` via probe-rs. In order for this to work, we need to provide the correct chip ID. We can do this by checking `probe-rs chip list`: + +[source,bash] +---- +$ probe-rs chip list | grep -i stm32g474re + STM32G474RETx +---- + +and copying `STM32G474RETx` into `.cargo/config.toml` as so: + +[source,toml] +---- +[target.'cfg(all(target_arch = "arm", target_os = "none"))'] +# replace STM32G071C8Rx with your chip as listed in `probe-rs chip list` +runner = "probe-rs run --chip STM32G474RETx" +---- + +== Cargo.toml + +Now that cargo knows what target to compile for (and probe-rs knows what chip to run it on), we’re ready to add some dependencies. + +Looking in `examples/stm32g4/Cargo.toml`, we can see that the examples require a number of embassy crates. For blinky, we’ll only need three of them: `embassy-stm32`, `embassy-executor` and `embassy-time`. + +At the time of writing, the latest version of embassy isn‘t available on crates.io, so we need to install it straight from the git repository. The recommended way of doing so is as follows: + +* Copy the required `embassy-*` lines from the example `Cargo.toml` +* Make any necessary changes to `features`, e.g. requiring the `stm32g474re` feature of `embassy-stm32` +* Remove the `path = ""` keys in the `embassy-*` entries +* Create a `[patch.crates-io]` section, with entries for each embassy crate we need. These should all contain identical values: a link to the git repository, and a reference to the commit we’re checking out. Assuming you want the latest commit, you can find it by running `git ls-remote https://github.com/embassy-rs/embassy.git HEAD` + +NOTE: When using this method, it’s necessary that the `version` keys in `[dependencies]` match up with the versions defined in each crate’s `Cargo.toml` in the specificed `rev` under `[patch.crates.io]`. This means that when updating, you have to a pick a new revision, change everything in `[patch.crates.io]` to match it, and then correct any versions under `[dependencies]` which have changed. Hopefully this will no longer be necessary once embassy is released on crates.io! + +At the time of writing, this method produces the following results: + +[source,toml] +---- +[dependencies] +embassy-stm32 = {version = "0.1.0", features = ["defmt", "time-driver-any", "stm32g474re", "memory-x", "unstable-pac", "exti"]} +embassy-executor = { version = "0.3.3", features = ["nightly", "arch-cortex-m", "executor-thread", "defmt", "integrated-timers"] } +embassy-time = { version = "0.2", features = ["defmt", "defmt-timestamp-uptime", "tick-hz-32_768"] } + +[patch.crates-io] +embassy-time = { git = "https://github.com/embassy-rs/embassy", rev = "7703f47c1ecac029f603033b7977d9a2becef48c" } +embassy-executor = { git = "https://github.com/embassy-rs/embassy", rev = "7703f47c1ecac029f603033b7977d9a2becef48c" } +embassy-stm32 = { git = "https://github.com/embassy-rs/embassy", rev = "7703f47c1ecac029f603033b7977d9a2becef48c" } +---- + +There are a few other dependencies we need to build the project, but fortunately they’re much simpler to install. Copy their lines from the example `Cargo.toml` to the the `[dependencies]` section in the new `Cargo.toml`: + +[source,toml] +---- +defmt = "0.3.5" +defmt-rtt = "0.4.0" +cortex-m = {version = "0.7.7", features = ["critical-section-single-core"]} +cortex-m-rt = "0.7.3" +panic-probe = "0.3.1" +---- + +These are the bare minimum dependencies required to run `blinky.rs`, but it’s worth taking a look at the other dependencies specified in the example `Cargo.toml`, and noting what features are required for use with embassy – for example `futures = { version = "0.3.17", default-features = false, features = ["async-await"] }`. + +Finally, copy the `[profile.release]` section from the example `Cargo.toml` into ours. + +[source,toml] +---- +[profile.release] +debug = 2 +---- + +== rust-toolchain.toml + +Before we can build our project, we need to add an additional file to tell cargo to use the nightly toolchain. Copy the `rust-toolchain.toml` from the embassy repo to ours, and trim the list of targets down to only the target triple relevent for our project — in this case, `thumbv7em-none-eabi`: + +[source] +---- +embassy-stm32g474 +├── .cargo +│   └── config.toml +├── Cargo.toml +├── rust-toolchain.toml +└── src + └── main.rs +---- + +[source,toml] +---- +# Before upgrading check that everything is available on all tier1 targets here: +# https://rust-lang.github.io/rustup-components-history +[toolchain] +channel = "nightly-2023-11-01" +components = [ "rust-src", "rustfmt", "llvm-tools", "miri" ] +targets = ["thumbv7em-none-eabi"] +---- + +== build.rs + +In order to produce a working binary for our target, cargo requires a custom build script. Copy `build.rs` from the example to our project: + +[source] +---- +embassy-stm32g474 +├── build.rs +├── .cargo +│ └── config.toml +├── Cargo.toml +├── rust-toolchain.toml +└── src + └── main.rs +---- + +== Building and running + +At this point, we‘re finally ready to build and run our project! Connect your board via a debug probe and run: + +[source,bash] +---- +cargo run --release +---- + +should result in a blinking LED (if there’s one attached to the pin in `src/main.rs` – change it if not!) and the following output: + +[source] +---- + Compiling embassy-stm32g474 v0.1.0 (/home/you/embassy-stm32g474) + Finished release [optimized + debuginfo] target(s) in 0.22s + Running `probe-rs run --chip STM32G474RETx target/thumbv7em-none-eabi/release/embassy-stm32g474` + Erasing sectors ✔ [00:00:00] [#########################################################] 18.00 KiB/18.00 KiB @ 54.09 KiB/s (eta 0s ) + Programming pages ✔ [00:00:00] [#########################################################] 17.00 KiB/17.00 KiB @ 35.91 KiB/s (eta 0s ) Finished in 0.817s +0.000000 TRACE BDCR configured: 00008200 +└─ embassy_stm32::rcc::bd::{impl#3}::init::{closure#4} @ /home/you/.cargo/git/checkouts/embassy-9312dcb0ed774b29/7703f47/embassy-stm32/src/fmt.rs:117 +0.000000 DEBUG rcc: Clocks { sys: Hertz(16000000), pclk1: Hertz(16000000), pclk1_tim: Hertz(16000000), pclk2: Hertz(16000000), pclk2_tim: Hertz(16000000), hclk1: Hertz(16000000), hclk2: Hertz(16000000), pll1_p: None, adc: None, adc34: None, rtc: Some(Hertz(32000)) } +└─ embassy_stm32::rcc::set_freqs @ /home/you/.cargo/git/checkouts/embassy-9312dcb0ed774b29/7703f47/embassy-stm32/src/fmt.rs:130 +0.000000 INFO Hello World! +└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:14 +0.000091 INFO high +└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:19 +0.300201 INFO low +└─ embassy_stm32g474::____embassy_main_task::{async_fn#0} @ src/main.rs:23 +---- \ No newline at end of file -- cgit From 16e31747cc860b194719d7d276f1a0c08e417632 Mon Sep 17 00:00:00 2001 From: Barnaby Walters Date: Thu, 7 Dec 2023 00:54:39 +0100 Subject: Changed example project name --- docs/modules/ROOT/pages/new_project.adoc | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) (limited to 'docs/modules') diff --git a/docs/modules/ROOT/pages/new_project.adoc b/docs/modules/ROOT/pages/new_project.adoc index ae819aa83..ce139ed8d 100644 --- a/docs/modules/ROOT/pages/new_project.adoc +++ b/docs/modules/ROOT/pages/new_project.adoc @@ -8,16 +8,15 @@ Run: [source,bash] ---- -mkdir embassy-stm32g474 -cd embassy-stm32g474 -cargo init +cargo new stm32g474-example +cd stm32g474-example ---- to create an empty rust project: [source] ---- -embassy-stm32g474 +stm32g474-example ├── Cargo.toml └── src └── main.rs @@ -31,7 +30,7 @@ Currently, we’d need to provide cargo with a target triple every time we run ` [source] ---- -embassy-stm32g474 +stm32g474-example ├── .cargo │   └── config.toml ├── Cargo.toml @@ -113,7 +112,7 @@ Before we can build our project, we need to add an additional file to tell cargo [source] ---- -embassy-stm32g474 +stm32g474-example ├── .cargo │   └── config.toml ├── Cargo.toml @@ -138,7 +137,7 @@ In order to produce a working binary for our target, cargo requires a custom bui [source] ---- -embassy-stm32g474 +stm32g474-example ├── build.rs ├── .cargo │ └── config.toml @@ -161,9 +160,9 @@ should result in a blinking LED (if there’s one attached to the pin in `src/ma [source] ---- - Compiling embassy-stm32g474 v0.1.0 (/home/you/embassy-stm32g474) + Compiling stm32g474-example v0.1.0 (/home/you/stm32g474-example) Finished release [optimized + debuginfo] target(s) in 0.22s - Running `probe-rs run --chip STM32G474RETx target/thumbv7em-none-eabi/release/embassy-stm32g474` + Running `probe-rs run --chip STM32G474RETx target/thumbv7em-none-eabi/release/stm32g474-example` Erasing sectors ✔ [00:00:00] [#########################################################] 18.00 KiB/18.00 KiB @ 54.09 KiB/s (eta 0s ) Programming pages ✔ [00:00:00] [#########################################################] 17.00 KiB/17.00 KiB @ 35.91 KiB/s (eta 0s ) Finished in 0.817s 0.000000 TRACE BDCR configured: 00008200 -- cgit From 8fa5a6b282792d7f9238964acc2916452b494965 Mon Sep 17 00:00:00 2001 From: James Munns Date: Thu, 7 Dec 2023 14:27:09 +0100 Subject: Tweak FAQ size profile suggestions If we want the smallest binary, we probably want codegen-units = 1, and disable incremental builds. --- docs/modules/ROOT/pages/faq.adoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/modules') diff --git a/docs/modules/ROOT/pages/faq.adoc b/docs/modules/ROOT/pages/faq.adoc index df3f66658..2ec438913 100644 --- a/docs/modules/ROOT/pages/faq.adoc +++ b/docs/modules/ROOT/pages/faq.adoc @@ -47,7 +47,8 @@ The first step to managing your binary size is to set up your link:https://doc.r debug = false lto = true opt-level = "s" -incremental = true +incremental = false +codegen-units = 1 ---- All of these flags are elaborated on in the Rust Book page linked above. -- cgit From c05149e5e4110bed416e8a8568cf446e9db8774d Mon Sep 17 00:00:00 2001 From: JuliDi <20155974+JuliDi@users.noreply.github.com> Date: Fri, 8 Dec 2023 13:00:21 +0100 Subject: add best practices first draft --- docs/modules/ROOT/nav.adoc | 5 +-- docs/modules/ROOT/pages/best_practices.adoc | 53 +++++++++++++++++++++++++++++ 2 files changed, 56 insertions(+), 2 deletions(-) create mode 100644 docs/modules/ROOT/pages/best_practices.adoc (limited to 'docs/modules') diff --git a/docs/modules/ROOT/nav.adoc b/docs/modules/ROOT/nav.adoc index 2154799f3..fabb80e31 100644 --- a/docs/modules/ROOT/nav.adoc +++ b/docs/modules/ROOT/nav.adoc @@ -2,6 +2,7 @@ ** xref:basic_application.adoc[Basic application] ** xref:project_structure.adoc[Project Structure] ** xref:new_project.adoc[Starting a new Embassy project] +** xref:best_practices.adoc[Best Practices] * xref:layer_by_layer.adoc[Bare metal to async] * xref:runtime.adoc[Executor] * xref:delaying_a_task.adoc[Delaying a Task] @@ -11,7 +12,7 @@ * xref:bootloader.adoc[Bootloader] * xref:examples.adoc[Examples] -* xref:developer.adoc[Developer] -** xref:developer_stm32.adoc[Developer: STM32] +* xref:developer.adoc[Developer Docs] +** xref:developer_stm32.adoc[Developer Docs: STM32] * xref:embassy_in_the_wild.adoc[Embassy in the wild] * xref:faq.adoc[Frequently Asked Questions] diff --git a/docs/modules/ROOT/pages/best_practices.adoc b/docs/modules/ROOT/pages/best_practices.adoc new file mode 100644 index 000000000..1e02f9ba9 --- /dev/null +++ b/docs/modules/ROOT/pages/best_practices.adoc @@ -0,0 +1,53 @@ += Best Practices + +Over time, a couple of best practices have emerged. The following list should serve as a guideline for developers writing embedded software in _Rust_, especially in the context of the _Embassy_ framework. + +== Passing Buffers by Reference +It may be tempting to pass arrays or wrappers, like link:https://docs.rs/heapless/latest/heapless/[`heapless::Vec`], to a function or return one just like you would with a `std::Vec`. However, in most embedded applications you don't want to spend ressources on an allocator and end up placing buffers on the stack. +This, however, can easily blow up your stack if you are not careful. + +Consider the following example: +[,rust] +---- +fn process_buffer(mut buf: [u8; 1024]) -> [u8; 1024] { + // do stuff and return new buffer + for elem in buf.iter_mut() { + *elem = 0; + } + buf +} + +pub fn main() -> () { + let buf = [1u8; 1024]; + let buf_new = process_buffer(buf); + // do stuff with buf_new + () +} +---- +When calling `process_buffer` in your program, a copy of the buffer you pass to the function will be created, +consuming another 1024 bytes. +After the processing, another 1024 byte buffer will be placed on the stack to be returned to the caller. +(You can check the assembly, there will be two memcopy operations, e.g., `bl __aeabi_memcpy` when compiling for a Cortex-M processor.) + +*Possible Solution:* + +Pass the data by reference and not by value on both, the way in and the way out. +For example, you could return a slice of the input buffer as the output. +Requiring the lifetime of the input slice and the output slice to be the same, the memory safetly of this procedure will be enforced by the compiler. + +[,rust] +---- +fn process_buffer<'a>(buf: &'a mut [u8]) -> &'a mut[u8] { + for elem in buf.iter_mut() { + *elem = 0; + } + buf +} + +pub fn main() -> () { + let mut buf = [1u8; 1024]; + let buf_new = process_buffer(&mut buf); + // do stuff with buf_new + () +} +---- -- cgit