From patchwork Fri May 31 06:12:53 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Stewart Smith X-Patchwork-Id: 1108177 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Received: from lists.ozlabs.org (lists.ozlabs.org [203.11.71.2]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 45FZbd6W88z9s00 for ; Fri, 31 May 2019 16:41:17 +1000 (AEST) Authentication-Results: ozlabs.org; dmarc=none (p=none dis=none) header.from=linux.ibm.com Received: from lists.ozlabs.org (lists.ozlabs.org [IPv6:2401:3900:2:1::3]) by lists.ozlabs.org (Postfix) with ESMTP id 45FZbd5NhfzDrCG for ; Fri, 31 May 2019 16:41:17 +1000 (AEST) X-Original-To: skiboot@lists.ozlabs.org Delivered-To: skiboot@lists.ozlabs.org Authentication-Results: lists.ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=linux.ibm.com (client-ip=148.163.156.1; helo=mx0a-001b2d01.pphosted.com; envelope-from=stewart@linux.ibm.com; receiver=) Authentication-Results: lists.ozlabs.org; dmarc=none (p=none dis=none) header.from=linux.ibm.com Received: from mx0a-001b2d01.pphosted.com (mx0a-001b2d01.pphosted.com [148.163.156.1]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by lists.ozlabs.org (Postfix) with ESMTPS id 45FZ1p400gzDqYb for ; Fri, 31 May 2019 16:15:26 +1000 (AEST) Received: from pps.filterd (m0098410.ppops.net [127.0.0.1]) by mx0a-001b2d01.pphosted.com (8.16.0.27/8.16.0.27) with SMTP id x4V648fn140958 for ; Fri, 31 May 2019 02:15:24 -0400 Received: from e16.ny.us.ibm.com (e16.ny.us.ibm.com [129.33.205.206]) by mx0a-001b2d01.pphosted.com with ESMTP id 2stx4vsbdx-1 (version=TLSv1.2 cipher=AES256-GCM-SHA384 bits=256 verify=NOT) for ; Fri, 31 May 2019 02:15:23 -0400 Received: from localhost by e16.ny.us.ibm.com with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted for from ; Fri, 31 May 2019 07:15:22 +0100 Received: from b01cxnp22036.gho.pok.ibm.com (9.57.198.26) by e16.ny.us.ibm.com (146.89.104.203) with IBM ESMTP SMTP Gateway: Authorized Use Only! Violators will be prosecuted; (version=TLSv1/SSLv3 cipher=AES256-GCM-SHA384 bits=256/256) Fri, 31 May 2019 07:15:20 +0100 Received: from b01ledav001.gho.pok.ibm.com (b01ledav001.gho.pok.ibm.com [9.57.199.106]) by b01cxnp22036.gho.pok.ibm.com (8.14.9/8.14.9/NCO v10.0) with ESMTP id x4V6E4di7471542 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-GCM-SHA384 bits=256 verify=OK) for ; Fri, 31 May 2019 06:14:04 GMT Received: from b01ledav001.gho.pok.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id 2972328059 for ; Fri, 31 May 2019 06:14:04 +0000 (GMT) Received: from b01ledav001.gho.pok.ibm.com (unknown [127.0.0.1]) by IMSVA (Postfix) with ESMTP id DBC6928058 for ; Fri, 31 May 2019 06:14:03 +0000 (GMT) Received: from birb.localdomain (unknown [9.185.142.91]) by b01ledav001.gho.pok.ibm.com (Postfix) with ESMTP for ; Fri, 31 May 2019 06:14:03 +0000 (GMT) Received: by birb.localdomain (Postfix, from userid 1000) id 56996503F99; Fri, 31 May 2019 16:13:57 +1000 (AEST) From: Stewart Smith To: skiboot@lists.ozlabs.org Date: Fri, 31 May 2019 16:12:53 +1000 X-Mailer: git-send-email 2.21.0 In-Reply-To: <20190531061351.22973-1-stewart@linux.ibm.com> References: <20190531061351.22973-1-stewart@linux.ibm.com> MIME-Version: 1.0 X-TM-AS-GCONF: 00 x-cbid: 19053106-0072-0000-0000-00000435AFE7 X-IBM-SpamModules-Scores: X-IBM-SpamModules-Versions: BY=3.00011189; HX=3.00000242; KW=3.00000007; PH=3.00000004; SC=3.00000286; SDB=6.01211088; UDB=6.00636340; IPR=6.00992125; MB=3.00027126; MTD=3.00000008; XFM=3.00000015; UTC=2019-05-31 06:15:21 X-IBM-AV-DETECTION: SAVI=unused REMOTE=unused XFE=unused x-cbparentid: 19053106-0073-0000-0000-00004C6D3DA1 Message-Id: <20190531061351.22973-53-stewart@linux.ibm.com> X-Proofpoint-Virus-Version: vendor=fsecure engine=2.50.10434:, , definitions=2019-05-31_03:, , signatures=0 X-Proofpoint-Spam-Details: rule=outbound_notspam policy=outbound score=0 priorityscore=1501 malwarescore=0 suspectscore=1 phishscore=0 bulkscore=0 spamscore=0 clxscore=1015 lowpriorityscore=0 mlxscore=0 impostorscore=0 mlxlogscore=771 adultscore=0 classifier=spam adjust=0 reason=mlx scancount=1 engine=8.0.1-1810050000 definitions=main-1905310040 Subject: [Skiboot] [PATCH 052/110] doc: Flesh out OPAL_(UN)REGISTER_DUMP_REGION docs X-BeenThere: skiboot@lists.ozlabs.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: Mailing list for skiboot development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: skiboot-bounces+incoming=patchwork.ozlabs.org@lists.ozlabs.org Sender: "Skiboot" Signed-off-by: Stewart Smith --- doc/opal-api/opal-dump-region-101-102.rst | 100 ++++++++++++++++++ .../opal-register-dump-region-101.rst | 45 -------- .../opal-unregister-dump-region-102.rst | 19 ---- 3 files changed, 100 insertions(+), 64 deletions(-) create mode 100644 doc/opal-api/opal-dump-region-101-102.rst delete mode 100644 doc/opal-api/opal-register-dump-region-101.rst delete mode 100644 doc/opal-api/opal-unregister-dump-region-102.rst 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 000000000000..dca63f6e5c9a --- /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 15300820d1e3..000000000000 --- 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 d382c82631b6..000000000000 --- 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).