1 /* SPDX-License-Identifier: GPL-2.0-only */
2 #ifndef PROGRAM_LOADING_H
3 #define PROGRAM_LOADING_H
4
5 #include <bootmem.h>
6 #include <commonlib/bsd/cbfs_serialized.h>
7 #include <commonlib/region.h>
8 #include <types.h>
9
10 enum {
11 /* Last segment of program. Can be used to take different actions for
12 * cache maintenance of a program load. */
13 SEG_FINAL = 1 << 0,
14 };
15
16 enum prog_type {
17 PROG_UNKNOWN,
18 PROG_BOOTBLOCK,
19 PROG_VERSTAGE,
20 PROG_ROMSTAGE,
21 PROG_RAMSTAGE,
22 PROG_REFCODE,
23 PROG_PAYLOAD,
24 PROG_BL31,
25 PROG_BL32,
26 PROG_POSTCAR,
27 PROG_OPENSBI,
28 };
29
30 /*
31 * prog_segment_loaded() is called for each segment of a program loaded. The
32 * SEG_FINAL flag will be set on the last segment loaded. The following two
33 * functions, platform_segment_loaded() and arch_segment_loaded(), are called
34 * in that order within prog_segment_loaded(). In short, rely on
35 * prog_segment_loaded() to perform the proper dispatch sequence.
36 */
37 void prog_segment_loaded(uintptr_t start, size_t size, int flags);
38 void platform_segment_loaded(uintptr_t start, size_t size, int flags);
39 void arch_segment_loaded(uintptr_t start, size_t size, int flags);
40
41 /* Representation of a program. */
42 struct prog {
43 enum prog_type type;
44 enum cbfs_type cbfs_type;
45 const char *name;
46 void *start; /* Program start in memory. */
47 size_t size; /* Program size in memory (including BSS). */
48 void (*entry)(void *); /* Function pointer to entry point. */
49 void *arg; /* Optional argument (only valid for some archs). */
50 };
51
52 #define PROG_INIT(type_, name_) \
53 { \
54 .type = (type_), \
55 .name = (name_), \
56 }
57
prog_name(const struct prog * prog)58 static inline const char *prog_name(const struct prog *prog)
59 {
60 return prog->name;
61 }
62
prog_type(const struct prog * prog)63 static inline enum prog_type prog_type(const struct prog *prog)
64 {
65 return prog->type;
66 }
67
prog_cbfs_type(const struct prog * prog)68 static inline enum cbfs_type prog_cbfs_type(const struct prog *prog)
69 {
70 return prog->cbfs_type;
71 }
72
prog_size(const struct prog * prog)73 static inline size_t prog_size(const struct prog *prog)
74 {
75 return prog->size;
76 }
77
prog_start(const struct prog * prog)78 static inline void *prog_start(const struct prog *prog)
79 {
80 return prog->start;
81 }
82
prog_entry(const struct prog * prog)83 static inline void *prog_entry(const struct prog *prog)
84 {
85 return prog->entry;
86 }
87
prog_entry_arg(const struct prog * prog)88 static inline void *prog_entry_arg(const struct prog *prog)
89 {
90 return prog->arg;
91 }
92
93 /* Can be used to get an rdev representation of program area in memory. */
prog_chain_rdev(const struct prog * prog,struct region_device * rdev_out)94 static inline void prog_chain_rdev(const struct prog *prog,
95 struct region_device *rdev_out)
96 {
97 rdev_chain_mem(rdev_out, prog->start, prog->size);
98 }
99
prog_set_area(struct prog * prog,void * start,size_t size)100 static inline void prog_set_area(struct prog *prog, void *start, size_t size)
101 {
102 prog->start = start;
103 prog->size = size;
104 }
105
prog_set_entry(struct prog * prog,void * e,void * arg)106 static inline void prog_set_entry(struct prog *prog, void *e, void *arg)
107 {
108 prog->entry = e;
109 prog->arg = arg;
110 }
111
prog_set_arg(struct prog * prog,void * arg)112 static inline void prog_set_arg(struct prog *prog, void *arg)
113 {
114 prog->arg = arg;
115 }
116
117 /* The prog_locate_hook() is called prior to CBFS traversal. The hook can be
118 * used to implement policy that allows or prohibits further program loading.
119 * The type and name field within struct prog are the only valid fields. A 0
120 * return value allows loading while a non-zero return value prohibits it. */
121 int prog_locate_hook(struct prog *prog);
122
123 /* Run the program described by prog. */
124 void prog_run(struct prog *prog);
125 /* Per architecture implementation running a program. */
126 void arch_prog_run(struct prog *prog);
127 /* Platform (SoC/chipset) specific overrides for running a program. This is
128 * called prior to calling the arch_prog_run. Thus, if there is anything
129 * special that needs to be done by the platform similar to the architecture
130 * code it needs to that as well. */
131 void platform_prog_run(struct prog *prog);
132
133 /************************
134 * ROMSTAGE LOADING *
135 ************************/
136
137 /* Run romstage from bootblock. */
138 void run_romstage(void);
139
140 /* Runtime selector for CBFS_PREFIX of romstage. */
141 enum cb_err legacy_romstage_select_and_load(struct prog *romstage);
142
143 /************************
144 * RAMSTAGE LOADING *
145 ************************/
146
147 /*
148 * Asynchronously preloads ramstage.
149 *
150 * This should be called early on to allow ramstage to load before
151 * `run_ramstage` is called.
152 */
153 void preload_ramstage(void);
154 /* Run ramstage from romstage. */
155 void __noreturn run_ramstage(void);
156
157 /***********************
158 * PAYLOAD LOADING *
159 ***********************/
160
161 int payload_arch_usable_ram_quirk(uint64_t start, uint64_t size);
162
163 /*
164 * Asynchronously preloads the payload.
165 *
166 * This should be called early on to allow the payload to load before
167 * `payload_load` is called.
168 */
169 void payload_preload(void);
170 /* Load payload into memory in preparation to run. */
171 void payload_load(void);
172
173 /* Run the loaded payload. */
174 void payload_run(void);
175
176 /*
177 * selfload() and selfload_check() load payloads into memory.
178 * selfload() does not check the payload to see if it targets memory.
179 * Call selfload_check() to check that the payload targets usable memory.
180 * If it does not, the load will fail and this function
181 * will return false. On successful payload loading these functions return true.
182 *
183 * Defined in src/lib/selfboot.c
184 */
185 bool selfload_check(struct prog *payload, enum bootmem_type dest_type);
186 bool selfload(struct prog *payload);
187 /* Like selfload_check() but with the payload data already mapped to memory. */
188 bool selfload_mapped(struct prog *payload, void *mapping,
189 enum bootmem_type dest_type);
190
191 /* Load a FIT payload. The payload data must already be mapped to memory. */
192 void fit_payload(struct prog *payload, void *data);
193
194 #endif /* PROGRAM_LOADING_H */
195