Merge #15

15: Start review of exceptions r=japaric a=andre-richter



Co-authored-by: Andre Richter <andre-richter@users.noreply.github.com>

Author: bors[bot]

src/exceptions.md

@@ -1,33 +1,36 @@
 # Exception handling
 
-During the "Memory layout" section we decided to start out simple and leave out handling of
-exceptions. In this section we'll add support for handling exceptions; this serves as an example of
+During the "Memory layout" section, we decided to start out simple and leave out handling of
+exceptions. In this section, we'll add support for handling them; this serves as an example of
 how to achieve compile time overridable behavior in stable Rust (i.e. without relying on the
 unstable `#[linkage = "weak"]` attribute, which makes a symbol weak).
 
 ## Background information
 
 In a nutshell, *exceptions* are a mechanism the Cortex-M and other architectures provide to let
-applications respond to asynchronous, usually external, events. The exception mechanism works like
-this: when the processor receives a signal or event associated to a type of exception it suspends
+applications respond to asynchronous, usually external, events. The most prominent type of exception,
+that most people will know, is the classical (hardware) interrupt.
+
+The Cortex-M exception mechanism works like this:
+When the processor receives a signal or event associated to a type of exception, it suspends
 the execution of the current subroutine (by stashing the state in the call stack) and then proceeds
 to execute the corresponding exception handler, another subroutine, in a new stack frame. After
-finishing the execution of the exception handler (i.e. returning from it) the processor resumes the
+finishing the execution of the exception handler (i.e. returning from it), the processor resumes the
 execution of the suspended subroutine.
 
 The processor uses the vector table to decide what handler to execute. Each entry in the table
 contains a pointer to a handler, and each entry corresponds to a different exception type. For
 example, the second entry is the reset handler, the third entry is the NMI (Non Maskable Interrupt)
 handler, and so on.
 
-As mentioned before the processor expects the vector table to be at some specific location and each
-entry in it can potentially be used by the processor at runtime so they must always contain valid
-values. Furthermore, we want the `rt` crate to be flexible so the end user can customize the
-behavior of each exception handler. Finally, the vector table is read only memory, or rather in not
+As mentioned before, the processor expects the vector table to be at some specific location in memory,
+and each entry in it can potentially be used by the processor at runtime. Hence, the entries must always
+contain valid values. Furthermore, we want the `rt` crate to be flexible so the end user can customize the
+behavior of each exception handler. Finally, the vector table resides in read only memory, or rather in not
 easily modified memory, so the user has to register the handler statically, rather than at runtime.
 
-To satisfy all these constraints we'll assign a *default* value to all the entries of the vector
-table in the `rt` crate but make these values kind of *weak* to let the end user override them
+To satisfy all these constraints, we'll assign a *default* value to all the entries of the vector
+table in the `rt` crate, but make these values kind of *weak* to let the end user override them
 at compile time.
 
 ## Rust side
@@ -36,8 +39,8 @@ Let's see how all this can be implemented. For simplicity, we'll only work with
 of the vector table; these entries are not device specific so they have the same function on any
 kind of Cortex-M microcontroller.
 
-The first thing we'll do is create an array of vectors (pointers to exception handlers) in the Rust
-code:
+The first thing we'll do is create an array of vectors (pointers to exception handlers) in the
+`rt` crate's code:
 
 ``` rust
 pub union Vector {
@@ -83,7 +86,7 @@ should be assigned the value `0` so we use a union to do exactly that. The entri
 to a handler make use of *external* functions; this is important because it lets the end user
 *provide* the actual function definition.
 
-Next we define a default exception handler in the Rust code. Exceptions that have not been assigned
+Next, we define a default exception handler in the Rust code. Exceptions that have not been assigned
 a handler by the end user will make use of this default handler.
 
 ``` rust
@@ -130,8 +133,9 @@ PROVIDE(PendSV = DefaultExceptionHandler);
 PROVIDE(SysTick = DefaultExceptionHandler);
 ```
 
-`PROVIDE` only takes effect when symbol on the RHS is still undefined after inspecting all the input
-object files. This is the scenario where the user didn't assign a handler to the exception.
+`PROVIDE` only takes effect when the symbol to the left of the equal sign is still undefined after
+inspecting all the input object files. This is the scenario where the user didn't implement the
+handler for the respective exception.
 
 ## Testing it
 
@@ -214,9 +218,24 @@ Contents of section .vector_table:
  0030 00000000 00000000 79000000 79000000  ........y...y...
 ```
 
+The vector table now resembles the results of all the code snippets in this book so far. To summarize:
+- In the [_Inspecting it_] section of the earlier memory chapter, we learned that:
+    - The first entry in the vector table contains the initial value of the stack pointer.
+    - Objdump prints in `little endian` format, so the stack starts at `0x2001_0000`.
+    - The second entry points to address `0x0000_0041`, the Reset handler.
+        - The address of the Reset handler can be seen in the disassembly above, being `0x40`.
+        - The first bit being set to 1 does not alter the address due to alignment requirements. Instead, it causes the function to be executed in _thumb mode_.
+- Afterwards, a pattern of addresses alternating between `0x79` and `0x00` is visible.
+    - Looking at the disassembly above, it is clear that `0x79` refers to the `DefaultExceptionHandler` (`0x78` executed in thumb mode).
+    - Cross referencing the pattern to the vector table that was set up earlier in this chapter (see the definition of `pub static EXCEPTIONS`) with [the vector table layout for the Cortex-M], it is clear that the address of the `DefaultExceptionHandler` is present each time a respective handler entry is present in the table.
+    - In turn, it is also visibile that the layout of the vector table data structure in the Rust code is aligned with all the reserved slots in the Cortex-M vector table. Hence, all reserved slots are correctly set to a value of zero. 
+
+[_Inspecting it_]: https://rust-embedded.github.io/embedonomicon/memory-layout.html#inspecting-it
+[the vector table layout for the Cortex-M]: https://developer.arm.com/docs/dui0552/latest/the-cortex-m3-processor/exception-model/vector-table
+
 ## Overriding a handler
 
-To override an exception handler the user has to provide a function whose symbol name exactly
+To override an exception handler, the user has to provide a function whose symbol name exactly
 matches the name we used in `EXCEPTIONS`.
 
 ``` rust
@@ -262,9 +281,9 @@ Process 1 stopped
 The program now executes the user defined `HardFault` function instead of the
 `DefaultExceptionHandler` in the `rt` crate.
 
-Like our first attempt at a `main` interface this first implementation has the problem of having no
+Like our first attempt at a `main` interface, this first implementation has the problem of having no
 type safety. It's also easy to mistype the name of the exception, but that doesn't produce an error
-or warning instead the user defined handler is simply ignored. Those problems can be fixed using a
+or warning. Instead the user defined handler is simply ignored. Those problems can be fixed using a
 macro like the [`exception!`] macro defined in `cortex-m-rt`.
 
 [`exception!`]: https://github.com/japaric/cortex-m-rt/blob/v0.5.1/src/lib.rs#L79