<p>Jonathan Neuschäfer has uploaded this change for <strong>review</strong>.</p><p><a href="https://review.coreboot.org/25680">View Change</a></p><pre style="font-family: monospace,monospace; white-space: pre-wrap;">Documentation/timestamp.md: Fix markdown formatting<br><br>Fix the headline levels (only the document's title should be a top-level<br>document), and use "# " instead of "====" to mark headlines, because<br>it's more obvious what the different levels of that are. Also fix some<br>other things.<br><br>Arguably, the explicit table of contents could be removed.<br><br>Change-Id: Ie29b6393e9d7871ea3c900e016b5c3ed415538ac<br>Signed-off-by: Jonathan Neuschäfer <j.neuschaefer@gmx.net><br>---<br>M Documentation/timestamp.md<br>1 file changed, 69 insertions(+), 69 deletions(-)<br><br></pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;">git pull ssh://review.coreboot.org:29418/coreboot refs/changes/80/25680/1</pre><pre style="font-family: monospace,monospace; white-space: pre-wrap;"><span>diff --git a/Documentation/timestamp.md b/Documentation/timestamp.md</span><br><span>index 821d462..bee4745 100644</span><br><span>--- a/Documentation/timestamp.md</span><br><span>+++ b/Documentation/timestamp.md</span><br><span>@@ -1,33 +1,31 @@</span><br><span style="color: hsl(0, 100%, 40%);">-Table of Contents</span><br><span style="color: hsl(0, 100%, 40%);">-=================</span><br><span style="color: hsl(120, 100%, 40%);">+# Timestamps</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+## Table of Contents</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> Introduction</span><br><span style="color: hsl(0, 100%, 40%);">- Transition from cache to cbmem</span><br><span style="color: hsl(120, 100%, 40%);">+- Transition from cache to cbmem</span><br><span> </span><br><span> Data structures used</span><br><span style="color: hsl(0, 100%, 40%);">- cache_state</span><br><span style="color: hsl(0, 100%, 40%);">- table</span><br><span style="color: hsl(0, 100%, 40%);">- entries</span><br><span style="color: hsl(120, 100%, 40%);">+- cache_state</span><br><span style="color: hsl(120, 100%, 40%);">+- table</span><br><span style="color: hsl(120, 100%, 40%);">+- entries</span><br><span> </span><br><span> Function APIs</span><br><span style="color: hsl(0, 100%, 40%);">- timestamp_init</span><br><span style="color: hsl(0, 100%, 40%);">- timestamp_add</span><br><span style="color: hsl(0, 100%, 40%);">- timestamp_add_now</span><br><span style="color: hsl(0, 100%, 40%);">- timestamp_sync</span><br><span style="color: hsl(120, 100%, 40%);">+- timestamp_init</span><br><span style="color: hsl(120, 100%, 40%);">+- timestamp_add</span><br><span style="color: hsl(120, 100%, 40%);">+- timestamp_add_now</span><br><span style="color: hsl(120, 100%, 40%);">+- timestamp_sync</span><br><span> </span><br><span> Use / Test Cases</span><br><span style="color: hsl(0, 100%, 40%);">- Case 1: Timestamp Region Exists</span><br><span style="color: hsl(0, 100%, 40%);">- Case 2: No timestamp region, fresh boot, cbmem_initialize called after</span><br><span style="color: hsl(0, 100%, 40%);">- timestamp_init</span><br><span style="color: hsl(0, 100%, 40%);">- Case 3: No timestamp region, fresh boot, cbmem_initialize called before</span><br><span style="color: hsl(0, 100%, 40%);">- timestamp_init</span><br><span style="color: hsl(0, 100%, 40%);">- Case 4: No timestamp region, resume, cbmem_initialize called after</span><br><span style="color: hsl(0, 100%, 40%);">- timestamp_init</span><br><span style="color: hsl(0, 100%, 40%);">- Case 5: No timestamp region, resume, cbmem_initialize called before</span><br><span style="color: hsl(0, 100%, 40%);">- timestamp_init</span><br><span style="color: hsl(120, 100%, 40%);">+- Case 1: Timestamp Region Exists</span><br><span style="color: hsl(120, 100%, 40%);">+- Case 2: No timestamp region, fresh boot, cbmem_initialize called after timestamp_init</span><br><span style="color: hsl(120, 100%, 40%);">+- Case 3: No timestamp region, fresh boot, cbmem_initialize called before timestamp_init</span><br><span style="color: hsl(120, 100%, 40%);">+- Case 4: No timestamp region, resume, cbmem_initialize called after timestamp_init</span><br><span style="color: hsl(120, 100%, 40%);">+- Case 5: No timestamp region, resume, cbmem_initialize called before timestamp_init</span><br><span> </span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Introduction</span><br><span style="color: hsl(0, 100%, 40%);">-============</span><br><span style="color: hsl(120, 100%, 40%);">+## Introduction</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> The aim of the timestamp library is to make it easier for different boards</span><br><span> to save timestamps in cbmem / stash (until cbmem is brought up) by</span><br><span> providing a simple API to initialize, add and sync timestamps. In order</span><br><span>@@ -51,8 +49,8 @@</span><br><span> 3. Add a new cbmem timestamp area based on whether a reset of the cbmem</span><br><span> timestamp region is required or not.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Transition from cache to cbmem</span><br><span>-------------------------------</span><br><span style="color: hsl(120, 100%, 40%);">+### Transition from cache to cbmem</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> To move timestamps from the cache to cbmem (and initialize the cbmem area in</span><br><span> the first place), we use the CBMEM_INIT_HOOK infrastructure of coreboot.</span><br><span> </span><br><span>@@ -62,25 +60,30 @@</span><br><span> After such a transition, timestamp_init() must not be run again.</span><br><span> </span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Data structures used</span><br><span style="color: hsl(0, 100%, 40%);">-====================</span><br><span style="color: hsl(120, 100%, 40%);">+## Data structures used</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> The main structure that maintains information about the timestamp cache is:</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span> struct __packed timestamp_cache {</span><br><span> uint16_t cache_state;</span><br><span> struct timestamp_table table;</span><br><span> struct timestamp_entry entries[MAX_TIMESTAMP_CACHE];</span><br><span> };</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-cache_state</span><br><span>------------</span><br><span style="color: hsl(0, 100%, 40%);">-The state of the cache is maintained by cache_state attribute which can</span><br><span style="color: hsl(120, 100%, 40%);">+### cache_state</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+The state of the cache is maintained by `cache_state` attribute which can</span><br><span> be any one of the following:</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span> enum {</span><br><span> TIMESTAMP_CACHE_UNINITIALIZED = 0,</span><br><span> TIMESTAMP_CACHE_INITIALIZED,</span><br><span> TIMESTAMP_CACHE_NOT_NEEDED,</span><br><span> };</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span> </span><br><span> By default, if the cache is stored in local stash (bss area), then</span><br><span> it will be reset to uninitialized state. However, if the cache is</span><br><span>@@ -89,112 +92,109 @@</span><br><span> initialized to default values by the library.</span><br><span> </span><br><span> Once the cache is initialized, its state is set to</span><br><span style="color: hsl(0, 100%, 40%);">-CACHE_INITIALIZED. Henceforth, the calls to cache i.e. timestamp_add</span><br><span style="color: hsl(120, 100%, 40%);">+`CACHE_INITIALIZED`. Henceforth, the calls to cache i.e. `timestamp_add`</span><br><span> know that the state reflected is valid and timestamps can be directly</span><br><span> saved in the cache.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Once the cbmem area is up (i.e. call to timestamp_sync_cache_to_cbmem),</span><br><span style="color: hsl(120, 100%, 40%);">+Once the cbmem area is up (i.e. call to `timestamp_sync_cache_to_cbmem`),</span><br><span> we do not need to store the timestamps in local stash / timestamp area</span><br><span style="color: hsl(0, 100%, 40%);">-anymore. Thus, the cache state is set to CACHE_NOT_NEEDED, which allows</span><br><span style="color: hsl(0, 100%, 40%);">-timestamp_add to store all timestamps directly into the cbmem area.</span><br><span style="color: hsl(120, 100%, 40%);">+anymore. Thus, the cache state is set to `CACHE_NOT_NEEDED`, which allows</span><br><span style="color: hsl(120, 100%, 40%);">+`timestamp_add` to store all timestamps directly into the cbmem area.</span><br><span> </span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-table</span><br><span>------</span><br><span style="color: hsl(120, 100%, 40%);">+### table</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> This field is represented by a structure which provides overall</span><br><span> information about the entries in the timestamp area:</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span> struct timestamp_table {</span><br><span> uint64_t base_time;</span><br><span> uint32_t max_entries;</span><br><span> uint32_t num_entries;</span><br><span> struct timestamp_entry entries[0]; /* Variable number of entries */</span><br><span> } __packed;</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span> </span><br><span> It indicates the base time for all timestamp entries, maximum number</span><br><span> of entries that can be stored, total number of entries that currently</span><br><span> exist and an entry structure to hold variable number of entries.</span><br><span> </span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-entries</span><br><span>--------</span><br><span style="color: hsl(120, 100%, 40%);">+### entries</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> This field holds the details of each timestamp entry, upto a maximum</span><br><span style="color: hsl(0, 100%, 40%);">-of MAX_TIMESTAMP_CACHE which is defined as 16 entries. Each entry is</span><br><span style="color: hsl(120, 100%, 40%);">+of `MAX_TIMESTAMP_CACHE` which is defined as 16 entries. Each entry is</span><br><span> defined by:</span><br><span> </span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span> struct timestamp_entry {</span><br><span> uint32_t entry_id;</span><br><span> uint64_t entry_stamp;</span><br><span> } __packed;</span><br><span style="color: hsl(120, 100%, 40%);">+```</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-entry_id holds the timestamp id corresponding to this entry and</span><br><span style="color: hsl(0, 100%, 40%);">-entry_stamp holds the actual timestamp.</span><br><span style="color: hsl(120, 100%, 40%);">+`entry_id` holds the timestamp id corresponding to this entry and</span><br><span style="color: hsl(120, 100%, 40%);">+`entry_stamp` holds the actual timestamp.</span><br><span> </span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-For timestamps stored in the cbmem area, a timestamp_table is allocated</span><br><span style="color: hsl(0, 100%, 40%);">-with space for MAX_TIMESTAMPS equal to 30. Thus, the cbmem area holds</span><br><span style="color: hsl(0, 100%, 40%);">-base_time, max_entries (which is 30), current number of entries and the</span><br><span style="color: hsl(0, 100%, 40%);">-actual entries represented by timestamp_entry.</span><br><span style="color: hsl(120, 100%, 40%);">+For timestamps stored in the cbmem area, a `timestamp_table` is allocated</span><br><span style="color: hsl(120, 100%, 40%);">+with space for `MAX_TIMESTAMPS` equal to 30. Thus, the cbmem area holds</span><br><span style="color: hsl(120, 100%, 40%);">+`base_time`, `max_entries` (which is 30), current number of entries and the</span><br><span style="color: hsl(120, 100%, 40%);">+actual entries represented by `timestamp_entry`.</span><br><span> </span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Function APIs</span><br><span style="color: hsl(0, 100%, 40%);">-=============</span><br><span style="color: hsl(120, 100%, 40%);">+## Function APIs</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-timestamp_init</span><br><span>---------------</span><br><span style="color: hsl(120, 100%, 40%);">+### timestamp_init</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> This function initializes the timestamp cache and should be run as early</span><br><span> as possible. On platforms with SRAM, this might mean in bootblock, on</span><br><span> x86 with its CAR backed memory in romstage, this means romstage before</span><br><span> memory init.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-timestamp_add</span><br><span>--------------</span><br><span style="color: hsl(120, 100%, 40%);">+### timestamp_add</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span> This function accepts from user a timestamp id and time to record in the</span><br><span> timestamp table. It stores the entry in the appropriate table in cbmem</span><br><span style="color: hsl(0, 100%, 40%);">-or _timestamp region or local stash.</span><br><span style="color: hsl(120, 100%, 40%);">+or `_timestamp` region or local stash.</span><br><span> </span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-timestamp_add_now</span><br><span>------------------</span><br><span style="color: hsl(0, 100%, 40%);">-This function calls timestamp_add with user-provided id and current time.</span><br><span style="color: hsl(120, 100%, 40%);">+### timestamp_add_now</span><br><span style="color: hsl(120, 100%, 40%);">+</span><br><span style="color: hsl(120, 100%, 40%);">+This function calls `timestamp_add` with user-provided id and current time.</span><br><span> </span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Use / Test Cases</span><br><span style="color: hsl(0, 100%, 40%);">-================</span><br><span style="color: hsl(120, 100%, 40%);">+## Use / Test Cases</span><br><span> </span><br><span> The following cases have been considered while designing the timestamp</span><br><span> library. It is important to ensure that any changes made to this library satisfy</span><br><span> each of the following use cases:</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Case 1: Timestamp Region Exists (Fresh Boot / Resume)</span><br><span>------------------------------------------------------</span><br><span style="color: hsl(120, 100%, 40%);">+### Case 1: Timestamp Region Exists (Fresh Boot / Resume)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-In this case, the library needs to call timestamp_init as early as possible to</span><br><span style="color: hsl(120, 100%, 40%);">+In this case, the library needs to call `timestamp_init` as early as possible to</span><br><span> enable the timestamp cache. Once cbmem is available, the values will be</span><br><span> transferred automatically.</span><br><span> </span><br><span> All regions are automatically reset on initialization.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Case 2: No timestamp region, fresh boot, cbmem_initialize called after timestamp_init</span><br><span>--------------------------------------------------------------------------------------</span><br><span style="color: hsl(120, 100%, 40%);">+### Case 2: No timestamp region, fresh boot, cbmem_initialize called after timestamp_init</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-timestamp_init will set up a local cache. cbmem must be initialized before that</span><br><span style="color: hsl(120, 100%, 40%);">+`timestamp_init` will set up a local cache. cbmem must be initialized before that</span><br><span> cache vanishes - as happens when jumping to the next stage.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Case 3: No timestamp region, fresh boot, cbmem_initialize called before timestamp_init</span><br><span>---------------------------------------------------------------------------------------</span><br><span style="color: hsl(120, 100%, 40%);">+### Case 3: No timestamp region, fresh boot, cbmem_initialize called before timestamp_init</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-This case is not supported right now, just don't call timestamp_init after</span><br><span style="color: hsl(0, 100%, 40%);">-cbmem_initialize. (Patches to make this more robust are welcome.)</span><br><span style="color: hsl(120, 100%, 40%);">+This case is not supported right now, just don't call `timestamp_init` after</span><br><span style="color: hsl(120, 100%, 40%);">+`cbmem_initialize`. (Patches to make this more robust are welcome.)</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Case 4: No timestamp region, resume, cbmem_initialize called after timestamp_init</span><br><span>----------------------------------------------------------------------------------</span><br><span style="color: hsl(120, 100%, 40%);">+### Case 4: No timestamp region, resume, cbmem_initialize called after timestamp_init</span><br><span> </span><br><span> We always reset the cbmem region before using it, so pre-suspend timestamps</span><br><span> will be gone.</span><br><span> </span><br><span style="color: hsl(0, 100%, 40%);">-Case 5: No timestamp region, resume, cbmem_initialize called before timestamp_init</span><br><span>-----------------------------------------------------------------------------------</span><br><span style="color: hsl(120, 100%, 40%);">+### Case 5: No timestamp region, resume, cbmem_initialize called before timestamp_init</span><br><span> </span><br><span> We always reset the cbmem region before using it, so pre-suspend timestamps</span><br><span> will be gone.</span><br><span></span><br></pre><p>To view, visit <a href="https://review.coreboot.org/25680">change 25680</a>. To unsubscribe, or for help writing mail filters, visit <a href="https://review.coreboot.org/settings">settings</a>.</p><div itemscope itemtype="http://schema.org/EmailMessage"><div itemscope itemprop="action" itemtype="http://schema.org/ViewAction"><link itemprop="url" href="https://review.coreboot.org/25680"/><meta itemprop="name" content="View Change"/></div></div>
<div style="display:none"> Gerrit-Project: coreboot </div>
<div style="display:none"> Gerrit-Branch: master </div>
<div style="display:none"> Gerrit-MessageType: newchange </div>
<div style="display:none"> Gerrit-Change-Id: Ie29b6393e9d7871ea3c900e016b5c3ed415538ac </div>
<div style="display:none"> Gerrit-Change-Number: 25680 </div>
<div style="display:none"> Gerrit-PatchSet: 1 </div>
<div style="display:none"> Gerrit-Owner: Jonathan Neuschäfer <j.neuschaefer@gmx.net> </div>