coreboot: add imd library

The imd (internal memory database) library provides a way to
track memory regions by assigning ids to each region. The implementation
is a direct descendant of dynamic cbmem. The intent is to replace
the existing mechanisms which do similar things: dynamic cbmem, stage
cache, etc.

Differences between dynamic cbmem and imd:
- All structures/objects are relative to one another. There
  are no absolute pointers serialized to memory.
- Allow limiting the size of the idm. i.e. provide a maximum
  memory usage.
- Allow setting the size of the root structure which allows
  control of the number of allocations to track.

Change-Id: Id7438cff80d396a594d6a7330d09b45bb4fedf2e
Signed-off-by: Aaron Durbin <adurbin@chromium.org>
Reviewed-on: http://review.coreboot.org/8621
Tested-by: build bot (Jenkins)
Reviewed-by: Marc Jones <marc.jones@se-eng.com>

1 files changed, 139 insertions, 0 deletions

diff --git a/src/include/imd.h b/src/include/imd.h
new file mode 100644
index 0000000000..8d5c4522b7
--- /dev/null
+++ b/src/include/imd.h
@@ -0,0 +1,139 @@
+/*
+ * This file is part of the coreboot project.
+ *
+ * Copyright 2015 Google, Inc.
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License as published by
+ * the Free Software Foundation; version 2 of the License.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc.
+ */
+
+#ifndef _IMD_H_
+#define _IMD_H_
+
+#include <stdint.h>
+#include <stddef.h>
+
+/*
+ * imd is an in-memory database/directory/datastore (whatever d word you
+ * desire). It grows downwards in memory from provided upper limit and
+ * root size. Each entry has a size alignment which is also provided by
+ * the caller.
+ *
+ *             +----------------------+ <- upper_limit
+ *    |   +----|   root pointer       |
+ *    |   |    +----------------------+
+ *    |   |    |                      |--------+
+ *    |   +--->|   root block         |-----+  |
+ *    |        +----------------------+-----|--|--- root_size
+ *    |        |                      |     |  |
+ *    |        |                      |     |  |
+ *    |        |   alloc N            |<----+  |
+ *    |        +----------------------+        |
+ *    |        |                      |        |
+ *    |        |                      |        |
+ *   \|/       |   alloc N + 1        |<-------+
+ *    v        +----------------------+
+ *
+ * The root_size in imd_create_empty() encompasses the root pointer
+ * and root block. The root_size value, therefore, dictates the number
+ * of allocations maintained by the imd.
+ */
+
+/*
+ * NOTE: This API has the following calling conventions: all functions
+ * returning int supply 0 on success or < 0 on error.
+ */
+
+struct imd_entry;
+struct imd;
+
+/*
+ * Initialize handle to use for working with an imd. Upper limit is the
+ * exclusive address to start allocating down from. This function needs
+ * to be called at least once before any other imd related functions
+ * can be used.
+ */
+void imd_handle_init(struct imd *imd, void *upper_limit);
+
+/*
+ * Initialize a handle with a shallow recovery. This function doesn't
+ * verify every entry, but it does set up the root pointer. Because of
+ * this behavior it's not very safe. However, the current CBMEM constraints
+ * demand having these semantics.
+ */
+void imd_handle_init_partial_recovery(struct imd *imd);
+
+/*
+ * Create an empty imd with a specified root_size and each entry is aligned to
+ * the provided entry_align. As noted above the root size encompasses the
+ * root pointer and root block leading to the number of imd entries being a
+ * function of the root_size parameter.
+ */
+int imd_create_empty(struct imd *imd, size_t root_size, size_t entry_align);
+
+/*
+ * Recover a previously created imd.
+ */
+int imd_recover(struct imd *imd);
+
+/* Limit imd to provided max_size. */
+int imd_limit_size(struct imd *imd, size_t max_size);
+
+/* Lock down imd from further modifications. */
+int imd_lockdown(struct imd *imd);
+
+/* Fill in base address and size of region used by imd. */
+int imd_region_used(struct imd *imd, void **base, size_t *size);
+
+/* Add an entry to the imd. If id already exists NULL is returned. */
+const struct imd_entry *imd_entry_add(const struct imd *imd, uint32_t id,
+					size_t size);
+
+/* Locate an entry within the imd. NULL is returned when not found. */
+const struct imd_entry *imd_entry_find(const struct imd *imd, uint32_t id);
+
+/* Find an existing entry or add a new one. */
+const struct imd_entry *imd_entry_find_or_add(const struct imd *imd,
+						uint32_t id, size_t size);
+
+/* Returns size of entry or 0 on failure. */
+size_t imd_entry_size(const struct imd *imd, const struct imd_entry *entry);
+
+/* Returns pointer to region described by entry or NULL on failure. */
+void *imd_entry_at(const struct imd *imd, const struct imd_entry *entry);
+
+/* Attempt to remove entry from imd. */
+int imd_entry_remove(const struct imd *imd, const struct imd_entry *entry);
+
+/* Print the entry information provided by lookup with the specified size. */
+struct imd_lookup {
+	uint32_t id;
+	const char *name;
+};
+
+int imd_print_entries(const struct imd *imd, const struct imd_lookup *lookup,
+			size_t size);
+
+
+/*
+ * The struct imd is a handle for working with an in-memory directory.
+ *
+ * NOTE: Do not directly touch any fields within this structure. An imd pointer
+ * is meant to be opaque, but the fields are exposed for stack allocation.
+ */
+struct imd {
+	uintptr_t limit;
+	void *r;
+};
+
+#endif /* _IMD_H_ */