src/include/imd.h

   1 /*
   2  * This file is part of the coreboot project.
   3  *
   4  * Copyright 2015 Google, Inc.
   5  *
   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.
   9  *
  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.
  14  */
  15
  16 #ifndef _IMD_H_
  17 #define _IMD_H_
  18
  19 #include <stdint.h>
  20 #include <stddef.h>
  21
  22 /*
  23  * imd is an in-memory database/directory/datastore (whatever d word you
  24  * desire). It grows downwards in memory from provided upper limit and
  25  * root size. Each entry has a size alignment which is also provided by
  26  * the caller.
  27  *
  28  *             +----------------------+ <- upper_limit
  29  *    |   +----|   root pointer       |
  30  *    |   |    +----------------------+
  31  *    |   |    |                      |--------+
  32  *    |   +--->|   root block         |-----+  |
  33  *    |        +----------------------+-----|--|--- root_size
  34  *    |        |                      |     |  |
  35  *    |        |                      |     |  |
  36  *    |        |   alloc N            |<----+  |
  37  *    |        +----------------------+        |
  38  *    |        |                      |        |
  39  *    |        |                      |        |
  40  *   \|/       |   alloc N + 1        |<-------+
  41  *    v        +----------------------+
  42  *
  43  * The root_size in imd_create_empty() encompasses the root pointer
  44  * and root block. The root_size value, therefore, dictates the number
  45  * of allocations maintained by the imd.
  46  */
  47
  48 /*
  49  * NOTE: This API has the following calling conventions: all functions
  50  * returning int supply 0 on success or < 0 on error.
  51  */
  52
  53 struct imd_entry;
  54 struct imd;
  55
  56 /*
  57  * Initialize handle to use for working with an imd. Upper limit is the
  58  * exclusive address to start allocating down from. This function needs
  59  * to be called at least once before any other imd related functions
  60  * can be used.
  61  */
  62 void imd_handle_init(struct imd *imd, void *upper_limit);
  63
  64 /*
  65  * Initialize a handle with a shallow recovery. This function doesn't
  66  * verify every entry, but it does set up the root pointer. Because of
  67  * this behavior it's not very safe. However, the current CBMEM constraints
  68  * demand having these semantics.
  69  */
  70 void imd_handle_init_partial_recovery(struct imd *imd);
  71
  72 /*
  73  * Create an empty imd with a specified root_size and each entry is aligned to
  74  * the provided entry_align. As noted above the root size encompasses the
  75  * root pointer and root block leading to the number of imd entries being a
  76  * function of the root_size parameter.
  77  */
  78 int imd_create_empty(struct imd *imd, size_t root_size, size_t entry_align);
  79
  80 /*
  81  * Create an empty imd with both large and small allocations. The small
  82  * allocations come from a fixed imd stored internally within the large
  83  * imd. The region allocated for tracking the smaller allocations is dependent
  84  * on the small root_size and the large entry alignment by calculating the
  85  * number of entries within the small imd and multiplying that by the small
  86  * entry alignment.
  87  */
  88 int imd_create_tiered_empty(struct imd *imd,
  89                                 size_t lg_root_size, size_t lg_entry_align,
  90                                 size_t sm_root_size, size_t sm_entry_align);
  91
  92 /*
  93  * Recover a previously created imd.
  94  */
  95 int imd_recover(struct imd *imd);
  96
  97 /* Limit imd to provided max_size. */
  98 int imd_limit_size(struct imd *imd, size_t max_size);
  99
 100 /* Lock down imd from further modifications. */
 101 int imd_lockdown(struct imd *imd);
 102
 103 /* Fill in base address and size of region used by imd. */
 104 int imd_region_used(struct imd *imd, void **base, size_t *size);
 105
 106 /* Add an entry to the imd. If id already exists NULL is returned. */
 107 const struct imd_entry *imd_entry_add(const struct imd *imd, uint32_t id,
 108                                         size_t size);
 109
 110 /* Locate an entry within the imd. NULL is returned when not found. */
 111 const struct imd_entry *imd_entry_find(const struct imd *imd, uint32_t id);
 112
 113 /* Find an existing entry or add a new one. */
 114 const struct imd_entry *imd_entry_find_or_add(const struct imd *imd,
 115                                                 uint32_t id, size_t size);
 116
 117 /* Returns size of entry or 0 on failure. */
 118 size_t imd_entry_size(const struct imd *imd, const struct imd_entry *entry);
 119
 120 /* Returns pointer to region described by entry or NULL on failure. */
 121 void *imd_entry_at(const struct imd *imd, const struct imd_entry *entry);
 122
 123 /* Returns id for the imd entry. */
 124 uint32_t imd_entry_id(const struct imd *imd, const struct imd_entry *entry);
 125
 126 /* Attempt to remove entry from imd. */
 127 int imd_entry_remove(const struct imd *imd, const struct imd_entry *entry);
 128
 129 /* Print the entry information provided by lookup with the specified size. */
 130 struct imd_lookup {
 131         uint32_t id;
 132         const char *name;
 133 };
 134
 135 int imd_print_entries(const struct imd *imd, const struct imd_lookup *lookup,
 136                         size_t size);
 137
 138 struct imd_cursor;
 139 /* Initialize an imd_cursor object to walk the IMD entries. */
 140 int imd_cursor_init(const struct imd *imd, struct imd_cursor *cursor);
 141
 142 /* Retrieve the next imd entry the cursor is referencing. Returns NULL when
 143  * no more entries exist. */
 144 const struct imd_entry *imd_cursor_next(struct imd_cursor *cursor);
 145
 146 /*
 147  * The struct imd is a handle for working with an in-memory directory.
 148  *
 149  * NOTE: Do not directly touch any fields within this structure. An imd pointer
 150  * is meant to be opaque, but the fields are exposed for stack allocation.
 151  */
 152 struct imdr {
 153         uintptr_t limit;
 154         void *r;
 155 };
 156 struct imd {
 157         struct imdr lg;
 158         struct imdr sm;
 159 };
 160
 161 struct imd_cursor {
 162         size_t current_imdr;
 163         size_t current_entry;
 164         const struct imdr *imdr[2];
 165 };
 166
 167 #endif /* _IMD_H_ */