PEL: Document saving FFDC in UserData sections
Describe how FFDC (First Failure Data Capture) data can be
placed into UserData sections in PELs via a specific D-Bus
creation method.
Signed-off-by: Matt Spinler <spinler@us.ibm.com>
Change-Id: Iecc0acf0f358aec23dd761b5de5198b58127b159
diff --git a/extensions/openpower-pels/README.md b/extensions/openpower-pels/README.md
index 7a0e543..8c85c17 100644
--- a/extensions/openpower-pels/README.md
+++ b/extensions/openpower-pels/README.md
@@ -4,6 +4,14 @@
possible to point to the raw PEL to use in the OpenBMC event, and then that
will be used instead of creating one.
+## Contents
+* [Passing in data when creating PELs](#passing-pel-related-data-within-an-openbmc-event-log)
+* [Default UserData sections for BMC created PELs](#default-userdata-sections-for-bmc-created-pels)
+* [The PEL Message Registry](#the-pel-message-registry)
+* [Callouts](#callouts)
+* [Action Flags and Event Type Rules](#action-flags-and-event-type-rules)
+* [D-Bus Interfaces](#d-bus-interfaces)
+
## Passing PEL related data within an OpenBMC event log
An error log creator can pass in data that is relevant to a PEL by using
@@ -71,6 +79,77 @@
This is used to pass in an I2C bus and address to create callouts from. See
[here for details](#passing-callouts-in-with-the-additionaldata-property)
+### FFDC Intended For UserData PEL sections
+
+When one needs to add FFDC into the PEL UserData sections, the
+`CreateWithFFDCFiles` D-Bus method on the `xyz.openbmc_project.Logging.Create`
+interface must be used when creating a new event log. This method takes a list
+of files to store in the PEL UserData sections.
+
+That API is the same as the 'Create' one, except it has a new parameter:
+
+```
+std::vector<std::tuple<enum[FFDCFormat],
+ uint8_t,
+ uint8_t,
+ sdbusplus::message::unix_fd>>
+```
+
+Each entry in the vector contains a file descriptor for a file that will
+be stored in a unique UserData section. The tuple's arguments are:
+
+- enum[FFDCFormat]: The data format type, the options are:
+ - 'JSON'
+ - The parser will use nlohmann::json\'s pretty print
+ - 'CBOR'
+ - The parser will use nlohmann::json\'s pretty print
+ - 'Text'
+ - The parser will output ASCII text
+ - 'Custom'
+ - The parser will hexdump the data, unless there is a parser registered
+ for this component ID and subtype.
+- uint8_t: subType
+ - Useful for the 'custom' type. Not used with the other types.
+- uint8_t: version
+ - The version of the data.
+ - Used for the custom type.
+ - Not planning on using for JSON/BSON unless a reason to do so appears.
+- unixfd - The file descriptor for the opened file that contains the
+ contents. The file descriptor can be closed and the file can be deleted if
+ desired after the method call.
+
+An example of saving JSON data to a file and getting its file descriptor is:
+
+```
+nlohmann::json json = ...;
+auto jsonString = json.dump();
+FILE* fp = fopen(filename, "w");
+fwrite(jsonString.data(), 1, jsonString.size(), fp);
+int fd = fileno(fp);
+```
+
+Alternatively, 'open()' can be used to obtain the file descriptor of the file.
+
+Upon receiving this data, the PEL code will create UserData sections for each
+entry in that vector with the following UserData fields:
+
+- Section header component ID:
+ - If the type field from the tuple is "custom", use the component ID from
+ the message registry.
+ - Otherwise, set the component ID to the phosphor-logging component ID so
+ that the parser knows to use the built in parsers (e.g. json) for the
+ type.
+- Section header subtype: The subtype field from the tuple.
+- Section header version: The version field from the tuple.
+- Section data: The data from the file.
+
+If there is a peltool parser registered for the custom type (method is TBD),
+that will be used by peltool to print the data, otherwise it will be hexdumped.
+
+Before adding each of these UserData sections, a check will be done to see if
+the PEL size will remain under the maximum size of 16KB. If not, the UserData
+section will be truncated down enough so that it will fit into the 16KB.
+
## Default UserData sections for BMC created PELs
The extension code that creates PELs will add these UserData sections to every
@@ -206,3 +285,6 @@
Additional rules may be added in the future if necessary.
## D-Bus Interfaces
+
+See the org.open_power.Logging.PEL interface definition for the most up to date
+information.