Merge pull request #2226 from AdinAck/faq-update-1

FAQ Update (1)
This commit is contained in:
Ulf Lilleengen 2023-11-27 18:59:53 +00:00 committed by GitHub
commit 3a8a950bb8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
3 changed files with 125 additions and 0 deletions

View File

@ -1,5 +1,6 @@
* xref:getting_started.adoc[Getting started] * xref:getting_started.adoc[Getting started]
** xref:basic_application.adoc[Basic application] ** xref:basic_application.adoc[Basic application]
** xref:project_structure.adoc[Project Structure]
* xref:layer_by_layer.adoc[Bare metal to async] * xref:layer_by_layer.adoc[Bare metal to async]
* xref:runtime.adoc[Executor] * xref:runtime.adoc[Executor]
* xref:hal.adoc[HAL] * xref:hal.adoc[HAL]

View File

@ -36,3 +36,47 @@ For Cortex-M targets, consider making sure that ALL of the following features ar
* `nightly` * `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]. 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.

View File

@ -0,0 +1,80 @@
= Project Structure
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]
----
{} = 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 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
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
]
----