[M] Change in coreboot[main]: Documentation/lib/timestamp.md: Reformat to 72 characters per line
Martin L Roth has uploaded this change for review. ( https://review.coreboot.org/c/coreboot/+/87291?usp=email )
Change subject: Documentation/lib/timestamp.md: Reformat to 72 characters per line ......................................................................
Documentation/lib/timestamp.md: Reformat to 72 characters per line
Change-Id: Ifecd528dc5ee3d728104632b84a505c70ac2077b Signed-off-by: Martin Roth gaumless@gmail.com --- M Documentation/lib/timestamp.md 1 file changed, 53 insertions(+), 47 deletions(-)
git pull ssh://review.coreboot.org:29418/coreboot refs/changes/91/87291/1
diff --git a/Documentation/lib/timestamp.md b/Documentation/lib/timestamp.md index a769f99..d08d442 100644 --- a/Documentation/lib/timestamp.md +++ b/Documentation/lib/timestamp.md @@ -2,15 +2,16 @@
## 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 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. +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: @@ -18,17 +19,18 @@ 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. +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. +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. @@ -38,7 +40,8 @@
## Data structures used
-The main structure that maintains information about the timestamp cache is: +The main structure that maintains information about the timestamp cache +is:
```c struct __packed timestamp_cache { @@ -50,8 +53,8 @@
### cache_state
-The state of the cache is maintained by `cache_state` attribute which can -be any one of the following: +The state of the cache is maintained by `cache_state` attribute which +can be any one of the following:
```c enum { @@ -61,10 +64,10 @@ }; ```
-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 +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 @@ -72,10 +75,11 @@ 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. +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 @@ -92,15 +96,15 @@ } __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. +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, up to a maximum -of `MAX_TIMESTAMP_CACHE` which is defined as 16 entries. Each entry is +This field holds the details of each timestamp entry, up to a maximum of +`MAX_TIMESTAMP_CACHE` which is defined as 16 entries. Each entry is defined by:
```c @@ -114,10 +118,10 @@ `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`. +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 @@ -138,39 +142,41 @@
### timestamp_add_now
-This function calls `timestamp_add` with user-provided id and current time. +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: +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. +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. +`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.) +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. +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. +We always reset the cbmem region before using it, so pre-suspend +timestamps will be gone.
-
Martin L Roth (Code Review)