1 // Copyright 2021 The Pigweed Authors 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); you may not 4 // use this file except in compliance with the License. You may obtain a copy of 5 // the License at 6 // 7 // https://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 11 // WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the 12 // License for the specific language governing permissions and limitations under 13 // the License. 14 #pragma once 15 16 // A pw_boot backend is similar to a traditional assembly startup file paired 17 // with a linker script. 18 19 #include <stdint.h> 20 21 #include "pw_preprocessor/compiler.h" 22 #include "pw_preprocessor/util.h" 23 24 // Forward declaration of main. Pigweed applications are expected to implement 25 // this function. An implementation of main() should NOT be provided by a 26 // backend. 27 // Ensure that this forward declaration is not inside the extern "C" block, 28 // to avoid a clang pedantic warning. 29 int main(void); 30 31 PW_EXTERN_C_START 32 33 // Reset handler or boot entry point. 34 // 35 // Backends must provide this method, and this method must call the user 36 // supplied functions below in the appropriate order, along with any other 37 // early initialization required by the target. 38 // 39 // A minimal implementation would be: 40 // 41 // void pw_boot_Entry() { // Boot entry point provided by backend. 42 // pw_boot_PreStaticMemoryInit(); // User-implemented function. 43 // // Static memory initialization. 44 // pw_boot_PreStaticConstructorInit(); // User-implemented function. 45 // // C++ static constructors are invoked. 46 // pw_boot_PreMainInit(); // User-implemented function. 47 // main(); // User-implemented function. 48 // pw_boot_PostMain(); // User-implemented function. 49 // PW_UNREACHABLE; 50 // } 51 PW_NO_RETURN void pw_boot_Entry(void); 52 53 // pw_boot hook: Before static memory is initialized (user supplied) 54 // 55 // This is a hook function that users of pw_boot must supply. It is called 56 // immediately upon entry to pw_boot_Entry() and before zero initialization of 57 // RAM (.bss) and loading values into static memory (commonly labeled as the 58 // .data section in an ELF file). 59 // WARNING: Be EXTREMELY careful when in the context of this function as it 60 // violates the C spec in several ways as .bss has not yet been zero-initialized 61 // and static values have not yet been loaded into memory. This function should 62 // NOT be implemented by a pw_boot backend. 63 // 64 // Interrupts are disabled until after this function returns. 65 void pw_boot_PreStaticMemoryInit(void); 66 67 // pw_boot hook: Before C++ static constructors are invoked (user supplied). 68 // 69 // This is a hook function that users of pw_boot must supply. It is called just 70 // after zero initialization of RAM and loading values into static memory 71 // (commonly labeled as the .data section in an ELF file). Per the naming, this 72 // function is called just before C++ static constructors are invoked. It is 73 // safe to run C code, but NOT safe to call out to any C++ code. This function 74 // should NOT be implemented by a pw_boot backend. 75 void pw_boot_PreStaticConstructorInit(void); 76 77 // pw_boot hook: Before main is invoked (user supplied). 78 // 79 // This is a hook function that users of pw_boot must supply. It is called by 80 // pw_boot_Entry() after memory initialization but before main. This allows 81 // targets to have pre-main initialization of the device and seamlessly swap out 82 // the main() implementation. This function should NOT be implemented by 83 // a pw_boot backend. 84 void pw_boot_PreMainInit(void); 85 86 // pw_boot hook: After main returned (user supplied). 87 // 88 // This is a hook function that users of pw_boot must supply. It is called by 89 // pw_boot_Entry() after main() has returned. This function must not return! 90 // This function should NOT be implemented by a pw_boot backend. 91 PW_NO_RETURN void pw_boot_PostMain(void); 92 93 PW_EXTERN_C_END 94