Documentation/timestamp.md

   1 Table of Contents
   2 =================
   3 Introduction
   4         Transition from cache to cbmem
   5
   6 Data structures used
   7         cache_state
   8         table
   9         entries
  10
  11 Function APIs
  12         timestamp_init
  13         timestamp_add
  14         timestamp_add_now
  15         timestamp_sync
  16
  17 Use / Test Cases
  18         Case 1: Timestamp Region Exists
  19         Case 2: No timestamp region, fresh boot, cbmem_initialize called after
  20         timestamp_init
  21         Case 3: No timestamp region, fresh boot, cbmem_initialize called before
  22         timestamp_init
  23         Case 4: No timestamp region, resume, cbmem_initialize called after
  24         timestamp_init
  25         Case 5: No timestamp region, resume, cbmem_initialize called before
  26         timestamp_init
  27
  28
  29 Introduction
  30 ============
  31 The aim of the timestamp library is to make it easier for different boards
  32 to  save timestamps in cbmem / stash (until cbmem is brought up) by
  33 providing a simple API to initialize, add and sync timestamps. In order
  34 to make the timestamps persistent and accessible from the kernel, we
  35 need to ensure that all the saved timestamps end up in cbmem under
  36 the CBMEM_ID_TIMESTAMP tag. However, until the cbmem area is available,
  37 the timestamps can be saved to a SoC-defined \_timestamp region or in a
  38 local stage-specific stash. The work of identifying the right location for
  39 storing timestamps is done by the library and is not exposed to the user.
  40
  41 Working of timestamp library from a user perspective can be outlined in
  42 the following steps:
  43 1. Initialize the base time and reset cbmem timestamp area
  44 2. Start adding timestamps
  45
  46 Behind the scenes, the timestamp library takes care of:
  47 1. Identifying the correct location for storing timestamps (cbmem or timestamp
  48    region or local stash).
  49 2. Once cbmem is up, ensure that all timestamps are synced from timestamp
  50    region or local stash into the cbmem area.
  51 3. Add a new cbmem timestamp area based on whether a reset of the cbmem
  52    timestamp region is required or not.
  53
  54 Transition from cache to cbmem
  55 ------------------------------
  56 To move timestamps from the cache to cbmem (and initialize the cbmem area in
  57 the first place), we use the CBMEM_INIT_HOOK infrastructure of coreboot.
  58
  59 When cbmem is initialized, the hook is called, which creates the area,
  60 copies all timestamps to cbmem and disables the cache.
  61
  62 After such a transition, timestamp_init() must not be run again.
  63
  64
  65 Data structures used
  66 ====================
  67 The main structure that maintains information about the timestamp cache is:
  68 struct __attribute__((__packed__)) timestamp_cache {
  69         uint16_t cache_state;
  70         struct timestamp_table table;
  71         struct timestamp_entry entries[MAX_TIMESTAMP_CACHE];
  72 };
  73
  74 cache_state
  75 -----------
  76 The state of the cache is maintained by cache_state attribute which can
  77 be any one of the following:
  78
  79 enum {
  80         TIMESTAMP_CACHE_UNINITIALIZED = 0,
  81         TIMESTAMP_CACHE_INITIALIZED,
  82         TIMESTAMP_CACHE_NOT_NEEDED,
  83 };
  84
  85 By default, if the cache is stored in local stash (bss area), then
  86 it will be reset to uninitialized state. However, if the cache is
  87 stored in timestamp region, then it might have garbage in any of the
  88 attributes. Thus, if the timestamp region is being used by any board, it is
  89 initialized to default values by the library.
  90
  91 Once the cache is initialized, its state is set to
  92 CACHE_INITIALIZED. Henceforth, the calls to cache i.e. timestamp_add
  93 know that the state reflected is valid and timestamps can be directly
  94 saved in the cache.
  95
  96 Once the cbmem area is up (i.e. call to timestamp_sync_cache_to_cbmem),
  97 we do not need to store the timestamps in local stash / timestamp area
  98 anymore. Thus, the cache state is set to CACHE_NOT_NEEDED, which allows
  99 timestamp_add to store all timestamps directly into the cbmem area.
 100
 101
 102 table
 103 -----
 104 This field is represented by a structure which provides overall
 105 information about the entries in the timestamp area:
 106
 107 struct timestamp_table {
 108         uint64_t        base_time;
 109         uint32_t        max_entries;
 110         uint32_t        num_entries;
 111         struct timestamp_entry entries[0]; /* Variable number of entries */
 112 } __attribute__((packed));
 113
 114 It indicates the base time for all timestamp entries, maximum number
 115 of entries that can be stored, total number of entries that currently
 116 exist and an entry structure to hold variable number of entries.
 117
 118
 119 entries
 120 -------
 121 This field holds the details of each timestamp entry, upto a maximum
 122 of MAX_TIMESTAMP_CACHE which is defined as 16 entries. Each entry is
 123 defined by:
 124
 125 struct timestamp_entry {
 126         uint32_t        entry_id;
 127         uint64_t        entry_stamp;
 128 } __attribute__((packed));
 129
 130 entry_id holds the timestamp id corresponding to this entry and
 131 entry_stamp holds the actual timestamp.
 132
 133
 134 For timestamps stored in the cbmem area, a timestamp_table is allocated
 135 with space for MAX_TIMESTAMPS equal to 30. Thus, the cbmem area holds
 136 base_time, max_entries (which is 30), current number of entries and the
 137 actual entries represented by timestamp_entry.
 138
 139
 140 Function APIs
 141 =============
 142
 143 timestamp_init
 144 --------------
 145 This function initializes the timestamp cache and should be run as early
 146 as possible. On platforms with SRAM, this might mean in bootblock, on
 147 x86 with its CAR backed memory in romstage, this means romstage before
 148 memory init.
 149
 150 timestamp_add
 151 -------------
 152 This function accepts from user a timestamp id and time to record in the
 153 timestamp table. It stores the entry in the appropriate table in cbmem
 154 or _timestamp region or local stash.
 155
 156
 157 timestamp_add_now
 158 -----------------
 159 This function calls timestamp_add with user-provided id and current time.
 160
 161
 162 Use / Test Cases
 163 ================
 164
 165 The following cases have been considered while designing the timestamp
 166 library. It is important to ensure that any changes made to this library satisfy
 167 each of the following use cases:
 168
 169 Case 1: Timestamp Region Exists (Fresh Boot / Resume)
 170 -----------------------------------------------------
 171
 172 In this case, the library needs to call timestamp_init as early as possible to
 173 enable the timestamp cache. Once cbmem is available, the values will be
 174 transferred automatically.
 175
 176 All regions are automatically reset on initialization.
 177
 178 Case 2: No timestamp region, fresh boot, cbmem_initialize called after timestamp_init
 179 -------------------------------------------------------------------------------------
 180
 181 timestamp_init will set up a local cache. cbmem must be initialized before that
 182 cache vanishes - as happens when jumping to the next stage.
 183
 184 Case 3: No timestamp region, fresh boot, cbmem_initialize called before timestamp_init
 185 --------------------------------------------------------------------------------------
 186
 187 This case is not supported right now, just don't call timestamp_init after
 188 cbmem_initialize. (Patches to make this more robust are welcome.)
 189
 190 Case 4: No timestamp region, resume, cbmem_initialize called after timestamp_init
 191 ---------------------------------------------------------------------------------
 192
 193 We always reset the cbmem region before using it, so pre-suspend timestamps
 194 will be gone.
 195
 196 Case 5: No timestamp region, resume, cbmem_initialize called before timestamp_init
 197 ----------------------------------------------------------------------------------
 198
 199 We always reset the cbmem region before using it, so pre-suspend timestamps
 200 will be gone.