Line data Source code
1 0 : /*
2 : * Copyright (c) 2015 Intel Corporation.
3 : *
4 : * SPDX-License-Identifier: Apache-2.0
5 : */
6 :
7 : #ifndef ZEPHYR_INCLUDE_INIT_H_
8 : #define ZEPHYR_INCLUDE_INIT_H_
9 :
10 : #include <stdint.h>
11 : #include <stddef.h>
12 :
13 : #include <zephyr/sys/util.h>
14 : #include <zephyr/toolchain.h>
15 :
16 : #ifdef __cplusplus
17 : extern "C" {
18 : #endif
19 :
20 : /**
21 : * @defgroup sys_init System Initialization
22 : * @ingroup os_services
23 : *
24 : * Zephyr offers an infrastructure to call initialization code before `main`.
25 : * Such initialization calls can be registered using SYS_INIT() or
26 : * SYS_INIT_NAMED() macros. By using a combination of initialization levels and
27 : * priorities init sequence can be adjusted as needed. The available
28 : * initialization levels are described, in order, below:
29 : *
30 : * - `EARLY`: Used very early in the boot process, right after entering the C
31 : * domain (``z_cstart()``). This can be used in architectures and SoCs that
32 : * extend or implement architecture code and use drivers or system services
33 : * that have to be initialized before the Kernel calls any architecture
34 : * specific initialization code.
35 : * - `PRE_KERNEL_1`: Executed in Kernel's initialization context, which uses
36 : * the interrupt stack. At this point Kernel services are not yet available.
37 : * - `PRE_KERNEL_2`: Same as `PRE_KERNEL_1`.
38 : * - `POST_KERNEL`: Executed after Kernel is alive. From this point on, Kernel
39 : * primitives can be used.
40 : * - `APPLICATION`: Executed just before application code (`main`).
41 : * - `SMP`: Only available if @kconfig{CONFIG_SMP} is enabled, specific for
42 : * SMP.
43 : *
44 : * Initialization priority can take a value in the range of 0 to 999.
45 : *
46 : * @note The same infrastructure is used by devices.
47 : * @{
48 : */
49 :
50 : struct device;
51 :
52 : /**
53 : * @brief Structure to store initialization entry information.
54 : *
55 : * @internal
56 : * Init entries need to be defined following these rules:
57 : *
58 : * - Their name must be set using Z_INIT_ENTRY_NAME().
59 : * - They must be placed in a special init section, given by
60 : * Z_INIT_ENTRY_SECTION().
61 : * - They must be aligned, e.g. using Z_DECL_ALIGN().
62 : *
63 : * See SYS_INIT_NAMED() for an example.
64 : * @endinternal
65 : */
66 1 : struct init_entry {
67 : /**
68 : * If the init function belongs to a SYS_INIT, this field stored the
69 : * initialization function, otherwise it is set to NULL.
70 : */
71 1 : int (*init_fn)(void);
72 : /**
73 : * If the init entry belongs to a device, this fields stores a
74 : * reference to it, otherwise it is set to NULL.
75 : */
76 1 : const struct device *dev;
77 : };
78 :
79 : /** @cond INTERNAL_HIDDEN */
80 :
81 : /* Helper definitions to evaluate level equality */
82 : #define Z_INIT_EARLY_EARLY 1
83 : #define Z_INIT_PRE_KERNEL_1_PRE_KERNEL_1 1
84 : #define Z_INIT_PRE_KERNEL_2_PRE_KERNEL_2 1
85 : #define Z_INIT_POST_KERNEL_POST_KERNEL 1
86 : #define Z_INIT_APPLICATION_APPLICATION 1
87 : #define Z_INIT_SMP_SMP 1
88 :
89 : /* Init level ordinals */
90 : #define Z_INIT_ORD_EARLY 0
91 : #define Z_INIT_ORD_PRE_KERNEL_1 1
92 : #define Z_INIT_ORD_PRE_KERNEL_2 2
93 : #define Z_INIT_ORD_POST_KERNEL 3
94 : #define Z_INIT_ORD_APPLICATION 4
95 : #define Z_INIT_ORD_SMP 5
96 :
97 : /**
98 : * @brief Obtain init entry name.
99 : *
100 : * @param init_id Init entry unique identifier.
101 : */
102 : #define Z_INIT_ENTRY_NAME(init_id) _CONCAT(__init_, init_id)
103 :
104 : /**
105 : * @brief Init entry section.
106 : *
107 : * Each init entry is placed in a section with a name crafted so that it allows
108 : * linker scripts to sort them according to the specified
109 : * level/priority/sub-priority.
110 : */
111 : #define Z_INIT_ENTRY_SECTION(level, prio, sub_prio) \
112 : __attribute__((__section__( \
113 : ".z_init_" #level "_P_" STRINGIFY(prio) "_SUB_" STRINGIFY(sub_prio)"_")))
114 :
115 : /** @endcond */
116 :
117 : /**
118 : * @brief Obtain the ordinal for an init level.
119 : *
120 : * @param level Init level (EARLY, PRE_KERNEL_1, PRE_KERNEL_2, POST_KERNEL,
121 : * APPLICATION, SMP).
122 : *
123 : * @return Init level ordinal.
124 : */
125 1 : #define INIT_LEVEL_ORD(level) \
126 : COND_CODE_1(Z_INIT_EARLY_##level, (Z_INIT_ORD_EARLY), \
127 : (COND_CODE_1(Z_INIT_PRE_KERNEL_1_##level, (Z_INIT_ORD_PRE_KERNEL_1), \
128 : (COND_CODE_1(Z_INIT_PRE_KERNEL_2_##level, (Z_INIT_ORD_PRE_KERNEL_2), \
129 : (COND_CODE_1(Z_INIT_POST_KERNEL_##level, (Z_INIT_ORD_POST_KERNEL), \
130 : (COND_CODE_1(Z_INIT_APPLICATION_##level, (Z_INIT_ORD_APPLICATION), \
131 : (COND_CODE_1(Z_INIT_SMP_##level, (Z_INIT_ORD_SMP), \
132 : (ZERO_OR_COMPILE_ERROR(0)))))))))))))
133 :
134 : /**
135 : * @brief Register an initialization function.
136 : *
137 : * The function will be called during system initialization according to the
138 : * given level and priority.
139 : *
140 : * @param init_fn Initialization function.
141 : * @param level Initialization level. Allowed tokens: `EARLY`, `PRE_KERNEL_1`,
142 : * `PRE_KERNEL_2`, `POST_KERNEL`, `APPLICATION` and `SMP` if
143 : * @kconfig{CONFIG_SMP} is enabled.
144 : * @param prio Initialization priority within @p _level. Note that it must be a
145 : * decimal integer literal without leading zeroes or sign (e.g. `32`), or an
146 : * equivalent symbolic name (e.g. `#define MY_INIT_PRIO 32`); symbolic
147 : * expressions are **not** permitted (e.g.
148 : * `CONFIG_KERNEL_INIT_PRIORITY_DEFAULT + 5`).
149 : */
150 1 : #define SYS_INIT(init_fn, level, prio) \
151 : SYS_INIT_NAMED(init_fn, init_fn, level, prio)
152 :
153 : /**
154 : * @brief Register an initialization function (named).
155 : *
156 : * @note This macro can be used for cases where the multiple init calls use the
157 : * same init function.
158 : *
159 : * @param name Unique name for SYS_INIT entry.
160 : * @param init_fn_ See SYS_INIT().
161 : * @param level See SYS_INIT().
162 : * @param prio See SYS_INIT().
163 : *
164 : * @see SYS_INIT()
165 : */
166 1 : #define SYS_INIT_NAMED(name, init_fn_, level, prio) \
167 : static const Z_DECL_ALIGN(struct init_entry) \
168 : Z_INIT_ENTRY_SECTION(level, prio, 0) __used __noasan \
169 : Z_INIT_ENTRY_NAME(name) = {.init_fn = (init_fn_), .dev = NULL} \
170 :
171 : /** @} */
172 :
173 : #ifdef __cplusplus
174 : }
175 : #endif
176 :
177 : #endif /* ZEPHYR_INCLUDE_INIT_H_ */
|
