[PATCH 01/12] MdePkg: Add DebugBootlog header

["Alexander Graf" <graf@amazon.com>]

We will shortly introduce a new bootlog framework. This commit contains the
main library header that defines its data structure and public APIs.

Signed-off-by: Alexander Graf <graf@amazon.com>
---
 MdePkg/Include/Library/DebugBootlog.h | 141 ++++++++++++++++++++++++++
 1 file changed, 141 insertions(+)
 create mode 100644 MdePkg/Include/Library/DebugBootlog.h

diff --git a/MdePkg/Include/Library/DebugBootlog.h b/MdePkg/Include/Library/DebugBootlog.h
new file mode 100644
index 0000000000..5e6b05411c
--- /dev/null
+++ b/MdePkg/Include/Library/DebugBootlog.h
@@ -0,0 +1,141 @@
+/** @file
+  Base Debug library for a RAM based boot log
+  It provides functions to store debug messages in RAM and make them available as
+  Bootlog Configuration Table.
+
+  Copyright (c) 2006 - 2019, Intel Corporation. All rights reserved.<BR>
+  Copyright (c) 2012, Red Hat, Inc.<BR>
+  Copyright (c) 2022, Amazon Development Center Germany GmbH.<BR>
+  SPDX-License-Identifier: BSD-2-Clause-Patent
+
+**/
+
+#include <Base.h>
+
+/*
+ * The bootlog framework is a way to collect all boot logging streams from the
+ * system into a single, condensed and time correlated data format. Its purpose
+ * is to allow extraction and correlation of boot logs from within the Operating
+ * System. Unlike I/O based logging, it's very cheap to use and can be used to
+ * easily identify duration of boot time code paths.
+ *
+ * Its intended use in edk2 is as a print backend for DebugLib, however you can
+ * use it stand alone as well. To append an edk2 log line, call
+ * DebugBootlogAppend() with the UTF-8 encoded string to append. The framework
+ * will initialize the boot log and add a configuration table if not existent
+ * automatically.
+ *
+ * The bootlog entry point is the bootlog configuration table. That table
+ * contains a dynamic number of pointers to bootlog logs. Each of these logs
+ * belong to one component of the boot flow, such as edk2 or grub and contain a
+ * dynamic number of log entries, each with a time stamp and optional additional
+ * data.
+ *
+ * All fields are Little Endian.
+ *
+ *  ___________________________________________________
+ * |             Bootlog Configuration Table           |
+ * |---------------------------------------------------|
+ * | UINT32 Signature | "BTLG"                         |
+ * | UINT16 MaxLogs   | Maximum number of logs this    |
+ * |                  | configuration table can hold.  |
+ * |                  | If you need more, create a     |
+ * |                  | clone and reregister it.       |
+ * | UINT16 NrLogs    | Number of occupied Log slots   |
+ * | BOOTLOG *Log[0]  |                             ---+------------,
+ * | BOOTLOG *Log[..] |                             ---+------------|
+ * |___________________________________________________|            |
+ *  ___________________________________________________________    /
+ * |                          Bootlog                          | <´
+ * |-----------------------------------------------------------|
+ * | UINT32 Signature          | "BTLH"                        |
+ * | CHAR8[4] Producer         | "edk2" for edk2, boot binary  |
+ * |                           | dependent.                    |
+ * | UINT16 ExtraHeaderType    | 1 for edk2                    |
+ * | UINT8  ExtraHeaderSize    | Bytes for ExtraHeader below   |
+ * | UINT8  MsgExtraHeaderSize | Bytes for Extra header in     |
+ * |                           | each log line                 |
+ * | UINT32 LastByte           | Length of the log, starting   |
+ * |                           | at &Signature                 |
+ * | UINT64 TicksPerSecond     | Frequency of the timer for    |
+ * |                           | each log line. Time at system |
+ * |                           | reset is 0 for all logs.      |
+ * | ExtraHeader ExtraHeader   | Depends on Type above      ---+---,
+ * | BootlogMessage Msgs[]     | Log lines                  ---+---|--,
+ * |___________________________________________________________|   |  |
+ *  _________________________________________________________     /   |
+ * |                     ExtraHeader (edk2)                  | <-´    |
+ * |---------------------------------------------------------|        |
+ * | UINT32 AllocatedSize | Size of the allocation for the   |        |
+ * |                      | current bootlog. Used internally |        |
+ * |                      | to resize on demand.             |        |
+ * |_________________________________________________________|        |
+ *  _________________________________________________________        /
+ * |                 Bootlog Message (edk2)                  | <----´
+ * |---------------------------------------------------------|
+ * | UINT32 ErrorLevel | edk2 defined ErrorLevel             |
+ * | UINT64 Ticks      | Ticks since power on                |
+ * | CHAR8  String[]   | '\0' terminated UTF-8 message       |
+ * |_________________________________________________________|
+ */
+
+
+#define SIG_BOOTLOG_CONFIG_TABLE 0x474c5442 /* BTLG */
+#define SIG_BOOTLOG_HEADER       0x484c5442 /* BTLH */
+
+#define BOOTLOG_PRODUCER "edk2"
+
+enum BOOTLOG_EXTRA_HEADER_TYPE {
+  BOOTLOG_EXTRA_HEADER_EDK2 = 1,
+};
+
+typedef struct {
+  UINT32 Signature;
+  UINT16 MaxLogs;
+  UINT16 NrLogs;
+  UINT64 LogAddress[];
+} BOOTLOG_CONFIG_TABLE;
+
+typedef struct {
+  UINT32 AllocatedSize;  /* Maximum space available for the log */
+} BOOTLOG_EXTRA_HEADER;
+
+typedef struct {
+  UINT32               Signature;            /* "BTLH" */
+  CHAR8                Producer[4];          /* "edk2" */
+  UINT16               ExtraHeaderType;      /* enum BOOTLOG_EXTRA_HEADER_TYPE */
+  UINT8                ExtraHeaderSize;      /* sizeof(ExtraHeader) */
+  UINT8                MsgExtraHeaderSize;   /* sizeof(BOOTLOG_ENTRY_EDK2) -
+                                                sizeof(BOOTLOG_ENTRY) */
+  UINT32               LastByte;             /* sizeof(BOOTLOG_HEADER) +
+                                                sizeof(Data) */
+  UINT64               TicksPerSecond;       /* Tick frequency. */
+  BOOTLOG_EXTRA_HEADER ExtraHeader;
+  CHAR8                Data[];               /* Multiple successive
+                                                BOOTLOG_ENTRY_EDK2 entries,
+                                                ends at LastByte */
+} BOOTLOG_HEADER;
+
+typedef struct {
+  UINT64 Ticks;                              /* Ticks since system start. */
+  CHAR8  String[];                           /* NULL terminated UTF-8 */
+} BOOTLOG_ENTRY;
+
+typedef struct {
+  UINT32        ErrorLevel;
+  BOOTLOG_ENTRY Log;
+} BOOTLOG_ENTRY_EDK2;
+
+RETURN_STATUS
+EFIAPI
+DebugBootlogAppend (
+  IN  CONST CHAR8  *String,
+  IN        UINTN  Length,
+  IN        UINTN  ErrorLevel
+  );
+
+UINT32
+EFIAPI
+GetDebugBootlogErrorLevel (
+  VOID
+  );
-- 
2.28.0.394.ge197136389




Amazon Development Center Germany GmbH
Krausenstr. 38
10117 Berlin
Geschaeftsfuehrung: Christian Schlaeger, Jonathan Weiss
Eingetragen am Amtsgericht Charlottenburg unter HRB 149173 B
Sitz: Berlin
Ust-ID: DE 289 237 879