1# BIOS->BMC SMM Error Logging Queue Daemon 2 3Author: 4* Brandon Kim / brandonkim@google.com / @brandonk 5 6Other contributors: 7* Marco Cruz-Heredia / mcruzheredia@google.com 8 9Created: 10 Mar 15, 2022 11 12## Problem Description 13 14We've identified use cases where the BIOS will go into System Management Mode 15(SMM) to provide error logs to the BMC, requiring messages to be sent as quickly 16as possible without a handshake / ack back from the BMC due to the time 17constraint that it's under. The goal of this daemon we are proposing is to 18implement a circular buffer over a shared BIOS->BMC buffer that the BIOS can 19fire-and-forget. 20 21## Background and References 22 23There are various ways of communicating between the BMC and the BIOS, but there 24are only a few that don't require a handshake and lets the data persist in 25shared memory. These will be listed in the "Alternatives Considered" section. 26 27Different BMC vendors support different methods such as Shared Memory (SHM, via 28LPC / eSPI) and P2A or PCI Mailbox, but the existing daemon that utilizes them 29do it over IPMI blob to communicate where and how much data has been 30transferred (see [phosphor-ipmi-flash](https://github.com/openbmc/phosphor-ipmi-flash) 31and [libmctp/astlpc](https://github.com/openbmc/libmctp/blob/master/docs/bindings/vendor-ibm-astlpc.md)) 32 33## Requirements 34 35The fundamental requirements for this daemon are listed as follows: 36 371. The BMC shall initialize the shared buffer in a way that the BIOS can 38 recognize when it can write to the buffer 392. After initialization, the BIOS shall not have to wait for an ack back from 40 the BMC before any writes to the shared buffer (**no synchronization**) 413. The BIOS shall be the main writer to the shared buffer, with the BMC mainly 42 reading the payloads, only writing to the buffer to update the header 434. The BMC shall read new payloads from the shared buffer for further processing 445. The BIOS must be able to write a payload (~1KB) to the buffer within 50µs 45 46The shared buffer will be as big as the protocol allows for a given BMC platform 47(for Nuvoton's PCI Mailbox for NPCM 7xx as an example, 16KB) and each of the 48payloads is estimated to be less than 1KB. 49 50This daemon assumes that no other traffic will communicate through the given 51protocol. The circular buffer and its header will provide some protection 52against corruption, but it should not be relied upon. 53 54## Proposed Design 55 56The implementation of interfacing with the shared buffer will very closely 57follow [phosphor-ipmi-flash](https://github.com/openbmc/phosphor-ipmi-flash). In 58the future, it may be wise to extract out the PCI Mailbox, P2A and LPC as 59separate libraries shared between `phosphor-ipmi-flash` and this daemon to 60reduce duplication of code. 61 62Taken from Marco's (mcruzheredia@google.com) internal design document for the 63circular buffer, the data structure of its header will look like the following: 64 65| Name | Size | Offset | Written by | Description | 66| ---------- | ----------- | ----------- | ------------ | ----------------- | 67| BMC Interface Version | 4 bytes | 0x0 | BMC at init | Allows the BIOS to determine if it is compatible with the BMC | 68| BIOS Interface Version | 4 bytes | 0x4 | BIOS at init | Allows the BMC to determine if it is compatible with the BIOS | 69| Magic Number | 16 bytes | 0x8 | BMC at init | Magic number to set the state of the queue as described below. Written by BMC once the memory region is ready to be used. Must be checked by BIOS before logging. BMC can change this number when it suspects data corruption to prevent BIOS from writing anything during reinitialization | 70| Queue size | 4 bytes | 0x18 | BMC at init | Indicates the size of the region allocated for the circular queue. Written by BMC on init only, should not change during runtime | 71| Uncorrectable Error region size | 2 bytes | 0x1c | BMC at init | Indicates the size of the region reserved for Uncorrectable Error (UE) logs. Written by BMC on init only, should not change during runtime | 72| BMC flags | 4 bytes | 0x1e | BMC | <ul><li>BIT0 - BMC UE reserved region “switch”<ul><li>Toggled when BMC reads a UE from the reserved region.</li></ul><li>BIT1 - Overflow<ul><li>Lets BIOS know BMC has seen the overflow incident</li><li>Toggled when BMC acks the overflow incident</li></ul><li>BIT2 - BMC_READY<ul><li>BMC sets this bit once it has received any initialization information it needs to get from the BIOS before it’s ready to receive logs.</li></ul> | 73| BMC read pointer | 4 bytes | 0x22 | BMC | Used to allow the BIOS to detect when the BMC was unable to read the previous error logs in time to prevent the circular buffer from overflowing. | 74| Padding | 2 bytes | 0x26 | Reserved | Padding for 8 byte alignment | 75| BIOS flags | 4 bytes | 0x28 | BIOS | <ul><li>BIT0 - BIOS UE reserved region “switch”<ul><li> Toggled when BIOS writes a UE to the reserved region.</li></ul><li>BIT1 - Overflow<ul><li>Lets the BMC know that it missed an error log</li><li>Toggled when BIOS sees overflow and not already overflowed</li></ul><li>BIT2 - Incomplete Initialization<ul><li>Set when BIOS has attempted to initialize but did not see BMC ack back with `BMC_READY` bit in BMC flags</li></ul>| 76| BIOS write pointer | 4 bytes | 0x2c | BIOS | Indicates where the next log will be written by BIOS. Used to tell BMC when it should read a new log | 77| Uncorrectable Error reserved region | TBD1 | 0x30 | BIOS | Reserved region only for UE logs. This region is only used if the rest of the buffer is going to overflow and there is no unread UE log already in the region. | 78| Error Logs from BIOS | Size of the Buffer - 0x30 - TBD1 | 0x30 + TBD1 | BIOS | Logs vary by type, so each log will self-describe with a header. This region will fill up the rest of the buffer | 79 80### Initialization 81 82This daemon will first initialize the shared buffer by writing zero to the whole 83buffer, then initializing the header's `BMC at init` fields before writing the 84`Magic Number`. Once the `Magic Number` is written to, the BIOS will assume that 85the shared buffer has been properly initialized, and will be able to start 86writing entries to it. 87 88If there are any further initialization between the BIOS and the BMC required, 89the BMC needs to set the `BMC_READY` bit in the BMC flags once the 90initialization completes. If the BIOS does not see the flag being set, the BIOS 91shall set the `Incomplete Initialization` flag to notify the BMC to reinitialize 92the buffer. 93 94### Reading and Processing 95 96This daemon will poll the buffer at a set interval (the exact number will be 97configurable as the processing time and performance of different platforms may 98require different polling rate) and once a new payload is detected, the payload 99will be processed by a library that can also be chosen and configured at 100compile-time. 101 102Note that the Uncorrectable Error logs have a reserved region as they contain 103critical information that we don't want to lose, and should be prioritized over 104normal error logs. This reserved region will be used to log a UE log only if an 105overflow of the normal error log queue is imminent and the BMC has acked that 106any preexisting UE log in this region has already been read using Bit0 of the 107`BMC flag`. 108 109An example of a processing library (and something we would like to push in our 110initial version of this daemon) would be an RDE decoder for processing a subset 111of Redfish Device Enablement (RDE) commands, and decoding its attached Binary 112Encoded JSON (BEJ) payloads. 113 114## Alternatives Considered 115 116* IPMI was considered, did not meet our speed requirement of writing 1KB entry 117 in about 50 microseconds. 118 * For reference, initial PCI Mailbox performance measurement showed 1KB entry 119 write took roughly 10 microseconds. 120* LPC / eSPI was also considered but our BMC's SHM buffer was limited to 4KB 121 which was not enough for our use case. 122* `libmctp` and MCTP PCIe VDM were considered. 123 * `libmctp`'s current implementation relies on LPC as the transport binding 124 and IPMI KCS for synchronization. LPC as discussed, does not fit our current 125 need and synchronization does not work. 126 * We may use MCTP PCIe VDM on our future platforms once we have more resources 127 with expertise both from the BMC and the BIOS side (which we currently lack) 128 for our current project timeline. 129 130## Impacts 131 132Reading from the buffer and processing it may hinder performance of the BMC, 133especially if the polling rate is set too high. 134 135### Organizational 136 137This design will require 2 repositories: 138- bios-bmc-smm-error-logger 139 - This repository will implement the daemon described in this document 140 - Proposed maintainer: wltu@google.com , brandonkim@google.com 141- libbej 142 - This repository will follow the PLDM RDE specification as much as possible 143 for RDE BEJ decoding (initially, encoding may come in the future) and will 144 host a library written in C 145 - Proposed maintainer: wltu@google.com , brandonkim@google.com 146 147## Testing 148 149Unit tests will cover each parts of the daemon, mainly: 150 151* Initialization 152* Circular buffer processing 153* Decoding / Processing library 154 155