Scott James Remnant | fa7f123 | 2021-07-21 15:25:39 -0700 | [diff] [blame] | 1 | .. _module-pw_boot: |
| 2 | |
| 3 | ------- |
| 4 | pw_boot |
| 5 | ------- |
Scott James Remnant | fa7f123 | 2021-07-21 15:25:39 -0700 | [diff] [blame] | 6 | Pigweed's boot module should provide a linker script and some early |
| 7 | initialization of static memory regions and C++ constructors. This is enough to |
| 8 | get many targets booted and ready to run C++ code. |
| 9 | |
| 10 | This module is split into two components: |
| 11 | |
| 12 | 1. The facade (this module) which declares the symbols exported by the backend |
| 13 | 2. The backend, provided elsewhere, that provides the implementation |
| 14 | |
| 15 | .. warning:: |
| 16 | This module is currently NOT stable! Depending on this module may cause |
| 17 | breakages as this module is updated. |
| 18 | |
| 19 | Sequence |
| 20 | ======== |
Scott James Remnant | fa7f123 | 2021-07-21 15:25:39 -0700 | [diff] [blame] | 21 | The high level pw_boot boot sequence looks like the following pseudo-code |
| 22 | invocation of the user-implemented functions: |
| 23 | |
| 24 | .. code:: cpp |
| 25 | |
| 26 | void pw_boot_Entry() { // Boot entry point provided by backend. |
| 27 | pw_boot_PreStaticMemoryInit(); // User-implemented function. |
| 28 | // Static memory initialization. |
| 29 | pw_boot_PreStaticConstructorInit(); // User-implemented function. |
| 30 | // C++ static constructors are invoked. |
| 31 | pw_boot_PreMainInit(); // User-implemented function. |
| 32 | main(); // User-implemented function. |
| 33 | pw_boot_PostMain(); // User-implemented function. |
| 34 | PW_UNREACHABLE; |
| 35 | } |
| 36 | |
| 37 | Setup |
| 38 | ===== |
| 39 | |
| 40 | User-Implemented Functions |
| 41 | -------------------------- |
| 42 | This module expects all of these extern "C" functions to be defined outside this |
| 43 | module: |
| 44 | |
| 45 | - ``int main()``: This is where applications reside. |
| 46 | - ``void pw_boot_PreStaticMemoryInit()``: This function executes just before |
| 47 | static memory has been zeroed and static data is intialized. This function |
| 48 | should set up any early initialization that should be done before static |
| 49 | memory is initialized, such as: |
| 50 | |
| 51 | - Enabling the FPU or other coprocessors. |
| 52 | - Opting into extra restrictions such as disabling unaligned access to ensure |
| 53 | the restrictions are active during static RAM initialization. |
| 54 | - Initial CPU clock, flash, and memory configurations including potentially |
| 55 | enabling extra memory regions with .bss and .data sections, such as SDRAM |
| 56 | or backup powered SRAM. |
| 57 | - Fault handler initialization if required before static memory |
| 58 | initialization. |
| 59 | |
| 60 | .. warning:: |
| 61 | Code running in this hook is violating the C spec as static values are not |
| 62 | yet initialized, meaning they have not been loaded (.data) nor |
| 63 | zero-initialized (.bss). |
| 64 | |
| 65 | - ``void pw_boot_PreStaticConstructorInit()``: This function executes just |
| 66 | before C++ static constructors are called. At this point, other static memory |
| 67 | has been zero or data initialized. This function should set up any early |
| 68 | initialization that should be done before C++ static constructors are run, |
| 69 | such as: |
| 70 | |
| 71 | - Run time dependencies such as Malloc, and ergo sometimes the RTOS. |
| 72 | - Persistent memory that survives warm reboots. |
| 73 | - Enabling the MPU to catch nullptr dereferences during construction. |
| 74 | - Main stack watermarking. |
| 75 | - Further fault handling configuration necessary for your platform which |
| 76 | were not safe before pw_boot_PreStaticRamInit(). |
| 77 | - Boot count and/or boot session UUID management. |
| 78 | |
| 79 | - ``void pw_boot_PreMainInit()``: This function executes just before main, and |
| 80 | can be used for any device initialization that isn't application specific. |
| 81 | Depending on your platform, this might be turning on a UART, setting up |
| 82 | default clocks, etc. |
| 83 | |
| 84 | - ``PW_NO_RETURN void pw_boot_PostMain()``: This function executes after main |
| 85 | has returned. This could be used for device specific teardown such as an |
| 86 | infinite loop, soft reset, or QEMU shutdown. In addition, if relevant for |
| 87 | your application, this would be the place to invoke the global static |
| 88 | destructors. This function must not return! |
| 89 | |
| 90 | |
| 91 | If any of these functions are unimplemented, executables will encounter a link |
| 92 | error. |
| 93 | |
| 94 | Backend-Implemented Functions |
| 95 | ----------------------------- |
| 96 | Backends for this module must implement the following extern "C" function: |
| 97 | |
| 98 | - ``void pw_boot_Entry()``: This function executes as the entry point for |
| 99 | the application, and must perform call the user defined methods in the |
| 100 | appropriate sequence for the target (see Sequence above). |
| 101 | |
| 102 | Dependencies |
| 103 | ============ |
| 104 | * ``pw_preprocessor`` module |