1.. _module-pw_boot: 2 3======= 4pw_boot 5======= 6.. pigweed-module:: 7 :name: pw_boot 8 9``pw_boot`` provides a linker script and some early initialization of static 10memory regions and C++ constructors. This is enough to get many targets booted 11and ready to run C++ code. 12 13This module is split into two components: 14 151. This module, which provides the :ref:`facade <docs-facades>`. 162. A backend module such as :ref:`module-pw_boot_cortex_m` that implements the 17 facade. 18 19.. _module-pw_boot-status: 20 21--------------------- 22Status of this module 23--------------------- 24``pw_boot`` can be used in production if it meets your needs. In practice 25most production projects probably won't use it because they need their own 26custom linker scripts. The ``pw_boot`` source code can still be a useful 27example of how to set up a boot sequence. 28 29.. _module-pw_boot-sequence: 30 31-------- 32Sequence 33-------- 34The high-level ``pw_boot`` sequence looks like the following pseudo-code 35invocation of the user-implemented functions: 36 37.. code-block:: cpp 38 39 void pw_boot_Entry() { // Boot entry point provided by backend. 40 pw_boot_PreStaticMemoryInit(); // User-implemented function. 41 // Static memory initialization. 42 pw_boot_PreStaticConstructorInit(); // User-implemented function. 43 // C++ static constructors are invoked. 44 pw_boot_PreMainInit(); // User-implemented function. 45 main(); // User-implemented function. 46 pw_boot_PostMain(); // User-implemented function. 47 PW_UNREACHABLE; 48 } 49 50.. _module-pw_boot-user: 51 52-------------------------- 53User-implemented functions 54-------------------------- 55This module expects all of the following ``extern "C"`` functions to be defined 56outside this module. If any of these functions are unimplemented, executables 57will encounter a link error. 58 59.. _module-pw_boot-prestaticmemoryinit: 60 61``pw_boot_PreStaticMemoryInit()`` 62--------------------------------- 63Signature: ``void pw_boot_PreStaticMemoryInit()`` 64 65This function executes just before static memory has been zeroed and static 66data is initialized. This function should set up any early initialization that 67should be done before static memory is initialized, such as: 68 69- Enabling the FPU or other coprocessors. 70- Opting into extra restrictions such as disabling unaligned access to ensure 71 the restrictions are active during static RAM initialization. 72- Initial CPU clock, flash, and memory configurations including potentially 73 enabling extra memory regions with ``.bss`` and ``.data`` sections, such as 74 SDRAM or backup powered SRAM. 75- Fault handler initialization if required before static memory 76 initialization. 77 78.. warning:: 79 80 Code running in this hook is violating the C spec as static values are not 81 yet initialized, meaning they have not been loaded (``.data``) nor 82 zero-initialized (``.bss``). 83 84.. _module-pw_boot-prestaticconstructorinit: 85 86``pw_boot_PreStaticConstructorInit()`` 87-------------------------------------- 88Signature: ``void pw_boot_PreStaticConstructorInit()`` 89 90This function executes just before C++ static constructors are called. At this 91point, other static memory has been zero-initialized or data-initialized. This 92function should set up any early initialization that should be done before C++ 93static constructors are run, such as: 94 95- Run time dependencies such as ``malloc``, and ergo sometimes the RTOS. 96- Persistent memory that survives warm reboots. 97- Enabling the MPU to catch ``nullptr`` dereferences during construction. 98- Main stack watermarking. 99- Further fault handling configuration necessary for your platform which 100 was not safe before ``pw_boot_PreStaticRamInit()``. 101- Boot count and/or boot session UUID management. 102 103.. _module-pw_boot-premaininit: 104 105``pw_boot_PreMainInit()`` 106------------------------- 107Signature: ``void pw_boot_PreMainInit()`` 108 109This function executes just before ``main()``, and can be used for any device 110initialization that isn't application-specific. Depending on your platform, 111this might be turning on a UART, setting up default clocks, etc. 112 113.. _module-pw_boot-main: 114 115``main()`` 116---------- 117Signature: ``int main()`` 118 119This is where applications reside. 120 121.. _module-pw_boot-postmain: 122 123``pw_boot_PostMain()`` 124---------------------- 125Signature: ``PW_NO_RETURN void pw_boot_PostMain()`` 126 127This function executes after ``main()`` has returned. This could be used for 128device-specific teardown such as an infinite loop, soft reset, or QEMU 129shutdown. In addition, if relevant for your application, this would be the 130place to invoke the global static destructors. This function must not return! 131 132.. _module-pw_boot-backend: 133 134----------------------------- 135Backend-implemented functions 136----------------------------- 137``pw_boot`` :ref:`backends <docs-facades-definition>` must implement the 138following ``extern "C"`` functions. 139 140.. _module-pw_boot-entry: 141 142``pw_boot_Entry()`` 143------------------- 144Signature: ``void pw_boot_Entry()`` 145 146This function executes as the entry point for the application, and must 147call the :ref:`module-pw_boot-user` in the correct 148:ref:`module-pw_boot-sequence`. 149 150.. _module-pw_boot-dependencies: 151 152------------ 153Dependencies 154------------ 155- :bdg-ref-primary-line:`module-pw_preprocessor` 156 157.. toctree:: 158 :hidden: 159 :maxdepth: 1 160 161 Backends <backends> 162