Linux-Architecture-Reference/LoPAR/sec_rtas_manage_storage_preservation.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_28221">
    <title>ibm,manage-storage-preservation</title>

    <para>Platforms may optionally preserve selected regions of storage
    (LMBs) across client program boot cycles.
    <xref linkend="dbdoclet.50569327_70628" /> for more information.</para>

    <variablelist>
     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
        xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
            must implement the
            <emphasis>ibm,manage-storage-preservation</emphasis> RTAS argument call
            buffer as defined by
            <xref linkend="dbdoclet.50569332_95221" />.</para>

            <table frame="all" pgwide="1" xml:id="dbdoclet.50569332_95221">
              <title><emphasis>ibm,manage-storage-preservation</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*" />
                <thead>
                  <row>
                    <entry>
                      <para>
                        <emphasis role="bold">Parameter Type</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">Name</emphasis>
                      </para>
                    </entry>
                    <entry align="center">
                      <para>
                        <emphasis role="bold">Values</emphasis>
                      </para>
                    </entry>
                  </row>
                </thead>
                <tbody valign="middle" >
                  <row>
                    <entry morerows="5" valign="middle">
                      <para>In</para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis>Token</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>Token for
                      <emphasis>ibm,manage-storage-preservation</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>2</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>
                        <emphasis>Subfunction</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>0 = unused (return -3)</para>
                      <para>1 = Register specified LMB for preservation</para>
                      <para>2 = Query preservation state of specified LMB</para>
                      <para>3 = Deregister for preservation Specific LMB</para>
                      <para>4 = Deregister for preservation all caller&#8217;s
                      LMBs.</para>
                      <para>All other values reserved (return -3)</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>
                        <emphasis>Reg High</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>The high order 32 bits of the LMB's
                      <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property (Subfunctions
                      1-3)</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>
                        <emphasis>Reg Low</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>The low order 32 bits of the LMB's
                      <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property (Subfunctions
                      1-3)</para>
                    </entry>
                  </row>
                  <row>
                    <entry morerows="1" valign="middle">
                      <para>Out</para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis>Status</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>-1: Hardware error</para>
                      <para>-2: Busy</para>
                      <para>-3: Parameter error (Subfunction or Reg invalid; or Reg
                      for a non-preservable LMB)</para>
                      <para>0: Success</para>
                      <para>990x: Extended delay where x is a number 0-5</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>
                        <emphasis>Preservation state</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>If
                      <emphasis>Status</emphasis>= Success, the current preservation
                      state of specified LMB (Subfunctions 1-3)</para>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
        xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
            must include the
            <emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property in the
            <emphasis>/memory</emphasis> nodes of its OF device tree, containing a
            value which reflects the platform's ability to preserve the specific
            LMB.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
        xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The value of the
            <emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property for the first
            LMB must be 0 (cannot be preserved).</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
        xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
            must not preserve the first LMB, thus must indicate a value of 0 for the
            <emphasis role="bold"><literal>&#8220;ibm,preservable&#8221;</literal></emphasis> property for the first
            LMB.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
        xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform
            must include the
            <emphasis role="bold"><literal>&#8220;ibm,preserved&#8221;</literal></emphasis> property in the
            <emphasis>/memory</emphasis> nodes of its OF device tree, valued to
            reflect the platform's preservation state of the specific LMB.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
        xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform, on
            a reboot, must include in the OF
            <emphasis role="bold"><literal>/rtas</literal></emphasis> node the
            <emphasis role="bold"><literal>&#8220;ibm,preserved-storage&#8221;</literal></emphasis> property if the
            previous client program registered one or more of its LMBs for
            preservation.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
        xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the Storage Preservation option:</emphasis> If the client
            program registered an LMB for preservation, the platform must preserve
            the LMB's storage state across client program reboots.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569332_28221"
        xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the Storage Preservation option:</emphasis> The platform, on
            a reboot, must include in the OF
            <emphasis role="bold"><literal>/rtas</literal></emphasis> node the
            <emphasis role="bold"><literal>&#8220;ibm,request-partition-shutdown&#8221;</literal></emphasis> property
            which reflects the value of the partition shutdown configuration
            variable, and if this property is not present, a value of 0 must be
            assumed by the OS.</para>
          </listitem>
     	</varlistentry>
    </variablelist>

  </section>