From 5844f5ce2d704058312ea607eb976e438ad990cb Mon Sep 17 00:00:00 2001
From: Adin Ackerman <adinackerman@gmail.com>
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 <adinackerman@gmail.com>
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 <adinackerman@gmail.com>
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 <bugadani@gmail.com>
---
 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 <adinackerman@gmail.com>
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 <bugadani@gmail.com>
---
 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