From e8d8d9492da48430fe2c059fef8e9116fc17c188 Mon Sep 17 00:00:00 2001 From: Patrick Rudolph Date: Wed, 17 Apr 2019 11:51:25 +0200 Subject: Documentation: Add small fixes * Remove empty security.md * Remove second H1 header from lib/index.md * Move two documents in appropriate subfolders * Fix file path * Drop document overview Change-Id: I0e9df6203e82003c01b84967ea6bd779d7583fef Signed-off-by: Patrick Rudolph Reviewed-on: https://review.coreboot.org/c/coreboot/+/32340 Tested-by: build bot (Jenkins) Reviewed-by: Paul Menzel Reviewed-by: Hung-Te Lin Reviewed-by: Martin Roth --- Documentation/abi-data-consumption.md | 24 ---- Documentation/index.md | 4 +- Documentation/lib/abi-data-consumption.md | 25 ++++ Documentation/lib/index.md | 4 +- Documentation/lib/timestamp.md | 176 ++++++++++++++++++++++++++ Documentation/security.md | 5 - Documentation/timestamp.md | 200 ------------------------------ 7 files changed, 205 insertions(+), 233 deletions(-) delete mode 100644 Documentation/abi-data-consumption.md create mode 100644 Documentation/lib/abi-data-consumption.md create mode 100644 Documentation/lib/timestamp.md delete mode 100644 Documentation/security.md delete mode 100644 Documentation/timestamp.md diff --git a/Documentation/abi-data-consumption.md b/Documentation/abi-data-consumption.md deleted file mode 100644 index 962f33eac5..0000000000 --- a/Documentation/abi-data-consumption.md +++ /dev/null @@ -1,24 +0,0 @@ -# ABI data consumption - -This text describes the ABI coreboot presents to downstream users. Such -users are payloads and/or operating systems. Therefore, this text serves -at what can be relied on for downstream consumption. Anything not explicitly -listed as consumable is subject to change without notice. - -## Background and Usage - -coreboot passes information to downstream users using coreboot tables. These -table definitions can be found in src/include/boot/coreboot_tables.h and -payloads/libpayload/include/coreboot_tables.h respectively within coreboot -and libpayload. One of the most vital and important pieces of information -found within these tables is the memory map of the system indicating -available and reserved memory. - -In 2009 cbmem was added to coreboot. The "CBMEM high table memory manager" -serves a way for coreboot to bookkeep its own internal data. While some -of this data may be exposed through the coreboot tables the data structures -used to manage the data within the cbmem area is subject to change. - -Provided the above, if one needs a piece of data exposed to the OS -or payload it should reside within the coreboot tables. If it isn't there -then a code change will be required to add it to the coreboot tables. diff --git a/Documentation/index.md b/Documentation/index.md index 6eb2e695c6..6dbbf4d91f 100644 --- a/Documentation/index.md +++ b/Documentation/index.md @@ -167,13 +167,10 @@ Contents: * [Code of Conduct](community/code_of_conduct.md) * [Community forums](community/forums.md) * [coreboot at conferences](community/conferences.md) -* [Security](security.md) * [Payloads](payloads.md) * [Distributions](distributions.md) -* [Timestamps](timestamp.md) * [Intel IFD Binary Extraction](Binary_Extraction.md) * [Dealing with Untrusted Input in SMM](technotes/2017-02-dealing-with-untrusted-input-in-smm.md) -* [ABI data consumption](abi-data-consumption.md) * [GPIO toggling in ACPI AML](acpi/gpio.md) * [Native Graphics Initialization with libgfxinit](gfx/libgfxinit.md) * [Architecture-specific documentation](arch/index.md) @@ -182,6 +179,7 @@ Contents: * [Mainboard-specific documentation](mainboard/index.md) * [Payload-specific documentation](lib/payloads/index.md) * [Library-specific documentation](lib/index.md) +* [Security](security/index.md) * [SuperIO-specific documentation](superio/index.md) * [Vendorcode-specific documentation](vendorcode/index.md) * [Utilities](util.md) diff --git a/Documentation/lib/abi-data-consumption.md b/Documentation/lib/abi-data-consumption.md new file mode 100644 index 0000000000..d162199cab --- /dev/null +++ b/Documentation/lib/abi-data-consumption.md @@ -0,0 +1,25 @@ +# ABI data consumption + +This text describes the ABI coreboot presents to downstream users. Such +users are payloads and/or operating systems. Therefore, this text serves +at what can be relied on for downstream consumption. Anything not explicitly +listed as consumable is subject to change without notice. + +## Background and Usage + +coreboot passes information to downstream users using coreboot tables. These +table definitions can be found in +`./src/commonlib/include/commonlib/coreboot_tables.h` and +`./payloads/libpayload/include/coreboot_tables.h` respectively within coreboot +and libpayload. One of the most vital and important pieces of information +found within these tables is the memory map of the system indicating +available and reserved memory. + +In 2009 cbmem was added to coreboot. The "CBMEM high table memory manager" +serves a way for coreboot to bookkeep its own internal data. While some +of this data may be exposed through the coreboot tables the data structures +used to manage the data within the cbmem area is subject to change. + +Provided the above, if one needs a piece of data exposed to the OS +or payload it should reside within the coreboot tables. If it isn't there +then a code change will be required to add it to the coreboot tables. diff --git a/Documentation/lib/index.md b/Documentation/lib/index.md index 85e046079d..99b8061325 100644 --- a/Documentation/lib/index.md +++ b/Documentation/lib/index.md @@ -3,5 +3,7 @@ This section contains documentation about coreboot internal technical information and libraries. -# Structure and layout +## Structure and layout - [Flashmap and Flashmap Descriptor](flashmap.md) +- [ABI data consumption](abi-data-consumption.md) +- [Timestamps](timestamp.md) diff --git a/Documentation/lib/timestamp.md b/Documentation/lib/timestamp.md new file mode 100644 index 0000000000..d5dc8facf3 --- /dev/null +++ b/Documentation/lib/timestamp.md @@ -0,0 +1,176 @@ +# Timestamps + +## Introduction + +The aim of the timestamp library is to make it easier for different boards +to save timestamps in cbmem / stash (until cbmem is brought up) by +providing a simple API to initialize, add and sync timestamps. In order +to make the timestamps persistent and accessible from the kernel, we +need to ensure that all the saved timestamps end up in cbmem under +the CBMEM_ID_TIMESTAMP tag. However, until the cbmem area is available, +the timestamps can be saved to a SoC-defined \_timestamp region or in a +local stage-specific stash. The work of identifying the right location for +storing timestamps is done by the library and is not exposed to the user. + +Working of timestamp library from a user perspective can be outlined in +the following steps: +1. Initialize the base time and reset cbmem timestamp area +2. Start adding timestamps + +Behind the scenes, the timestamp library takes care of: +1. Identifying the correct location for storing timestamps (cbmem or timestamp + region or local stash). +2. Once cbmem is up, ensure that all timestamps are synced from timestamp + region or local stash into the cbmem area. +3. Add a new cbmem timestamp area based on whether a reset of the cbmem + timestamp region is required or not. + +### Transition from cache to cbmem + +To move timestamps from the cache to cbmem (and initialize the cbmem area in +the first place), we use the CBMEM_INIT_HOOK infrastructure of coreboot. + +When cbmem is initialized, the hook is called, which creates the area, +copies all timestamps to cbmem and disables the cache. + +After such a transition, timestamp_init() must not be run again. + + +## Data structures used + +The main structure that maintains information about the timestamp cache is: + +```c +struct __packed timestamp_cache { + uint16_t cache_state; + struct timestamp_table table; + struct timestamp_entry entries[MAX_TIMESTAMP_CACHE]; +}; +``` + +### cache_state + +The state of the cache is maintained by `cache_state` attribute which can +be any one of the following: + +```c +enum { + TIMESTAMP_CACHE_UNINITIALIZED = 0, + TIMESTAMP_CACHE_INITIALIZED, + TIMESTAMP_CACHE_NOT_NEEDED, +}; +``` + +By default, if the cache is stored in local stash (bss area), then +it will be reset to uninitialized state. However, if the cache is +stored in timestamp region, then it might have garbage in any of the +attributes. Thus, if the timestamp region is being used by any board, it is +initialized to default values by the library. + +Once the cache is initialized, its state is set to +`CACHE_INITIALIZED`. Henceforth, the calls to cache i.e. `timestamp_add` +know that the state reflected is valid and timestamps can be directly +saved in the cache. + +Once the cbmem area is up (i.e. call to `timestamp_sync_cache_to_cbmem`), +we do not need to store the timestamps in local stash / timestamp area +anymore. Thus, the cache state is set to `CACHE_NOT_NEEDED`, which allows +`timestamp_add` to store all timestamps directly into the cbmem area. + + +### table + +This field is represented by a structure which provides overall +information about the entries in the timestamp area: + +```c +struct timestamp_table { + uint64_t base_time; + uint32_t max_entries; + uint32_t num_entries; + struct timestamp_entry entries[0]; /* Variable number of entries */ +} __packed; +``` + +It indicates the base time for all timestamp entries, maximum number +of entries that can be stored, total number of entries that currently +exist and an entry structure to hold variable number of entries. + + +### entries + +This field holds the details of each timestamp entry, upto a maximum +of `MAX_TIMESTAMP_CACHE` which is defined as 16 entries. Each entry is +defined by: + +```c +struct timestamp_entry { + uint32_t entry_id; + uint64_t entry_stamp; +} __packed; +``` + +`entry_id` holds the timestamp id corresponding to this entry and +`entry_stamp` holds the actual timestamp. + + +For timestamps stored in the cbmem area, a `timestamp_table` is allocated +with space for `MAX_TIMESTAMPS` equal to 30. Thus, the cbmem area holds +`base_time`, `max_entries` (which is 30), current number of entries and the +actual entries represented by `timestamp_entry`. + + +## Function APIs + +### timestamp_init + +This function initializes the timestamp cache and should be run as early +as possible. On platforms with SRAM, this might mean in bootblock, on +x86 with its CAR backed memory in romstage, this means romstage before +memory init. + +### timestamp_add + +This function accepts from user a timestamp id and time to record in the +timestamp table. It stores the entry in the appropriate table in cbmem +or `_timestamp` region or local stash. + + +### timestamp_add_now + +This function calls `timestamp_add` with user-provided id and current time. + + +## Use / Test Cases + +The following cases have been considered while designing the timestamp +library. It is important to ensure that any changes made to this library satisfy +each of the following use cases: + +### Case 1: Timestamp Region Exists (Fresh Boot / Resume) + +In this case, the library needs to call `timestamp_init` as early as possible to +enable the timestamp cache. Once cbmem is available, the values will be +transferred automatically. + +All regions are automatically reset on initialization. + +### Case 2: No timestamp region, fresh boot, cbmem_initialize called after timestamp_init + +`timestamp_init` will set up a local cache. cbmem must be initialized before that +cache vanishes - as happens when jumping to the next stage. + +### Case 3: No timestamp region, fresh boot, cbmem_initialize called before timestamp_init + +This case is not supported right now, just don't call `timestamp_init` after +`cbmem_initialize`. (Patches to make this more robust are welcome.) + +### Case 4: No timestamp region, resume, cbmem_initialize called after timestamp_init + +We always reset the cbmem region before using it, so pre-suspend timestamps +will be gone. + +### Case 5: No timestamp region, resume, cbmem_initialize called before timestamp_init + +We always reset the cbmem region before using it, so pre-suspend timestamps +will be gone. diff --git a/Documentation/security.md b/Documentation/security.md deleted file mode 100644 index 73b167fdc4..0000000000 --- a/Documentation/security.md +++ /dev/null @@ -1,5 +0,0 @@ -# Security - -## Google VBoot2 Measured boot extension - -- [Measured Boot](vboot/measured_boot.md) diff --git a/Documentation/timestamp.md b/Documentation/timestamp.md deleted file mode 100644 index 9233ed97cc..0000000000 --- a/Documentation/timestamp.md +++ /dev/null @@ -1,200 +0,0 @@ -# Timestamps - -## Table of Contents - -Introduction -- Transition from cache to cbmem - -Data structures used -- cache_state -- table -- entries - -Function APIs -- timestamp_init -- timestamp_add -- timestamp_add_now -- timestamp_sync - -Use / Test Cases -- Case 1: Timestamp Region Exists -- Case 2: No timestamp region, fresh boot, cbmem_initialize called after timestamp_init -- Case 3: No timestamp region, fresh boot, cbmem_initialize called before timestamp_init -- Case 4: No timestamp region, resume, cbmem_initialize called after timestamp_init -- Case 5: No timestamp region, resume, cbmem_initialize called before timestamp_init - - -## Introduction - -The aim of the timestamp library is to make it easier for different boards -to save timestamps in cbmem / stash (until cbmem is brought up) by -providing a simple API to initialize, add and sync timestamps. In order -to make the timestamps persistent and accessible from the kernel, we -need to ensure that all the saved timestamps end up in cbmem under -the CBMEM_ID_TIMESTAMP tag. However, until the cbmem area is available, -the timestamps can be saved to a SoC-defined \_timestamp region or in a -local stage-specific stash. The work of identifying the right location for -storing timestamps is done by the library and is not exposed to the user. - -Working of timestamp library from a user perspective can be outlined in -the following steps: -1. Initialize the base time and reset cbmem timestamp area -2. Start adding timestamps - -Behind the scenes, the timestamp library takes care of: -1. Identifying the correct location for storing timestamps (cbmem or timestamp - region or local stash). -2. Once cbmem is up, ensure that all timestamps are synced from timestamp - region or local stash into the cbmem area. -3. Add a new cbmem timestamp area based on whether a reset of the cbmem - timestamp region is required or not. - -### Transition from cache to cbmem - -To move timestamps from the cache to cbmem (and initialize the cbmem area in -the first place), we use the CBMEM_INIT_HOOK infrastructure of coreboot. - -When cbmem is initialized, the hook is called, which creates the area, -copies all timestamps to cbmem and disables the cache. - -After such a transition, timestamp_init() must not be run again. - - -## Data structures used - -The main structure that maintains information about the timestamp cache is: - -``` -struct __packed timestamp_cache { - uint16_t cache_state; - struct timestamp_table table; - struct timestamp_entry entries[MAX_TIMESTAMP_CACHE]; -}; -``` - -### cache_state - -The state of the cache is maintained by `cache_state` attribute which can -be any one of the following: - -``` -enum { - TIMESTAMP_CACHE_UNINITIALIZED = 0, - TIMESTAMP_CACHE_INITIALIZED, - TIMESTAMP_CACHE_NOT_NEEDED, -}; -``` - -By default, if the cache is stored in local stash (bss area), then -it will be reset to uninitialized state. However, if the cache is -stored in timestamp region, then it might have garbage in any of the -attributes. Thus, if the timestamp region is being used by any board, it is -initialized to default values by the library. - -Once the cache is initialized, its state is set to -`CACHE_INITIALIZED`. Henceforth, the calls to cache i.e. `timestamp_add` -know that the state reflected is valid and timestamps can be directly -saved in the cache. - -Once the cbmem area is up (i.e. call to `timestamp_sync_cache_to_cbmem`), -we do not need to store the timestamps in local stash / timestamp area -anymore. Thus, the cache state is set to `CACHE_NOT_NEEDED`, which allows -`timestamp_add` to store all timestamps directly into the cbmem area. - - -### table - -This field is represented by a structure which provides overall -information about the entries in the timestamp area: - -``` -struct timestamp_table { - uint64_t base_time; - uint32_t max_entries; - uint32_t num_entries; - struct timestamp_entry entries[0]; /* Variable number of entries */ -} __packed; -``` - -It indicates the base time for all timestamp entries, maximum number -of entries that can be stored, total number of entries that currently -exist and an entry structure to hold variable number of entries. - - -### entries - -This field holds the details of each timestamp entry, upto a maximum -of `MAX_TIMESTAMP_CACHE` which is defined as 16 entries. Each entry is -defined by: - -``` -struct timestamp_entry { - uint32_t entry_id; - uint64_t entry_stamp; -} __packed; -``` - -`entry_id` holds the timestamp id corresponding to this entry and -`entry_stamp` holds the actual timestamp. - - -For timestamps stored in the cbmem area, a `timestamp_table` is allocated -with space for `MAX_TIMESTAMPS` equal to 30. Thus, the cbmem area holds -`base_time`, `max_entries` (which is 30), current number of entries and the -actual entries represented by `timestamp_entry`. - - -## Function APIs - -### timestamp_init - -This function initializes the timestamp cache and should be run as early -as possible. On platforms with SRAM, this might mean in bootblock, on -x86 with its CAR backed memory in romstage, this means romstage before -memory init. - -### timestamp_add - -This function accepts from user a timestamp id and time to record in the -timestamp table. It stores the entry in the appropriate table in cbmem -or `_timestamp` region or local stash. - - -### timestamp_add_now - -This function calls `timestamp_add` with user-provided id and current time. - - -## Use / Test Cases - -The following cases have been considered while designing the timestamp -library. It is important to ensure that any changes made to this library satisfy -each of the following use cases: - -### Case 1: Timestamp Region Exists (Fresh Boot / Resume) - -In this case, the library needs to call `timestamp_init` as early as possible to -enable the timestamp cache. Once cbmem is available, the values will be -transferred automatically. - -All regions are automatically reset on initialization. - -### Case 2: No timestamp region, fresh boot, cbmem_initialize called after timestamp_init - -`timestamp_init` will set up a local cache. cbmem must be initialized before that -cache vanishes - as happens when jumping to the next stage. - -### Case 3: No timestamp region, fresh boot, cbmem_initialize called before timestamp_init - -This case is not supported right now, just don't call `timestamp_init` after -`cbmem_initialize`. (Patches to make this more robust are welcome.) - -### Case 4: No timestamp region, resume, cbmem_initialize called after timestamp_init - -We always reset the cbmem region before using it, so pre-suspend timestamps -will be gone. - -### Case 5: No timestamp region, resume, cbmem_initialize called before timestamp_init - -We always reset the cbmem region before using it, so pre-suspend timestamps -will be gone. -- cgit v1.2.3