Documentation/lib/timestamp.md: Reformat to 72 characters per line
Change-Id: Ifecd528dc5ee3d728104632b84a505c70ac2077b Signed-off-by: Martin Roth <gaumless@gmail.com> Reviewed-on: https://review.coreboot.org/c/coreboot/+/87291 Tested-by: build bot (Jenkins) <no-reply@coreboot.org> Reviewed-by: Nicholas Chin <nic.c3.14@gmail.com>
This commit is contained in:
Martin Roth
Matt DeVillier
parent
22118a137b
commit
2170ad0c60
1 changed files with 53 additions and 47 deletions
|
|
@ -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 @@ the following steps:
|
|||
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 @@ 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:
|
||||
The main structure that maintains information about the timestamp cache
|
||||
is:
|
||||
|
||||
```c
|
||||
struct __packed timestamp_cache {
|
||||
|
|
@ -50,8 +53,8 @@ struct __packed timestamp_cache {
|
|||
|
||||
### 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 @@ enum {
|
|||
};
|
||||
```
|
||||
|
||||
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 @@ Once the cache is initialized, its state is set to
|
|||
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 @@ struct timestamp_table {
|
|||
} __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 @@ struct timestamp_entry {
|
|||
`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 @@ or `_timestamp` region or local stash.
|
|||
|
||||
### 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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue