src/include/program_loading.h

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