src/include/cbmem.h

   1 /* SPDX-License-Identifier: GPL-2.0-only */
   2
   3 #ifndef _CBMEM_H_
   4 #define _CBMEM_H_
   5
   6 #include <commonlib/bsd/cbmem_id.h> /* IWYU pragma: export */
   7 #include <stddef.h>
   8 #include <stdint.h>
   9 #include <boot/coreboot_tables.h>
  10
  11 #define CBMEM_FSP_HOB_PTR       0x614
  12
  13 struct cbmem_entry;
  14
  15 /*
  16  * The dynamic cbmem infrastructure allows for growing cbmem dynamically as
  17  * things are added. It requires an external function, cbmem_top(), to be
  18  * implemented by the board or chipset to define the upper address where
  19  * cbmem lives. This address is required to be a 32-bit address. Additionally,
  20  * the address needs to be consistent in both romstage and ramstage.  The
  21  * dynamic cbmem infrastructure allocates new regions below the last allocated
  22  * region. Regions are defined by a cbmem_entry struct that is opaque. Regions
  23  * may be removed, but the last one added is the only that can be removed.
  24  */
  25
  26 #define DYN_CBMEM_ALIGN_SIZE (4096)
  27 #define CBMEM_ROOT_SIZE      DYN_CBMEM_ALIGN_SIZE
  28
  29 /* The root region is at least DYN_CBMEM_ALIGN_SIZE . */
  30 #define CBMEM_ROOT_MIN_SIZE DYN_CBMEM_ALIGN_SIZE
  31 #define CBMEM_LG_ALIGN CBMEM_ROOT_MIN_SIZE
  32
  33 /* Small allocation parameters. */
  34 #define CBMEM_SM_ROOT_SIZE 1024
  35 #define CBMEM_SM_ALIGN 32
  36
  37 /* Determine the size for CBMEM root and the small allocations */
  38 static inline size_t cbmem_overhead_size(void)
  39 {
  40         return 2 * CBMEM_ROOT_MIN_SIZE;
  41 }
  42
  43 /* By default cbmem is attempted to be recovered. Returns 0 if cbmem was
  44  * recovered or 1 if cbmem had to be reinitialized. */
  45 int cbmem_initialize(void);
  46 int cbmem_initialize_id_size(u32 id, u64 size);
  47
  48 /* Initialize cbmem to be empty. */
  49 void cbmem_initialize_empty(void);
  50 void cbmem_initialize_empty_id_size(u32 id, u64 size);
  51
  52 /* Return the top address for dynamic cbmem. The address returned needs to
  53  * be consistent across romstage and ramstage, and it is required to be
  54  * below 4GiB for 32bit coreboot builds. On 64bit coreboot builds there's no
  55  * upper limit. This should not be called before memory is initialized.
  56  */
  57 /* The assumption is made that the result of cbmem_top_romstage fits in the size
  58    of uintptr_t in the ramstage. */
  59 extern uintptr_t _cbmem_top_ptr;
  60 uintptr_t cbmem_top(void);
  61 /* With CONFIG_RAMSTAGE_CBMEM_TOP_ARG set, the result of cbmem_top is passed via
  62  * calling arguments to the next stage and saved in the global _cbmem_top_ptr
  63  * global variable. Only a romstage callback needs to be implemented by the
  64  * platform. It is up to the stages after romstage to save the calling argument
  65  * in the _cbmem_top_ptr symbol. Without CONFIG_RAMSTAGE_CBMEM_TOP_ARG the same
  66  * implementation as used in romstage will be used.
  67  */
  68 uintptr_t cbmem_top_chipset(void);
  69
  70 /* Add a cbmem entry of a given size and id. These return NULL on failure. The
  71  * add function performs a find first and do not check against the original
  72  * size. */
  73 const struct cbmem_entry *cbmem_entry_add(u32 id, u64 size);
  74
  75 /* Find a cbmem entry of a given id. These return NULL on failure. */
  76 const struct cbmem_entry *cbmem_entry_find(u32 id);
  77
  78 /* Remove a region defined by a cbmem_entry. Returns 0 on success, < 0 on
  79  * error. Note: A cbmem_entry cannot be removed unless it was the last one
  80  * added. */
  81 int cbmem_entry_remove(const struct cbmem_entry *entry);
  82
  83 /* cbmem_entry accessors to get pointer and size of a cbmem_entry. */
  84 void *cbmem_entry_start(const struct cbmem_entry *entry);
  85 u64 cbmem_entry_size(const struct cbmem_entry *entry);
  86
  87 /* Returns 0 if old cbmem was recovered. Recovery is only attempted if
  88  * s3resume is non-zero. */
  89 int cbmem_recovery(int s3resume);
  90 /* Add a cbmem entry of a given size and id. These return NULL on failure. The
  91  * add function performs a find first and do not check against the original
  92  * size. */
  93 void *cbmem_add(u32 id, u64 size);
  94 /* Find a cbmem entry of a given id. These return NULL on failure. */
  95 void *cbmem_find(u32 id);
  96
  97 /* Indicate to each hook if cbmem is being recovered or not. */
  98 typedef void (* const cbmem_init_hook_t)(int is_recovery);
  99 void cbmem_run_init_hooks(int is_recovery);
 100
 101 /* Ramstage only functions. */
 102 /* Add the cbmem memory used to the memory map at boot. */
 103 void cbmem_add_bootmem(void);
 104 /* Return the cbmem memory used */
 105 void cbmem_get_region(void **baseptr, size_t *size);
 106 void cbmem_list(void);
 107 void cbmem_add_records_to_cbtable(struct lb_header *header);
 108
 109 #define _CBMEM_INIT_HOOK_UNUSED(init_fn_) __attribute__((unused)) \
 110         static cbmem_init_hook_t init_fn_ ## _unused_ = init_fn_
 111
 112 #define _CBMEM_INIT_HOOK(init_fn_) \
 113         static cbmem_init_hook_t init_fn_ ## _ptr_ __attribute__((used, \
 114         section(".rodata.cbmem_init_hooks"))) = init_fn_
 115
 116 /* Early hooks get executed before other hooks. Use sparingly for hooks that create
 117    CBMEM regions which need to remain in a constant location across boot modes. */
 118 #define _CBMEM_INIT_HOOK_EARLY(init_fn_) \
 119         static cbmem_init_hook_t init_fn_ ## _ptr_ __attribute__((used, \
 120         section(".rodata.cbmem_init_hooks_early"))) = init_fn_
 121
 122 /* Use CBMEM_CREATION_HOOK for code that needs to be run when cbmem is initialized
 123    for the first time. */
 124 #if ENV_CREATES_CBMEM
 125 #define CBMEM_CREATION_HOOK(x)          _CBMEM_INIT_HOOK(x)
 126 #else
 127 #define CBMEM_CREATION_HOOK(x)          _CBMEM_INIT_HOOK_UNUSED(x)
 128 #endif
 129
 130 /* Use CBMEM_READY_HOOK for code that needs to run in all stages that have cbmem. */
 131 #if ENV_HAS_CBMEM
 132 #define CBMEM_READY_HOOK(x)             _CBMEM_INIT_HOOK(x)
 133 #define CBMEM_READY_HOOK_EARLY(x)       _CBMEM_INIT_HOOK_EARLY(x)
 134 #else
 135 #define CBMEM_READY_HOOK(x)             _CBMEM_INIT_HOOK_UNUSED(x)
 136 #define CBMEM_READY_HOOK_EARLY(x)       _CBMEM_INIT_HOOK_UNUSED(x)
 137 #endif
 138
 139 /* Returns 1 after running cbmem init hooks, 0 otherwise. */
 140 static inline int cbmem_online(void)
 141 {
 142         extern int cbmem_initialized;
 143
 144         if (!ENV_HAS_CBMEM)
 145                 return 0;
 146
 147         return cbmem_initialized;
 148 }
 149
 150 #endif /* _CBMEM_H_ */