.. _opal-dumps:

==========
OPAL Dumps
==========

.. code-block:: c

   #define OPAL_REGISTER_DUMP_REGION		101
   #define OPAL_UNREGISTER_DUMP_REGION		102

   int64_t opal_register_dump_region(uint32_t id, uint64_t addr, uint64_t size);
   int64_t opal_unregister_dump_region(uint32_t id);

In the event of crashes, some service processors and firmware support gathering
a limited amount of memory from a limited number of memory regions to save into
a debug dump that can be useful for firmware and operating system developers
in diagnosing problems. Typically, firmware and kernel log buffers are useful to
save in a dump.

An OS can register a memory region with :ref:`OPAL_REGISTER_DUMP_REGION` and should,
when the region is no longer valid (e.g. when kexec()ing), it should unregister the
region with :ref:`OPAL_UNREGISTER_DUMP_REGION`.

An OS will be made aware of a dump being available through :ref:`OPAL_EVENT_DUMP_AVAIL`
being set from a :ref:`OPAL_POLL_EVENTS` call.

Retreiving dumps from a service processor can also be performed using the
:ref:`OPAL_DUMP_INFO`, :ref:`OPAL_DUMP_INFO2`, :ref:`OPAL_DUMP_READ`,
and :ref:`OPAL_DUMP_RESEND` calls. Dumps are identified by a ``uint32_t``, and
once a dump is acknowledged, this ID can be re-used.

Dumps can also be initiated by OPAL through the :ref:`OPAL_DUMP_INIT` call, which
will request that the service processor performs the requested type of dump.

A call to :ref:`OPAL_DUMP_ACK` indicates to the service processor that we have
retreived/acknowledged the dump and the service processor can free up the storage
used by it.

.. code-block:: c

   #define OPAL_DUMP_INIT				81
   #define OPAL_DUMP_INFO				82
   #define OPAL_DUMP_READ				83
   #define OPAL_DUMP_ACK				84
   #define OPAL_DUMP_RESEND				91
   #define OPAL_DUMP_INFO2				94

   int64_t opal_dump_init(uint8_t dump_type);
   int64_t opal_dump_info(uint32_t *dump_id, uint32_t *dump_size);
   int64_t opal_dump_read(uint32_t dump_id, struct opal_sg_list *list);
   int64_t opal_dump_ack(uint32_t dump_id);
   int64_t opal_dump_resend_notification(void);
   int64_t opal_dump_info2(uint32_t *dump_id, uint32_t *dump_size, uint32_t *dump_type);


.. _OPAL_REGISTER_DUMP_REGION:

OPAL_REGISTER_DUMP_REGION
=========================

.. code-block:: c

   #define OPAL_REGISTER_DUMP_REGION		101

   int64_t opal_register_dump_region(uint32_t id, uint64_t addr, uint64_t size);

This call is used to register regions of memory for a service processor to capture
when the host crashes.

e.g. if an assert is hit in OPAL, a service processor will copy the region of
memory into some kind of crash dump for further analysis.

This is an OPTIONAL feature that may be unsupported, the host OS should use an
:ref:`OPAL_CHECK_TOKEN` call to find out if :ref:`OPAL_REGISTER_DUMP_REGION` is supported.

:ref:`OPAL_REGISTER_DUMP_REGION` accepts 3 parameters:

- region ID
- address
- length

There is a range of region IDs that can be used by the host OS. A host OS should
start from OPAL_DUMP_REGION_HOST_END and work down if it wants to add a not well
defined region to dump. Currently the only well defined region is for the host
OS log buffer (e.g. dmesg on linux). ::

  /*
   * Dump region ID range usable by the OS
   */
   #define OPAL_DUMP_REGION_HOST_START		0x80
   #define OPAL_DUMP_REGION_LOG_BUF		0x80
   #define OPAL_DUMP_REGION_HOST_END		0xFF

:ref:`OPAL_REGISTER_DUMP_REGION` will return :ref:`OPAL_UNSUPPORTED` if the call is present but
the system doesn't support registering regions to be dumped.

In the event of being passed an invalid region ID, :ref:`OPAL_REGISTER_DUMP_REGION` will
return :ref:`OPAL_PARAMETER`.

Systems likely have a limit as to how many regions they can support being dumped. If
this limit is reached, :ref:`OPAL_REGISTER_DUMP_REGION` will return :ref:`OPAL_INTERNAL_ERROR`.

BUGS
----
Some skiboot versions incorrectly returned :ref:`OPAL_SUCCESS` in the case of
:ref:`OPAL_REGISTER_DUMP_REGION` being supported on a platform (so the call was present)
but the call being unsupported for some reason (e.g. on an IBM POWER7 machine).

See also: :ref:`OPAL_UNREGISTER_DUMP_REGION`

.. _OPAL_UNREGISTER_DUMP_REGION:

OPAL_UNREGISTER_DUMP_REGION
===========================

.. code-block:: c

   #define OPAL_UNREGISTER_DUMP_REGION		102

   int64_t opal_unregister_dump_region(uint32_t id);

While :ref:`OPAL_REGISTER_DUMP_REGION` registers a region, :ref:`OPAL_UNREGISTER_DUMP_REGION`
will unregister a region by region ID.

:ref:`OPAL_UNREGISTER_DUMP_REGION` takes one argument: the region ID.

