didactic changes

embedded-workshop-book/src/binary-size.md

@@ -2,10 +2,18 @@
 
 ELF files contain metadata like debug information so their size on disk is not a good indication of the amount of Flash the program will use once it's loaded on the target device's memory.
 
-To display the amount of Flash the program will occupy on the target device use the `cargo-size` tool (part of the `cargo-binutils` package):
+To display the amount of Flash the program will occupy on the target device use the `cargo-size` tool, which is part of the `cargo-binutils` package.
+
+✅ Use the following command to print the binary's size in system V format.
 
 ``` console
 $ cargo size --bin hello -- -A
+```
+
+Expected output:
+The breakdown of the program's static memory usage per *linker section*.
+
+``` console
 hello  :
 section              size        addr
 .vector_table         256         0x0
@@ -16,9 +24,12 @@ section              size        addr
 .uninit                 0  0x20000854
 ```
 
-This gives you a breakdown of the program's static memory usage per *linker section*.
+**🔎 More details about each linker section:**
 
-The `.vector_table` section contains the *vector table*, a data structure required by the Cortex-M ISA. The `.text` section contains the instructions the program will execute. The `.rodata` section contains constants like strings literals. These three sections are contiguously located in Flash memory -- Flash memory spans from address `0x0000_0000` to `0x0010_0000` (1 MB).
+The first three sections are contiguously located in Flash memory -- Flash memory spans from address `0x0000_0000` to `0x0010_0000` (1 MB).
+* The `.vector_table` section contains the *vector table*, a data structure required by the Cortex-M ISA. 
+* The `.text` section contains the instructions the program will execute. 
+* The `.rodata` section contains constants like strings literals. 
 
 The next three sections, `.data`, `.bss` and `.uninit`, are located in RAM -- RAM memory spans the address range `0x2000_0000` - `0x2004_0000` (256 KB). These sections contain statically allocated variables (`static` variables).
 

embedded-workshop-book/src/building-program.md

@@ -1,12 +1,6 @@
 # Building an Embedded Program
 
-The following command cross compiles the program to the ARM Cortex-M4 architecture.
-
-``` console
-$ cargo build --bin hello
-```
-
-The default in a Cargo project is to compile for the host (native compilation) but the `beginner/apps` project has been configured for cross compilation. This configuration can be seen in the Cargo configuration file (`.cargo/config`):
+The default in a Cargo project is to compile for the host (native compilation). The `beginner/apps` project has been configured for cross compilation to the ARM Cortex-M4 architecture. This configuration can be seen in the Cargo configuration file (`.cargo/config`):
 
 ``` text
 # .cargo/config
@@ -14,9 +8,18 @@ The default in a Cargo project is to compile for the host (native compilation) b
 target = "thumbv7em-none-eabi" # = ARM Cortex-M4
 ```
 
+✅ Inside the folder `beginner/apps`, use the following command to cross compile the program to the ARM Cortex-M4 architecture.
+
+``` console
+$ cargo build --bin hello
+```
+
 The output of the compilation process will be an ELF (Executable and Linkable Format) file. The file will be placed in the `target/thumbv7em-none-eabi` directory.
 
+✅ Run `$ file target/thumbv7em-none-eabi/debug/hello` and compare if your output is as expected.
+
+Expected output:
 ``` console
 $ file target/thumbv7em-none-eabi/debug/hello
 hello: ELF 32-bit LSB executable, ARM, EABI5 version 1 (SYSV), statically linked, with debug_info, not stripped
-```
+```

embedded-workshop-book/src/flashing-program.md

@@ -1,12 +1,12 @@
 # Flashing the Program
 
-The following command will flash the ELF file to the device.
+✅ Use the following command to flash the ELF file to the device.
 
 ``` console
 $ cargo flash --chip nRF52840_xxAA --elf target/thumbv7em-none-eabi/debug/hello
 ```
 
-> NOTE if you run into an error along the lines of "Debug power request failed" retry the operation and the error should disappear
+> NOTE: If you run into an error along the lines of "Debug power request failed" retry the operation and the error should disappear.
 
 Alternatively you can run this command, which builds the application before flashing it.
 
@@ -16,4 +16,6 @@ $ cargo flash --chip nRF52840_xxAA --bin hello
 
 The `cargo-flash` subcommand flashes and runs the program but won't display logs. It is a deployment tool.
 
+**🔎 How does flashing work?**
+
 The flashing process consists of the PC communicating with a second microcontroller on the nRF52840 DK over USB (J2 port). This second microcontroller, named J-Link, is connected to the nRF52840 through a electrical interface known as JTAG. The JTAG protocol specifies procedures for reading memory, writing to memory, halting the target processor, reading the target processor registers, etc.

embedded-workshop-book/src/parts-embedded-program.md

@@ -1,26 +1,35 @@
 # Parts of an Embedded Program
 
-[❗️Intro ]
-Open the `beginner/apps` folder in VS Code.
+We will look at the elements that distinguish an embedded Rust program from a desktop program.
+
+
+✅ Open the `beginner/apps` folder in VS Code.
 
 ``` console
 $ # or use "File > Open Folder" in VS Code
 $ code beginner/apps
 ```
 
-Then open the `src/bin/hello.rs` file.
+✅ Then open the `src/bin/hello.rs` file.
 
-If you find it more convenient to open the repository at the root then please also add the `beginner/apps` folder to the VS Code workspace: right click the left side panel, select "Add folder to workspace" and add the `beginner/apps` folder.
-[❗️No optional way of doing things here]
 
-Note the differences between this embedded program and a desktop program:
 
-[❗️Have a non embedded program up to compare]
+> NOTE: If you find it more convenient to open the repository at the root then please also add the `beginner/apps` folder to the VS Code workspace: right click the left side panel, select "Add folder to workspace" and add the `beginner/apps` folder.
 
- The `#![no_std]` attribute indicates that the program will not make use of the standard library, `std` crate. Instead it will use the `core` library, a subset of the standard library that does depend not on a underlying operating system (OS).
+
+
+## In the file, you will find the following attributes:
+
+### `#![no_std]`
+
+ The `#![no_std]` attribute indicates that the program will not make use of the standard library, the `std` crate. Instead it will use the `core` library, a subset of the standard library that does not depend on an underlying operating system (OS).
+
+### `#![no_main]`
 
 The `#![no_main]` attribute indicates that the program will use a custom entry point instead of the default `fn main() { .. }` one.
 
-The `#[entry]` attribute declares the custom entry point of the program. The entry point must be a divergent function; note that the return type is the never type `!`. The function is not allowed to return; therefore the program is not allowed to terminate.
+### `#[entry]`
+
+The `#[entry]` attribute declares the custom entry point of the program. The entry point must be a divergent function whose return type is the never type `!`. The function is not allowed to return; therefore the program is not allowed to terminate.