linux/Documentation/ABI/stable/sysfs-firmware-opal-elog
Stewart Smith 774fea1a38 powerpc/powernv: Read OPAL error log and export it through sysfs
Based on a patch by: Mahesh Salgaonkar <mahesh@linux.vnet.ibm.com>

This patch adds support to read error logs from OPAL and export
them to userspace through a sysfs interface.

We export each log entry as a directory in /sys/firmware/opal/elog/

Currently, OPAL will buffer up to 128 error log records, we don't
need to have any knowledge of this limit on the Linux side as that
is actually largely transparent to us.

Each error log entry has the following files: id, type, acknowledge, raw.
Currently we just export the raw binary error log in the 'raw' attribute.
In a future patch, we may parse more of the error log to make it a bit
easier for userspace (e.g. to be able to display a brief summary in
petitboot without having to have a full parser).

If we have >128 logs from OPAL, we'll only be notified of 128 until
userspace starts acknowledging them. This limitation may be lifted in
the future and with this patch, that should "just work" from the linux side.

A userspace daemon should:
- wait for error log entries using normal mechanisms (we announce creation)
- read error log entry
- save error log entry safely to disk
- acknowledge the error log entry
- rinse, repeat.

On the Linux side, we read the error log when we're notified of it. This
possibly isn't ideal as it would be better to only read them on-demand.
However, this doesn't really work with current OPAL interface, so we
read the error log immediately when notified at the moment.

I've tested this pretty extensively and am rather confident that the
linux side of things works rather well. There is currently an issue with
the service processor side of things for >128 error logs though.

Signed-off-by: Stewart Smith <stewart@linux.vnet.ibm.com>
Signed-off-by: Benjamin Herrenschmidt <benh@kernel.crashing.org>
2014-03-07 16:19:00 +11:00

60 lines
2.2 KiB
Plaintext

What: /sys/firmware/opal/elog
Date: Feb 2014
Contact: Stewart Smith <stewart@linux.vnet.ibm.com>
Description:
This directory exposes error log entries retrieved
through the OPAL firmware interface.
Each error log is identified by a unique ID and will
exist until explicitly acknowledged to firmware.
Each log entry has a directory in /sys/firmware/opal/elog.
Log entries may be purged by the service processor
before retrieved by firmware or retrieved/acknowledged by
Linux if there is no room for more log entries.
In the event that Linux has retrieved the log entries
but not explicitly acknowledged them to firmware and
the service processor needs more room for log entries,
the only remaining copy of a log message may be in
Linux.
Typically, a user space daemon will monitor for new
entries, read them out and acknowledge them.
The service processor may be able to store more log
entries than firmware can, so after you acknowledge
an event from Linux you may instantly get another one
from the queue that was generated some time in the past.
The raw log format is a binary format. We currently
do not parse this at all in kernel, leaving it up to
user space to solve the problem. In future, we may
do more parsing in kernel and add more files to make
it easier for simple user space processes to extract
more information.
For each log entry (directory), there are the following
files:
id: An ASCII representation of the ID of the
error log, in hex - e.g. "0x01".
type: An ASCII representation of the type id and
description of the type of error log.
Currently just "0x00 PEL" - platform error log.
In the future there may be additional types.
raw: A read-only binary file that can be read
to get the raw log entry. These are
<16kb, often just hundreds of bytes and
"average" 2kb.
acknowledge: Writing 'ack' to this file will acknowledge
the error log to firmware (and in turn
the service processor, if applicable).
Shortly after acknowledging it, the log
entry will be removed from sysfs.
Reading this file will list the supported
operations (curently just acknowledge).