From dc24fd7fe912fd715f29be38b358b4d404ea3c23 Mon Sep 17 00:00:00 2001 From: Stewart Smith Date: Fri, 31 May 2019 16:12:57 +1000 Subject: doc: Document OPAL_DUMP_* calls Signed-off-by: Stewart Smith --- doc/opal-api/opal-dump-81-82-83-84-94-101-102.rst | 293 ++++++++++++++++++++++ doc/opal-api/opal-dump-region-101-102.rst | 100 -------- doc/opal-api/opal-poll-events.rst | 9 +- 3 files changed, 299 insertions(+), 103 deletions(-) create mode 100644 doc/opal-api/opal-dump-81-82-83-84-94-101-102.rst delete mode 100644 doc/opal-api/opal-dump-region-101-102.rst diff --git a/doc/opal-api/opal-dump-81-82-83-84-94-101-102.rst b/doc/opal-api/opal-dump-81-82-83-84-94-101-102.rst new file mode 100644 index 0000000..04dc8a0 --- /dev/null +++ b/doc/opal-api/opal-dump-81-82-83-84-94-101-102.rst @@ -0,0 +1,293 @@ +.. _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. diff --git a/doc/opal-api/opal-dump-region-101-102.rst b/doc/opal-api/opal-dump-region-101-102.rst deleted file mode 100644 index dca63f6..0000000 --- a/doc/opal-api/opal-dump-region-101-102.rst +++ /dev/null @@ -1,100 +0,0 @@ -================= -OPAL Dump Regions -================= - -.. 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. - -.. _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). diff --git a/doc/opal-api/opal-poll-events.rst b/doc/opal-api/opal-poll-events.rst index 71ca21b..c4bf24d 100644 --- a/doc/opal-api/opal-poll-events.rst +++ b/doc/opal-api/opal-poll-events.rst @@ -75,9 +75,12 @@ OPAL_EVENT_PCI_ERROR = 0x200 ---------------------------- TODO +.. _OPAL_EVENT_DUMP_AVAIL: + OPAL_EVENT_DUMP_AVAIL = 0x400 ----------------------------- -Signifies that there is a pending system dump available. See OPAL_DUMP suite -of calls for details. :: +Signifies that there is a pending system dump available. See :ref:`opal-dumps` suite +of calls for details. - OPAL_EVENT_MSG_PENDING = 0x800, +OPAL_EVENT_MSG_PENDING = 0x800 +------------------------------ -- cgit v1.1