3 files changed, 31 insertions, 1 deletions
diff --git a/src/include/boot_device.h b/src/include/boot_device.h
index a03e5aa8f3..84bd16ef65 100644
--- a/src/include/boot_device.h
+++ b/src/include/boot_device.h
@@ -27,7 +27,8 @@ enum bootdev_prot_type {
  * most likely not to work so don't rely on such semantics.
  */
 
-/* Return the region_device for the read-only boot device. */
+/* Return the region_device for the read-only boot device. This is the root
+   device for all CBFS boot devices. */
 const struct region_device *boot_device_ro(void);
 
 /* Return the region_device for the read-write boot device. */
diff --git a/src/include/cbfs.h b/src/include/cbfs.h
index 32ed7f899e..1b446ac7a8 100644
--- a/src/include/cbfs.h
+++ b/src/include/cbfs.h
@@ -42,6 +42,12 @@ size_t cbfs_load_and_decompress(const struct region_device *rdev, size_t offset,
 /* Load stage into memory filling in prog. Return 0 on success. < 0 on error. */
 int cbfs_prog_stage_load(struct prog *prog);
 
+/*
+ * Data structure that represents "a" CBFS boot device, with optional metadata
+ * cache. Generally we only have one of these, or two (RO and RW) when
+ * CONFIG(VBOOT) is set. The region device stored here must always be a
+ * subregion of boot_device_ro().
+ */
 struct cbfs_boot_device {
 	struct region_device rdev;
 	void *mcache;
diff --git a/src/include/cbfs_private.h b/src/include/cbfs_private.h
new file mode 100644
index 0000000000..8e9803616f
--- /dev/null
+++ b/src/include/cbfs_private.h
@@ -0,0 +1,23 @@
+/* SPDX-License-Identifier: GPL-2.0-only */
+
+#ifndef _CBFS_PRIVATE_H_
+#define _CBFS_PRIVATE_H_
+
+#include <commonlib/bsd/cbfs_private.h>
+#include <commonlib/region.h>
+#include <types.h>
+
+/*
+ * This header contains low-level CBFS APIs that should only be used by code
+ * that really needs this level of access. Most code (particularly platform
+ * code) should use the higher-level CBFS APIs in <cbfs.h>. Code using these
+ * APIs needs to take special care to ensure CBFS file data is verified (in a
+ * TOCTOU-safe manner) before access (TODO: add details on how to do this once
+ * file verification code is in).
+ */
+
+/* Find by name, load metadata into |mdata| and chain file data to |rdev|. */
+cb_err_t cbfs_boot_lookup(const char *name, bool force_ro,
+			  union cbfs_mdata *mdata, struct region_device *rdev);
+
+#endif