third_party/pigweed/repo/pw_boot_armv7m/docs.rst

   1 .. _module-pw_boot_armv7m:
   2
   3 --------------
   4 pw_boot_armv7m
   5 --------------
   6
   7 The ARMv7-M boot module provides a linker script and some early initialization
   8 of static memory regions and C++ constructors. This is enough to get many
   9 ARMv7-M cores booted and ready to run C++ code.
  10
  11 This module is currently designed to support a very minimal device memory layout
  12 configuration:
  13
  14  - One contiguous region for RAM.
  15  - One contiguous region for flash.
  16  - Static, in-flash vector table at the default location expected by the SoC.
  17
  18 Note that this module is not yet particularly suited for projects that utilize
  19 a bootloader, as it's relatively opinionated regarding where code is stored.
  20
  21 .. warning::
  22   This module is currently NOT stable! Depending on this module may cause
  23   breakages as this module is updated.
  24
  25 Sequence
  26 ========
  27
  28 The high level pw_boot_armv7m boot sequence looks like the following psuedo-code
  29 invocation of the user-implemented functions:
  30
  31 .. code:: cpp
  32
  33   void pw_boot_Entry() {  // Boot entry point.
  34     pw_boot_PreStaticMemoryInit();  // User-implemented function.
  35     // Static memory initialization.
  36     pw_boot_PreStaticConstructorInit();  // User-implemented function.
  37     // C++ static constructors are invoked.
  38     pw_boot_PreMainInit();  // User-implemented function.
  39     main();  // User-implemented function.
  40     pw_boot_PostMain();  // User-implemented function.
  41     PW_UNREACHABLE;
  42   }
  43
  44 Setup
  45 =====
  46
  47 User-Implemented Functions
  48 --------------------------
  49 This module expects all of these extern "C" functions to be defined outside this
  50 module:
  51
  52  - ``int main()``: This is where applications reside.
  53  - ``void pw_boot_PreStaticMemoryInit()``: This function executes just before
  54    static memory has been zerod and static data is intialized. This function
  55    should set up any early initialization that should be done before static
  56    memory is initialized, such as:
  57
  58    - Enabling the FPU or other coprocessors.
  59    - Opting into extra restrictions such as disabling unaligned access to ensure
  60      the restrictions are active during static RAM initialization.
  61    - Initial CPU clock, flash, and memory configurations including potentially
  62      enabling extra memory regions with .bss and .data sections, such as SDRAM
  63      or backup powered SRAM.
  64    - Fault handler initialization if required before static memory
  65      initialization.
  66
  67    .. warning::
  68      Code running in this hook is violating the C spec as static values are not
  69      yet initialized, meaning they have not been loaded (.data) nor
  70      zero-initialized (.bss).
  71
  72  - ``void pw_boot_PreStaticConstructorInit()``: This function executes just
  73    before C++ static constructors are called. At this point, other static memory
  74    has been zero or data initialized. This function should set up any early
  75    initialization that should be done before C++ static constructors are run,
  76    such as:
  77
  78    - Run time dependencies such as Malloc, and ergo sometimes the RTOS.
  79    - Persistent memory that survives warm reboots.
  80    - Enabling the MPU to catch nullptr dereferences during construction.
  81    - Main stack watermarking.
  82    - Further fault handling configuration necessary for your platform which
  83      were not safe before pw_boot_PreStaticRamInit().
  84    - Boot count and/or boot session UUID management.
  85
  86  - ``void pw_boot_PreMainInit()``: This function executes just before main, and
  87    can be used for any device initialization that isn't application specific.
  88    Depending on your platform, this might be turning on a UART, setting up
  89    default clocks, etc.
  90
  91  - ``PW_NO_RETURN void pw_boot_PostMain()``: This function executes after main
  92    has returned. This could be used for device specific teardown such as an
  93    infinite loop, soft reset, or QEMU shutdown. In addition, if relevant for
  94    your application, this would be the place to invoke the global static
  95    destructors. This function must not return!
  96
  97
  98 If any of these functions are unimplemented, executables will encounter a link
  99 error.
 100
 101 Required Configs
 102 ----------------
 103 This module has a number of required configuration options that mold the linker
 104 script to fit to a wide variety of ARMv7-M SoCs. The ``pw_boot_armv7m_config``
 105 GN variable has a ``defines`` member that can be used to modify these linker
 106 script options. See the documentation section on configuration for information
 107 regarding which configuration options are required.
 108
 109 Vector Table
 110 ------------
 111 Targets using ``pw_boot_armv7m`` will need to provide an ARMv7-M interrupt
 112 vector table (ARMv7-M Architecture Reference Manual DDI 0403E.b section B1.5.2
 113 and B1.5.3). This is done by storing an array into the ``.vector_table``
 114 section, and properly configuring ``PW_BOOT_VECTOR_TABLE_*`` preprocessor
 115 defines to cover the address region your SoC expects the vector table to be
 116 located at (often the beginning of the flash region). If using a bootloader,
 117 ensure VTOR (Vector Table Offset Register) is configured to point to the vector
 118 table. Otherwise, refer to the hardware vendor's documentation to determine
 119 where the vector table should be located such that it resides where VTOR is
 120 initialized to by default.
 121
 122 Example vector table:
 123
 124 .. code-block:: cpp
 125
 126   typedef void (*InterruptHandler)();
 127
 128   PW_KEEP_IN_SECTION(".vector_table")
 129   const InterruptHandler vector_table[] = {
 130       // The starting location of the stack pointer.
 131       // This address is NOT an interrupt handler/function pointer, it is simply
 132       // the address that the main stack pointer should be initialized to. The
 133       // value is reinterpret casted because it needs to be in the vector table.
 134       [0] = reinterpret_cast<InterruptHandler>(&pw_boot_stack_high_addr),
 135
 136       // Reset handler, dictates how to handle reset interrupt. This is the
 137       // address that the Program Counter (PC) is initialized to at boot.
 138       [1] = pw_boot_Entry,
 139
 140       // NMI handler.
 141       [2] = DefaultFaultHandler,
 142       // HardFault handler.
 143       [3] = DefaultFaultHandler,
 144       ...
 145   };
 146
 147 Usage
 148 =====
 149
 150 Publicly exported symbols
 151 -------------------------
 152 The linker script provided by this module exports a number of symbols that
 153 may be used to retrieve the locations of specific memory regions at runtime.
 154 These symbols are declared as ``uint8_t`` variables. The variables themselves
 155 do not contain the addresses, they only reside at the memory location they
 156 reference. To retrieve the memory locations, simply take the reference of the
 157 symbol (e.g. ``&pw_boot_vector_table_addr``).
 158
 159 ``pw_boot_heap_[low/high]_addr``: Beginning and end of the memory range of the heap.
 160 These addresses may be identical, indicating a heap with a size of zero bytes.
 161
 162 ``pw_boot_stack_[low/high]_addr``: Beginning and end of the memory range of the main
 163 stack. This might not be the only stack in the system.
 164
 165 ``pw_boot_vector_table_addr``: Beginning of the ARMv7-M interrupt vector table.
 166
 167 Configuration
 168 =============
 169 These configuration options can be controlled by appending list items to
 170 ``pw_boot_armv7m_LINK_CONFIG_DEFINES`` as part of a Pigweed target
 171 configuration.
 172
 173 ``PW_BOOT_HEAP_SIZE`` (required):
 174 How much memory (in bytes) to reserve for the heap. This can be zero.
 175
 176 ``PW_BOOT_MIN_STACK_SIZE`` (required):
 177 The minimum size reserved for the main stack. If statically allocated memory
 178 begins to cut into the minimum, a link error will be emitted.
 179
 180 ``PW_BOOT_FLASH_BEGIN`` (required):
 181 The start address of the MCU's flash region. This region must NOT include the
 182 vector table. (i.e. if the VECTOR_TABLE is in flash, the flash region
 183 should begin *after* the vtable)
 184
 185 ``PW_BOOT_FLASH_SIZE`` (required):
 186 Size of the flash region in bytes.
 187
 188 ``PW_BOOT_RAM_BEGIN`` (required):
 189 The start address of the MCU's RAM region.
 190
 191 ``PW_BOOT_RAM_SIZE`` (required):
 192 Size of the RAM region in bytes.
 193
 194 ``PW_BOOT_VECTOR_TABLE_BEGIN`` (required):
 195 Address the target MCU expects the link-time vector table to be located at. This
 196 is typically the beginning of the flash region. While the vector table may be
 197 changed later in the boot process, a minimal vector table MUST be present for
 198 the MCU to operate as expected.
 199
 200 ``PW_BOOT_VECTOR_TABLE_SIZE`` (required):
 201 Number of bytes to reserve for the ARMv7-M vector table.
 202
 203 Dependencies
 204 ============
 205   * ``pw_preprocessor`` module