src/include/program_loading.h

   1 /*
   2  * This file is part of the coreboot project.
   3  *
   4  * Copyright 2015 Google Inc.
   5  * Copyright (C) 2014 Imagination Technologies
   6  *
   7  * This program is free software; you can redistribute it and/or modify
   8  * it under the terms of the GNU General Public License as published by
   9  * the Free Software Foundation; version 2 of the License.
  10  *
  11  * This program is distributed in the hope that it will be useful,
  12  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  13  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14  * GNU General Public License for more details.
  15  */
  16 #ifndef PROGRAM_LOADING_H
  17 #define PROGRAM_LOADING_H
  18
  19 #include <commonlib/region.h>
  20 #include <stdint.h>
  21 #include <stddef.h>
  22
  23 enum {
  24         /* Last segment of program. Can be used to take different actions for
  25          * cache maintenance of a program load. */
  26         SEG_FINAL = 1 << 0,
  27 };
  28
  29 enum prog_type {
  30         PROG_UNKNOWN,
  31         PROG_VERSTAGE,
  32         PROG_ROMSTAGE,
  33         PROG_RAMSTAGE,
  34         PROG_REFCODE,
  35         PROG_PAYLOAD,
  36         PROG_BL31,
  37         PROG_BL32,
  38 };
  39
  40 /*
  41  * prog_segment_loaded() is called for each segment of a program loaded. The
  42  * SEG_FINAL flag will be set on the last segment loaded. The following two
  43  * functions, platform_segment_loaded() and arch_segment_loaded(), are called
  44  * in that order within prog_segment_loaded(). In short, rely on
  45  * prog_segment_loaded() to perform the proper dispatch sequence.
  46  */
  47 void prog_segment_loaded(uintptr_t start, size_t size, int flags);
  48 void platform_segment_loaded(uintptr_t start, size_t size, int flags);
  49 void arch_segment_loaded(uintptr_t start, size_t size, int flags);
  50
  51 /* Return true if arch supports bounce buffer.  */
  52 int arch_supports_bounce_buffer(void);
  53
  54 /* Representation of a program. */
  55 struct prog {
  56         /* The region_device is the source of program content to load. After
  57          * loading program it represents the memory region of the stages and
  58          * payload. For architectures that use a bounce buffer
  59          * then it would represent the bounce buffer. */
  60         enum prog_type type;
  61         const char *name;
  62         struct region_device rdev;
  63         /* Entry to program with optional argument. It's up to the architecture
  64          * to decide if argument is passed. */
  65         void (*entry)(void *);
  66         void *arg;
  67 };
  68
  69 #define PROG_INIT(type_, name_)                         \
  70         {                                               \
  71                 .type = (type_),                        \
  72                 .name = (name_),                        \
  73         }
  74
  75 static inline const char *prog_name(const struct prog *prog)
  76 {
  77         return prog->name;
  78 }
  79
  80 static inline enum prog_type prog_type(const struct prog *prog)
  81 {
  82         return prog->type;
  83 }
  84
  85 static inline struct region_device *prog_rdev(struct prog *prog)
  86 {
  87         return &prog->rdev;
  88 }
  89
  90 /* Only valid for loaded programs. */
  91 static inline size_t prog_size(const struct prog *prog)
  92 {
  93         return region_device_sz(&prog->rdev);
  94 }
  95
  96 /* Only valid for loaded programs. */
  97 static inline void *prog_start(const struct prog *prog)
  98 {
  99         return rdev_mmap_full(&prog->rdev);
 100 }
 101
 102 static inline void *prog_entry(const struct prog *prog)
 103 {
 104         return prog->entry;
 105 }
 106
 107 static inline void *prog_entry_arg(const struct prog *prog)
 108 {
 109         return prog->arg;
 110 }
 111
 112 /* region_device representing the 32-bit flat address space. */
 113 extern const struct mem_region_device addrspace_32bit;
 114
 115 static inline void prog_memory_init(struct prog *prog, uintptr_t ptr,
 116                                         size_t size)
 117 {
 118         rdev_chain(&prog->rdev, &addrspace_32bit.rdev, ptr, size);
 119 }
 120
 121 static inline void prog_set_area(struct prog *prog, void *start, size_t size)
 122 {
 123         prog_memory_init(prog, (uintptr_t)start, size);
 124 }
 125
 126 static inline void prog_set_entry(struct prog *prog, void *e, void *arg)
 127 {
 128         prog->entry = e;
 129         prog->arg = arg;
 130 }
 131
 132 /* Locate the identified program to run. Return 0 on success. < 0 on error. */
 133 int prog_locate(struct prog *prog);
 134
 135 /* Run the program described by prog. */
 136 void prog_run(struct prog *prog);
 137 /* Per architecture implementation running a program. */
 138 void arch_prog_run(struct prog *prog);
 139 /* Platform (SoC/chipset) specific overrides for running a program. This is
 140  * called prior to calling the arch_prog_run. Thus, if there is anything
 141  * special that needs to be done by the platform similar to the architecture
 142  * code it needs to that as well. */
 143 void platform_prog_run(struct prog *prog);
 144
 145 struct prog_loader_ops {
 146         const char *name;
 147         /* Determine if the loader is the active one. If so returns 1 else 0
 148          * or < 0 on error. */
 149         int (*is_loader_active)(struct prog *prog);
 150         /* Returns < 0 on error or 0 on success. This function locates
 151          * the rdev representing the file data associated with the passed in
 152          * prog. */
 153         int (*locate)(struct prog *prog);
 154 };
 155
 156 /************************
 157  *   ROMSTAGE LOADING   *
 158  ************************/
 159
 160 /* Run romstage from bootblock. */
 161 void run_romstage(void);
 162
 163 /************************
 164  *   RAMSTAGE LOADING   *
 165  ************************/
 166
 167 /* Run ramstage from romstage. */
 168 void run_ramstage(void);
 169
 170 /* Called when the stage cache couldn't load ramstage on resume. */
 171 void ramstage_cache_invalid(void);
 172
 173 /***********************
 174  *   PAYLOAD LOADING   *
 175  ***********************/
 176
 177 /* Load payload into memory in preparation to run. */
 178 void payload_load(void);
 179
 180 /* Run the loaded payload. */
 181 void payload_run(void);
 182
 183 /* Mirror the payload to be loaded. */
 184 void mirror_payload(struct prog *payload);
 185
 186 /* Defined in src/lib/selfboot.c */
 187 void *selfload(struct prog *payload);
 188
 189 #endif /* PROGRAM_LOADING_H */