soc/intel/xeon_sp/spr: Drop microcode constraints
[coreboot2.git] / src / include / imd.h
blobdf669fd3669ffdf8abece992087900e298cd9f2f
1 /* SPDX-License-Identifier: GPL-2.0-only */
3 #ifndef _IMD_H_
4 #define _IMD_H_
6 #include <stdint.h>
7 #include <stddef.h>
9 /*
10 * imd is an in-memory database/directory/datastore (whatever d word you
11 * desire). It grows downwards in memory from provided upper limit and
12 * root size. Each entry has a size alignment which is also provided by
13 * the caller.
15 * +----------------------+ <- upper_limit
16 * | +----| root pointer |
17 * | | +----------------------+
18 * | | | |--------+
19 * | +--->| root block |-----+ |
20 * | +----------------------+-----|--|--- root_size
21 * | | | | |
22 * | | | | |
23 * | | alloc N |<----+ |
24 * | +----------------------+ |
25 * | | | |
26 * | | | |
27 * \|/ | alloc N + 1 |<-------+
28 * v +----------------------+
30 * The root_size in imd_create_empty() encompasses the root pointer
31 * and root block. The root_size value, therefore, dictates the number
32 * of allocations maintained by the imd.
36 * NOTE: This API has the following calling conventions: all functions
37 * returning int supply 0 on success or < 0 on error.
40 struct imd_entry;
41 struct imd;
43 static const size_t LIMIT_ALIGN = 4096;
46 * Initialize handle to use for working with an imd. Upper limit is the
47 * exclusive address (aligned down to LIMIT_ALIGN) to start allocating down
48 * from. This function needs to be called at least once before any other imd
49 * related functions can be used.
51 void imd_handle_init(struct imd *imd, void *upper_limit);
54 * Initialize a handle with a shallow recovery. This function doesn't
55 * verify every entry, but it does set up the root pointer. Because of
56 * this behavior it's not very safe. However, the current CBMEM constraints
57 * demand having these semantics.
59 void imd_handle_init_partial_recovery(struct imd *imd);
62 * Create an empty imd with a specified root_size and each entry is aligned to
63 * the provided entry_align. As noted above the root size encompasses the
64 * root pointer and root block leading to the number of imd entries being a
65 * function of the root_size parameter. Please note, that one entry is allocated
66 * for covering root region, thus caller should consider this calculating
67 * root_size.
69 int imd_create_empty(struct imd *imd, size_t root_size, size_t entry_align);
72 * Create an empty imd with both large and small allocations. The small
73 * allocations come from a fixed imd stored internally within the large
74 * imd. The region allocated for tracking the smaller allocations is dependent
75 * on the small root_size and the large entry alignment by calculating the
76 * number of entries within the small imd and multiplying that by the small
77 * entry alignment.
79 int imd_create_tiered_empty(struct imd *imd,
80 size_t lg_root_size, size_t lg_entry_align,
81 size_t sm_root_size, size_t sm_entry_align);
84 * Recover a previously created imd.
86 int imd_recover(struct imd *imd);
88 /* Limit imd to provided max_size. */
89 int imd_limit_size(struct imd *imd, size_t max_size);
91 /* Lock down imd from further modifications. */
92 int imd_lockdown(struct imd *imd);
94 /* Fill in base address and size of region used by imd. */
95 int imd_region_used(struct imd *imd, void **base, size_t *size);
97 /* Add an entry to the imd. If id already exists NULL is returned. */
98 const struct imd_entry *imd_entry_add(const struct imd *imd, uint32_t id,
99 size_t size);
101 /* Locate an entry within the imd. NULL is returned when not found. */
102 const struct imd_entry *imd_entry_find(const struct imd *imd, uint32_t id);
104 /* Find an existing entry or add a new one. */
105 const struct imd_entry *imd_entry_find_or_add(const struct imd *imd,
106 uint32_t id, size_t size);
108 /* Returns size of entry. */
109 size_t imd_entry_size(const struct imd_entry *entry);
111 /* Returns pointer to region described by entry or NULL on failure. */
112 void *imd_entry_at(const struct imd *imd, const struct imd_entry *entry);
114 /* Returns id for the imd entry. */
115 uint32_t imd_entry_id(const struct imd_entry *entry);
117 /* Attempt to remove entry from imd. */
118 int imd_entry_remove(const struct imd *imd, const struct imd_entry *entry);
120 /* Print the entry information provided by lookup with the specified size. */
121 struct imd_lookup {
122 uint32_t id;
123 const char *name;
126 int imd_print_entries(const struct imd *imd, const struct imd_lookup *lookup,
127 size_t size);
129 struct imd_cursor;
130 /* Initialize an imd_cursor object to walk the IMD entries. */
131 int imd_cursor_init(const struct imd *imd, struct imd_cursor *cursor);
133 /* Retrieve the next imd entry the cursor is referencing. Returns NULL when
134 * no more entries exist. */
135 const struct imd_entry *imd_cursor_next(struct imd_cursor *cursor);
138 * The struct imd is a handle for working with an in-memory directory.
140 * NOTE: Do not directly touch any fields within this structure. An imd pointer
141 * is meant to be opaque, but the fields are exposed for stack allocation.
143 struct imdr {
144 uintptr_t limit;
145 void *r;
147 struct imd {
148 struct imdr lg;
149 struct imdr sm;
152 struct imd_cursor {
153 size_t current_imdr;
154 size_t current_entry;
155 const struct imdr *imdr[2];
158 #endif /* _IMD_H_ */