You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
621 lines
26 KiB
XML
621 lines
26 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!--
|
|
Copyright (c) 2016, 2020 OpenPOWER Foundation
|
|
|
|
Licensed under the Apache License, Version 2.0 (the "License");
|
|
you may not use this file except in compliance with the License.
|
|
You may obtain a copy of the License at
|
|
|
|
http://www.apache.org/licenses/LICENSE-2.0
|
|
|
|
Unless required by applicable law or agreed to in writing, software
|
|
distributed under the License is distributed on an "AS IS" BASIS,
|
|
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
See the License for the specific language governing permissions and
|
|
limitations under the License.
|
|
|
|
-->
|
|
<section xmlns="http://docbook.org/ns/docbook"
|
|
xmlns:xi="http://www.w3.org/2001/XInclude"
|
|
xmlns:xl="http://www.w3.org/1999/xlink"
|
|
version="5.0"
|
|
xml:lang="en"
|
|
xml:id="dbdoclet.50569332_67111">
|
|
<title><emphasis>ibm,configure-kernel-dump</emphasis> RTAS Call</title>
|
|
|
|
<para>This RTAS call is used to register and unregister with the platform
|
|
a data structure describing kernel dump information. This dump
|
|
information is preserved as needed by the platform in support of a
|
|
platform assisted kernel dump option.</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
|
|
xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
|
|
option:</emphasis> The platform must implement the
|
|
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call using the
|
|
argument call buffer defined by
|
|
<xref linkend="dbdoclet.50569332_24141" />.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_24141">
|
|
<title><emphasis>ibm,configure-kernel-dump</emphasis> Argument Call Buffer</title>
|
|
<tgroup cols="3">
|
|
<colspec colname="c1" colwidth="1*" align="center" />
|
|
<colspec colname="c2" colwidth="2*" align="center" />
|
|
<colspec colname="c3" colwidth="4*" />
|
|
<tbody valign="middle" >
|
|
<row>
|
|
<entry>
|
|
<para>Parameter Type</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Name</para>
|
|
</entry>
|
|
<entry align="center">
|
|
<para>Values</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry morerows="5" valign="middle">
|
|
<para>In</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Token</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Token for
|
|
<emphasis>ibm,configure-kernel-dump</emphasis></para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Number Inputs</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>3</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Number Outputs</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>1</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Command</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>1: Register for future kernel dump</para>
|
|
<para>2: Unregister for future kernel dump</para>
|
|
<para>3: Complete/Invalidate current kernel dump</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Work_buffer_address</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>When command is 1: Register for future kernel dump,
|
|
points to a structure as defined in
|
|
<xref linkend="dbdoclet.50569332_76933" />.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Work_buffer_length</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>Length of Kernel Dump Memory Structure when defined
|
|
above</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Out</para>
|
|
</entry>
|
|
<entry>
|
|
<para>
|
|
<emphasis>Status</emphasis>
|
|
</para>
|
|
</entry>
|
|
<entry>
|
|
<para>0: Success</para>
|
|
<para>-1: Hardware Error</para>
|
|
<para>-2: Busy</para>
|
|
<para>-3: Parameter Error</para>
|
|
<para>-9: Dump Already Registered</para>
|
|
<para>-10: Dump Active</para>
|
|
<para>990x:Extended Delay</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
|
|
xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
|
|
option:</emphasis> The work-buffer address and work-buffer-length for the
|
|
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call must point to an
|
|
RMR-memory buffer that contains the structures described in
|
|
<xref linkend="dbdoclet.50569332_76933" />, whenever the command is 1,
|
|
register for future kernel dump; otherwise the call may return -3,
|
|
“Parameter Error.”</para>
|
|
<para>The Dump Memory Structure specified in
|
|
<xref linkend="dbdoclet.50569332_76933" /> is passed by the operating
|
|
system during a
|
|
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call. It is also
|
|
reported by the platform using the
|
|
<emphasis>ibm,kernel-dump</emphasis> RTAS property after a dump has been
|
|
initiated.</para>
|
|
|
|
<table frame="all" pgwide="1" xml:id="dbdoclet.50569332_76933">
|
|
<title>Kernel Assisted Dump Memory Structure</title>
|
|
<tgroup cols="5">
|
|
<colspec colname="c1" colwidth="1*" align="center" />
|
|
<colspec colname="c2" colwidth="1*" align="center" />
|
|
<colspec colname="c3" colwidth="1*" align="center" />
|
|
<colspec colname="c4" colwidth="2*" />
|
|
<colspec colname="c5" colwidth="2*" />
|
|
<thead>
|
|
<row>
|
|
<entry nameend="c5" namest="c1">
|
|
<para>
|
|
<emphasis>Header</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
</thead>
|
|
<tbody valign="middle" >
|
|
<row>
|
|
<entry>
|
|
<para>Offset</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>Number of Bytes</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4" align="center">
|
|
<para>Value</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x0</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>4</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Dump Format Version = 0x00000001</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x4</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>2</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Number of Kernel Dump Sections</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x6</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>2</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Dump Status Flags</para>
|
|
<para>A bit mask with value</para>
|
|
<para>0x8000 = Dump performed (Set to 0 by caller of the
|
|
ibm,configure-kernel-dump call)</para>
|
|
<para>0x4000 = Dump was triggered by the previous system boot
|
|
(set by platform)</para>
|
|
<para>0x2000 = Dump error occurred (set by platform)</para>
|
|
<para>All other bits reserved</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x8</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>4</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Offset to first Kernel Dump Section, offset from the
|
|
beginning of the Structure</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0xc</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>4</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Number of bytes in a block of the dump-disk, if data to
|
|
be written to a dump-disk, If not, should be set to 0
|
|
(indicating the no disk dump option.)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x10</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>8</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Starting block# offset on dump-disk (set to 0 for the no
|
|
disk dump option)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x18</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>8</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Number of blocks on dump-disk usable for dump (set to 0
|
|
for the no disk dump option)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x20</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>4</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Offset from start of structure to a Null-terminated
|
|
Dump-disk path string (set to 0 for the no disk dump
|
|
option)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>0x24</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>4</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Maximum time allowed (milliseconds) after
|
|
Non-Maskable-Interrupt for the OS to call
|
|
<emphasis>ibm,configure-kernel-dump</emphasis>
|
|
<emphasis>Function</emphasis> 2 (unregister) to prevent an
|
|
automatic dump-reboot (set to 0 to disable the automatic
|
|
dump-reboot function)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry nameend="c5" namest="c1">
|
|
<para>
|
|
<emphasis>Dump-disk Path String</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Offset specified above</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>Varies</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Null-terminated Dump-disk path string specifying the
|
|
dump-disk. If no disk dump option is indicated, this section is
|
|
not included.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry nameend="c5" namest="c1">
|
|
<para>
|
|
<emphasis>First Kernel Dump Section</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Offset specified above</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>4</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Dump Request Flags:</para>
|
|
<para>A bit-mask</para>
|
|
<para>Bit 0x00000001 When set, firmware to copy source data to
|
|
partition memory. This option must be selected if no disk dump
|
|
option is indicated.</para>
|
|
<para>All other bit values reserved</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Section Start+4</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>2</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Source Data type, describes section of dump memory being
|
|
described</para>
|
|
<para>0x0001 = CPU State Data</para>
|
|
<para>0x0002 = Hardware Page Table for Real Mode Region</para>
|
|
<para>0x0011 = Real Mode Region</para>
|
|
<para>0x0012 = Dump OS identified string (identifies that the
|
|
dump is for a particular OS type and version)</para>
|
|
<para>0x0100 - 0xFFFF OS defined source types</para>
|
|
<para>All Other values reserved</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Section Start+6</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>2</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Dump Error Flags (set by platform)</para>
|
|
<para>Bit mask</para>
|
|
<para>0x8000 = Invalid section data type</para>
|
|
<para>0x4000 = Invalid source address</para>
|
|
<para>0x2000 = Requested section length exceeds source</para>
|
|
<para>0x1000 = Invalid partition destination address</para>
|
|
<para>0x0800 = Partition memory destination too small</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Section Start+8</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>8</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Source address (logical address if section came from
|
|
partition memory, or byte offset if section is platform
|
|
memory)</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Section Start+16</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>8</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Requested data length, represents number of bytes to
|
|
dump</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Section Start+24</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>8</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Actual data length, number of bytes dumped</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Section Start+32</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>8</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>Destination address, logical address used for sections
|
|
not written to disk by the platform, always required for a Real
|
|
mode region section and for all sections when the no disk dump
|
|
option is used.</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry nameend="c5" namest="c1">
|
|
<para>
|
|
<emphasis>Subsequent Sections</emphasis>
|
|
</para>
|
|
</entry>
|
|
</row>
|
|
<row>
|
|
<entry>
|
|
<para>Previous Section Start+40</para>
|
|
</entry>
|
|
<entry nameend="c3" namest="c2">
|
|
<para>Start of Next Section</para>
|
|
</entry>
|
|
<entry nameend="c5" namest="c4">
|
|
<para>A total of up to nine additional 40 bytes sections with
|
|
values as described in the First Section may be specified so
|
|
long as the entire structure does not exceed 512 bytes for
|
|
version 1.</para>
|
|
</entry>
|
|
</row>
|
|
</tbody>
|
|
</tgroup>
|
|
</table>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
|
|
xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis>ibm,os-term</emphasis> RTAS call, or on a system reset without
|
|
an
|
|
<emphasis>ibm,nmi-interlock</emphasis> RTAS call, if the platform has a
|
|
dump structure registered through the
|
|
<emphasis>ibm,configure-kernel-dump</emphasis> call, the platform must
|
|
process each registered kernel dump section as required and, when
|
|
available, present the dump structure information to the operating system
|
|
through the
|
|
<emphasis role="bold"><literal>“ibm,kernel-dump”</literal></emphasis> property, updated with
|
|
status for each dump section, until the dump has been invalidated through
|
|
the
|
|
<emphasis>ibm,configure-kernel-dump</emphasis> RTAS call.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
|
|
xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
|
|
<listitem>
|
|
<para>If <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call is made to
|
|
register or unregister for a dump while a dump is currently active, the
|
|
platform must return a
|
|
<emphasis>Status</emphasis> of -9, “Dump Active” indicating
|
|
that a dump has been copied by the platform and a call must be made to
|
|
complete/invalidate the active dump before another call to register or
|
|
unregister a dump can be completed successfully.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
|
|
xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
|
|
<listitem>
|
|
<para>If <emphasis>ibm,configure-kernel-dump</emphasis> RTAS call is made to
|
|
register a dump after a dump has already been registered by a call, the
|
|
platform must return a
|
|
<emphasis>Status</emphasis> of -8, “Dump Already Registered”
|
|
unless an intervening call was made to invalidate the previously
|
|
registered dump.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
|
|
xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
|
|
Option:</emphasis> Partition memory not specifically mentioned in the call
|
|
structure must be preserved by the platform at the same location as
|
|
existed prior to the os termination or platform reboot.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
|
|
xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
|
|
Option:</emphasis> The platform must present the RTAS property,
|
|
<emphasis role="bold"><literal>“ibm,configure-kernel-dump-sizes”</literal></emphasis> in the
|
|
OF device tree, which describes how much space is required to store dump
|
|
data for the firmware provided dump sections, where the firmware defined
|
|
dump sections are:</para>
|
|
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>0x0001 = CPU State Data</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>0x0002 = Hardware Page Table for Real Mode Region</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
|
|
xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
|
|
Option:</emphasis> The platform must present the RTAS property,
|
|
<emphasis role="bold"><literal>“ibm-configure-kernel-dump-version”</literal></emphasis> in
|
|
the OF device tree.</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_67111"
|
|
xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
|
|
<listitem>
|
|
<para><emphasis role="bold">For the Configure Platform Assisted Kernel Dump
|
|
Option:</emphasis> After a dump registration is disabled (for example, by
|
|
a partition migration operation), calls to
|
|
<emphasis>ibm,os-term</emphasis> must return to the OS as though a dump
|
|
was not registered.</para>
|
|
<para>
|
|
<emphasis role="bold">Programming Note:</emphasis> The intended flow of interactions
|
|
that utilize this call is as follows:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The OS registers sections of memory for dump preservation during
|
|
OS initialization</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The OS terminates abnormally</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The Platform moves registered sections of memory as instructed
|
|
during dump registration.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The Partition reboots and provides the prior registration data
|
|
in the device tree.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The OS writes the preserved memory regions to disk before using
|
|
those memory regions for regular use</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The OS completes/invalidates current dump status.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>The OS must use H_CLEAR_HPT to clear the page table if running
|
|
in XIVE Exploitation Mode, H_REMOVE is not a sufficient mechanism
|
|
to clear the HPT. Failure to use H_CLEAR_HPT may result in H_READ
|
|
returning invalid entries as valid.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</section>
|