2 * This file is part of the coreboot project.
4 * Copyright 2015 Google, Inc.
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; version 2 of the License.
10 * This program is distributed in the hope that it will be useful,
11 * but WITHOUT ANY WARRANTY; without even the implied warranty of
12 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 * GNU General Public License for more details.
15 * You should have received a copy of the GNU General Public License
16 * along with this program; if not, write to the Free Software
27 * imd is an in-memory database/directory/datastore (whatever d word you
28 * desire). It grows downwards in memory from provided upper limit and
29 * root size. Each entry has a size alignment which is also provided by
32 * +----------------------+ <- upper_limit
33 * | +----| root pointer |
34 * | | +----------------------+
36 * | +--->| root block |-----+ |
37 * | +----------------------+-----|--|--- root_size
40 * | | alloc N |<----+ |
41 * | +----------------------+ |
44 * \|/ | alloc N + 1 |<-------+
45 * v +----------------------+
47 * The root_size in imd_create_empty() encompasses the root pointer
48 * and root block. The root_size value, therefore, dictates the number
49 * of allocations maintained by the imd.
53 * NOTE: This API has the following calling conventions: all functions
54 * returning int supply 0 on success or < 0 on error.
61 * Initialize handle to use for working with an imd. Upper limit is the
62 * exclusive address to start allocating down from. This function needs
63 * to be called at least once before any other imd related functions
66 void imd_handle_init(struct imd
*imd
, void *upper_limit
);
69 * Initialize a handle with a shallow recovery. This function doesn't
70 * verify every entry, but it does set up the root pointer. Because of
71 * this behavior it's not very safe. However, the current CBMEM constraints
72 * demand having these semantics.
74 void imd_handle_init_partial_recovery(struct imd
*imd
);
77 * Create an empty imd with a specified root_size and each entry is aligned to
78 * the provided entry_align. As noted above the root size encompasses the
79 * root pointer and root block leading to the number of imd entries being a
80 * function of the root_size parameter.
82 int imd_create_empty(struct imd
*imd
, size_t root_size
, size_t entry_align
);
85 * Create an empty imd with both large and small allocations. The small
86 * allocations come from a fixed imd stored internally within the large
87 * imd. The region allocated for tracking the smaller allocations is dependent
88 * on the small root_size and the large entry alignment by calculating the
89 * number of entries within the small imd and multiplying that by the small
92 int imd_create_tiered_empty(struct imd
*imd
,
93 size_t lg_root_size
, size_t lg_entry_align
,
94 size_t sm_root_size
, size_t sm_entry_align
);
97 * Recover a previously created imd.
99 int imd_recover(struct imd
*imd
);
101 /* Limit imd to provided max_size. */
102 int imd_limit_size(struct imd
*imd
, size_t max_size
);
104 /* Lock down imd from further modifications. */
105 int imd_lockdown(struct imd
*imd
);
107 /* Fill in base address and size of region used by imd. */
108 int imd_region_used(struct imd
*imd
, void **base
, size_t *size
);
110 /* Add an entry to the imd. If id already exists NULL is returned. */
111 const struct imd_entry
*imd_entry_add(const struct imd
*imd
, uint32_t id
,
114 /* Locate an entry within the imd. NULL is returned when not found. */
115 const struct imd_entry
*imd_entry_find(const struct imd
*imd
, uint32_t id
);
117 /* Find an existing entry or add a new one. */
118 const struct imd_entry
*imd_entry_find_or_add(const struct imd
*imd
,
119 uint32_t id
, size_t size
);
121 /* Returns size of entry or 0 on failure. */
122 size_t imd_entry_size(const struct imd
*imd
, const struct imd_entry
*entry
);
124 /* Returns pointer to region described by entry or NULL on failure. */
125 void *imd_entry_at(const struct imd
*imd
, const struct imd_entry
*entry
);
127 /* Attempt to remove entry from imd. */
128 int imd_entry_remove(const struct imd
*imd
, const struct imd_entry
*entry
);
130 /* Print the entry information provided by lookup with the specified size. */
136 int imd_print_entries(const struct imd
*imd
, const struct imd_lookup
*lookup
,
141 * The struct imd is a handle for working with an in-memory directory.
143 * NOTE: Do not directly touch any fields within this structure. An imd pointer
144 * is meant to be opaque, but the fields are exposed for stack allocation.