diff options
author | Stewart Smith <stewart@linux.ibm.com> | 2019-05-31 16:12:53 +1000 |
---|---|---|
committer | Stewart Smith <stewart@linux.ibm.com> | 2019-06-03 10:19:59 +1000 |
commit | 77f7c48a1fd6eef9f09b97a0f3e7a90d5844d08c (patch) | |
tree | 4f44b7f3b90e3f3cc36b8b823cfcc51be6bd4b8c | |
parent | ed702b6524b703efe2d8f2e37f8baa53fe61e0d2 (diff) | |
download | skiboot-77f7c48a1fd6eef9f09b97a0f3e7a90d5844d08c.zip skiboot-77f7c48a1fd6eef9f09b97a0f3e7a90d5844d08c.tar.gz skiboot-77f7c48a1fd6eef9f09b97a0f3e7a90d5844d08c.tar.bz2 |
doc: Flesh out OPAL_(UN)REGISTER_DUMP_REGION docs
Signed-off-by: Stewart Smith <stewart@linux.ibm.com>
-rw-r--r-- | doc/opal-api/opal-dump-region-101-102.rst | 100 | ||||
-rw-r--r-- | doc/opal-api/opal-register-dump-region-101.rst | 45 | ||||
-rw-r--r-- | doc/opal-api/opal-unregister-dump-region-102.rst | 19 |
3 files changed, 100 insertions, 64 deletions
diff --git a/doc/opal-api/opal-dump-region-101-102.rst b/doc/opal-api/opal-dump-region-101-102.rst new file mode 100644 index 0000000..dca63f6 --- /dev/null +++ b/doc/opal-api/opal-dump-region-101-102.rst @@ -0,0 +1,100 @@ +================= +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-register-dump-region-101.rst b/doc/opal-api/opal-register-dump-region-101.rst deleted file mode 100644 index 1530082..0000000 --- a/doc/opal-api/opal-register-dump-region-101.rst +++ /dev/null @@ -1,45 +0,0 @@ -OPAL_REGISTER_DUMP_REGION -========================= - -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 - -This is an OPTIONAL feature that may be unsupported, the host OS should use an -OPAL_CHECK_TOKEN call to find out if OPAL_REGISTER_DUMP_REGION is supported. - -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 - -OPAL_REGISTER_DUMP_REGION will return 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, OPAL_REGISTER_DUMP_REGION will -return OPAL_PARAMETER. - -Systems likely have a limit as to how many regions they can support being dumped. If -this limit is reached, OPAL_REGISTER_DUMP_REGION will return OPAL_INTERNAL_ERROR. - -BUGS ----- -Some skiboot versions incorrectly returned OPAL_SUCCESS in the case of -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: OPAL_UNREGISTER_DUMP_REGION diff --git a/doc/opal-api/opal-unregister-dump-region-102.rst b/doc/opal-api/opal-unregister-dump-region-102.rst deleted file mode 100644 index d382c82..0000000 --- a/doc/opal-api/opal-unregister-dump-region-102.rst +++ /dev/null @@ -1,19 +0,0 @@ -OPAL_UNREGISTER_DUMP_REGION -=========================== - -While OPAL_REGISTER_DUMP_REGION registers a region, OPAL_UNREGISTER_DUMP_REGION -will unregister a region by region ID. - -OPAL_UNREGISTER_DUMP_REGION takes one argument: the region ID. - -A host OS should check OPAL_UNREGISTER_DUMP_REGION is supported through a call to -OPAL_CHECK_TOKEN. - -If OPAL_UNREGISTER_DUMP_REGION is called on a system where the call is present but -unsupported, it will return OPAL_UNSUPPORTED. - -BUGS ----- -Some skiboot versions incorrectly returned OPAL_SUCCESS in the case of -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). |