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 PW_EXTERN_C_START 25 26 // Forward declaration of main. Pigweed applications are expected to implement 27 // this function. An implementation of main() should NOT be provided by a 28 // backend. 29 int main(void); 30 31 // Reset handler or boot entry point. 32 // 33 // Backends must provide this method, and this method must call the user 34 // supplied functions below in the appropriate order, along with any other 35 // early initialization required by the target. 36 // 37 // A minimal implementation would be: 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 PW_NO_RETURN void pw_boot_Entry(void); 50 51 // pw_boot hook: Before static memory is initialized (user supplied) 52 // 53 // This is a hook function that users of pw_boot must supply. It is called 54 // immediately upon entry to pw_boot_Entry() and before zero initialization of 55 // RAM (.bss) and loading values into static memory (commonly labeled as the 56 // .data section in an ELF file). 57 // WARNING: Be EXTREMELY careful when in the context of this function as it 58 // violates the C spec in several ways as .bss has not yet been zero-initialized 59 // and static values have not yet been loaded into memory. This function should 60 // NOT be implemented by a pw_boot backend. 61 // 62 // Interrupts are disabled until after this function returns. 63 void pw_boot_PreStaticMemoryInit(void); 64 65 // pw_boot hook: Before C++ static constructors are invoked (user supplied). 66 // 67 // This is a hook function that users of pw_boot must supply. It is called just 68 // after zero initialization of RAM and loading values into static memory 69 // (commonly labeled as the .data section in an ELF file). Per the naming, this 70 // function is called just before C++ static constructors are invoked. It is 71 // safe to run C code, but NOT safe to call out to any C++ code. This function 72 // should NOT be implemented by a pw_boot backend. 73 void pw_boot_PreStaticConstructorInit(void); 74 75 // pw_boot hook: Before main is invoked (user supplied). 76 // 77 // This is a hook function that users of pw_boot must supply. It is called by 78 // pw_boot_Entry() after memory initialization but before main. This allows 79 // targets to have pre-main initialization of the device and seamlessly swap out 80 // the main() implementation. This function should NOT be implemented by 81 // a pw_boot backend. 82 void pw_boot_PreMainInit(void); 83 84 // pw_boot hook: After main returned (user supplied). 85 // 86 // This is a hook function that users of pw_boot must supply. It is called by 87 // pw_boot_Entry() after main() has returned. This function must not return! 88 // This function should NOT be implemented by a pw_boot backend. 89 PW_NO_RETURN void pw_boot_PostMain(void); 90 91 PW_EXTERN_C_END 92