pw_boot#

Pigweed AI summary: Pigweed's boot module provides a linker script and early initialization of static memory regions and C++ constructors to boot targets and run C++ code. The module is split into a facade and a backend, with the backend providing the implementation. The boot sequence includes user-implemented functions such as PreStaticMemoryInit, PreStaticConstructorInit, PreMainInit, and PostMain. Backends must implement the Entry function as the entry point for the application. Unimplemented functions will result in link errors.

Pigweed’s boot module should provide a linker script and some early initialization of static memory regions and C++ constructors. This is enough to get many targets booted and ready to run C++ code.

This module is split into two components:

  1. The facade (this module) which declares the symbols exported by the backend

  2. The backend, provided elsewhere, that provides the implementation

Warning

This module is currently NOT stable! Depending on this module may cause breakages as this module is updated.

Sequence#

Pigweed AI summary: The high level pw_boot boot sequence includes the invocation of user-implemented functions such as pw_boot_PreStaticMemoryInit(), pw_boot_PreStaticConstructorInit(), pw_boot_PreMainInit(), main(), and pw_boot_PostMain(). These functions are called in a specific order to initialize static memory and invoke C++ static constructors before executing the main function. The sequence ends with the pw_boot_PostMain() function and a PW_UNREACHABLE statement.

The high level pw_boot boot sequence looks like the following pseudo-code invocation of the user-implemented functions:

void pw_boot_Entry() {  // Boot entry point provided by backend.
  pw_boot_PreStaticMemoryInit();  // User-implemented function.
  // Static memory initialization.
  pw_boot_PreStaticConstructorInit();  // User-implemented function.
  // C++ static constructors are invoked.
  pw_boot_PreMainInit();  // User-implemented function.
  main();  // User-implemented function.
  pw_boot_PostMain();  // User-implemented function.
  PW_UNREACHABLE;
}

Setup#

Pigweed AI summary: This document outlines the setup requirements for a module, including the user-implemented functions that must be defined outside the module, such as "int main()" and "void pw_boot_PreStaticMemoryInit()". The document also lists backend-implemented functions that must be implemented, including "void pw_boot_Entry()", which serves as the entry point for the application. If any of these functions are not implemented, link errors will occur. The document provides details on the specific tasks that each function should perform.

User-Implemented Functions#

Pigweed AI summary: This module requires the implementation of several "extern C" functions outside of the module, including "int main()", "void pw_boot_PreStaticMemoryInit()", "void pw_boot_PreStaticConstructorInit()", "void pw_boot_PreMainInit()", and "PW_NO_RETURN void pw_boot_PostMain()". These functions are responsible for various initialization tasks such as setting up memory configurations, enabling coprocessors, and invoking global static destructors. If any of these functions are not implemented, link errors will occur

This module expects all of these extern “C” functions to be defined outside this module:

  • int main(): This is where applications reside.

  • void pw_boot_PreStaticMemoryInit(): This function executes just before static memory has been zeroed and static data is intialized. This function should set up any early initialization that should be done before static memory is initialized, such as:

    • Enabling the FPU or other coprocessors.

    • Opting into extra restrictions such as disabling unaligned access to ensure the restrictions are active during static RAM initialization.

    • Initial CPU clock, flash, and memory configurations including potentially enabling extra memory regions with .bss and .data sections, such as SDRAM or backup powered SRAM.

    • Fault handler initialization if required before static memory initialization.

    Warning

    Code running in this hook is violating the C spec as static values are not yet initialized, meaning they have not been loaded (.data) nor zero-initialized (.bss).

  • void pw_boot_PreStaticConstructorInit(): This function executes just before C++ static constructors are called. At this point, other static memory has been zero or data initialized. This function should set up any early initialization that should be done before C++ static constructors are run, such as:

    • Run time dependencies such as Malloc, and ergo sometimes the RTOS.

    • Persistent memory that survives warm reboots.

    • Enabling the MPU to catch nullptr dereferences during construction.

    • Main stack watermarking.

    • Further fault handling configuration necessary for your platform which were not safe before pw_boot_PreStaticRamInit().

    • Boot count and/or boot session UUID management.

  • void pw_boot_PreMainInit(): This function executes just before main, and can be used for any device initialization that isn’t application specific. Depending on your platform, this might be turning on a UART, setting up default clocks, etc.

  • PW_NO_RETURN void pw_boot_PostMain(): This function executes after main has returned. This could be used for device specific teardown such as an infinite loop, soft reset, or QEMU shutdown. In addition, if relevant for your application, this would be the place to invoke the global static destructors. This function must not return!

If any of these functions are unimplemented, executables will encounter a link error.

Backend-Implemented Functions#

Pigweed AI summary: Backends for this module must implement the "pw_boot_Entry()" function as the entry point for the application, which must call the user-defined methods in the appropriate sequence for the target.

Backends for this module must implement the following extern “C” function:

  • void pw_boot_Entry(): This function executes as the entry point for the application, and must perform call the user defined methods in the appropriate sequence for the target (see Sequence above).

Dependencies#

Pigweed AI summary: This paragraph discusses the dependencies of a certain module called "pw_preprocessor".