embassy/docs/modules/ROOT/pages/faq.adoc

= Frequently Asked Questions

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 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.

Configure the runner to use this tool, add this to `.cargo/config.toml`:
[source,toml]
----
[target.'cfg(all(target_arch = "arm", target_os = "none"))']
runner = "elf2uf2-rs --deploy --serial --verbose"
----

The command-line parameters `--deploy` will detect your device and upload the binary, `--serial` starts a serial connection. See the documentation for more info.

== Missing main macro

If you see an error like this:

[source,rust]
----
#[embassy_executor::main]
|                   ^^^^ could not find `main` in `embassy_executor`
----

You are likely missing some features of the `embassy-executor` crate.

For Cortex-M targets, consider making sure that ALL of the following features are active in your `Cargo.toml` for the `embassy-executor` crate:

* `arch-cortex-m`
* `executor-thread`
* `nightly`

For 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 = false
codegen-units = 1
----

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.

== `embassy-time` throws linker errors

If you see linker error like this:

[source,text]
----
  = note: rust-lld: error: undefined symbol: _embassy_time_now
          >>> referenced by driver.rs:127 (src/driver.rs:127)
          >>>               embassy_time-846f66f1620ad42c.embassy_time.4f6a638abb75dd4c-cgu.0.rcgu.o:(embassy_time::driver::now::hefb1f99d6e069842) in archive Devel/Embedded/pogodyna/target/thumbv7em-none-eabihf/debug/deps/libembassy_time-846f66f1620ad42c.rlib

          rust-lld: error: undefined symbol: _embassy_time_allocate_alarm
          >>> referenced by driver.rs:134 (src/driver.rs:134)
          >>>               embassy_time-846f66f1620ad42c.embassy_time.4f6a638abb75dd4c-cgu.0.rcgu.o:(embassy_time::driver::allocate_alarm::hf5145b6bd46706b2) in archive Devel/Embedded/pogodyna/target/thumbv7em-none-eabihf/debug/deps/libembassy_time-846f66f1620ad42c.rlib

          rust-lld: error: undefined symbol: _embassy_time_set_alarm_callback
          >>> referenced by driver.rs:139 (src/driver.rs:139)
          >>>               embassy_time-846f66f1620ad42c.embassy_time.4f6a638abb75dd4c-cgu.0.rcgu.o:(embassy_time::driver::set_alarm_callback::h24f92388d96eafd2) in archive Devel/Embedded/pogodyna/target/thumbv7em-none-eabihf/debug/deps/libembassy_time-846f66f1620ad42c.rlib

          rust-lld: error: undefined symbol: _embassy_time_set_alarm
          >>> referenced by driver.rs:144 (src/driver.rs:144)
          >>>               embassy_time-846f66f1620ad42c.embassy_time.4f6a638abb75dd4c-cgu.0.rcgu.o:(embassy_time::driver::set_alarm::h530a5b1f444a6d5b) in archive Devel/Embedded/pogodyna/target/thumbv7em-none-eabihf/debug/deps/libembassy_time-846f66f1620ad42c.rlib
----

You probably need to enable a time driver for your HAL (not in `embassy-time`!). For example with `embassy-stm32`, you might need to enable `time-driver-any`:

[source,toml]
----
[dependencies.embassy-stm32]
version = "0.1.0"
features = [
    # ...
    "time-driver-any", # Add this line!
    # ...
]
----

== Error: `Only one package in the dependency graph may specify the same links value.`

You have multiple versions of the same crate in your dependency tree. This means that some of your
embassy crates are coming from crates.io, and some from git, each of them pulling in a different set
of dependencies.

To resolve this issue, make sure to only use a single source for all your embassy crates! To do this,
you should patch your dependencies to use git sources using `[patch.crates.io]` and maybe `[patch.'https://github.com/embassy-rs/embassy.git']`.

Example:

[source,toml]
----
[patch.crates-io]
embassy-time = { git = "https://github.com/embassy-rs/embassy.git", rev = "e5fdd35" }
----

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"`
* 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`
    ** 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.

== How do I set up the task arenas on stable?

When you aren't using the `nightly` feature of `embassy-executor`, the executor uses a bump allocator, which may require configuration.

Check out link:https://docs.embassy.dev/embassy-executor/git/cortex-m/index.html#task-arena[Task Arena Documentation] for more details.