A host OS should check :ref:`OPAL_UNREGISTER_DUMP_REGION` is supported through a call to
:ref:`OPAL_CHECK_TOKEN`.

If :ref:`OPAL_UNREGISTER_DUMP_REGION` is called on a system where the call is present but
unsupported, it will return :ref:`OPAL_UNSUPPORTED`.

BUGS
----
Some skiboot versions incorrectly returned :ref:`OPAL_SUCCESS` in the case of
:ref:`OPAL_UNREGISTER_DUMP_REGION` being supported on a platform (so the call was present)
but the call being unsupported for some reason (e.g. on an IBM POWER7 machine).

.. _OPAL_DUMP_INIT:

OPAL_DUMP_INIT
==============

.. code-block:: c

   #define OPAL_DUMP_INIT				81

   #define DUMP_TYPE_FSP		0x01
   #define DUMP_TYPE_SYS		0x02
   #define DUMP_TYPE_SMA		0x03

   int64_t opal_dump_init(uint8_t dump_type);

Ask the service processor to initiate a dump. Currently, only ``DUMP_TYPE_FSP``
is supported.

Currently only implemented on FSP based systems. Use :ref:`OPAL_CHECK_TOKEN` to
ensure the call is valid.

Returns
-------
:ref:`OPAL_SUCCESS`
     Dump initiated
:ref:`OPAL_PARAMETER`
     Unsupported dump type. Currently only ``DUMP_TYPE_FSP`` is supported and
     only on FSP based platforms.
:ref:`OPAL_INTERNAL_ERROR`
     Failed to ask service processor to initiated dump.

.. _OPAL_DUMP_INFO:

OPAL_DUMP_INFO
==============

.. code-block:: c

   #define OPAL_DUMP_INFO				82

   int64_t opal_dump_info(uint32_t *dump_id, uint32_t *dump_size);

Obsolete, use :ref:`OPAL_DUMP_INFO2` instead.

No upstream Linux code ever used :ref:`OPAL_DUMP_INFO`, although early PowerKVM
trees did. :ref:`OPAL_DUMP_INFO` is implemented as a wrapper around
:ref:`OPAL_DUMP_INFO2`.

.. _OPAL_DUMP_READ:

OPAL_DUMP_READ
==============

.. code-block:: c

   #define OPAL_DUMP_READ				83

   int64_t opal_dump_read(uint32_t dump_id, struct opal_sg_list *list);

Read ``dump_id`` dump from the service processor into memory.


Returns
-------
:ref:`OPAL_INTERNAL_ERROR`
     Invalid Dump ID or internal error.
:ref:`OPAL_PARAMETER`
     Insuffcient space to store dump.
:ref:`OPAL_BUSY_EVENT`
     Fetching dump, call :ref:`OPAL_POLL_EVENTS` to crank the state machine,
     and call :ref:`OPAL_DUMP_READ` again until neither :ref:`OPAL_BUSY_EVENT`
     nor :ref:`OPAL_BUSY` are returned.
:ref:`OPAL_PARTIAL`
     Only part of the dump was read.
:ref:`OPAL_SUCCESS`
     Dump successfully read.

.. _OPAL_DUMP_ACK:

OPAL_DUMP_ACK
=============

.. code-block:: c

   #define OPAL_DUMP_ACK				84

   int64_t opal_dump_ack(uint32_t dump_id);

Acknowledge the dump to the service processor. This means the service processor
can re-claim the storage space used by the dump. Effectively, this is an
``unlink`` style operation.

Returns
-------
:ref:`OPAL_SUCCESS`
     Dump successfully acknowledged.
:ref:`OPAL_INTERNAL_ERROR`
     Failed to acknowledge the dump, e.g. could not communicate with service
     processor.
:ref:`OPAL_PARAMETER`
     Invalid dump ID.


.. _OPAL_DUMP_RESEND:

OPAL_DUMP_RESEND
================

.. code-block:: c

   #define OPAL_DUMP_RESEND				91

   int64_t opal_dump_resend_notification(void);

Resend notification to the OS if there is a dump available. This will
cause OPAL to check if a dump is available and set the
:ref:`OPAL_EVENT_DUMP_AVAIL` bit in the next :ref:`OPAL_POLL_EVENTS` call.

Returns
-------
:ref:`OPAL_SUCCESS`
     Successfully reset :ref:`OPAL_EVENT_DUMP_AVAIL` bit.

In future, this may return other standard OPAL error codes.

.. _OPAL_DUMP_INFO2:

OPAL_DUMP_INFO2
===============

.. code-block:: c

   #define OPAL_DUMP_INFO2				94

   #define DUMP_TYPE_FSP		0x01
   #define DUMP_TYPE_SYS		0x02
   #define DUMP_TYPE_SMA		0x03

   int64_t opal_dump_info2(uint32_t *dump_id, uint32_t *dump_size, uint32_t *dump_type);

Retreives information about a dump, notably it's ``dump_id``, size, and type.
Call this after the :ref:`OPAL_EVENT_DUMP_AVAIL` bit is set from a
:ref:`OPAL_POLL_EVENTS` call. It will retreive the information on the *next*
dump to be retreived and/or ACKed, even though there may be more than one dump
available for retreiving.

This call replaces :ref:`OPAL_DUMP_INFO`.

Returns
-------
:ref:`OPAL_SUCCESS`
     Information retreived.
:ref:`OPAL_INTERNAL_ERROR`
     No dump available or internal error.