From 64931a3d658b90d383ab9d65f05d9f2adbe4d653 Mon Sep 17 00:00:00 2001 From: Nicolas Kochlowski Date: Mon, 14 Oct 2024 11:57:01 -0300 Subject: [PATCH] Documentation/getting_started/cbmem.md: Add cbmem documentation Change-Id: I514cfbd6df85f332419444c35d066a518d5044f3 Signed-off-by: Nicolas Kochlowski Reviewed-on: https://review.coreboot.org/c/coreboot/+/84761 Tested-by: build bot (Jenkins) Reviewed-by: Ana Carolina Cabral Reviewed-by: Martin L Roth --- Documentation/getting_started/cbmem.md | 41 ++++++++++++++++++++++++++ Documentation/getting_started/index.md | 1 + 2 files changed, 42 insertions(+) create mode 100644 Documentation/getting_started/cbmem.md diff --git a/Documentation/getting_started/cbmem.md b/Documentation/getting_started/cbmem.md new file mode 100644 index 0000000000..13e6cf807e --- /dev/null +++ b/Documentation/getting_started/cbmem.md @@ -0,0 +1,41 @@ +# CBMEM high table memory manager + +## Introduction +CBMEM (coreboot memory) is a dynamic memory infrastructure used in +coreboot to store runtime data structures, logs, and other information +that needs to persist across different boot stages. CBMEM is crucial +for maintaining state and logging information across different stages +of the coreboot boot process. + +## Creation and Placement +CBMEM is initialized by coreboot during romstage, but is used mainly in +ramstage for storing data such as coreboot and ACPI tables, SMBIOS, +timestamps, stage information, vendor-specific data structures, etc. + +For 32-bit builds, CBMEM is typically located at the highest usable +DRAM address below the 4GiB boundary. For 64-bit builds, while there +is no strict upper limit, it is advisable to follow the same guidelines +to prevent access or addressing issues. Regardless of the build type, +the CBMEM address must remain consistent between romstage and ramstage. + +Each platform may need to implement its own method for determining the +`cbmem_top` address, as this can depend on specific hardware +configurations and memory layouts. + +## Usage +Each CBMEM region is identified by a unique ID, allowing different +components to store and retrieve their data during runtime. The ID is a +32-bit value that optionally encodes characters to indicate the type or +source of the data. + +Upon creating an entry, a block of memory is allocated of the requested +size from the reserved CBMEM region. This region persists across warm +reboots, making it useful for debugging and passing information to +payloads. + +Note that CBMEM is implemented as imd (in-memory database), meaning +it grows downwards in memory from the provided upper limit, and only +the latest added entry may be removed. + +The `cbmem` tool in `/util` can be used to list and access entries +using their ID. diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md index 7180c9615a..8b2ce3a31c 100644 --- a/Documentation/getting_started/index.md +++ b/Documentation/getting_started/index.md @@ -10,5 +10,6 @@ Kconfig Writing Documentation Setting up GPIOs Adding devices to a device tree +CBMEM Frequently Asked Questions ```