Linux-Architecture-Reference/Virtualization/ch_lpar_option.xml

<chapter xmlns="http://docbook.org/ns/docbook"
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" xml:id="dbdoclet.50569344_14591">
  <title>Logical Partitioning Option</title>

  <section>
    <title>Overview</title>
    <para>The Logical PARtitioning option (LPAR) simultaneously runs one or
    more copies of a single OS or multiple heterogeneous LoPAR compliant OSs
    on a single LoPAR platform. A partition, within which an OS image runs, is
    assigned a non-overlapping sub-set of the platform&#8217;s resources. These
    platform-allocatable resources include one or more architecturally distinct
    processors with their interrupt management area, regions of system memory,
    and I/O adapter bus slots. Partition firmware loaded into each partition
    generates an OF device tree to represent the resources of the partition to
    the OS image. Allocatable resources are directly controlled by an OS. This
    architecture restricts the sharing of allocatable resources between
    partitions; to do so requires the use of optional facilities presented in
    <xref linkend="dbdoclet.50569348_67470" />. Platform resources, other than
    allocatable resources mentioned above, that are represented by OF nodes in
    the device tree of more than one partition (for example, memory controllers
    and processor host bridges) are marked <emphasis>&#8216;used-by-rtas&#8217;</emphasis>.</para>
    <para>Since one of the main purposes of partitioning is isolation of the
    OSs, the ability to manage real system resources that are common to all
    partitions is modified for the LPAR option. This means that partition use
    of RTAS functions which ostensibly use real system resources such as power
    and time-of-day clocks are buffered from actual manipulation of those
    resources. The RTAS is modified for LPAR, and has hypervisor support, to
    virtualize real resources for the partitions. Operational management of the
    platform moves to a Hardware Management Console (HMC) which is an
    application, either local or remote, that manages platform resources with
    messages to the hypervisor rather than being under direct control of a
    partition&#8217;s OS.</para>
    <para>Platforms supporting LPAR, contain Power PC processors that support
    the hypervisor addressing mode, in which the physical address is equal to
    the effective address and all processor resources are available. The
    &#8220;Real Mode&#8221; addressing mode, in these processors, is redefined
    to translate and limit the physical addresses that the processor can access
    and to restrict access to certain address translation controlling processor
    resources. The virtual addressing mode is unchanged. See the
    <xref linkend="dbdoclet.50569387_99718" /> (level 2.0 and beyond) for the
    architecture extensions required for the processor.</para>
    <para>The I/O subsystems of these platforms contain I/O bridges that
    restrict the bus addresses that I/O adapters can access. These restricted
    bus addresses are subsequently translated through the Translation Control
    Entry (TCE) mechanism to restrict Direct Memory Accesses (DMAs) by I/O
    devices. This restriction is to system memory allocated to a partition and
    managed by the OS image owning the device. The interrupt subsystem of these
    platforms is enhanced with multiple (one per partition) global interrupt
    queues to direct interrupts to any processor assigned to the I/O
    adapter&#8217;s owning OS image.</para>
    <para>Logical Partitioning platforms employ a unique firmware component
    called the hypervisor (that runs in hypervisor mode) to manage the address
    mapping and common platform hardware facilities, thereby ensuring isolation
    between partitions. The OS uses new hypervisor interfaces to manage the
    partition&#8217;s page frame and TCE tables. The platform firmware utilizes
    implementation dependent interfaces to platform hardware common to all
    partitions. Thus, a system with LPAR has different OS support than a system
    without LPAR.</para>
    <para>In addition to generating per partition device trees, the OF
    component of a logically partitioned platform manages the initial booting
    and any subsequent booting of the specific OS image associated with each
    partition.</para>
    <para>The NVRAM of a platform contains configuration variables, policy
    options, and working storage that is protected from accesses that might
    adversely affect one or more partitions and their OS images. The hypervisor
    firmware component restricts an OS image&#8217;s access to NVRAM to a
    region assigned to its partition. This may restrict the number of
    partitions.</para>
    <para>Most system management on systems without LPAR is performed by OS
    based applications that are given access to modify the platform&#8217;s
    configuration variables, policy options and firmware flash. For various
    Reliability Availability and Serviceability (RAS) reasons, LoPAR Logical
    Partitioning platforms do not restrict platform operational management
    functions to applications running on a preferred partition or OS image.
    Access to these Operational Management facilities is provided via a Support
    Processor communication port that is connected to an HMC and/or through a
    communications port that is connected through a PCI adapter in a partition.
    The HMC is a set of applications running in a separate stand-alone platform
    or in one of the platform&#8217;s partitions. These HMC applications are
    required to establish the platform&#8217;s LPAR configuration, however, the
    configuration is stored in the platform and, therefore, the HMC is not
    required to boot or operate the platform in a pre-configured non-error
    condition.</para>

    <section>
      <title>Real Mode Accesses</title>
      <para>When the OS controlling an LPAR runs with address translation
      turned off (MSR<subscript>DR</subscript> or MSR<subscript>IR</subscript>
      bit(s) =0) (real mode) the LPAR hardware
      translates the memory addresses to an LPAR unique area known as the Real
      Mode Area (RMA). When control is initially passed to the OS from the
      platform, the RMA starts at the LPAR's logical address 0 and is the first
      logical memory block reported in the LPAR&#8217;s device tree. In
      general, the RMA is a subset of the LPAR's logical address space.
      Attempting a non relocated access beyond the bounds of the RMA results in
      an storage interrupt (ISI/DSI depending upon instruction or data
      reference). The RMA hardware translation scheme is platform dependent.
      The options are given below.</para>

      <section>
        <title>Offset and Limit Registers</title>
        <para>The Offset RMA architecture checks the LPAR effective address
        against the contents of an RMOL register allowing the access, after
        adding an LPAR specific offset to form the real address, if the effective
        address is less, else signaling a protection exception.</para>
      </section>

      <section>
        <title>Reserved Virtual Addresses</title>
        <para>The platform may map the RMA through the hashed paged table via a
        reserved range of virtual addresses. This mapping from the effective
        address is done by setting the high order virtual address bits
        corresponding to the VSID to the 0b00 || 0x001FFFFFF 1 TB VSID value.
        This virtual address is then translated as other virtual addresses. If
        the effective address is outside the bounds of the RMA, the storage
        interrupt signals a PTEG miss. The platform firmware prepopulates the
        LPAR's page frame table with &#8220;bolted&#8221; entries representing
        the real storage blocks that make up the RMA. Note, this method allows
        for the RMA to be discontiguous in real address space. The Virtualized
        Real Mode Area (VRMA) option gives the OS the ability to dynamically
        relocate, expand, and shrink the RMA. See
        <xref linkend="dbdoclet.50569344_39908" /> for more details.</para>
      </section>
    </section>

    <section xml:id="sec_gen_lpar">
      <title>General LPAR Reservations and Conventions</title>
      <para>This section documents general LPAR reserved facilities and
      conventions. Other sections document reserved facilities and conventions
      specific to the function they describe.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_gen_lpar"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> To avoid conflict with the
              platform&#8217;s reserved addresses, the OS must not use the 1 TB (SLB
              and PTE B field equal to one) 0b00 || 0x001FFFFFF VSID for purposes other
              than virtualizing the RMA.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_gen_lpar"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> In order to avoid a storage
              exception, the OS must not remove PTEs marked with the
              &#8220;bolted&#8221; indicator (PTE bit 59 = 1) unless the virtual
              address space can be referenced by another PTE or the OS does not intend
              to access the virtual address space.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_gen_lpar"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> To avoid conflict with the
              platform&#8217;s hypervisor, the OS must be prepared to share use of
              SPRG2 as the interrupt scratch register whenever an hcall() is made, or a
              machine check or reset interrupt is taken.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_gen_lpar"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> If the platform virtualizes the
              RMA, prior to transferring control to the OS, the platform must select a
              page size for the RMA such that the platform uses only one page table
              entry per page table entry group to virtualize the RMA.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_gen_lpar"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> If the platform virtualizes the
              RMA, prior to transferring control to the OS, the platform must use only
              the last page table entry of a page table entry group to virtualize the
              RMA.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

    </section>
  </section>

  <section xml:id="sec_proc_req">
    <title>Processor Requirements</title>

    <variablelist>
     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_proc_req"
        xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The platform processors must
            support the Logical Partitioning (LPAR) facilities as defined in
            <xref linkend="dbdoclet.50569387_99718" /> (Version 2.0 or later).</para>
          </listitem>
     	</varlistentry>
    </variablelist>

  </section>

  <section xml:id="sec_io_req">
    <title>I/O Sub-System Requirements</title>
    <para>The platform divides the I/O subsystem up into Partitionable
    Endpoints (PEs). See
    <xref linkend="LoPAR.Platform" /> for more information on PEs. Each PE has
    its own (separate) error, addressing, and interrupt domains which allows
    the assignment of separate PEs to different LPAR partitions.</para>
    <para>The following are the requirements for I/O subsystems when the
    platform implements LPAR.</para>

    <variablelist>
     	<varlistentry xml:id="dbdoclet.50569344_47137">
        <term><emphasis role="bold">R1-<xref linkend="sec_io_req"
        xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must provide methods
            and mechanisms to isolate IOA and I/O bus errors from one PE from affecting
            another PE, from affecting a partition to which the PE is not given access
            authority by the platform, and from affecting system resources such as the
            service processor which are shared between partitions, and must do so with
            the EEH option programming model.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry xml:id="dbdoclet.50569344_28369">
        <term><emphasis role="bold">R1-<xref linkend="sec_io_req"
        xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis>
            The platform must enable the EEH option for all PEs by default.</para>
            <para><emphasis role="bold">Software and Firmware Implementation Notes:</emphasis> For the
            platform (versus the OS or device driver) to enable EEH, there must be some
            assurance that the device drivers are EEH aware, if not EEH enabled. For
            example, the device driver or OS may signal its awareness by using
            <emphasis>ibm,set-eeh-option</emphasis> RTAS call to enable EEH prior to a
            configuration cycle via the
            <emphasis>ibm,write-pci-config</emphasis> RTAS call which enables the Memory
            Space or IO Space enable bits in the PCI Command register, and firmware can
            ignore the
            <emphasis>ibm,write-pci-config</emphasis> RTAS call which enables the Memory
            Space or IO Space enable bits for an IOA if EEH for that IOA has not been
            enabled first. To be EEH aware, a device driver does not need to be able to
            recover from an MMIO Stopped and DMA Stopped state, only recognize the
            all-1's condition (from a
            <emphasis>Load</emphasis> from its IOA or on a PCI configuration read from
            its IOA) and not use data from operations that may have occurred since the
            last all-1's checkpoint. In addition, the device driver under such failure
            circumstances needs to turn off interrupts (using the
            <emphasis>ibm,set-int-off</emphasis> RTAS call, or for conventional PCI and
            PCI-X infrastructures only: by resetting the IOA and keeping it reset with
            <emphasis>ibm,set-slot-reset</emphasis> or
            <emphasis>ibm,slot-error-detail</emphasis>) to make sure that any
            (unserviceable) interrupts from the IOA do not affect the system (MSIs are
            blocked by the EEH DMA Stopped State, but LSIs are not). Note that if
            all-1&#8217;s data may be valid, the
            <emphasis>ibm,read-slot-reset-state2</emphasis> RTAS call should be used to
            discover the true EEH state of the device.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_io_req"
        xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must assign a PE to
            one and only one partition at a time.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry xml:id="dbdoclet.50569344_34063">
        <term><emphasis role="bold">R1-<xref linkend="sec_io_req"
        xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis>
            The platform must limit the DMA addresses accessible to a PE to the address ranges assigned
            to the partition to which the PE is allocated, and, if the PE is used to
            implement a VIO device, then also to any allowed redirected DMA address
            ranges.</para>
            <para>
              <emphasis role="bold">Architecture and Implementation Notes:</emphasis>
              <orderedlist>
                <listitem>
                  <para>Platforms which do not implement either Requirement
                  <xref linkend="dbdoclet.50569344_47137" /> or Requirement
                  <xref linkend="dbdoclet.50569344_34063" /> require PE granularity of
                  everything below the PHB, resulting in poor LPAR partition I/O assignment
                  granularity.</para>
                </listitem>

                <listitem>
                  <para>Requirement <emphasis><xref linkend="dbdoclet.50569344_34063" /></emphasis>
                  has implications in preventing access to both to I/O address
                  ranges and system memory address ranges. That is, Requirement
                  <emphasis>
                    <xref linkend="dbdoclet.50569344_34063" />
                  </emphasis> requires prevention of peer to peer operations from one IOA to
                  another IOA when those IOA addresses are not owned by the same partition,
                  as well as to providing an access protection mechanism to protect system
                  memory. Note that relative to peer to peer operations, some bridges or
                  switches may not provide the capabilities to limit peer to peer, and the
                  use of such bridges or switches require the limitation that all IOAs under
                  such bridges or switches be assigned to the same partition.</para>
                </listitem>
              </orderedlist>
            </para>
          </listitem>
     	</varlistentry>

     	<varlistentry xml:id="dbdoclet.50569344_20446">
        <term><emphasis role="bold">R1-<xref linkend="sec_io_req"
        xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must
            provide a PE the capability of accessing all of the System Memory addresses
            assigned to the partition to which the PE is allocated.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_io_req"
        xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> If TCEs are used to satisfy
            Requirements
            <xref linkend="dbdoclet.50569344_34063" />, and
            <xref linkend="dbdoclet.50569344_20446" />, then the platform must provide
            the capability to map simultaneously and at all times at least 256 MB for
            each PE.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_io_req"
        xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> If TCEs are used to satisfy
            Requirements
            <xref linkend="dbdoclet.50569344_34063" />, and
            <xref linkend="dbdoclet.50569344_20446" />, then the platform must prevent
            any DMA operations to System Memory addresses which are not translated by
            TCEs.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_io_req"
        xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The DMA address range accessible
            to a PCI IOA on its I/O bus must be defined by the
            <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property in its
            parent&#8217;s OF device tree node.</para>
            <para><emphasis  role="bold">Platform Implementation Note:</emphasis> To maximize the ability to migrate
            memory pages underneath active DMA operations, when ever possible, a bridge
            should create a bus for a single IOA and either its representing bridge
            node should include the
            <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property specific for the
            IOA for conventional PCI or PCI-X IOAs or the IOA function nodes should
            contain the
            <emphasis role="bold"><literal>&#8220;ibm,my-dma-window&#8221;</literal></emphasis> property specific for
            the IOA function for PCI Express IOAs. When the configuration of a bus
            precludes memory migration, the platform may combine the DMA address for
            multiple IOAs that share a bus into a single
            <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property housed in the
            bridge node representing the bridge that creates the shared bus.</para>
          </listitem>
     	</varlistentry>
    </variablelist>

  </section>

  <section xml:id="sec_interrupt_req">
    <title>Interrupt Sub-System Requirements</title>

    <variablelist>
     	<varlistentry xml:id="dbdoclet.50569344_19261">
        <term><emphasis role="bold">R1-<xref linkend="sec_interrupt_req"
        xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must
            not assign the same interrupt (LSI or MSI) or same interrupt source number
            to different PEs (interrupts cannot be shared between partitions).</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_interrupt_req"
        xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The interrupt presentation layer
            must support at least one global interrupt queue per platform supported
            partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_interrupt_req"
        xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The interrupt presentation layer
            must separate the per processor interrupt management areas into a separate
            4 K pages per processor so that they can each be individually protected by
            the PTE mechanism and assigned to their respective assigned
            partitions.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_interrupt_req"
        xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must restrict the
            processors that service a global queue to those assigned to a single
            partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_interrupt_req"
        xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> If the interrupt source layer
            supports message signaled interrupts, the platform must isolate the PCI
            Message interrupt Input Port (PMIP) in its own 4 K page of the
            platform&#8217;s address space.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_interrupt_req"
        xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> If the interrupt source layer
            supports message signaled interrupts, the hardware must ignore all writes
            to the PMIP&#8217;s 4 K page except those to the PMIP itself.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_interrupt_req"
        xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> If the interrupt source layer
            supports message signaled interrupts, the hardware must return all ones on
            reads of the PMIP&#8217;s 4 K page except those to the PMIP itself.
            Signalling a machine check interrupt to the affected processor on a read
            that returns all 1s as above is optional.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_interrupt_req"
        xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The interrupt source layer must
            support a means in addition to the inter-processor interrupt mechanism for
            the hypervisor to signal an interrupt to any processor assigned to a
            partition.</para>
            <para>
            <emphasis role="bold">Software Note:</emphasis> While firmware takes all reasonable
            steps to prevent it, it may be possible, on some hardware implementations,
            for an OS to erroneously direct an individual IOA&#8217;s interrupt to
            another partition&#8217;s processor. An OS supporting LPAR should ignore
            such &#8220;Phantom&#8221; interrupts.</para>
          </listitem>
     	</varlistentry>
    </variablelist>

  </section>

  <section>
    <title>Hypervisor Requirements</title>
    <para>The purpose of the hypervisor is to virtualize the facilities of
    platforms, with LPAR, such that multiple copies of a LoPAR compliant OS
    may simultaneously run protected from each other in different logical
    partitions of the platform. That is, the various OS images may, without
    explicit knowledge of each other, boot, run applications, handle exceptions
    and events and terminate without affecting each other.</para>
    <para>The hypervisor is entered by way of three interrupts: the System
    Reset Interrupt, the Machine Check Interrupt and System (hypervisor) Call
    Interrupt. These use hypervisor interrupt vectors 0x0100, 0x0200, and
    0x0C00 respectively. In addition, a processor implementation dependent
    interrupt, at its assigned address may cause the hypervisor to be entered.
    The return from the hypervisor to the OS is via the rfid (Return from
    Interrupt Doubleword) instruction. The target of the rfid (instruction at
    the address contained in SRR0) is either a firmware glue routine (in the
    case of System Reset or Machine Check) or the instruction immediately
    following the invoking hypervisor call. The reason for the firmware glue
    routines is that the OS must do its own processing because of the
    asynchronous nature of System Reset or Machine Check interruptions. The
    firmware glue routine calls an OS registered recovery routine for the
    System Reset or Machine Check condition for further details see (reference
    to recoverable machine check ACR material to be added when available). The
    glue routines are registered by the partition&#8217;s OS through RTAS.
    Until the glue routines are registered, the OS does not receive direct
    reports of either System Reset or Machine Check interrupts but is simply
    re-booted by the hypervisor. The glue routines contain a register buffer
    area that the hypervisor fills with register values that the glue routine
    must pass to the OS when calling the interrupt handler. The last element in
    this buffer is a lock word. The lock word is set with the value of the
    using processor, and reset by the glue routine just before calling the OS
    interrupt handler. This way only one buffer is needed per partition rather
    than one per processor.</para>
    <para>At the invocation of the hypervisor, footprint records are generated
    for recovery conditions. Machine Check and Check Stop conditions are, in
    some cases, isolatable to the affected partition(s). In these cases, the
    hypervisor can then prove that it was not executing changes to the global
    system tables on the offending processor when the error occurred. If this
    cannot be proven, the global state of the complex is in doubt and the error
    cannot be contained. It is anticipated that check stops that only corrupt
    the internal state of the affected processor, stop that processor only.
    When the service processor subsequently notices the stopped processor it
    notifies one of the other processors in the partition through a simulated
    recoverable machine check. The hypervisor running on the notified processor
    then takes appropriate action to log out and restart the partition, or if
    there is an alternate cpu capability, then continue execution with a
    substitute for the stopped processor.</para>
    <para>The following table presents the functions supplied by the
    hypervisor.</para>
    <para><emphasis role="bold">Architecture Note:</emphasis> Some functions performed by partition firmware (OF
    and RTAS) require hypervisor assist, but those firmware implementation
    dependent interfaces do not appear in this document.</para>

    <table frame="all" pgwide="1">
      <title>Architected hcall()s</title>
      <tgroup cols="2">
        <colspec colname="c1" colwidth="35*" />
        <colspec colname="c2" colwidth="65*" />
        <thead valign="middle">
          <row>
            <entry align="center" >
              <para>
                <emphasis role="bold">Function Name/Section</emphasis>
              </para>
            </entry>
            <entry align="center">
              <para>
                <emphasis role="bold">Comments</emphasis>
              </para>
            </entry>
          </row>
        </thead>
        <tbody valign="middle">
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_80550" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_80550" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Removes a PTE from the partition&#8217;s node Page Frame
              Table</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_23009" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_23009" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Removes up to four (4) PTEs from the partition&#8217;s node
              Page Frame Table</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_block_remove" xrefstyle="select: title nopage" /> / <xref linkend="sec_block_remove" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Removes PTEs of a naturally aligned block of Virtual addresses from the partition’s Page Frame Table</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_61580" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_61580" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Inserts a PTE into the partition&#8217;s node Page Frame
              Table</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_50644" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_50644" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Reads the specified PTE from the partition&#8217;s node
              Page Frame Table</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_53301" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_53301" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Clears the Modified bit in the specified PTE in the
              partition&#8217;s node Page Frame Table</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_35125" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_35125" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Clears the Referenced bit in the specified PTE in the
              partition&#8217;s node Page Frame Table</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_34458" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_34458" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Sets the Page Protection and Storage Key bits in the
              specified PTE in the partition&#8217;s node Page Frame
              Table</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_resize_hpt_prepare" xrefstyle="select: title nopage" /> / <xref linkend="sec_resize_hpt_prepare" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Prepares for resizing the partition's HPT</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_resize_hpt_commit" xrefstyle="select: title nopage" /> / <xref linkend="sec_resize_hpt_commit" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Changes the partition's HPT to a new size</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_38645" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_38645" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Returns the value of the specified DMA Translation Control
              Entry</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_44496" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_44496" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Inserts the specified value into the specified DMA
              Translation Control Entry</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_31179" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_31179" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Inserts the specified value into multiple DMA Translation
              Control Entries</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_50921" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_50921" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Inserts a list of values into the specified range of DMA
              Translation Control Entries</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_77407" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_77407" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>SPRG0 is architecturally a hypervisor resource. This call
              allows the OS to write the register.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_91084" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_91084" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>DABR is architecturally a hypervisor resource. This call
              allows the OS to write the register.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_36623" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_36623" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Initializes pages in real mode either to zero or to the
              copied contents of another page.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_51622" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_51622" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Manage the Extended DABR facility.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_adjust_resource" xrefstyle="select: title nopage" /> / <xref linkend="sec_adjust_resource" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Adjust implementation dependent tuning values</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_set_switches" xrefstyle="select: title nopage" /> / <xref linkend="sec_set_switches" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Set implementation dependent tuning switches</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_96762" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_96762" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Returns the value contained in a cache inhibited logical
              address</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_70927" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_70927" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Stores a value into a cache inhibited logical
              address</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569352_18926" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569352_18926" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Returns up to 16 bytes of virtualized console terminal
              data.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569352_36115" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569352_36115" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Sends up to 16 bytes of data to a virtualized console
              terminal.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569352_31370" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569352_31370" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Gets a list of possible client Vterm IOA
              connections.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569352_39886" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569352_39886" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Associates server Vterm IOA to client Vterm IOA.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569352_49502" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569352_49502" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Breaks association between server Vterm IOA and client
              Vterm IOA.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_34502" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_34502" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Returns internal hypervisor work areas for code
              maintenance.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_clear_hpt" xrefstyle="select: title nopage" /> / <xref linkend="sec_clear_hpt" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Clears the hash page table for a partition in preparation for a restart</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_20734" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_20734" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Generates and End Of Interrupt</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_29571" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_29571" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Sets the Processor&#8217;s Current Interrupt
              Priority</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_16166" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_16166" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Generates an Inter-processor Interrupt</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_23590" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_23590" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Polls for pending interrupt</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_26587" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_26587" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Accepts pending interrupt</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_int_get_source_info" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_get_source_info" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Get the ESB addresses for a LISN</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_int_set_source_config" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_set_source_config" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Assign a target and priority to a LISN</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_int_get_source_config" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_get_source_config" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Get the target and priority assigned to a LISN </para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_int_get_queue_info" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_get_queue_info" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Get the notification management page for a LISN</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_int_set_queue_config" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_set_queue_config" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Set/Reset an EQ for a target and priority</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_int_get_queue_config" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_get_queue_config" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Get the EQ set for a target and priority</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_int_set_os_reporting_line" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_set_os_reporting_line" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Set the OS reporting cache line pair for a target</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_int_get_os_reporting_line" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_get_os_reporting_line" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Get the OS reporting cache line pair for a target</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_int_esb" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_esb" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Load or store operation on the ESB page for a LISN</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_int_sync" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_sync" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Issue the requested sync</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_int_reset" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_reset" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Reset interrupt state to the initial state</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_23386" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_23386" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Migrates the page underneath an active DMA
              operation.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_88471" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_88471" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Manages the performance monitor facility.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_98622" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_98622" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Registers the virtual processor area that contains the
              virtual processor dispatch count</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_80840" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_80840" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Makes processor virtual processor cycles available for
              other uses (called when an OS image is idle)</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_29793" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_29793" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Causes a virtual processor&#8217;s cycles to be transferred
              to a specified processor. (Called by a blocked OS image to allow
              a lock holder to use virtual processor cycles rather than waiting
              for the block to clear.)</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_67798" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_67798" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Awakens a virtual processor that has ceded its
              cycles.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_61487" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_61487" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Returns the partition&#8217;s virtual processor performance
              parameters.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_14689" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_14689" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Sets the partition&#8217;s virtual processor performance
              parameters (within constraints).</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_23727" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_23727" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Returns the value of the virtual processor utilization
              register.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_98220" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_98220" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Polls the hypervisor for the existence of pending work to
              dispatch on the calling processor.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_39055" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_39055" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Returns the summation of the physical processor
              pool&#8217;s idle cycles.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_96691" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_96691" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Register Command/Response Queue</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_96323" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_96323" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Frees the memory associated with the Command/Response
              Queue</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_53470" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_53470" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Controls the virtual interrupt signaling of virtual
              IOAs</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_67318" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_67318" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Sends a message on the Command/Response Queue</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_96734" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_96734" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Loads a Redirected Remote DMA Remote Translation Control
              Entry</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_99406" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_99406" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Loads a list of Redirected Remote DMA Remote Translation
              Control Entries</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_87976" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_87976" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Unmaps a redirected TCE that was previously built with
              H_PUT_RTCE or H_PUT_RTCE_INDIRECT</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_67792" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_67792" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Allows modification of LIOBN Attributes.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_43271" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_43271" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Copies data between partitions as if by TCE mapped
              DMA.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_55103" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_55103" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Write parameter data to remote DMA buffer.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_34894" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_34894" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Read data from remote DMA buffer to return
              registers.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569350_38939" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_38939" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Registers the partition&#8217;s logical LAN control
              structures with the hypervisor</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569350_78305" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_78305" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Releases the partition&#8217;s logical LAN control
              structures</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569350_41506" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_41506" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Adds receive buffers to the logical LAN receive buffer
              pool</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569350_62760" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_62760" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Sends a logical LAN message</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569350_71401" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_71401" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Controls the reception and filtering of non-broadcast
              multicast packets.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569350_19596" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_19596" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Changes the MAC address for an ILLAN virtual IOA.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569350_67792" xrefstyle="select: title nopage" /> /<xref linkend="dbdoclet.50569350_67792" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Allows modifications of ILLAN Attributes.</para>
            </entry>
          </row>
          <!-- FIXME: Entry doesn't resolve to a section.  What's needed here? >
                <row>
                  <entry><para> <xref linkend="dbdoclet.50569348_44496"/></para></entry>
                  <entry><para> Map from 4 KB up to the size of a full LMB per RTCE table TCE entry, and map multiple TCEs (and therefore multiple LMBs) in one operation.</para></entry>
                </row-->
          <!-- FIXME: Missing documentation.  Do we need these hcalls? >
                <row>
                  <entry><para> <xref linkend="error_section"/>17a VIO Infrastructure.htm#50569348_38581&#160;</para></entry>
                  <entry><para> ALRDMA CRQ and ASQ setup and control.</para></entry>
                </row-->
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_71928" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_71928" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Constructs a cookie, specific to the intended client,
              representing a shared resource.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_37799" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_37799" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Invalidates a cookie representing a shared resource.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_74094" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_74094" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Maps a shared resource into the client&#8217;s logical
              address space</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_58491" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_58491" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Removes a shared resource from a client&#8217;s logical
              address space.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569350_83832" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_83832" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Removes receive buffers of specified size from the logical
              LAN receive buffer pool.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_33176" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_33176" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Allows the partition to manipulate or query certain virtual
              IOA behaviors.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_15933" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_15933" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Join active threads and return H_CONTINUE to final calling
              thread</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_vasi_h_donor_operations" xrefstyle="select: title nopage" /> / <xref linkend="sec_vasi_h_donor_operations" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Use the calling processor to perform platform operations.</para></entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_h_vasi_signal" xrefstyle="select: title nopage" /> / <xref linkend="sec_h_vasi_signal" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Transition VASI operation stream state.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_h_vasi_state" xrefstyle="select: title nopage" /> / <xref linkend="sec_h_vasi_state" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para> Return the VASI operation stream state.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_43427" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_43427" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Reactivate a suspended CRQ.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_74652" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_74652" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Change the page mapping characteristics of the Virtualized
              Real Mode Area.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_30144" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_30144" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Returns Virtual Partition Memory pool statistics</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_22106" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_22106" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Set Memory Performance Parameters</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_90056" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_90056" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Get Memory Performance Parameters</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_47885" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_47885" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Determine Memory Overcommit Performance</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_63838" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_63838" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Register a Sub-CRQ.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_39734" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_39734" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Free a Sub-CRQ.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_62703" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_62703" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Send a message to a Sub-CRQ.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569348_16926" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_16926" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Send a list of messages to a Sub-CRQ.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_30997" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_30997" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Report the home node associativity for a given virtual
              processor</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_66904" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_66904" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Get the partition energy management parameters</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_61969" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_61969" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Returns hints for activating/releasing resource instances
              to achieve the best energy efficiency.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_76215" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_76215" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Registers Subvention Notification Structure</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_74640" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_74640" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Get a random number</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_29950" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_29950" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Initiate a co-processor operation</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_73950" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_73950" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Stop a co-processor operation</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_73194" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_73194" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Get Extended Memory Performance Parameters</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_97588" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_97588" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Set Processing resource mode</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="dbdoclet.50569344_88592" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_88592" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Search TCE table for entries within a specified
              range</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_memstat_ctrl" xrefstyle="select: title nopage" /> / <xref linkend="sec_memstat_ctrl" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Configure Memory Usage Instrumentation</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_reset_memstats" xrefstyle="select: title nopage" /> / <xref linkend="sec_reset_memstats" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Reset page age and affinity log, and/or PUT/HBA</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_return_pageinfo" xrefstyle="select: title nopage" /> / <xref linkend="sec_return_pageinfo" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Return the page usage information for a logical address range of pages</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_bulk_read_hba" xrefstyle="select: title nopage" /> / <xref linkend="sec_bulk_read_hba" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Return multiple HBA</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_clean_slb" xrefstyle="select: title nopage" /> / <xref linkend="sec_clean_slb" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Invalidate the specified process segment from all segment lookaside buffers in the system.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_invalidate_pid" xrefstyle="select: title nopage" /> / <xref linkend="sec_invalidate_pid" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Invalidate the specified process table entry.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_register_process_table" xrefstyle="select: title nopage" /> / <xref linkend="sec_register_process_table" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Manage the virtual address translation mode including registration of a process table.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_attach_ca_process" xrefstyle="select: title nopage" /> / <xref linkend="sec_attach_ca_process" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Attach a process to a coherent platform function.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_detach_ca_process" xrefstyle="select: title nopage" /> / <xref linkend="sec_detach_ca_process" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Detach a process to a coherent platform function.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_control_ca_function" xrefstyle="select: title nopage" /> / <xref linkend="sec_control_ca_function" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Control a coherent platform function.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_collect_ca_int_info" xrefstyle="select: title nopage" /> / <xref linkend="sec_collect_ca_int_info" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Collect interrupt information for a coherent platform function.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_control_ca_faults" xrefstyle="select: title nopage" /> / <xref linkend="sec_control_ca_faults" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Control faults for a coherent platform function.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_download_ca_function" xrefstyle="select: title nopage" /> / <xref linkend="sec_download_ca_function" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Download an application to a coherent platform function.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_download_ca_facility" xrefstyle="select: title nopage" /> / <xref linkend="sec_download_ca_facility" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Download an application to a coherent platform facility.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>
                <xref linkend="sec_control_ca_facility" xrefstyle="select: title nopage" /> / <xref linkend="sec_control_ca_facility" xrefstyle="select: labelnumber nopage" />
              </para>
            </entry>
            <entry>
              <para>Control a coherent platform facility.</para>
            </entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <section xml:id="sec_system_reset_req">
      <title>System Reset Interrupt</title>
      <para>Hypervisor code saves all processor state by saving the contents of
      one register in SPRG2 (SPRG1 if
      <emphasis>ibm,nmi-register-2</emphasis> was used) (Multiplexing the use of
      this resource with the OS). The processor&#8217;s stack and data area are
      found by processing the Processor Identification Register.</para>

      <variablelist>
       	<varlistentry >
          <term><emphasis role="bold">R1-<xref linkend="sec_system_reset_req"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must support
              signalling system reset interrupts to all processors assigned to a
              partition.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_system_reset_req"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must support
              signalling system reset interrupts individually as well as collectively
              to all supported partitions.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_system_reset_req"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The system reset interrupts
              signaled to one partition must not affect operations of another
              partition.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_system_reset_req"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The hypervisor must intercept
              all system reset interrupts.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_system_reset_req"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must implement the
              FWNMI option.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_system_reset_req"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The hypervisor must maintain a
              count, reset when the partition&#8217;s OS, through RTAS, registers for
              system reset interrupt notification, of system reset interrupts signaled
              to a partition&#8217;s processor.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_system_reset_req"
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> Once the partition&#8217;s OS
              has registered for system reset interrupt notification, the hypervisor
              must forward the first and second system reset interrupts signaled to a
              partition&#8217;s processor.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_system_reset_req"
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The hypervisor must on the third
              and all subsequent system reset interrupts signaled to a
              partition&#8217;s processor invoke OF to initiate the partition&#8217;s
              reboot policy.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry xml:id="dbdoclet.50569344_53372">
          <term><emphasis role="bold">R1-<xref linkend="sec_system_reset_req"
          xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis>
              The hypervisor must have the capability to receive and handle the system reset
              interrupts simultaneously on multiple processors in the same or different
              partitions up to the number of processors in the system.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

    </section>

    <section xml:id="sec_machine_check">
      <title>Machine Check Interrupt</title>
      <para>Hypervisor code saves all processor state by saving the contents of
      one register in SPRG2 (SPRG1 if
      <emphasis>ibm,nmi-register-2</emphasis> was used) (Multiplexing the use of
      this resource with the OS). The processor&#8217;s stack and data area are
      found by processing the Processor Identification Register.</para>
      <para>The hypervisor investigates the cause of the machine check. The
      cause is either a recoverable event on the current processor, or a
      non-recoverable event either on the current processor or one of the other
      processors in the logical partition. Also the hypervisor must determine
      if the machine check may have corrupted its own internal state (by
      looking at the footprints, if any, that were left in the per processor
      data area of the errant processor.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_machine_check"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The hypervisor must have the
              capability to receive and handle the machine check interrupts
              simultaneously on multiple processors in the same or different partitions
              up to the number of processors in the system.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

    </section>

    <section xml:id="sec_hyp_call_int">
      <title>Hypervisor Call Interrupt</title>
      <para>The hypervisor call (hcall) interrupt is a special variety of the
      system call instruction. The parameters to the hcall() are passed in
      registers using the PA ABI definitions (Reg 3-12 for parameters). In
      contrast to the PA ABI, pass by reference parameters are avoided to or
      from hcall(). This minimizes the address translation problem pointer
      parameters cause. Some input parameters are indexes. Output parameters,
      when generated, are passed in registers 4 through 12 and require special
      in-line assembler code on the part of the caller. The first parameter to
      hcall() is the function token.
      <xref linkend="dbdoclet.50569344_49986" /> specifies the valid hcall()
      function names and token values. Some of the hcall() functions are
      optional, to indicate if the platform is in LPAR mode, and which
      functions are available on a given platform, the OF property
      <emphasis role="bold"><literal>&#8220;ibm,hypertas-functions&#8221;</literal></emphasis> is provided in
      the <emphasis role="bold"><literal>/rtas</literal></emphasis> node of the partition&#8217;s device tree. The
      property is present if the platform is in LPAR mode while its value
      specifies which function sets are implemented by a given implementation.
      If platform implements any hcall() of a function set it implements the
      entire function set. Additionally, certain values of the
      <emphasis role="bold"><literal>&#8220;ibm,hypertas-functions&#8221;</literal></emphasis> property
      indicate that the platform supports a given architecture extension to a
      standard hcall().</para>
      <para>The floating point registers along with the FPSCR are in general
      preserved across hcall() functions, unless the &#8220;Maintain
      FPRs&#8221; field of the VPA =0, see
      <xref linkend="dbdoclet.50569344_46490" />. The general purpose registers
      r0 and r3-r12, the CTR and XER registers are volatile along with the
      condition register fields 0 and 1 plus 5-7. Specific hcall()s may specify
      a more restricted &#8220;kill set&#8221;, refer to the specific hcall()
      specification below.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_hyp_call_int"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The platform&#8217;s
              <emphasis role="bold"><literal>/rtas</literal></emphasis> node must contain an
              <emphasis role="bold"><literal>&#8220;ibm,hypertas-functions&#8221;</literal></emphasis> property as
              defined below.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_hyp_call_int"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> If a platform reports in its
              <emphasis role="bold"><literal>&#8220;ibm,hypertas-functions&#8221;</literal></emphasis> property (see
              <xref linkend="LoPAR.RTAS" />) that it supports a function set, then it
              must support all hcall()s of that function set as defined in
              <xref linkend="dbdoclet.50569344_49986" />.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

      <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_49986">
        <title>Hypervisor Call Function Table</title>
        <tgroup cols="5">
          <colspec colname="c1" colwidth="35*" />
          <colspec colname="c2" colwidth="12*" align="center" />
          <colspec colname="c3" colwidth="18*" align="center" />
          <colspec colname="c4" colwidth="17*" align="center" />
          <colspec colname="c5" colwidth="18*" align="center" />
          <thead valign="middle">
            <row>
              <entry align="center">
                <para>
                  <emphasis role="bold">Hypervisor Call Function
                  Name/Section</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Hypervisor Call Function
                  Token</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Hypervisor Call Performance
                  Class</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Function Mandatory?</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Function Set</emphasis>
                </para>
              </entry>
            </row>
          </thead>
          <tbody valign="middle">
            <row>
              <entry>
                <para>UNUSED</para>
              </entry>
              <entry>
                <para>0x0</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_80550" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_80550" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x4</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-pft</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_61580" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_61580" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x8</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-pft</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_50644" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_50644" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0xC</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-pft</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_53301" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_53301" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x10</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-pft</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_35125" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_35125" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x14</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-pft</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_34458" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_34458" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x18</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-pft</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_38645" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_38645" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x1C</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-tce</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_44496" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_44496" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x20</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-tce</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_77407" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_77407" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x24</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-sprg0</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_91084" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_91084" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x28</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes - if DABR exists</para>
              </entry>
              <entry>
                <para>hcall-dabr</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_36623" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_36623" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2C</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-copy</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_96762" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_96762" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x3C</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-debug</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_70927" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_70927" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x40</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-debug</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569352_18926" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569352_18926" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x54</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-term</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569352_36115" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569352_36115" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x58</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-term</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_34502" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_34502" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x60</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>Yes if enabled by HMC (default disabled)</para>
              </entry>
              <entry>
                <para>hcall-dump</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_20734" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_20734" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x64</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-interrupt</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_29571" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_29571" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x68</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-interrupt</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_16166" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_16166" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x6C</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-interrupt</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_23590" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_23590" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x70</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-interrupt</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <link linkend="dbdoclet.50569344_26587" xrefstyle="select: nopage">H_XIRR</link> / <xref linkend="dbdoclet.50569344_26587" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x74</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-interrupt</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <link linkend="dbdoclet.50569344_26587" xrefstyle="select: nopage" >H_XIRR-X</link> / <xref linkend="dbdoclet.50569344_26587" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2FC</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-interrupt</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_23386" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_23386" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x78</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If LRDR option is implemented</para>
              </entry>
              <entry>
                <para>hcall-migrate</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_88471" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_88471" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x7C</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If performance monitor is implemented</para>
              </entry>
              <entry>
                <para>hcall-perfmon</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x80 - 0xD8</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_98622" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_98622" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0xDC</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If SPLPAR or SLB Shadow Buffer option is
                implemented</para>
              </entry>
              <entry>
                <para>hcall-splpar</para>
                <para>SLB-Buffer</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_80840" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_80840" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0xE0</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If SPLPAR option is implemented</para>
              </entry>
              <entry>
                <para>hcall-splpar</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_29793" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_29793" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0xE4</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If SPLPAR option is implemented</para>
              </entry>
              <entry>
                <para>hcall-splpar</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_67798" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_67798" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0xE8</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If SPLPAR option is implemented</para>
              </entry>
              <entry>
                <para>hcall-splpar</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_61487" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_61487" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0xEC</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If SPLPAR option is implemented</para>
              </entry>
              <entry>
                <para>hcall-splpar</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_14689" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_14689" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0xF0</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If SPLPAR option is implemented</para>
              </entry>
              <entry>
                <para>hcall-splpar</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_23727" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_23727" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0xF4</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If SPLPAR option is implemented</para>
              </entry>
              <entry>
                <para>hcall-splpar</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_39055" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_39055" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0xF8</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If SPLPAR option is implemented</para>
              </entry>
              <entry>
                <para>hcall-pic</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_96691" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_96691" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0xFC</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If VSCSI option is implemented</para>
              </entry>
              <entry>
                <para>hcall-crq</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_96323" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_96323" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x100</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If VSCSI option is implemented</para>
              </entry>
              <entry>
                <para>hcall-crq</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_53470" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_53470" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x104</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If either the VSCSI or logical LAN option is
                implemented</para>
              </entry>
              <entry>
                <para>hcall-vio</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_67318" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_67318" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x108</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If VSCSI option is implemented</para>
              </entry>
              <entry>
                <para>hcall-crq</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_96734" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_96734" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x10C</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If VSCSI option is implemented</para>
              </entry>
              <entry>
                <para>hcall-rdma</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_43271" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_43271" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x110</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If VSCSI option is implemented</para>
              </entry>
              <entry>
                <para>hcall-rdma</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569350_38939" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_38939" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x114</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If logical LAN option is implemented</para>
              </entry>
              <entry>
                <para>hcall-lLAN</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569350_78305" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_78305" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x118</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If logical LAN option is implemented</para>
              </entry>
              <entry>
                <para>hcall-lLAN</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569350_41506" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_41506" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x11C</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If logical LAN option is implemented</para>
              </entry>
              <entry>
                <para>hcall-lLAN</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569350_62760" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_62760" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x120</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If logical LAN option is implemented</para>
              </entry>
              <entry>
                <para>hcall-lLAN</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_23009" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_23009" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x124</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>New designs as of 01/01/2003</para>
              </entry>
              <entry>
                <para>hcall-bulk</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_55103" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_55103" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x128</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If VSCSI option is implemented</para>
              </entry>
              <entry>
                <para>hcall-rdma</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_34894" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_34894" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x12C</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If VSCSI option is implemented</para>
              </entry>
              <entry>
                <para>hcall-rdma</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569350_71401" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_71401" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x130</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If logical LAN option is implemented</para>
              </entry>
              <entry>
                <para>hcall-lLAN</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_51622" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_51622" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x134</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If Extended DABR option is implemented</para>
              </entry>
              <entry>
                <para>hcall-xdabr</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_31179" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_31179" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x138</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>hcall-multi-tce</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_50921" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_50921" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x13C</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>hcall-multi-tce</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_99406" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_99406" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x140</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>hcall-multi-tce</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x144</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x148</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569350_19596" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_19596" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x14C</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If Logical LAN option is implemented</para>
              </entry>
              <entry>
                <para>hcall-ILAN</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569352_31370" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569352_31370" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x150</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Server Vterm option is implemented</para>
              </entry>
              <entry>
                <para>hcall-vty</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569352_39886" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569352_39886" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x154</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Server Vterm option is implemented</para>
              </entry>
              <entry>
                <para>hcall-vty</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569352_49502" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569352_49502" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x158</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Server Vterm option is implemented</para>
              </entry>
              <entry>
                <para>hcall-vty</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_71928" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_71928" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x1C4</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If Shared Logical Resource option is Implemented</para>
              </entry>
              <entry>
                <para>hcall-slr</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_37799" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_37799" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x1C8</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If Shared Logical Resource option is Implemented</para>
              </entry>
              <entry>
                <para>hcall-slr</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_74094" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_74094" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x1CC</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If Shared Logical Resource option is Implemented</para>
              </entry>
              <entry>
                <para>hcall-slr</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_58491" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_58491" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x1D0</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If Shared Logical Resource option is Implemented</para>
              </entry>
              <entry>
                <para>hcall-slr</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569350_83832" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_83832" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x1D4</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If logical LAN option is implemented</para>
              </entry>
              <entry>
                <para>hcall-lLAN</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_98220" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_98220" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x1D8</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If SPLPAR option is implemented</para>
              </entry>
              <entry>
                <para>hcall-poll-pending</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x1DC - 0x1E0</para>
              </entry>
              <entry>
                <para>Varies</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x1E8 - 0x1EC</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x1F0 - 0x23C</para>
              </entry>
              <entry>
                <para>Varies</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_67792" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_67792" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x240</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If LIOBN Attributes are implemented</para>
              </entry>
              <entry>
                <para>hcall-liobn-attributes</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569350_67792" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569350_67792" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x244</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If ILLAN Checksum Offload Support is implemented</para>
                <para>If ILLAN Backup Trunk Adapter option is
                implemented</para>
              </entry>
              <entry>
                <para>hcall-illan-options</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x248</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_87976" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_87976" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x24C</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>If H_PUT_RTCE is implemented</para>
              </entry>
              <entry>
                <para>hcall-rdma</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x27C</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x280</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x28C-0x294</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_15933" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_15933" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x298</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If Thread Join option is implemented</para>
              </entry>
              <entry>
                <para>hcall-join</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_vasi_h_donor_operations" xrefstyle="select: title nopage" /> / <xref linkend="sec_vasi_h_donor_operations" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x29C</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If VASI option is implemented</para>
              </entry>
              <entry>
                <para>hcall-vasi</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_h_vasi_signal" xrefstyle="select: title nopage" /> / <xref linkend="sec_h_vasi_signal" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2A0</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If VASI option is implemented</para>
              </entry>
              <entry>
                <para> hcall-vasi</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_h_vasi_state" xrefstyle="select: title nopage" /> / <xref linkend="sec_h_vasi_state" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2A4</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If VASI option is implemented</para>
              </entry>
              <entry>
                <para>hcall-vasi</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_33176" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_33176" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2A8</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If any virtual I/O options are implemented</para>
              </entry>
              <entry>
                <para>hcall-vioctl</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_74652" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_74652" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2AC</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the VRMA option is implemented.</para>
              </entry>
              <entry>
                <para>hcall-vrma</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_43427" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_43427" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2B0</para>
              </entry>
              <entry>
                <para>Continued</para>
              </entry>
              <entry>
                <para>If partition suspension option is implemented</para>
              </entry>
              <entry>
                <para>hcall-suspend</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x2B4</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_66904" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_66904" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2B8</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Partition Energy Management Option is
                implemented</para>
              </entry>
              <entry>
                <para>hcall-get-emparm</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_30144" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_30144" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2BC</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Cooperative Memory Over-commitment Option is
                implemented</para>
              </entry>
              <entry>
                <para>hcall-cmo</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_22106" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_22106" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2D0</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Cooperative Memory Over-commitment Option is
                implemented</para>
              </entry>
              <entry>
                <para>hcall-cmo</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_90056" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_90056" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2D4</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Cooperative Memory Over-commitment Option is
                implemented</para>
              </entry>
              <entry>
                <para>hcall-cmo</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_47885" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_47885" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2D8</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Cooperative Memory Over-commitment Option is
                implemented and the calling partition is authorized.</para>
              </entry>
              <entry>
                <para>hcall-cmo</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_63838" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_63838" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2DC</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Subordinate CRQ Option is implemented</para>
              </entry>
              <entry>
                <para>hcall-sub-crq</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_39734" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_39734" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2E0</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Subordinate CRQ Option is implemented</para>
              </entry>
              <entry>
                <para>hcall-sub-crq</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_62703" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_62703" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2E4</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Subordinate CRQ Option is implemented</para>
              </entry>
              <entry>
                <para>hcall-sub-crq</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569348_16926" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569348_16926" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2E8</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Subordinate CRQ Option is implemented</para>
              </entry>
              <entry>
                <para>hcall-sub-crq</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_30997" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_30997" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2EC</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the VPHN Option is implemented</para>
              </entry>
              <entry>
                <para>hcall-vphn</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x2F0</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_61969" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_61969" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2F4</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Partition Energy Management Option is
                implemented</para>
              </entry>
              <entry>
                <para>hcall-best-energy-1&lt;list&gt;<footnote xml:id="pgfId-1236046">
                  <para>The &lt;list&gt; suffix for hcall-best-energy indicates
                  an optional dash delimited series (may be null) of supported
                  resource codes encoded as ASCII decimal values in addition to
                  the minimal support value of 1 for processors, other values
                  are define in
                  <xref linkend="dbdoclet.50569344_61969" />.</para>
                </footnote></para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_76215" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_76215" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2F8</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Expropriation Subvention Notification Option is
                implemented</para>
              </entry>
              <entry>
                <para>hcall-esn</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <link linkend="dbdoclet.50569344_26587" xrefstyle="select: nopage" >X_XIRR-X</link> / <xref linkend="dbdoclet.50569344_26587" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x2FC</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>Yes</para>
              </entry>
              <entry>
                <para>hcall-interrupt</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_74640" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_74640" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x300</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If a random number generator Platform Facilities Option
                is implemented</para>
              </entry>
              <entry>
                <para>hcall-random</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x310</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_29950" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_29950" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x304</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If one or more Coprocessor Platform Facilities Options
                are implemented</para>
              </entry>
              <entry>
                <para>hcall-cop</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_73950" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_73950" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x308</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If one or more Coprocessor Platform Facilities Options
                are implemented</para>
              </entry>
              <entry>
                <para>hcall-cop</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_73194" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_73194" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x314</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the Extended Cooperative Memory Overcommittment Option
                is implemented</para>
              </entry>
              <entry>
                <para>hcall-cmo-x</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_97588" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_97588" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x31C</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the platform supports POWER ISA version 2.07 or
                higher</para>
              </entry>
              <entry>
                <para>hcall-set-mode</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x320</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="dbdoclet.50569344_88592" xrefstyle="select: title nopage" /> / <xref linkend="dbdoclet.50569344_88592" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x324</para>
              </entry>
              <entry>
                <para>normal</para>
              </entry>
              <entry>
                <para>If the plaform implements the LRDR option at LoPAR
                Version 2.7 or higher</para>
              </entry>
              <entry>
                <para>hcall-xlates-limited</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_block_remove" xrefstyle="select: title nopage" /> / <xref linkend="sec_block_remove" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x328</para>
              </entry>
              <entry>
                <para>Critical</para>
              </entry>
              <entry>
                <para>if the platform supports the "block invalidate" option</para>
              </entry>
              <entry>
                <para>hcall-block-remove</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_memstat_ctrl" xrefstyle="select: title nopage" /> / <xref linkend="sec_memstat_ctrl" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x32C</para>
              </entry>
              <entry>
                <para>normal</para>
              </entry>
              <entry>
                <para>If the Memory Usage Instrumentation Option is implemented</para>
              </entry>
              <entry>
                <para>hcall-mui</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_reset_memstats" xrefstyle="select: title nopage" /> / <xref linkend="sec_reset_memstats" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x330</para>
              </entry>
              <entry>
                <para>normal</para>
              </entry>
              <entry>
                <para>If the Memory Usage Instrumentation Option is implemented</para>
              </entry>
              <entry>
                <para>hcall-mui</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_return_pageinfo" xrefstyle="select: title nopage" /> / <xref linkend="sec_return_pageinfo" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x334</para>
              </entry>
              <entry>
                <para>normal</para>
              </entry>
              <entry>
                <para>If the Memory Usage Instrumentation Option is implemented</para>
              </entry>
              <entry>
                <para>hcall-mui</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_bulk_read_hba" xrefstyle="select: title nopage" /> / <xref linkend="sec_bulk_read_hba" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x338</para>
              </entry>
              <entry>
                <para>normal</para>
              </entry>
              <entry>
                <para>If the Memory Usage Instrumentation Option is implemented</para>
              </entry>
              <entry>
                <para>hcall-mui</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_adjust_resource" xrefstyle="select: title nopage" /> / <xref linkend="sec_adjust_resource" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x33C</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the plaform implements the LRDR option at LoPAR Verstion 2.8 or higher</para>
              </entry>
              <entry>
                <para>hcall-implementation-<?linebreak?>dependent-tuning</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_set_switches" xrefstyle="select: title nopage" /> / <xref linkend="sec_set_switches" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x340</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the plaform implements the LRDR option at LoPAR Verstion 2.8 or higher</para>
              </entry>
              <entry>
                <para>hcall-implementation-<?linebreak?>dependent-tuning</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_attach_ca_process" xrefstyle="select: title nopage" /> / <xref linkend="sec_attach_ca_process" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x344</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If one or more Coherent Platform Facilities Options are implemented</para>
              </entry>
              <entry>
                <para>hcall-ca</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_detach_ca_process" xrefstyle="select: title nopage" /> / <xref linkend="sec_detach_ca_process" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x348</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If one or more Coherent Platform Facilities Options are implemented</para>
              </entry>
              <entry>
                <para>hcall-ca</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_control_ca_function" xrefstyle="select: title nopage" /> / <xref linkend="sec_control_ca_function" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x34C</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If one or more Coherent Platform Facilities Options are implemented</para>
              </entry>
              <entry>
                <para>hcall-ca</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_collect_ca_int_info" xrefstyle="select: title nopage" /> / <xref linkend="sec_collect_ca_int_info" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x350</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If one or more Coherent Platform Facilities Options are implemented</para>
              </entry>
              <entry>
                <para>hcall-ca</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_control_ca_faults" xrefstyle="select: title nopage" /> / <xref linkend="sec_control_ca_faults" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x354</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If one or more Coherent Platform Facilities Options are implemented</para>
              </entry>
              <entry>
                <para>hcall-ca</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_clear_hpt" xrefstyle="select: title nopage" /> / <xref linkend="sec_clear_hpt" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x358</para>
              </entry>
              <entry>
                <para>Terminal</para>
              </entry>
              <entry>
                <para>For LoPAR Verstion 2.8 and higher</para>
              </entry>
              <entry>
                <para>hcall-clr-hpt</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_download_ca_function" xrefstyle="select: title nopage" /> / <xref linkend="sec_download_ca_function" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x35C</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If one or more Coherent Platform Facilities Options are implemented</para>
              </entry>
              <entry>
                <para>hcall-ca</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x360</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_download_ca_facility" xrefstyle="select: title nopage" /> / <xref linkend="sec_download_ca_facility" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x364</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If one or more Coherent Platform Facilities Options are implemented</para>
              </entry>
              <entry>
                <para>hcall-ca</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_control_ca_facility" xrefstyle="select: title nopage" /> / <xref linkend="sec_control_ca_facility" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x368</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If one or more Coherent Platform Facilities Options are implemented</para>
              </entry>
              <entry>
                <para>hcall-ca</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_resize_hpt_prepare" xrefstyle="select: title nopage" /> / <xref linkend="sec_resize_hpt_prepare" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x36C</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the platform supports the Hash Page Table Resize Option</para>
              </entry>
              <entry>
                <para>hcall-hpt-resize</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_resize_hpt_commit" xrefstyle="select: title nopage" /> / <xref linkend="sec_resize_hpt_commit" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x370</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the platform supports the Hash Page Table Resize Option</para>
              </entry>
              <entry>
                <para>hcall-hpt-resize</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_clean_slb" xrefstyle="select: title nopage" /> / <xref linkend="sec_clean_slb" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x374</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the platform supports the In-Memory Table Translation Option</para>
              </entry>
              <entry>
                <para>hcall-imtt</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_invalidate_pid" xrefstyle="select: title nopage" /> / <xref linkend="sec_invalidate_pid" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x378</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the platform supports the In-Memory Table Translation Option</para>
              </entry>
              <entry>
                <para>hcall-imtt</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_register_process_table" xrefstyle="select: title nopage" /> / <xref linkend="sec_register_process_table" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x37C</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the platform supports the In-Memory Table Translation Option</para>
              </entry>
              <entry>
                <para>hcall-imtt</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_int_get_source_info" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_get_source_info" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x3A8</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the OS enabled XIVE exploitation</para>
              </entry>
              <entry>
                <para>hcall-int-exploitation</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_int_set_source_config" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_set_source_config" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x3AC</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the OS enabled XIVE exploitation</para>
              </entry>
              <entry>
                <para>hcall-int-exploitation</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_int_get_source_config" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_get_source_config" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x3B0</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the OS enabled XIVE exploitation</para>
              </entry>
              <entry>
                <para>hcall-int-exploitation</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_int_get_queue_info" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_get_queue_info" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x3B4</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the OS enabled XIVE exploitation</para>
              </entry>
              <entry>
                <para>hcall-int-exploitation</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_int_set_queue_config" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_set_queue_config" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x3B8</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the OS enabled XIVE exploitation</para>
              </entry>
              <entry>
                <para>hcall-int-exploitation</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_int_get_queue_config" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_get_queue_config" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x3BC</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the OS enabled XIVE exploitation</para>
              </entry>
              <entry>
                <para>hcall-int-exploitation</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_int_set_os_reporting_line" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_set_os_reporting_line" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x3C0</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the OS enabled XIVE exploitation</para>
              </entry>
              <entry>
                <para>hcall-int-exploitation</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_int_get_os_reporting_line" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_get_os_reporting_line" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x3C4</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the OS enabled XIVE exploitation</para>
              </entry>
              <entry>
                <para>hcall-int-exploitation</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_int_esb" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_esb" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x3C8</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the OS enabled XIVE exploitation</para>
              </entry>
              <entry>
                <para>hcall-int-exploitation</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_int_sync" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_sync" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x3CC</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the OS enabled XIVE exploitation</para>
              </entry>
              <entry>
                <para>hcall-int-exploitation</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <xref linkend="sec_int_reset" xrefstyle="select: title nopage" /> / <xref linkend="sec_int_reset" xrefstyle="select: labelnumber nopage" />
                </para>
              </entry>
              <entry>
                <para>0x3D0</para>
              </entry>
              <entry>
                <para>Normal</para>
              </entry>
              <entry>
                <para>If the OS enabled XIVE exploitation</para>
              </entry>
              <entry>
                <para>hcall-int-exploitation</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>hcalls to support an Ultravisor</para>
              </entry>
              <entry>
                <para>0xEF00 - 0xEF80</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved for platform-dependent hcall()s /
                <xref linkend="dbdoclet.50569383_58396" xrefstyle="select: label nopage"  /></para>
              </entry>
              <entry>
                <para>0xF000 - 0xFFFC</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>ILLEGAL</para>
              </entry>
              <entry>
                <para>Any token value having a one in either of the low order
                two bits</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>0x380 - 0xEEFF and 0x10000 - 0xFFFFFFFF-<?linebreak?>FFFFFFFC: RTAS
                implementations may assigns values in these ranges to their own
                internal interfaces, as long as they are prepared for the
                growth of architected functions into this range.</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para><emphasis  role="bold">Firmware Implementation Note:</emphasis> The assignment of function tokens is
      designed such that a single mask operation can validate that the value is
      within the range of a reasonable size branch table. Entries within the
      branch table can handle unimplemented code points.</para>
      <para>The hypervisor routines are optimized for execution speed. In some
      rare cases, locks are taken, and specific hardware designs require short
      wait loops. However, if a needed resource is truly busy, or processing is
      required by an agent, the hypervisor returns to the caller, either to
      have the function retried or continued at a later time. The Performance
      Class establishes specific performance requirements against each specific
      hcall() function as defined below.</para>
      <para>Hypervisor Call Performance Classes:</para>
      <para>Critical Must make continuous forward progress, encountering any
      busy resource must cause the function to back out and return with a
      &#8220;hardware busy&#8221; return code. When subsequently called, the
      operation begins again. Short loops for larwx and stwcx to acquire an
      apparently unheld lock are allowed. These functions may not include wait
      loops for slow hardware access.</para>
      <para>Normal Similar to critical, however, wait loops for slow hardware
      access are allowed. These functions may not include wait loops for an
      agent such as an external micro-processor or message transmission
      device.</para>
      <para>Continued This class of functions is expected to serialize on the
      use of external agents. If the external agent is busy the function
      returns &#8220;hardware busy&#8221;. If the interface to the external
      agent is not busy, the interface is marked busy and used to start the
      function. The function returns one of the &#8220;function in
      progress&#8221; return codes. Later, the caller may check on the
      completion of the function by issuing the &#8220;check&#8221; Hcall
      function with the &#8220;function in progress&#8221; parameter code. If
      the function completed properly, the hypervisor maintains no status and
      the &#8220;check&#8221; Hcall returns success. If the operation is still
      in process, the same &#8220;function in progress&#8221; code is returned.
      If the function completed in error, the completion error code is
      returned. The hypervisor maintains room for at least one outstanding
      error status per external agent interface per processor. If there is no
      room to record the error status, the hypervisor returns &#8220;hardware
      busy&#8221; and does not start the function.</para>
      <para>Terminal This class of functions is used to manage a partition when
      the OS is not in regular operation. These events include postmortems and
      extensive recoveries.</para>
      <para>The hypervisor performance classes are ordered in decreasing
      restriction.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_hyp_call_int"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The caller must perform properly
              given that the hypervisor meets the performance class specified.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_hyp_call_int"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The hypervisor implementation
              must meet the specified performance class or higher.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_hyp_call_int"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> Platform hardware designs must
              take the allowable performance classes into account when choosing the
              hardware access technology for the various facilities.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_hyp_call_int"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The hypervisor must have the
              capability to receive and handle the hypervisor call interrupts
              simultaneously on multiple processors in the same or different partitions
              up to the number of processors in the system.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_hyp_call_int"
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The hypervisor must check the
              state of the MSR register bits that are not set to a specific value by
              the processor hardware during the invoking interrupt per
              <xref linkend="dbdoclet.50569344_29923" />.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

      <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_29923">
        <title>MSR State on Entrance to Hypervisor</title>
        <?dbhtml table-width="75%" ?><?dbfo table-width="75%" ?>
        <tgroup cols="3">
          <colspec colname="c1" colwidth="33*" align="center" />
          <colspec colname="c2" colwidth="33*" align="center" />
          <colspec colname="c3" colwidth="33*" align="center" />
          <thead valign="middle">
            <row>
              <entry>
                <para>
                  <emphasis role="bold">MSR Bit</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Required State</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Error-Code</emphasis>
                </para>
              </entry>
            </row>
          </thead>
          <tbody valign="middle">
            <row>
              <entry>
                <para>HV - Hypervisor</para>
              </entry>
              <entry>
                <para>1</para>
              </entry>
              <entry>
                <para>None</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Bits 2,4:46, 57, and 60 Reserved</para>
              </entry>
              <entry>
                <para>Set to 0 by Hardware</para>
              </entry>
              <entry>
                <para>None</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>ILE - Interrupt Little Endian</para>
              </entry>
              <entry>
                <para>As Last set by the hypervisor</para>
              </entry>
              <entry>
                <para>None</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>ME - Machine check Enable</para>
              </entry>
              <entry>
                <para>As last set by the hypervisor</para>
              </entry>
              <entry>
                <para>None</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>LE Little-Endian Mode</para>
              </entry>
              <entry>
                <para>0 forced by ILE</para>
              </entry>
              <entry>
                <para>None</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_hyp_call_int"
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The Hcall() flags field must
              meet the definition in:
              <xref linkend="dbdoclet.50569344_11209" />; the hypervisor may safely
              ignore flag field values not explicitly defined by the specific hcall()
              semantic.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_hyp_call_int"
          xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must ensure that
              flag field values not defined for a specific hcall() do not compromise
              partitioning integrity.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_hyp_call_int"
          xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> Implementations that normally
              choose to ignore invalid flag field values must provide a &#8220;debug
              mode&#8221; that does check for invalid flag field values and returns
              H_Parameter when any are found.</para>
              <para>
              <emphasis role="bold">Architecture Note:</emphasis> The method for invocation of a
              platform&#8217;s &#8220;debug mode&#8221; is beyond the scope of this
              architecture.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

      <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_11209">
        <title>Page Frame Table Access flags field
        definition</title>
        <tgroup cols="8">
          <colspec colname="c1" colwidth="8*" align="center" />
          <colspec colname="c2" colwidth="17*" align="center" />
          <colspec colname="c3" colwidth="8*" align="center" />
          <colspec colname="c4" colwidth="17*" align="center" />
          <colspec colname="c5" colwidth="8*" align="center" />
          <colspec colname="c6" colwidth="17*" align="center" />
          <colspec colname="c7" colwidth="8*" align="center" />
          <colspec colname="c8" colwidth="17*" align="center" />
          <thead valign="middle">
            <row>
              <entry>
                <para>
                  <emphasis role="bold">Bit</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Function</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Bit</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Function</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Bit</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Function</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Bit</emphasis>
                </para>
              </entry>
              <entry>
                <para>
                  <emphasis role="bold">Function</emphasis>
                </para>
              </entry>
            </row>
          </thead>
          <tbody valign="middle">
            <row>
              <entry morerows="11">
                <para>0-15</para>
              </entry>
              <entry morerows="11">
                <para>NUMA CEC Cookie</para>
              </entry>
              <entry morerows="3">
                <para>16-23</para>
              </entry>
              <entry morerows="3">
                <para>Subfunction Codes</para>
              </entry>
              <entry>
                <para>32</para>
              </entry>
              <entry>
                <para>AVPN</para>
              </entry>
              <entry>
                <para>48</para>
              </entry>
              <entry>
                <para>Zero Page</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>33</para>
              </entry>
              <entry>
                <para>andcond</para>
              </entry>
              <entry>
                <para>49</para>
              </entry>
              <entry>
                <para>Copy Page</para>
              </entry>
            </row>
            <row>
              <entry morerows="1">
                <para>34-39</para>
              </entry>
              <entry morerows="1">
                <para>Reserved</para>
              </entry>
              <entry>
                <para>50-54</para>
              </entry>
              <entry>
                <para>key0-key4<footnote xml:id="pgfId-1194306">
                  <para>Bits 50-54 (key0 - key4) shall be treated as reserved
                  on platforms that either do not contain an
                  <emphasis role="bold"><literal>&#8220;ibm,processor-storage-keys&#8221;</literal></emphasis> property,
                  or contain an
                  <emphasis role="bold"><literal>&#8220;ibm,processor-storage-keys&#8221;</literal></emphasis> property
                  with the value of zero in both cells.</para>
                </footnote></para>
              </entry>
            </row>
            <row>
              <entry>
                <para>55</para>
              </entry>
              <entry>
                <para>pp0<footnote xml:id="pgfId-1195365">
                  <para>Bit 55 (pp0) shall be treated as reserved on platforms
                  that do not have the &#8220;Support for the &#8220;110&#8221;
                  value of the Page Protection (PP) bits&#8221; bit set to a
                  value of 1 in the
                  <emphasis role="bold"><literal>&#8220;ibm,pa-features&#8221;</literal></emphasis> property.</para>
                </footnote></para>
              </entry>
            </row>
            <row>
              <entry>
                <para>24</para>
              </entry>
              <entry>
                <para>Exact</para>
              </entry>
              <entry>
                <para>40</para>
              </entry>
              <entry>
                <para>I-Cache-Invalidate</para>
              </entry>
              <entry>
                <para>56</para>
              </entry>
              <entry>
                <para>Compression</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>25</para>
              </entry>
              <entry>
                <para>R-XLATE</para>
              </entry>
              <entry>
                <para>41</para>
              </entry>
              <entry>
                <para>I-Cache-Synchronize</para>
              </entry>
              <entry>
                <para>57</para>
              </entry>
              <entry>
                <para>Checksum</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>26</para>
              </entry>
              <entry>
                <para>READ-4</para>
              </entry>
              <entry>
                <para>42</para>
              </entry>
              <entry>
                <para>CC (Coalesce Candidate)</para>
              </entry>
              <entry morerows="2">
                <para>58-60</para>
              </entry>
              <entry morerows="2">
                <para>Reserved</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>27</para>
              </entry>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry morerows="3">
                <para>43-46</para>
              </entry>
              <entry morerows="3">
                <para>MUI Options<footnote>
                  <para>Bits 43-46 (MUI Options) detail is provided in
                  <xref linkend="table_mui_opt_flags_pft" />
                  in <xref linkend="sec_mui_opt" />.</para>
                </footnote></para>
              </entry>
            </row>
            <row>
              <entry morerows="3">
                <para>28-31</para>
              </entry>
              <entry morerows="3">
                <para>CMO Option Flags</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>61</para>
              </entry>
              <entry>
                <para>N</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>62</para>
              </entry>
              <entry>
                <para>pp1</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>47</para>
              </entry>
              <entry>
                <para>Reserved</para>
              </entry>
              <entry>
                <para>63</para>
              </entry>
              <entry>
                <para>pp2</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_hyp_call_int"
          xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The caller of Hcall must be in
              privileged mode (MSR<subscript>PR</subscript> = 0) or the hypervisor immediately returns an
              H_Privilege return code. See
              <xref linkend="dbdoclet.50569344_38816" /> for this and other architected
              return codes.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_hyp_call_int"
          xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis> The caller of hcall() must be
              prepared for a return code of H_Hardware from all functions.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry xml:id="dbdoclet.50569344_62943">
          <term><emphasis role="bold">R1-<xref linkend="sec_hyp_call_int"
          xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the LPAR option:</emphasis>
              In order for the platform to return H_Hardware, the error must not have resulted in an
              undetectable state/data corruption nor will continued operation propagate
              an undetectable state/data corruption as a result of the original
              error.</para>
              <para><emphasis role="bold">Notes:</emphasis>
              <orderedlist>
                <listitem>
                    <para>A detectable corruption, when accessed, results in either a
                    H_Hardware return code, machine check or check stop per platform
                    policy.</para>
                </listitem>

                <listitem>
                    <para>Among other implications of Requirement
                    <xref linkend="dbdoclet.50569344_62943" /> are: the effective state of the
                    partition appears to not change due to the failed hcall() -- (any partial
                    changes to persistent state/data are backed out); and the recovery of
                    platform resources that held lost state/data does not hide the state/data
                    loss to subsequent users of that state/data.</para>
                </listitem>

                <listitem>
                    <para>The operating system is not expected to log a serviceable event
                    due to an H_Hardware return code from an hcall(), and treats the hcall()
                    as failing due to nonspecific hardware reasons. Any logging of a
                    serviceable event in response to the underlying cause is handled by
                    separate platform initiated operations.</para>
                </listitem>
              </orderedlist>
              </para>
            </listitem>
       	</varlistentry>
      </variablelist>

      <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_38816">
        <title>Hypervisor Call Return Code Table</title>
        <?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
        <tgroup cols="2">
          <colspec colname="c1" colwidth="30*" align="center" />
          <colspec colname="c2" colwidth="70*" />
          <thead valign="middle">
            <row>
              <entry>
                <para>
                  <emphasis role="bold">Hypervisor Call Return Code Values
                  (R3)</emphasis>
                </para>
              </entry>
              <entry align="center">
                <para>
                  <emphasis role="bold">Meaning</emphasis>
                </para>
              </entry>
            </row>
          </thead>
          <tbody valign="middle">
            <row>
              <entry>
                <para>0x0100000 - 0x0FFFFFFF</para>
              </entry>
              <entry>
                <para>Function in Progress</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>9905</para>
              </entry>
              <entry>
                <para>H_LongBusyOrder100sec - Similar to LongBusyOrder1msec,
                but the hint is 100 second wait this time.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>9904</para>
              </entry>
              <entry>
                <para>H_LongBusyOrder10sec - Similar to LongBusyOrder1msec, but
                the hint is 10 second wait this time.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>9903</para>
              </entry>
              <entry>
                <para>H_LongBusyOrder1Sec - Similar to LongBusyOrder1msec, but
                the hint is 1 second wait this time.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>9902</para>
              </entry>
              <entry>
                <para>H_LongBusyOrder100mSec - Similar to LongBusyOrder1msec,
                but the hint is 100mSec wait this time.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>9901</para>
              </entry>
              <entry>
                <para>H_LongBusyOrder10mSec - Similar to LongBusyOrder1msec,
                but the hint is 10mSec wait this time.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>9900</para>
              </entry>
              <entry>
                <para>H_LongBusyOrder1msec - This return code is identical to
                H_Busy, but with the added bonus of a hint to the partition OS.
                If the partition OS can delay for 1 millisecond, the hcall will
                likely succeed on a new hcall with no further busy return
                codes. If the partition OS cannot handle a delay, they are
                certainly free to immediately turn around and try again.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>18</para>
              </entry>
              <entry>
                <para>H_CONTINUE</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>17</para>
              </entry>
              <entry>
                <para>H_PENDING</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>16</para>
              </entry>
              <entry>
                <para>H_PARTIAL_STORE</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>15</para>
              </entry>
              <entry>
                <para>H_PAGE_REGISTERED</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>14</para>
              </entry>
              <entry>
                <para>H_IN_PROGRESS</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>13</para>
              </entry>
              <entry>
                <para>Sensor value &gt;= Critical high</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>12</para>
              </entry>
              <entry>
                <para>Sensor value &gt;= Warning high</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>11</para>
              </entry>
              <entry>
                <para>Sensor value normal</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>10</para>
              </entry>
              <entry>
                <para>Sensor value &lt;= Warning low</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>9</para>
              </entry>
              <entry>
                <para>Sensor value &lt;= Critical low</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>5</para>
              </entry>
              <entry>
                <para>H_PARTIAL (The request completed only partially
                successful. Parameters were valid but some specific hcall
                function condition prevented fully completing the architected
                function, see the specific hcall definition for possible
                reasons.)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>4</para>
              </entry>
              <entry>
                <para>H_Constrained (The request called for resources in excess
                of the maximum allowed. The resultant allocation was
                constrained to maximum allowed)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>3</para>
              </entry>
              <entry>
                <para>H_NOT_AVAILABLE</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>2</para>
              </entry>
              <entry>
                <para>H_Closed (virtual I/O connection is closed)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>1</para>
              </entry>
              <entry>
                <para>H_Busy</para>
                <para>Hardware Busy -- Retry Later</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>0</para>
              </entry>
              <entry>
                <para>H_Success</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-1</para>
              </entry>
              <entry>
                <para>H_Hardware (Error)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-2</para>
              </entry>
              <entry>
                <para>H_Function (Not Supported)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-3</para>
              </entry>
              <entry>
                <para>H_Privilege (Caller not in privileged mode).</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-4</para>
              </entry>
              <entry>
                <para>H_Parameter (Outside Valid Range for Partition or
                conflicting)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-5</para>
              </entry>
              <entry>
                <para>bad_mode (Illegal MSR value)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-6</para>
              </entry>
              <entry>
                <para>H_PTEG_FULL (The requested pteg was full)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-7</para>
              </entry>
              <entry>
                <para>H_Not_Found (The requested entity was not found)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-8</para>
              </entry>
              <entry>
                <para>H_RESERVED_DABR (The requested address is reserved by the
                hypervisor on this processor)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-9</para>
              </entry>
              <entry>
                <para>H_NOMEM</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-10</para>
              </entry>
              <entry>
                <para>H_AUTHORITY (The caller did not have authority to perform
                the function)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-11</para>
              </entry>
              <entry>
                <para>H_Permission (The mapping specified by the request does
                not allow for the requested transfer)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-12</para>
              </entry>
              <entry>
                <para>H_Dropped (One or more packets could not be delivered to
                their requested destinations)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-13</para>
              </entry>
              <entry>
                <para>H_S_Parm (The source parameter is illegal)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-14</para>
              </entry>
              <entry>
                <para>H_D_Parm (The destination parameter is illegal)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-15</para>
              </entry>
              <entry>
                <para>H_R_Parm (The remote TCE mapping is illegal)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-16</para>
              </entry>
              <entry>
                <para>H_Resource (One or more required resources are in
                use)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-17</para>
              </entry>
              <entry>
                <para>H_ADAPTER_PARM (invalid adapter)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-18</para>
              </entry>
              <entry>
                <para>H_RH_PARM (resource not valid or logical partition
                conflicting)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-19</para>
              </entry>
              <entry>
                <para>H_RCQ_PARM (RCQ not valid or logical partition
                conflicting)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-20</para>
              </entry>
              <entry>
                <para>H_SCQ_PARM (SCQ not valid or logical partition
                conflicting)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-21</para>
              </entry>
              <entry>
                <para>H_EQ_PARM (EQ not valid or logical partition
                conflicting)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-22</para>
              </entry>
              <entry>
                <para>H_RT_PARM (invalid resource type)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-23</para>
              </entry>
              <entry>
                <para>H_ST_PARM (invalid service type)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-24</para>
              </entry>
              <entry>
                <para>H_SIGT_PARM (invalid signalling type)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-25</para>
              </entry>
              <entry>
                <para>H_TOKEN_PARM (invalid token)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-27</para>
              </entry>
              <entry>
                <para>H_MLENGTH_PARM (invalid memory length)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-28</para>
              </entry>
              <entry>
                <para>H_MEM_PARM (invalid memory I/O virtual address)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-29</para>
              </entry>
              <entry>
                <para>H_MEM_ACCESS_PARM (invalid memory access control)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-30</para>
              </entry>
              <entry>
                <para>H_ATTR_PARM (invalid attribute value)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-31</para>
              </entry>
              <entry>
                <para>H_PORT_PARM (invalid port number)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-32</para>
              </entry>
              <entry>
                <para>H_MCG_PARM (invalid multicast group)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-33</para>
              </entry>
              <entry>
                <para>H_VL_PARM (invalid virtual lane)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-34</para>
              </entry>
              <entry>
                <para>H_TSIZE_PARM (invalid trace size)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-35</para>
              </entry>
              <entry>
                <para>H_TRACE_PARM (invalid trace buffer)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-36</para>
              </entry>
              <entry>
                <para>H_TRACE_PARM (invalid trace buffer)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-37</para>
              </entry>
              <entry>
                <para>H_MASK_PARM (invalid mask value)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-38</para>
              </entry>
              <entry>
                <para>H_MCG_FULL (multicast attachments exceeded)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-39</para>
              </entry>
              <entry>
                <para>H_ALIAS_EXIST (alias QP already defined)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-40</para>
              </entry>
              <entry>
                <para>H_P_COUNTER (invalid counter specification)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-41</para>
              </entry>
              <entry>
                <para>H_TABLE_FULL (resource page table full)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-42</para>
              </entry>
              <entry>
                <para>H_ALT_TABLE (alternate table already exists / alternate
                page table not available)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-43</para>
              </entry>
              <entry>
                <para>H_MR_CONDITION (invalid memory region condition)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-44</para>
              </entry>
              <entry>
                <para>H_NOT_ENOUGH_RESOURCES (insufficient resources)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-45</para>
              </entry>
              <entry>
                <para>H_R_STATE (invalid resource state condition or sequencing
                error)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-46</para>
              </entry>
              <entry>
                <para>H_RESCINDED</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-54</para>
              </entry>
              <entry>
                <para>H_Aborted</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-55</para>
              </entry>
              <entry>
                <para>H_P2</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-56</para>
              </entry>
              <entry>
                <para>H_P3</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-57</para>
              </entry>
              <entry>
                <para>H_P4</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-58</para>
              </entry>
              <entry>
                <para>H_P5</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-59</para>
              </entry>
              <entry>
                <para>H_P6</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-60</para>
              </entry>
              <entry>
                <para>H_P7</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-61</para>
              </entry>
              <entry>
                <para>H_P8</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-62</para>
              </entry>
              <entry>
                <para>H_P9</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-63</para>
              </entry>
              <entry>
                <para>H_NOOP</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-64</para>
              </entry>
              <entry>
                <para>H_TOO_BIG</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-65</para>
              </entry>
              <entry>
                <para>Reserved</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-66</para>
              </entry>
              <entry>
                <para>Reserved</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-67</para>
              </entry>
              <entry>
                <para>H_UNSUPPORTED (Parameter value outside of the range
                supported by this implementation)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-68</para>
              </entry>
              <entry>
                <para>H_OVERLAP (unsupported overlap among passed buffer
                areas)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-69</para>
              </entry>
              <entry>
                <para>H_INTERRUPT (Interrupt specification is invalid)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-70</para>
              </entry>
              <entry>
                <para>H_BAD_DATA (uncorrectable data error)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-71</para>
              </entry>
              <entry>
                <para>H_NOT_ACTIVE (Not associated with an active
                operation)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-72</para>
              </entry>
              <entry>
                <para>H_SG_LIST (A scatter/gather list element is
                invalid)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-73</para>
              </entry>
              <entry>
                <para>H_OP_MODE (There is a conflict between</para>
                <para>the subcommand and the requested operation
                notification)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-74</para>
              </entry>
              <entry>
                <para>H_COP_HW (co-processor hardware error)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-75</para>
              </entry>
              <entry>
                <para>H_STATE (invalid state)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-76</para>
              </entry>
              <entry>
                <para>H_RESERVED (a reserved value was specified)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-77</para>
              </entry>
              <entry>
                <para>H_IN_USE (a specified resource is already in use)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-78 : -255</para>
              </entry>
              <entry>
                <para>Reserved</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>-256 -- -511</para>
              </entry>
              <entry>
                <para>H_UNSUPPORTED_FLAG (An unsupported binary flag bit was
                specified. The returned value is -256 - the bit position of the
                unsupported flag bit [high order flag bit is 0 etc.])</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
    </section>

    <section>
      <title>Hypervisor Call Functions</title>
      <para />

      <section xml:id="sec_pft_access">
        <title>Page Frame Table Access</title>
        <para>All hypervisor Page Frame Table (PFT) access routines are called
        using 64 bit linkage conventions and apply to all page sizes that the
        platform supports as specified by the
        <emphasis role="bold"><literal>&#8220;ibm,processor-page-sizes&#8221;</literal></emphasis> property. (See
        <xref linkend="LoPAR.DeviceTree" /> for more details.)
        The Page actual size is encoded in the PFT entry
        per the <xref linkend="dbdoclet.50569387_99718" /> architecture Book IIIs along with the
        segment base page size per the <xref linkend="dbdoclet.50569387_99718" />
        Book IVa.
        The hypervisor PFT
        access functions carefully update a given Page Table Entry (PTE) with at
        least 64 bit store operations since an invalid update sequence could
        result in machine checks. To guard against multiple conflicting
        allocations of a PTE that could result in a check stop condition, the
        hypervisor PTE allocation routine (H_ENTER) reserves the first two (high
        order) software PTE bits for use as PTE locks while the low order two
        software PTE bits are reserved for OS use (not used by firmware). If a
        firmware PTE bit is on, the OS is to assume that the PTE is in use, just
        as if the V bit were on. The hypervisor PFT access routines often execute
        the tlbie instruction, on certain platforms, this instruction may only be
        executed by one processor in a partition at a time, the hypervisor uses
        locks to assure this. The tlbie instruction flushes a specific translate
        lookaside buffer (TLB) entry from all processors participating in the
        protocol. All the processors participating in the tlbie protocol are
        defined as a translation domain. All processors of a given partition that
        are in a given translation domain share the same hardware PFT. Book III
        of the PA specifies the codes sequences needed to safely access the PFT,
        in its chapter titled &#8220;Storage Control Instructions and Table
        Updates&#8221;. These code sequences are part of this specification by
        reference. The hypervisor PFT access routines are in the critical
        performance path of the machine, therefore, extraordinary care must be
        given to their performance, including machine dependent coding, minimal
        run time checking, and code path length optimization. For performance
        reasons, all parameter linkage is through registers, and no indirect
        parameter linkage is allowed. This requires special glue code on the part
        of the caller to pick up the return parameters. The hypervisor PFT access
        routines modify the calling processor&#8217;s partition PFT on the
        calling node. On NUMA systems, if an LPAR partition spans multiple
        Central Electronics Complexes (CECs), the partition&#8217;s processors
        may be in separate translation domains. Each platform translation domain
        has a separate PFT. Therefore, the partition&#8217;s OS must modify each
        PFT individually. This is done either by making hcall() accesses
        specifying the NUMA CEC Cookie (which identifies the translation domain)
        in the high order 16 bits of the flags parameter (H_ENTER and H_READ
        only) or by issuing the hcall() from a processor within the translation
        domain as identified by the processor&#8217;s NUMA CEC Cookie field of
        the
        <emphasis role="bold"><literal>&#8220;ibm,pft-size&#8221;</literal></emphasis> property.</para>
        <para>The PFT is preallocated based upon the value of the
        partition&#8217;s PFT_size configuration variable. This configuration
        variable is initialized to 4 PTEs per node local page frame and 2 PTEs
        per remote node page frame. The size of the PFT per node is communicated
        to the partition&#8217;s OS image via the
        <emphasis role="bold"><literal>&#8220;ibm,pft-size&#8221;</literal></emphasis> property of the
        node.</para>
        <para>The value of the configuration variable
        <emphasis>PFT_size</emphasis> consists of two comma separated integers,
        the first is the number of hardware PFT entries to allocate per CEC local
        page, and the second is the number of hardware PFT entries to allocate
        per remote CEC page (if NUMA configured). These allocations are made at
        partition boot time based upon the initial partition memory allocation,
        based upon specific situations (such as low page table usage or future
        need for dynamic memory addition) the OS may wish to override the
        platform default values.</para>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_pft_access"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must allocate the
                partition&#8217;s page frame table. The size of this table is determined
                by the PFT_size configuration variable in the OS image&#8217;s
                &#8220;common&#8221; NVRAM partition.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_pft_access"
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must provide the
                <emphasis role="bold"><literal>&#8220;ibm,pft-size&#8221;</literal></emphasis> property in the processor
                nodes of the device tree (children of type
                <emphasis role="bold"><literal>cpu</literal></emphasis> of the
                <emphasis role="bold"><literal>/cpus</literal></emphasis> node).</para>
                <para>Register Linkage (For hcall() tokens 0x04 - 0x18)</para>
              </listitem>
         	</varlistentry>
        </variablelist>

        <itemizedlist>
          <listitem><para>On Call:</para>
            <itemizedlist>
              <listitem><para>R3 function call token</para></listitem>
              <listitem><para>R4 flags (see <xref linkend="dbdoclet.50569344_11209" />)</para></listitem>
              <listitem><para>R5 Page Table Entry Index (PTEX)</para></listitem>
              <listitem><para>R6 Page Table Entry High word (PTEH) (on H_ENTER only)</para></listitem>
              <listitem><para>R7 Page Table Entry Low word (PTEL) (on H_ENTER only)</para></listitem>
            </itemizedlist>
          </listitem>
          <listitem><para>On Return:</para>
            <itemizedlist>
              <listitem><para>R3 Status Word</para></listitem>
              <listitem><para>R4 chosen PTEX (from H_ENTER) / High Order Half of old PTE</para></listitem>
              <listitem><para>R5 Low Order Half of old PTE</para></listitem>
              <listitem><para>R6</para></listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>

        <para>Semantics checks for all hypervisor PTE access routines:</para>

        <itemizedlist>
          <listitem>
            <para>Hypervisor checks that the caller was in privileged mode or
            H_Privilege return code.</para>
          </listitem>

          <listitem>
            <para>On NUMA platforms for the H_ENTER and H_READ calls only, the
            hypervisor checks that the NUMA CEC Cookie is within the range of values
            assigned to the partition else return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>Hypervisor checks that the PTEX is zero or greater and less than
            the partition maximum, else H_Parameter return code.</para>
          </listitem>

          <listitem>
            <para>Hypervisor checks the logical address contained in any PTE to be
            entered into the PFT to insure that it is valid and then translates the
            logical address into the assigned physical address.</para>
          </listitem>

          <listitem>
            <para>When hypervisor returns the contents of a PTE, the contents of
            the RPN are usually architecturally undefined. It is expected that
            hypervisor implementations leave the contents of this field as it was
            read from the PTE since it cannot be used by the OS to directly access
            real memory. The exception to this rule is when the R-XLATE flag is
            specified to the H_READ hcall(), then the RPN in the PTE is reverse
            translated into the LPN prior to return.</para>
          </listitem>

          <listitem>
            <para>Logical addressing:</para>
            <para>LPAR adds another level of virtual address translation managed by
            the hypervisor. The OS is never allowed to use the physical address of
            its memory this includes System Memory, MMIO space, NVRAM etc. The OS
            sees System Memory as N regions of contiguous logical memory. Each
            logical region is mapped by the hypervisor into a corresponding block of
            contiguous physical memory on a specific node. All regions on a specific
            system are the same size though different systems with different amount
            of memory may have different region sizes since they are the quantum of
            memory allocation to partitions. That is, partitions are granted memory
            in region size chunks and if a partition&#8217;s OS gives up memory, it
            is in units of a full region. On NUMA platforms, groups of regions may be
            associated with groups of processors forming logical CECs for allocation
            and migration purposes.</para>
            <para>Logical addresses are divided into two fields, the logical region
            identifier and the region offset. The region offset is the low order bits
            needed to represent the region size. The logical region identifier are
            the remaining high order bits.</para>
          </listitem>

          <listitem>
            <para>Logical addresses start at zero. When control is initially passed
            to the OS from the platform, the first region is the single RMA. The
            first region has logical region identifier of zero. This first region is
            specified by the first address - length pair of the
            <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property of the
            <emphasis role="bold"><literal>/memory</literal></emphasis> node of the OF device tree. Subsequent
            regions each have their own address - length pair. At initial program
            load time, the logical region identifiers are sequential starting at zero
            but over time, with dynamic memory reconfiguration, holes may appear in
            the partition&#8217;s address space.</para>
          </listitem>

          <listitem>
            <para>Logical to physical translation: This translation is based upon a
            simple indexed table per partition of the physical addresses associated
            with the start of each region (in logical region identifier order). At
            least two special values are recognized:</para>

            <orderedlist>
              <listitem>
                <para>The invalid value for those regions that do not have a physical
                mapping (so that there can be holes in the logical address map for
                various reasons such as memory expansion).</para>
              </listitem>

              <listitem>
                <para>The I/O region value, that calls for further checking against
                partition I/O address range allocations.</para>
              </listitem>

            </orderedlist>
          </listitem>

          <listitem>
            <para>The logical region identifier is checked for being less than the
            maximum size, and then used to index the logical to physical translation
            table.</para>
          </listitem>

          <listitem>
            <para>If the physical region identifier is valid (certain values are
            reserved say 0 and all F&#8217;s) then it replaces the logical region
            identifier in the PTE and the PTE access function continues.</para>
          </listitem>

          <listitem>
            <para>If the physical region identifier is the I/O region, then proceed
            to the I/O translation algorithm (implementation dependent based upon
            platform characteristics).</para>
          </listitem>

          <listitem>
            <para>If the physical region identifier is invalid, return
            H_Parameter</para>
          </listitem>
        </itemizedlist>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_pft_access"
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> The OS must make no assumptions
                about the logical to physical mapping other than the low order
                bits.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_pft_access"
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> Each logical region must have
                its own address - length pair in the
                <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property of the OF
                <emphasis role="bold"><literal>/memory</literal></emphasis> node.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_pft_access"
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> When control is initially passed
                to the OS from the platform, the first logical region (having logical
                region identifier 0) must be the region accessed when the OS operates
                with translate off.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_pft_access"
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> When control is initially passed
                to the OS from the platform, the size of the logical region must be equal
                to a real mode length size supported by the platform.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry xml:id="dbdoclet.50569344_81616">
            <term><emphasis role="bold">R1-<xref linkend="sec_pft_access"
            xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis>
                Each logical region must start and end on a boundary of the largest page size that the
                logical region supports (see
                <emphasis role="bold"><literal>&#8220;ibm,dynamic-memory&#8221;</literal></emphasis> and
                <emphasis role="bold"><literal>&#8220;ibm,lmb-page-sizes&#8221;</literal></emphasis> in
                <xref linkend="LoPAR.DeviceTree" /> as well as
                <xref linkend="dbdoclet.50569344_65610" /> for more details).</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_pft_access"
            xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> The pages that contain the
                platform&#8217;s per processor interrupt management areas or any other
                device marked
                <emphasis role="bold"><literal>&#8220;used-by-rtas&#8221;</literal></emphasis> must not be mapped into
                the partition virtual address space.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry xml:id="dbdoclet.50569344_65610">
            <term><emphasis role="bold">R1-<xref linkend="sec_pft_access"
            xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis>
                Each logical region must support all page sizes presented in the
                <emphasis role="bold"><literal>&#8220;ibm,processor-page-sizes&#8221;</literal></emphasis> property in
                <xref linkend="LoPAR.DeviceTree" /> that are less than or equal to the
                size of the logical region as specified by either the OF standard
                <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property of the logical
                region&#8217;s OF
                <emphasis role="bold"><literal>/memory</literal></emphasis> node, or the
                <emphasis role="bold"><literal>&#8220;ibm,lmb-size&#8221;</literal></emphasis> property of the logical
                region&#8217;s
                <emphasis role="bold"><literal>/ibm,dynamic-reconfiguration-memory</literal></emphasis> node in
                <xref linkend="LoPAR.DeviceTree" />.</para>

                <para><emphasis role="bold">Implementation Note:</emphasis> 32 bit versions of AIX only support 36 bit
                logical address memory spaces. Providing such a partition with a larger
                logical memory address space may cause OS failures.</para>

                <para><emphasis role="bold">Implementation Note:</emphasis> Requirement
                <xref linkend="dbdoclet.50569344_81616" /> may be met by ensuring that all
                logical regions start and end on a boundary of the largest page size
                supported by the platform.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

        <section xml:id="dbdoclet.50569344_80550">
          <title>H_REMOVE</title>
          <para>This hcall is for invalidating an entry in the page table. The PTEX
          identifies a specific page table entry. If the PFO option is implemented
          an optional flag causes the hypervisor to compress the page contents to
          one or more data blocks after invalidating the page table entry given
          that a compression coprocessor is available and the page is small enough
          to be synchronously compressed. If the compression coprocessor is busy,
          or the page is too large, the compression can be subsequently performed
          using the H_COP_OP hcall() see
          <xref linkend="dbdoclet.50569344_29950" />. If the page contents are
          compressed, then a checksum may be appended by setting the checksum flag
          - if the compression flag is not set the checksum flag is
          ignored.</para>

          <simplesect>
            <title>Syntax:</title>

            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_RESCINDED */
                       /* H_Function: The compression request is not authorized */
                       /* H_UNSUPPORTED_FLAG */
                       /* H_P3: The out parameter is invalid */
                       /* H_P4: The outlen parameter is invalid */
                       /* H_SG_LIST: A scatter/gather list element is invalid */
                       /* H_TOO_BIG: The specified page is too long for the output */
                       /*   buffer */
                       /* H_PARTIAL: The compression portion of the call was not */
                       /*   performed because the compressor was busy */
                       /* H_Constrained: The compression portion of the call was */
                       /*   not performed because the page was too large to be */
                       /*   compressed synchronously */
                       /* H_COP_HW: The compressor portion of the call experienced a */
                       /*   hardware error */
                       /* H_Busy: The hardware is busy user may call back later */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_REMOVE,
        uint64 flags,  /* see “Page Frame Table Access flags field definition‚” */
                       /*   in previous section */
        uint64 PTEX,   /* The index of the PTE to be removed */
        uint64 AVPN,   /* If the AVPN flag is valid else this parameter value is */
                       /*   unused the following two parameters are valid only if */
                       /*   the compression flag is on */
        uint64 out,    /* Output data block logical real address */
        int64 outlen   /* If non negative the length of the output data block, */
                       /*   if negative the length of the output data descriptor */
                       /*   list in bytes */
      );]]></programlisting>

          </simplesect>

          <simplesect>
            <title>Parameters:</title>
            <itemizedlist>
              <listitem>
                <para>flags: AVPN, andcond, and for the CMO option: CMO Option flags as
                defined in
                <xref linkend="dbdoclet.50569344_92498" /> and for the PFO option the
                compression and checksum flags.</para>
              </listitem>

              <listitem>
                <para>PTEX (index of the PTE in the page table to be used)</para>
              </listitem>

              <listitem>
                <para>AVPN: Optional &#8220;Abbreviated Virtual Page Number&#8221; --
                used as a check for the correct PTE</para>

                <itemizedlist>
                  <listitem>
                    <para>When the AVPN flag is set, the contents of the AVPN parameter are
                    compared to the first double word of the PTE (after bits 57-63 of the PTE
                    have been masked). Note, the low order 7 bits are undefined and should be
                    zero otherwise the likely result is a return code of H_Not_Found.</para>
                  </listitem>

                  <listitem>
                    <para>When the andcond flag is set, the contents of the AVPN parameter
                    are bit anded with the first double word of the PTE. If the result is
                    non-zero the return code is H_Not_Found.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>out: For the PFO option, the output data block logical real
                address when the compression flag bit is on.</para>
              </listitem>

              <listitem>
                <para>outlen: For the PFO option, the length of the compression data
                block or compression data block descriptor list when the compression flag
                bit is on.</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>
          <itemizedlist>
            <listitem>
              <para>Check that the PTEX accesses within the PFT else return
              H_Parameter</para>
            </listitem>

            <listitem>
              <para>If the AVPN flag is set, and the AVPN parameter bits 0-56 do not
              match that of the specified PTE then return H_Not_Found.</para>
            </listitem>

            <listitem>
              <para>If the andcond flag is set, the AVPN parameter is bit anded with
              the first double word of the specified PTE, if the result is non-zero,
              then return H_Not_Found.</para>
            </listitem>

            <listitem>
              <para>The hypervisor Synchronizes the PTE specified by the PTEX and
              returns its value</para>

              <itemizedlist>
                <listitem>
                  <para>Use the architected &#8220;Deleting a Page Table Entry&#8221;
                  sequence such that the first double word of the resultant PFT entry is
                  all 0s.</para>
                </listitem>

                <listitem>
                  <para>Use the proper tlbie instruction for the page size within a
                  critical section protected by the proper lock (per large page bit in the
                  specified PTE).</para>
                </listitem>

                <listitem>
                  <para>The synchronized value of the old PTE value ends up in R4 and R5
                  for return to the caller.</para>
                </listitem>

                <listitem>
                  <para>For the CMO option: set the page usage state per the CMO Option
                  flags field of the flags parameter as defined in
                  <xref linkend="dbdoclet.50569344_92498" />.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>For the PFO option: If the Compression flag is on:</para>

              <itemizedlist>
                <listitem>
                  <para>Check that the calling partition is authorized to use the
                  compression co-processor else return H_Function.</para>
                </listitem>

                <listitem>
                  <para>If the page is not &#8220;main store memory&#8221; then return
                  H_UNSUPPORTED_FLAG TBD (value - 312)</para>
                </listitem>

                <listitem>
                  <para>Check that the page size is &lt;= the compression value in
                  <emphasis role="bold"><literal>&#8220;ibm,max-sync-cop&#8221;</literal></emphasis> else return
                  H_Constrained.</para>
                </listitem>

                <listitem>
                  <para>Build CRB for compression of the page size indicated in the
                  PTE</para>
                </listitem>

                <listitem>
                  <para>If the checksum flag is on command that a checksum be
                  built</para>
                </listitem>

                <listitem>
                  <para>Verify that the &#8220;out&#8221; parameter represents a valid
                  logical real address within the caller&#8217;s partition else return
                  H_P3</para>
                </listitem>

                <listitem>
                  <para>If the &#8220;outlen&#8221; parameter is non-negative verify that
                  the logical real address of (out + outlen) is a valid logical real
                  address within the same 4K page as the &#8220;out&#8221; parameter else
                  return H_P4.</para>
                </listitem>

                <listitem>
                  <para>If the &#8220;outlen&#8221; parameter is negative:</para>

                  <itemizedlist>
                    <listitem>
                      <para>Verify that the absolute value of outlen meet all of the follow
                      else return H_P4:</para>

                      <itemizedlist>
                        <listitem>
                          <para>Is &lt;= the value of
                          <emphasis role="bold"><literal>&#8220;ibm,max-sg-len&#8221;</literal></emphasis></para>
                        </listitem>

                        <listitem>
                          <para>Is an even multiple of 16</para>
                        </listitem>

                        <listitem>
                          <para>That out + the absolute value of outlen represents a valid
                          logical real address within the same 4K page as the out parameter.</para>
                        </listitem>
                      </itemizedlist>
                    </listitem>

                    <listitem>
                      <para>Verify that each 16 byte scatter gather list entry meets all of
                      the following else return H_SG_LIST:</para>

                      <itemizedlist>
                        <listitem>
                          <para>Verify that the first 8 bytes represents a valid logical real
                          address within the caller&#8217;s partition.</para>
                        </listitem>

                        <listitem>
                          <para>Verify that the logical real address represented by the sum of
                          the first 8 bytes and the second 8 bytes is a valid logical real address
                          within the same 4K page as the first 8 bytes.</para>
                        </listitem>
                      </itemizedlist>
                    </listitem>
                  </itemizedlist>
                </listitem>

                <listitem>
                  <para>For the Shared Logical Resource Option if any of the memory
                  represented by the out/outlen parameters have been rescinded then return
                  H_RESCINDED.</para>
                </listitem>

                <listitem>
                  <para>Fill in the destination DDE list from the converted the
                  out/outlen parameters.</para>
                </listitem>

                <listitem>
                  <para>Issue icswx instruction to execute CRB</para>
                </listitem>

                <listitem>
                  <para>Check coprocessor busy - retry / return H_PARTIAL if
                  execution time expired / return H_COP_HW if compressor is broken</para>
                </listitem>

                <listitem>
                  <para>Wait for coprocessor to complete</para>
                </listitem>

                <listitem>
                  <para>If compressor hardware error return H_COP_HW</para>
                </listitem>

                <listitem>
                  <para>Check that the compressor had enough room to house the compressed
                  image else return H_TOO_BIG</para>
                </listitem>

                <listitem>
                  <para>Save compression block size in R6</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Return H_Success</para>
            </listitem>
          </itemizedlist>

          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_61580">
          <title>H_ENTER</title>
          <para>This hcall adds an entry into the page frame table. PTEH and PTEL
          contain the new entry. PTEX identifies either the page table entry group
          or the specific PTE where the entry is to be added, depending upon the
          setting of the Exact flag. If the Exact flag is off, the hypervisor
          selects the first free (invalid) PTE in the page table entry group. For
          pages with sizes less than or equal to 64 K, Flags further provide the
          option to zero the page, and provide two levels of programmed I-Cache
          coherence management before activating the page table mapping. This hcall
          returns the PTE index of the entered mapping. If the PFO option is
          implemented an optional compression flag causes the hypervisor to
          initialize the page from one or more compressed data blocks and
          optionally (checksum flag) check the end to end block data integrity
          prior to adding the entry to the page table. If the compression flag is
          not set the checksum flag is ignored.  If the Memory Usage Instrumentation
          (MUI) option is implemented,
          flags allow for initializing MUI state for the page when the translation is
          entered.</para>

          <simplesect>
            <title>Syntax:</title>

            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_RESCINDED */
                       /* H_TOO_BIG: The specified Input stream is too long */
                       /* H_Function: The compression request is not authorized */
                       /* H_Aborted: The specified input stream was too small to */
                       /*   fill the page */
                       /* H_BAD_DATA: The initialization data is corrupted */
                       /* H_P4: The in parameter is invalid */
                       /* H_P5: The inlen parameter is invalid */
                       /* H_SG_LIST: A Scatter/gather list element is invalid */
                       /* H_Busy: The hardware is busy user may call back later */
                       /* PTEX, PTEH, or PTEL parameters are invalid
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_ENTER,
        uint64 flags,  /* see “Page Frame Table Access flags field definition‚” */
                       /*   in previous section */
        int64 PTEX,    /* Index of the first PTE in the page table entry group to */
                       /*   be used */
        uint64 PTEH,   /* The high order 8 bytes of the page table entry */
        uint64 PTEL,   /* The low order 8 bytes of the page table entry */
        uint64 in,     /* For the PFO option input data block logical real address */
        int64 inlen    /* For the PFO option if non negative the length of the */
                       /*   input data block, if negative the length of the input */
                       /*   data descriptor list in bytes */
      );]]></programlisting>
          </simplesect>


          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>Flags</para>

                <itemizedlist>
                  <listitem>
                    <para>CEC Cookie</para>
                  </listitem>

                  <listitem>
                    <para>Zero Page: Zero the System Memory page in real mode before
                    placing its mapping into the PTE. This flag is ignored for memory mapped
                    I/O space pages; as an attempt to zero missing memory might result in a
                    machine check or worse. This function should use a processor dependent
                    algorithm optimized for maximum performance on the specific hardware.
                    This usually is a sequence of dcbz instructions. Setting this flag for a
                    page with a size larger than 64 K will result in return code of
                    H_TOO_BIG.</para>
                  </listitem>

                  <listitem>
                    <para>I-Cache-Invalidate: Issue an icbi etc. instruction sequence to
                    manage the I-Cache coherency of the cachable page. This flag is ignored
                    for memory mapped I/O pages. For use when the D-Cache is known to be
                    clean, before placing its mapping into the PTE. Setting this flag for a
                    page with a size larger than 64 K will result in return code of
                    H_TOO_BIG.</para>
                  </listitem>

                  <listitem>
                    <para>I-Cache-Synchronize: Issue dcbst and icbi, etc., instruction
                    sequence to manage the I-Cache coherency of the cachable page. This flag
                    is ignored for memory mapped I/O pages. For use when the D-Cache may
                    contain modified data, before placing its mapping into the PTE. Setting
                    this flag for a page with a size larger than 64 K will result in return
                    code of H_TOO_BIG.</para>
                  </listitem>

                  <listitem>
                    <para>Exact: Place the entry in the exact PTE specified by PTEX if it
                    is empty else return H_PTEG_FULL.</para>
                  </listitem>

                  <listitem>
                    <para>For the CMO option: CMO Option flags as defined in
                    <xref linkend="dbdoclet.50569344_92498" />.</para>
                  </listitem>

                  <listitem>
                    <para>For the MUI option: The HBA bits specify settings of implementation dependent PTE bits and
                    associated MUI array entries for the page who’s translation is being entered.</para>
                  </listitem>

                  <listitem>
                    <para>For the MUI option: The Affinity-Clear and Page-Age-Clear bits clear associated MUI array
                    entries for the page who’s translation is being entered.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>PTEX (index of the first PTE in the page table entry group to be
                used for the PTE insertion)</para>
              </listitem>

              <listitem>
                <para>PTEH -- the high order 8 bytes of the page table entry.</para>
              </listitem>

              <listitem>
                <para>PTEL -- the low order 8 bytes of the page table entry.</para>
              </listitem>
            </itemizedlist>

          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>The hypervisor checks that the logical page number is within the
                bounds of partition allocated memory resources, else returns
                H_Parameter.</para>

                <itemizedlist>
                  <listitem>
                    <para>If the Shared Logical Resource option is implemented and the
                    logical page number represents a page that has been rescinded by the
                    owner, return H_RESCINDED.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>The hypervisor checks that the address boundary matches the
                setting of the input PTE&#8217;s large page bits; else return
                H_Parameter.</para>
              </listitem>

              <listitem>
                <para>The hypervisor checks that the page size described by the setting
                of the input PTE&#8217;s page size bits is less than or equal to the
                largest page size supported by the logical region that is being mapped;
                else return H_Parameter.</para>
              </listitem>

              <listitem>
                <para>The hypervisor checks that the WIMG bits within the PTE are
                appropriate for the physical page number else H_Parameter return. (For
                System Memory pages WIMG=0010, or, 1110 if the SAO option is enabled, and
                for IO pages WIMG=01**.)</para>
              </listitem>

              <listitem>
                <para>For pages with sizes greater than 64 K, the hypervisor checks
                that the Zero Page, I-Cache-Invalidate, and I-Cache_Synchronize bits of
                the Flags parameter are not set; else return H_TOO_BIG.</para>
              </listitem>

              <listitem>
                <para>Force off RS mode reserved PTEL bits (1<footnote xml:id="pgfId-1193462">
                  <para>In addition, bits 52 and 53 are forced off on platforms that
                  either do not contain an
                  <emphasis role="bold"><literal>&#8220;ibm,processor-storage-keys&#8221;</literal></emphasis> property,
                  or contain an
                  <emphasis role="bold"><literal>&#8220;ibm,processor-storage-keys&#8221;</literal></emphasis> property
                  with the value of zero in both cells. Bit 0 is forced off on platforms
                  that do not have the &#8220;Support for the &#8220;110&#8221; value of
                  the Page Protection (PP) bits&#8221; bit set to a value of 1 in the
                  <emphasis role="bold"><literal>&#8220;ibm,pa-features&#8221;</literal></emphasis> property.</para>
                </footnote>) as well as hypervisor reserved software bits (57 and 58) in
                PTEH.</para>
              </listitem>

              <listitem>
                <para>If the Exact flag is off, set the low order 3 bits of the PTEX to
                zero (insures that the algorithm stays inside partition&#8217;s PFT and
                is faster than a check and error code response).</para>
              </listitem>

              <listitem>
                <para>If the Zero Page flag is set, use optimized routine to clear page
                (usually series of dcbz instructions).</para>
              </listitem>

              <listitem>
                <para>For the PFO option: if the compression flag is on then</para>

                <itemizedlist>
                  <listitem>
                    <para>Check that the calling partition is authorized to use the
                    compression co-processor else return H_Function.</para>
                  </listitem>

                  <listitem>
                    <para>If the page is not &#8220;main store memory&#8221; then return
                    H_UNSUPPORTED_FLAG.</para>
                  </listitem>

                  <listitem>
                    <para>Build CRB for decompression</para>
                  </listitem>

                  <listitem>
                    <para>If the checksum flag is on command that a checksum be
                    verified.</para>
                  </listitem>


                  <listitem>
                    <para>Validate the inlen/in parameters and build the source DDE</para>

                    <itemizedlist>
                      <listitem>
                        <para>Verify that the &#8220;in&#8221; parameter represents a valid
                        logical real address within the caller&#8217;s partition else return
                        H_P4</para>
                      </listitem>

                      <listitem>
                        <para>If the &#8220;inlen&#8221; parameter is non-negative verify that
                        the logical real address of (in + inlen) is a valid logical real address
                        within the same 4K page as the &#8220;in&#8221; parameter else return
                        H_P5.</para>
                      </listitem>

                      <listitem>
                        <para>If the &#8220;inlen&#8221; parameter is negative: Verify that the
                        absolute value of inlen meet all of the follow else return H_P5:</para>

                        <itemizedlist>
                          <listitem>
                            <para>Is &lt;= the value of
                            <emphasis role="bold"><literal>&#8220;ibm,max-sg-len&#8221;</literal></emphasis></para>
                          </listitem>

                          <listitem>
                            <para>Is an even multiple of 16</para>
                          </listitem>

                          <listitem>
                            <para>That in + the absolute value of inlen represents a valid logical
                            real address within the same 4K page as the in parameter.</para>
                          </listitem>
                        </itemizedlist>
                      </listitem>

                      <listitem>
                        <para>Verify that each 16 byte scatter gather list entry meets all of
                        the following else return H_SG_LIST:</para>

                        <itemizedlist>
                          <listitem>
                            <para>Verify that the first 8 bytes represents a valid logical real
                            address within the caller&#8217;s partition.</para>
                          </listitem>

                          <listitem>
                            <para>Verify that the logical real address represented by the sum of
                            the first 8 bytes and the second 8 bytes is a valid logical real address
                            within the same 4K page as the first 8 bytes.</para>
                          </listitem>
                        </itemizedlist>
                      </listitem>

                      <listitem>
                        <para>Verify that the sum of all the scatter gather length fields
                        (second 8 bytes of each 16 byte entry) is &lt;= the decompression value
                        in
                        <emphasis role="bold"><literal>&#8220;ibm,max-sync-cop&#8221;</literal></emphasis> else return
                        H_TOO_BIG.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>

                  <listitem>
                    <para>For the Shared Logical Resource Option if any of the memory
                    represented by the in/inlen parameters have been rescinded then return
                    H_RESCINDED.</para>
                  </listitem>

                  <listitem>
                    <para>Fill in the source DDE list from the converted the in/inlen
                    parameters.</para>
                  </listitem>

                  <listitem>
                    <para>Build the destination DDE referencing the start of the PTE page
                    with the length of the PTE page size.</para>
                  </listitem>

                  <listitem>
                    <para>Issue icswx instruction to execute CRB</para>
                  </listitem>

                  <listitem>
                    <para>Check coprocessor busy - retry / return H_Busy if execution
                    time exhausted / return H_Hardware if compressor is broken</para>
                  </listitem>

                  <listitem>
                    <para>Wait for coprocessor to complete</para>
                  </listitem>

                  <listitem>
                    <para>If compressor ran out of destination space return
                    H_TOO_BIG</para>
                  </listitem>

                  <listitem>
                    <para>Check that the decompression filled the full page else return
                    H_Aborted</para>
                  </listitem>

                  <listitem>
                    <para>If the checksum flag is on check that the data is valid else
                    return H_BAD_DATA</para>
                  </listitem>

                  <listitem>
                    <para>If hardware error return H_Hardware</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>If the I-Cache-Invalidate flag is set, issue icbi instructions
                for all of the page&#8217;s cache lines</para>
              </listitem>

              <listitem>
                <para>If the Cache-Synchronize flag is set, issue dcbst and icbi
                instructions for all of the page&#8217;s cache lines. Implementations may
                need to issue a sync instruction to complete the coherency management of
                the I-Cache.</para>
              </listitem>

              <listitem>
                <para>The hypervisor selects a PTE within the page table entry group
                using the following.</para>
              </listitem>

              <listitem>
                <para><literallayout>If the MUI option is enabled
  {
    Switch (HBA flags field)
    {
      Case ‘0b11: return H_UNSUPPORTED_FLAG;
      Case ‘0b10:
        enable implementation dependent HBA update bit in PTE;
        set implementation dependent PTE PUT field to previous time;
        Set Reference History Bit Array entry for physical page to configured initial
        value;
      Case ‘0b01:
        enable implementation HBA update in PTE;
        set implementation dependent PTE PUT field to previous time;
      Default: disable implementation dependent HBA update bit in PTE;
    }
    If the Affinity-Clear flag is on clear the MUI ALA for the page;
    If the Page-Age-Clear flag is on clear the MUI PAG for the page;
  }</literallayout></para>
              </listitem>
            </itemizedlist>

          </simplesect>

          <simplesect>
            <title>Algorithm:</title>

            <itemizedlist>
              <listitem>
                <para>if Exact flag is on then set t to 0 else set t to 7</para>
              </listitem>

              <listitem>
                <para>for i=0;i&lt;= t; i++</para>

                <itemizedlist>
                  <listitem>
                    <para>Combine page table base, PTEX and offset base on (i) into
                    R3</para>
                  </listitem>

                  <listitem>
                    <para>R8 &lt;- ldarx PTEH(R3) /* prepare to take a lock on the PTE
                    */</para>
                  </listitem>

                  <listitem>
                    <para>if PTE is valid (R8 (bit 63) is set) then continue</para>
                  </listitem>

                  <listitem>
                    <para>if PTE is locked (R8 (bit 57) is set) then continue</para>
                  </listitem>

                  <listitem>
                    <para>set R8 (bit 57) /* prepare to lock PTE */</para>
                  </listitem>

                  <listitem>
                    <para>PTEH(R3) &lt;- stdcx R8 /* attempt to take lock */</para>
                  </listitem>

                  <listitem>
                    <para>if stdcx failed continue</para>
                  </listitem>

                  <listitem>
                    <para>goto insert</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>return H_PTEG_FULL</para>
              </listitem>

              <listitem>
                <para>insert: use code sequence from PA Book III</para>
              </listitem>

              <listitem>
                <para>construct return PTEX (R4 &lt;- (R3 - PFTbase) shifted down 4
                places)</para>
              </listitem>

              <listitem>
                <para>For the CMO option: set the page usage state per the CMO Option
                flags field of the flags parameter as defined in
                <xref linkend="dbdoclet.50569344_92498" />.</para>
              </listitem>

              <listitem>
                <para>return H_Success</para>
              </listitem>
            </itemizedlist>

          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_50644">
          <title>H_READ</title>
          <para>This hcall returns the contents of a specific PTE in registers R4
          and R5.</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64 hcall ( const uint64 H_READ, uint64 flags, int64 PTEX );]]></programlisting>
          </simplesect>


          <simplesect>
            <title>Parameters:</title>


            <itemizedlist>
              <listitem>
                <para>flags:</para>

                <itemizedlist>
                  <listitem>
                    <para>CEC Cookie: Cross CEC PFT access</para>
                  </listitem>

                  <listitem>
                    <para>READ_4: Return 4 PTEs</para>
                  </listitem>

                  <listitem>
                    <para>R-XLATE: Include a valid logical page number in the PTE if the
                    valid bit is set, else the contents of the logical page number field is
                    undefined.</para>
                  </listitem>

                  <listitem>
                    <para>For the CMO option: CMO Option flags as defined in
                    <xref linkend="dbdoclet.50569344_92498" />.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>PTEX (index of the PTE in the page table to be used -- if the
                READ_4 flag is set the low order two bits of the PTEX are forced to zero
                by the hypervisor to insure that they are in the range of the PTEG and it
                is faster than checking.)</para>
              </listitem>
            </itemizedlist>

          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Checks that the PTEX is within the defined range of the
                partition&#8217;s PFT else return H_Parmaeter</para>
              </listitem>

              <listitem>
                <para>If the READ_4 bit is clear Then load the specified PTE into R4
                and R5</para>

                <itemizedlist>
                  <listitem>
                    <para>If R-XLATE flag is set, then reverse translate the RPN field into
                    the logical page number.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Else</para>

                <itemizedlist>
                  <listitem>
                    <para>clear the two low order bits of the PTEX (faster than checking
                    them)</para>
                  </listitem>

                  <listitem>
                    <para>load the 4 PTEs starting at PTEX into R4 through R11.</para>

                    <itemizedlist>
                      <listitem>
                        <para>If R-XLATE flag is set, then reverse translate the RPN fields
                        into the logical page number.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>For the CMO option: set the page usage state per the CMO Option
                flags field of the flags parameter as defined in
                <xref linkend="dbdoclet.50569344_92498" />.</para>
              </listitem>

              <listitem>
                <para>Set H_Success in R3 and return</para>
              </listitem>
            </itemizedlist>

          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_53301">
          <title>H_CLEAR_MOD
          </title>
          <para>This hcall clears the modified bit in the specific PTE. The second
          double word of the old PTE is returned in R4.</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_PARAMETER: The PTE index was out of bounds */
                       /* H_Not_Found: The requested valid PTE Entry was not found */
hcall ( const uint64 H_CLEAR_MOD, /* Clears the PTE Modified bit */
        uint64 flags,  /* None Defined */
        int64 PTEX );  /* Index of the PTE to be used */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>flags: For the CMO option: CMO Option flags as defined in
                <xref linkend="dbdoclet.50569344_92498" />.</para>
              </listitem>

              <listitem>
                <para>PTEX (index of the PTE in the page table to be used)</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Check that the PTEX accesses within the PFT, else returns
                H_Parameter</para>
              </listitem>

              <listitem>
                <para>Check that the &#8220;V&#8221; bit is one, else return
                H_Not_Found.</para>
              </listitem>

              <listitem>
                <para>Fetch the low order double word of the PTE into R4. If the
                &#8220;C&#8221; bit is zero, then return H_Success.</para>
              </listitem>

              <listitem>
                <para>The hypervisor synchronizes the PTE specified by the PTEX, clears
                the mod bit, and returns its old value:</para>

                <itemizedlist>
                  <listitem>
                    <para>Use the architected &#8220;Modifying a Page Table Entry General
                    Case&#8221; sequence from PA Book III.</para>
                  </listitem>

                  <listitem>
                    <para>Only PTE bits to be modified are:</para>

                    <itemizedlist>
                      <listitem>
                        <para>In double word 0 SW bit 57 and the V bit (63)</para>
                      </listitem>

                      <listitem>
                        <para>In double word 1, C bit (56).</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>

                  <listitem>
                    <para>Use the proper tlbie instruction for the page size (per large
                    page flag within PTE) within a critical section protected by the proper
                    lock.</para>
                  </listitem>

                  <listitem>
                    <para>The second double word of the old PTE value ends up in R4.</para>
                  </listitem>

                  <listitem>
                    <para>At the point where the new values are to be activated, use the
                    old values with the &#8220;C&#8221; bit cleared.</para>
                  </listitem>

                  <listitem>
                    <para>For the CMO option: set the page usage state per the CMO Option
                    flags field of the flags parameter as defined in
                    <xref linkend="dbdoclet.50569344_92498" />.</para>
                  </listitem>

                  <listitem>
                    <para>Return H_Success</para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </itemizedlist>

          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_35125">
          <title>H_CLEAR_REF</title>
          <para>This hcall clears the reference bit in the specific PTE. The second
          double word of the old PTE is returned in R4.</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Parameter: The PTE index was out of bounds */
                       /* H_Not_Found: The requested valid PTE Entry was not found */
hcall ( const uint64 H_CLEAR_REF, /* Clears the PTE Reference bit */
        uint64 flags,  /* None Defined */
        int64 PTEX );  /* index of the PTE to be used */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>flags: For the CMO option: CMO Option flags as defined in
                <xref linkend="dbdoclet.50569344_92498" />.</para>
              </listitem>

              <listitem>
                <para>PTEX (index of the PTE in the page table to be used)</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Check that the PTEX accesses within the PFT, else return
                H_Parameter.</para>
              </listitem>

              <listitem>
                <para>Check that the &#8220;V&#8221; bit is one, else return
                H_Not_Found.</para>
              </listitem>

              <listitem>
                <para>Only PTE bits to be modified are:</para>

                <itemizedlist>
                  <listitem>
                    <para>In double word 1 the R bit (55)</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Use the architected &#8220;Resetting the Reference Bit&#8221;
                sequence from PA Book III with the original second double word of the PTE
                ending up in R4.</para>
              </listitem>

              <listitem>
                <para>For the CMO option: set the page usage state per the CMO Option
                flags field of the flags parameter as defined in
                <xref linkend="dbdoclet.50569344_92498" />.</para>
              </listitem>

              <listitem>
                <para>Return H_Success</para>
              </listitem>
            </itemizedlist>

          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_34458">
          <title>H_PROTECT</title>
          <para>This hcall sets the page protect bits in the specific PTE.</para>

          <simplesect>
          <title>Syntax:</title>
          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Parameter: The PTE index was out of bounds */
                       /* H_Not_Found: The requested valid PTE Entry was not found */
hcall ( const uint64 H_PROTECT, /* Changes the page protection specification */
        uint64 flags,  /* Special function indications */
        int64 PTEX,    /* index of the PTE to be used */
        uint64 AVPN ); /* Abbreviated virtual page number */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>flags: AVPN, pp0<footnote xml:id="pgfId-1193470">
                  <para>The pp0 portion of the flags parameter is ignored on platforms
                  that do not have the &#8220;Support for the &#8220;110&#8221; value of
                  the Page Protection (PP) bits&#8221; bit set to a value of 1 in the
                  <emphasis role="bold"><literal>&#8220;ibm,pa-features&#8221;</literal></emphasis> property.</para>
                </footnote>, pp1, pp2, key0-key4<footnote xml:id="pgfId-1193478">
                  <para>The key0-key4 portion of the flags parameter is ignored on
                  platforms that either do not contain an
                  <emphasis role="bold"><literal>&#8220;ibm,processor-storage-keys&#8221;</literal></emphasis> property,
                  or contain an
                  <emphasis role="bold"><literal>&#8220;ibm,processor-storage-keys&#8221;</literal></emphasis> property
                  with the value of zero in both cells.</para>
                </footnote>, n, and for the CMO option: CMO Option flags as defined in
                <xref linkend="dbdoclet.50569344_92498" />.</para>
              </listitem>

              <listitem>
                <para>PTEX (index of the PTE in the page table to be used)</para>
              </listitem>

              <listitem>
                <para>AVPN: Optional &#8220;Abbreviated Virtual Page Number&#8221; --
                used as a check for the correct PTE when the AVPN flag is set.</para>
              </listitem>
            </itemizedlist>

          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Check that the PTEX accesses within the PFT, else return
                H_Parameter</para>
              </listitem>

              <listitem>
                <para>Check that the &#8220;V&#8221; bit is one, else return
                H_Not_Found.</para>
              </listitem>

              <listitem>
                <para>If the AVPN flag is set, and the AVPN parameter bits 0-56 do not
                match that of the specified PTE, then return H_Not_Found.</para>
              </listitem>

              <listitem>
                <para>The hypervisor synchronizes the PTE specified by the PTEX, sets
                the pp0<footnote xml:id="pgfId-1193487">
                  <para>The pp0 bit is not modified on platforms that do not have the
                  &#8220;Support for the &#8220;110&#8221; value of the Page Protection
                  (PP) bits&#8221; bit set to a value of 1 in the
                  <emphasis role="bold"><literal>&#8220;ibm,pa-features&#8221;</literal></emphasis> property.</para>
                </footnote>, pp1, pp2, key0-key4<emphasis><footnote xml:id="pgfId-1193496">
                    <para>The key0 - key4 bits are not modified on platforms that either
                    do not contain an <emphasis role="bold"><literal>&#8220;ibm,processor-storage-keys&#8221;</literal></emphasis>
                    property, or contain an
                    <emphasis role="bold"><literal>&#8220;ibm,processor-storage-keys&#8221;</literal></emphasis> property
                    with the value of zero in both cells.</para>
                  </footnote></emphasis>, and n bits per the flags parameter.</para>

                <itemizedlist>
                  <listitem>
                    <para>Only PTE bits to be modified are:</para>

                    <itemizedlist>
                      <listitem>
                        <para>In double word 0 SW bit 57 and the V bit (63)</para>
                      </listitem>

                      <listitem>
                        <para>In double word 1 pp0<footnoteref linkend="pgfId-1193487" />, pp1, pp2,
                        key0-key4<footnoteref linkend="pgfId-1193496" />, and n</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>

                  <listitem>
                    <para>Use the architected &#8220;Modifying a Page Table Entry General
                    Case&#8221; sequence.</para>
                  </listitem>

                  <listitem>
                    <para>Use the proper tlbie instruction for the page size (per value in
                    PTE) within a critical section protected by the proper lock.</para>
                  </listitem>

                  <listitem>
                    <para>At the point where the new values are to be activated use the old
                    values with the &#8220;R&#8221; bit cleared and the
                    pp0<footnoteref linkend="pgfId-1193487" />,
                    pp1, pp2, key0-key4<footnoteref linkend="pgfId-1193496" />,
                    and n bits set as specified in
                    the flags parameter.</para>
                  </listitem>

                  <listitem>
                    <para>For the CMO option: set the page usage state per the CMO Option
                    flags field of the flags parameter as defined in
                    <xref linkend="dbdoclet.50569344_92498" />.</para>
                  </listitem>

                  <listitem>
                    <para>Return H_Success</para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </itemizedlist>

          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_23009">
          <title>H_BULK_REMOVE</title>
          <para>This hcall is for invalidating up to four entries in the page
          table. The PTEX in the translation specifier high parameters identifies
          the specific page table entries.</para>
          <para>Prototype:</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_HARDWARE: Hardware Error */
                       /* H_PARAMETER: One or more parameters were in error first */
                       /*   found was flagged */
hcall ( const int64 H_BULK_REMOVE, /* Function Code */
        uint64 TSH1,   /* Translation Specifier High 1*/
        uint64 TSL1,   /* Translation Specifier Low 1*/
        uint64 TSH2,   /* Translation Specifier High 2*/
        uint64 TSL2,   /* Translation Specifier Low 2*/
        uint64 TSH3,   /* Translation Specifier High 3*/
        uint64 TSL3,   /* Translation Specifier Low 3*/
        uint64 TSH4,   /* Translation Specifier High 4*/
        uint64 TSL4 ); /* Translation Specifier Low 4*/]]></programlisting>

            <para>Translation specifiers:</para>
            <para>Each is 16 bytes long made up of two 8 byte double words; a
            translation specifier high and a translation specifier low.</para>

            <itemizedlist>
              <listitem>
                <para>Translation Specifier High double word:</para>

                <itemizedlist>
                  <listitem>
                    <para>First byte (0) is a control/status byte:</para>

                    <itemizedlist>
                      <listitem>
                        <para>High order two bits (0 and 1) are type code:</para>

                        <itemizedlist>
                          <listitem>
                            <para>00 Unused -- if found stop processing and return
                            H_PARAMETER</para>
                          </listitem>

                          <listitem>
                            <para>01 Request -- Processes As per H_REMOVE as modified by low order
                            two control bits.</para>
                          </listitem>

                          <listitem>
                            <para>10 Response -- written by hypervisor as a return status from
                            processing individual &#8220;request&#8221; translation specifier</para>
                          </listitem>

                          <listitem>
                            <para>11 End of String -- if found stop processing and return
                            H_Success.</para>
                          </listitem>
                        </itemizedlist>
                      </listitem>

                      <listitem>
                        <para>Next two bits (2 and 3) are response code (in response to
                        processing an individual &#8220;request&#8221; translation specifier
                        (type code modified to 10)):</para>

                        <itemizedlist>
                          <listitem>
                            <para>00 Success -- the specified translation was removed as per
                            H_REMOVE with the PTE's RC bits in the next two status bits.</para>
                          </listitem>

                          <listitem>
                            <para>01 Not found -- the specified translation was not found as per
                            H_REMOVE.</para>
                          </listitem>

                          <listitem>
                            <para>10 H_PARM -- one or more of the parameters of the specified
                            translation were invalid per H_REMOVE -- processing of the bulk entries
                            stops at this point and the hypervisor returns H_PARAMETER.</para>
                          </listitem>

                          <listitem>
                            <para>11 H_HW -- The hardware experienced an uncorrected error
                            processing this translation specifier -- processing of the bulk entries
                            stops at this point and the hypervisor returns H_HARDWARE.</para>
                          </listitem>
                        </itemizedlist>
                      </listitem>

                      <listitem>
                        <para>Next two bits (4 and 5) are the Reference/Change bits from the
                        removed PTE (These bits are only valid if bits 0-3 are 1000):</para>
                      </listitem>

                      <listitem>
                        <para>Low order two bits (6 and 7) are request modification
                        flags:</para>

                        <itemizedlist>
                          <listitem>
                            <para>00 absolute -- remove the specified PTEX entry
                            unconditionally</para>
                          </listitem>

                          <listitem>
                            <para>01 andcond -- remove the specified PTEX entry as with the andcond
                            flag of H_REMOVE</para>
                          </listitem>

                          <listitem>
                            <para>10 AVPN -- remove the specified PTEX entry as with the AVPN flag
                            of H_REMOVE</para>
                          </listitem>

                          <listitem>
                            <para>11 not used -- if found stop processing and return
                            H_PARAMETER.</para>
                          </listitem>
                        </itemizedlist>
                      </listitem>
                    </itemizedlist>
                  </listitem>

                  <listitem>
                    <para>Bytes 1 through 7 are the PTEX (PFT byte offset divided by
                    16)</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Translation Specifier Low double word:</para>

                <itemizedlist>
                  <listitem>
                    <para>Bytes 0 through 7 are the AVPN as per H_REMOVE</para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>For each translation specifier, while the translation specifier
                is not &#8220;end of string&#8221;:</para>

                <itemizedlist>
                  <listitem>
                    <para>Check that the PTEX accesses within the PFT else set H_PARM
                    response status in the specific translation specifier high register and
                    return H_Parameter</para>
                  </listitem>

                  <listitem>
                    <para>If the AVPN flag is set, and the AVPN parameter bits 0-56 do not
                    match that of the specified PTE then set response status Not found in the
                    specific translation specifier high register, Continue.</para>
                  </listitem>

                  <listitem>
                    <para>If the andcond flag is set, the AVPN parameter is bit anded with
                    the first double word of the specified PTE (after bits 57-63 of the PTE
                    have been masked), if the result is non-zero, then set response status
                    Not found in the specific translation specifier high register, Continue.
                    (Note the low order 7 bits of the AVPN parameter should be zero otherwise
                    the likely result is a response status of Not found).</para>
                  </listitem>

                  <listitem>
                    <para>The hypervisor Synchronizes the PTE specified by the PTEX.</para>
                  </listitem>

                  <listitem>
                    <para>Use the architected &#8220;Deleting a Page Table Entry&#8221;
                    sequence.</para>
                  </listitem>

                  <listitem>
                    <para>Use the proper tlbie instruction for the page size within a
                    critical section protected by the proper lock (per large page bit in the
                    specified PTE).</para>
                  </listitem>

                  <listitem>
                    <para>The synchronized value of the old PTE RC bits ends up in bits 4
                    and 5 of the individual translation specifier high register along with
                    success response status.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>return H_Success</para>
              </listitem>
            </itemizedlist>

          </simplesect>
        </section>

        <section xml:id="sec_block_remove">
          <title>H_BLOCK_REMOVE</title>

          <para>This hcall removes up to eight sequential virtual
          page table entries. Some platforms that support this hcall() might remove
          fewer than 8 entries for a given actual page size / base page
          size combination as communicated by the “Block Invalidate
          Characteristics” system parameter (see
          <xref linkend="LoPAR.RTAS" />).
          The virtual pages are all within
          the same naturally aligned 8 page virtual address block and
          have the same page and segment size encodings. The AVA parameter,
          if used, covers the entire block of virtual page
          addresses. If another processor is currently accessing
          the page table entry, the entry is not removed. The availability of
          is hcall() might change after partition migration, the
          caller should be prepared for an H_Function return code. The
          PTEX field of the translation specifier parameters
          identifies the specific page table entries.</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_PARTIAL: one or more page table entries were not */
                       /*   removed see response codes
                       /* H_HARDWARE: Hardware Error */
hcall ( const int64 H_BLOCK_REMOVE, /* Function Code */
        uint64 AVA,    /* Abbreviated Virtual Address */
        uint64 TS0,    /* Translation Specifier Zero */
        uint64 TS1,    /* Translation Specifier One */
        uint64 TS2,    /* Translation Specifier Two */
        uint64 TS3,    /* Translation Specifier Three */
        uint64 TS4,    /* Translation Specifier Four */
        uint64 TS5,    /* Translation Specifier Five */
        uint64 TS6,    /* Translation Specifier Size */
        uint64 TS7 );  /* Translation Specifier Seven */]]></programlisting>

            <para>The AVA parameter is the 8 byte AVPN as per H_REMOVE.</para>

            <para>Each Translation Specifier is 8 bytes long:</para>

            <table>
              <title>H_BLOCK_REMOVE Translation Specifier</title>
              <tgroup cols="64">
                <colspec colname="c1" colwidth="9pt" align="center" />
                <colspec colname="c2" colwidth="9pt" align="center" />
                <colspec colname="c3" colwidth="9pt" align="center" />
                <colspec colname="c4" colwidth="9pt" align="center" />
                <colspec colname="c5" colwidth="9pt" align="center" />
                <colspec colname="c6" colwidth="9pt" align="center" />
                <colspec colname="c7" colwidth="9pt" align="center" />
                <colspec colname="c8" colwidth="9pt" align="center" />
                <colspec colname="c9" colwidth="9pt" align="center" />
                <colspec colname="c10" colwidth="9pt" align="center" />
                <colspec colname="c11" colwidth="9pt" align="center" />
                <colspec colname="c12" colwidth="9pt" align="center" />
                <colspec colname="c13" colwidth="9pt" align="center" />
                <colspec colname="c14" colwidth="9pt" align="center" />
                <colspec colname="c15" colwidth="9pt" align="center" />
                <colspec colname="c16" colwidth="9pt" align="center" />
                <colspec colname="c17" colwidth="9pt" align="center" />
                <colspec colname="c18" colwidth="9pt" align="center" />
                <colspec colname="c19" colwidth="9pt" align="center" />
                <colspec colname="c20" colwidth="9pt" align="center" />
                <colspec colname="c21" colwidth="9pt" align="center" />
                <colspec colname="c22" colwidth="9pt" align="center" />
                <colspec colname="c23" colwidth="9pt" align="center" />
                <colspec colname="c24" colwidth="9pt" align="center" />
                <colspec colname="c25" colwidth="9pt" align="center" />
                <colspec colname="c26" colwidth="9pt" align="center" />
                <colspec colname="c27" colwidth="9pt" align="center" />
                <colspec colname="c28" colwidth="9pt" align="center" />
                <colspec colname="c29" colwidth="9pt" align="center" />
                <colspec colname="c30" colwidth="9pt" align="center" />
                <colspec colname="c31" colwidth="9pt" align="center" />
                <colspec colname="c32" colwidth="9pt" align="center" />
                <colspec colname="c33" colwidth="9pt" align="center" />
                <colspec colname="c34" colwidth="9pt" align="center" />
                <colspec colname="c35" colwidth="9pt" align="center" />
                <colspec colname="c36" colwidth="9pt" align="center" />
                <colspec colname="c37" colwidth="9pt" align="center" />
                <colspec colname="c38" colwidth="9pt" align="center" />
                <colspec colname="c39" colwidth="9pt" align="center" />
                <colspec colname="c40" colwidth="9pt" align="center" />
                <colspec colname="c41" colwidth="9pt" align="center" />
                <colspec colname="c42" colwidth="9pt" align="center" />
                <colspec colname="c43" colwidth="9pt" align="center" />
                <colspec colname="c44" colwidth="9pt" align="center" />
                <colspec colname="c45" colwidth="9pt" align="center" />
                <colspec colname="c46" colwidth="9pt" align="center" />
                <colspec colname="c47" colwidth="9pt" align="center" />
                <colspec colname="c48" colwidth="9pt" align="center" />
                <colspec colname="c49" colwidth="9pt" align="center" />
                <colspec colname="c50" colwidth="9pt" align="center" />
                <colspec colname="c51" colwidth="9pt" align="center" />
                <colspec colname="c52" colwidth="9pt" align="center" />
                <colspec colname="c53" colwidth="9pt" align="center" />
                <colspec colname="c54" colwidth="9pt" align="center" />
                <colspec colname="c55" colwidth="9pt" align="center" />
                <colspec colname="c56" colwidth="9pt" align="center" />
                <colspec colname="c57" colwidth="9pt" align="center" />
                <colspec colname="c58" colwidth="9pt" align="center" />
                <colspec colname="c59" colwidth="9pt" align="center" />
                <colspec colname="c60" colwidth="9pt" align="center" />
                <colspec colname="c61" colwidth="9pt" align="center" />
                <colspec colname="c62" colwidth="9pt" align="center" />
                <colspec colname="c63" colwidth="9pt" align="center" />
                <colspec colname="c64" colwidth="9pt" align="center" />
                <thead>
                  <row>
                    <entry namest="c1" nameend="c8">
                      <para role="font-size:6pt">Byte 0</para>
                    </entry>
                    <entry namest="c9" nameend="c16">
                      <para role="font-size:6pt">Byte 1</para>
                    </entry>
                    <entry namest="c17" nameend="c24">
                      <para role="font-size:6pt">Byte 2</para>
                    </entry>
                    <entry namest="c25" nameend="c32">
                      <para role="font-size:6pt">Byte 3</para>
                    </entry>
                    <entry namest="c33" nameend="c40">
                      <para role="font-size:6pt">Byte 4</para>
                    </entry>
                    <entry namest="c41" nameend="c48">
                      <para role="font-size:6pt">Byte 5</para>
                    </entry>
                    <entry namest="c49" nameend="c56">
                      <para role="font-size:6pt">Byte 6</para>
                    </entry>
                    <entry namest="c57" nameend="c64">
                      <para role="font-size:6pt">Byte 7</para>
                    </entry>
                  </row>
                  <row>
                    <entry><para role="font-size:6pt">0</para></entry>
                    <entry><para role="font-size:6pt">1</para></entry>
                    <entry><para role="font-size:6pt">2</para></entry>
                    <entry><para role="font-size:6pt">3</para></entry>
                    <entry><para role="font-size:6pt">4</para></entry>
                    <entry><para role="font-size:6pt">5</para></entry>
                    <entry><para role="font-size:6pt">6</para></entry>
                    <entry><para role="font-size:6pt">7</para></entry>
                    <entry><para role="font-size:6pt">0</para></entry>
                    <entry><para role="font-size:6pt">1</para></entry>
                    <entry><para role="font-size:6pt">2</para></entry>
                    <entry><para role="font-size:6pt">3</para></entry>
                    <entry><para role="font-size:6pt">4</para></entry>
                    <entry><para role="font-size:6pt">5</para></entry>
                    <entry><para role="font-size:6pt">6</para></entry>
                    <entry><para role="font-size:6pt">7</para></entry>
                    <entry><para role="font-size:6pt">0</para></entry>
                    <entry><para role="font-size:6pt">1</para></entry>
                    <entry><para role="font-size:6pt">2</para></entry>
                    <entry><para role="font-size:6pt">3</para></entry>
                    <entry><para role="font-size:6pt">4</para></entry>
                    <entry><para role="font-size:6pt">5</para></entry>
                    <entry><para role="font-size:6pt">6</para></entry>
                    <entry><para role="font-size:6pt">7</para></entry>
                    <entry><para role="font-size:6pt">0</para></entry>
                    <entry><para role="font-size:6pt">1</para></entry>
                    <entry><para role="font-size:6pt">2</para></entry>
                    <entry><para role="font-size:6pt">3</para></entry>
                    <entry><para role="font-size:6pt">4</para></entry>
                    <entry><para role="font-size:6pt">5</para></entry>
                    <entry><para role="font-size:6pt">6</para></entry>
                    <entry><para role="font-size:6pt">7</para></entry>
                    <entry><para role="font-size:6pt">0</para></entry>
                    <entry><para role="font-size:6pt">1</para></entry>
                    <entry><para role="font-size:6pt">2</para></entry>
                    <entry><para role="font-size:6pt">3</para></entry>
                    <entry><para role="font-size:6pt">4</para></entry>
                    <entry><para role="font-size:6pt">5</para></entry>
                    <entry><para role="font-size:6pt">6</para></entry>
                    <entry><para role="font-size:6pt">7</para></entry>
                    <entry><para role="font-size:6pt">0</para></entry>
                    <entry><para role="font-size:6pt">1</para></entry>
                    <entry><para role="font-size:6pt">2</para></entry>
                    <entry><para role="font-size:6pt">3</para></entry>
                    <entry><para role="font-size:6pt">4</para></entry>
                    <entry><para role="font-size:6pt">5</para></entry>
                    <entry><para role="font-size:6pt">6</para></entry>
                    <entry><para role="font-size:6pt">7</para></entry>
                    <entry><para role="font-size:6pt">0</para></entry>
                    <entry><para role="font-size:6pt">1</para></entry>
                    <entry><para role="font-size:6pt">2</para></entry>
                    <entry><para role="font-size:6pt">3</para></entry>
                    <entry><para role="font-size:6pt">4</para></entry>
                    <entry><para role="font-size:6pt">5</para></entry>
                    <entry><para role="font-size:6pt">6</para></entry>
                    <entry><para role="font-size:6pt">7</para></entry>
                    <entry><para role="font-size:6pt">0</para></entry>
                    <entry><para role="font-size:6pt">1</para></entry>
                    <entry><para role="font-size:6pt">2</para></entry>
                    <entry><para role="font-size:6pt">3</para></entry>
                    <entry><para role="font-size:6pt">4</para></entry>
                    <entry><para role="font-size:6pt">5</para></entry>
                    <entry><para role="font-size:6pt">6</para></entry>
                    <entry><para role="font-size:6pt">7</para></entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry namest="c1" nameend="c8">
                      <para role="font-size:6pt">Control</para>
                    </entry>
                    <entry namest="c9" nameend="c9">
                      <para role="font-size:6pt">0</para>
                    </entry>
                    <entry namest="c10" nameend="c16">
                      <para role="font-size:6pt">Reserved</para>
                    </entry>
                    <entry namest="c17" nameend="c64">
                      <para role="font-size:6pt">PTEX (PFT byte offset divided by 16)</para>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>

            <table>
              <title>H_BLOCK_REMOVE Control Byte Format</title>
              <tgroup cols="8">
                <colspec colname="c1" colwidth="5*" align="center" />
                <colspec colname="c2" colwidth="3*" align="center" />
                <colspec colname="c3" colwidth="3*" align="center" />
                <colspec colname="c4" colwidth="3*" align="center" />
                <colspec colname="c5" colwidth="3*" align="center" />
                <colspec colname="c6" colwidth="3*" align="center" />
                <colspec colname="c7" colwidth="3*" align="center" />
                <colspec colname="c8" colwidth="77*" align="center" />
                <thead>
                  <row>
                    <entry namest="c1" nameend="c7">
                      <para>Control</para>
                    </entry>
                    <entry>
                      <para>Description</para>
                    </entry>
                  </row>
                </thead>
                <tbody>
                  <row>
                    <entry><para>Type</para></entry>
                    <entry><para>&#160;</para></entry>
                    <entry><para>&#160;</para></entry>
                    <entry><para>&#160;</para></entry>
                    <entry><para>&#160;</para></entry>
                    <entry><para>&#160;</para></entry>
                    <entry><para>&#160;</para></entry>
                    <entry><para>&#160;</para></entry>
                  </row>
                  <row>
                    <entry><para>00</para></entry>
                    <entry namest="c2" nameend="c8"><para>Unused</para></entry>
                  </row>
                  <row>
                    <entry><para>01</para></entry>
                    <entry namest="c2" nameend="c8"><para>Request</para></entry>
                  </row>
                  <row>
                    <entry morerows="6"><para>&#160;</para></entry>
                    <entry morerows="1" namest="c2" nameend="c6"><para>&#160;</para></entry>
                    <entry><para>0</para></entry>
                    <entry><para>absolute -- remove the specified PTEX entry unconditionally</para></entry>
                  </row>
                  <row>
                    <entry><para>1</para></entry>
                    <entry><para>AVPN -- remove the specified PTEX entry as with the AVPN flag of H_REMOVE</para></entry>
                  </row>
                  <row>
                    <entry namest="c2" nameend="c3"><para>Page State</para></entry>
                    <entry namest="c4" nameend="c8"><para>&#160;</para></entry>
                  </row>
                  <row>
                    <entry><para>0</para></entry>
                    <entry><para>0</para></entry>
                    <entry namest="c4" nameend="c8"><para>Inhibit page usage state change</para></entry>
                  </row>
                  <row>
                    <entry><para>0</para></entry>
                    <entry><para>1</para></entry>
                    <entry namest="c4" nameend="c8"><para>Reserved</para></entry>
                  </row>
                  <row>
                    <entry><para>1</para></entry>
                    <entry><para>0</para></entry>
                    <entry namest="c4" nameend="c8"><para>For CMO option set page usage state to “Unused” if Success</para></entry>
                  </row>
                  <row>
                    <entry><para>1</para></entry>
                    <entry><para>1</para></entry>
                    <entry namest="c4" nameend="c8"><para>For CMO option set page usage state to “Loaned” if Success</para></entry>
                  </row>
                  <row>
                    <entry namest="c1" nameend="c8"><para>&#160;</para></entry>
                  </row>
                  <row>
                    <entry><para>10</para></entry>
                    <entry namest="c2" nameend="c8"><para>Response</para></entry>
                  </row>
                  <row>
                    <entry morerows="9"><para>&#160;</para></entry>
                    <entry><para>0</para></entry>
                    <entry><para>0</para></entry>
                    <entry><para>0</para></entry>
                    <entry namest="c5" nameend="c8"><para>Success -- the specified translation was removed as per H_REMOVE
                    with the PTE's RC bits in the next two status bits.</para></entry>
                  </row>
                  <row>
                    <entry><para>0</para></entry>
                    <entry><para>0</para></entry>
                    <entry><para>1</para></entry>
                    <entry namest="c5" nameend="c8"><para>Not found -- the specified translation was either not found a
                    s per H_REMOVE, Invalid (V bit = 0), or entry was “bolted” (PTE bit 59 = 1)</para></entry>
                  </row>
                  <row>
                    <entry><para>0</para></entry>
                    <entry><para>1</para></entry>
                    <entry><para>0</para></entry>
                    <entry namest="c5" nameend="c8"><para>H_PARM Parameter is invalid</para></entry>
                  </row>
                  <row>
                    <entry><para>0</para></entry>
                    <entry><para>1</para></entry>
                    <entry><para>1</para></entry>
                    <entry namest="c5" nameend="c8"><para>Inconsistent Page/Segment Size (does not match the L||LP and B
                    fields of the block anchor Page Table Entry)</para></entry>
                  </row>
                  <row>
                    <entry><para>1</para></entry>
                    <entry><para>0</para></entry>
                    <entry><para>0</para></entry>
                    <entry namest="c5" nameend="c8"><para>Busy (The page table entry is being modified by another processor)</para></entry>
                  </row>
                  <row>
                    <entry><para>1</para></entry>
                    <entry><para>0</para></entry>
                    <entry><para>1</para></entry>
                    <entry namest="c5" nameend="c8"><para>Cross Boundary (The page table entry crosses an 8 page virtual address boundary)</para></entry>
                  </row>
                  <row>
                    <entry><para>1</para></entry>
                    <entry><para>1</para></entry>
                    <entry><para>0</para></entry>
                    <entry namest="c5" nameend="c8"><para>Beyond Capacity (The page table entry exceeded the number supported on this platform)</para></entry>
                  </row>
                  <row>
                    <entry><para>1</para></entry>
                    <entry><para>1</para></entry>
                    <entry><para>1</para></entry>
                    <entry namest="c5" nameend="c8"><para>The hardware experienced an uncorrected error processing this translation specifier --
                    processing of the bulk entries stops at this point and the hypervisor returns H_HARDWARE.</para></entry>
                  </row>
                  <row>
                    <entry namest="c2" nameend="c4"><para>&#160;</para></entry>
                    <entry><para>R</para></entry>
                    <entry namest="c6" nameend="c8"><para>Reference bit from the removed PTE (bit is only valid if bits 0-4 are 10000)</para></entry>
                  </row>
                  <row>
                    <entry namest="c2" nameend="c5"><para>&#160;</para></entry>
                    <entry><para>R</para></entry>
                    <entry namest="c7" nameend="c8"><para>Reference bit from the removed PTE (bit is only valid if bits 0-4 are 10000)</para></entry>
                  </row>
                  <row>
                    <entry namest="c1" nameend="c8"><para>&#160;</para></entry>
                  </row>
                  <row>
                    <entry><para>11</para></entry>
                    <entry namest="c2" nameend="c8"><para>End of String -- if found stop processing and return the accumulated return code.</para></entry>
                  </row>
                </tbody>
              </tgroup>
            </table>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Initialize return code to H_Success (overwritten if appropriate)</para>
              </listitem>
              <listitem>
                <para>Initialize “anchored” flag to false and PTECOUNT to zero.</para>
              </listitem>
              <listitem>
                <para>For each translation specifier, while the translation specifier type is not “end of string”:</para>

                <itemizedlist>
                  <listitem>
                    <para>If the translation specifer type is not “Request” Return H_PARAMETER.</para>
                  </listitem>
                  <listitem>
                    <para>Check that the PTEX accesses within the PFT else set H_PARM response status in the specific translation specifier
                    high register set return code to H_PARTIAL and Continue.</para>
                  </listitem>
                  <listitem>
                    <para>If the lock for the associated page table entry can not be immediately obtained, then set the TSn response code to
                    “Busy”, set return code to H_PARTIAL and Continue.</para>
                  </listitem>
                  <listitem>
                    <para>If the PTEX specified entry is either invalid (PTE V bit = 0) or “bolted” (PTE bit 59 = 1) then set response status
                    “Not found” in the specific translation specifier high register, set return code to H_PARTIAL and Continue.</para>
                  </listitem>
                  <listitem>
                    <para>Check that actual page size / base page size combination of the PTEX specified entry is supported for
                    H_BLOCK_REMOVE as communicated by the “Block Invalidate Characteristics” system parameter else set
                    H_PARM response status in the specific translation specifier high register set return code to H_PARTIAL and
                    Continue.</para>
                  </listitem>
                  <listitem>
                    <para>If the AVPN flag is set, and the AVPN parameter bits 0-56 do not match that of the specified PTE then set response
                    status “Not found” in the specific translation specifier high register, set return code to H_PARTIAL and
                    Continue.</para>
                  </listitem>
                  <listitem>
                    <para>If NOT Anchored:</para>

                    <itemizedlist>
                      <listitem>
                        <para>then:</para>

                        <itemizedlist>
                          <listitem>
                            <para>Establish the block L||LP</para>
                          </listitem>
                          <listitem>
                            <para>Establish the block segment size encoding</para>
                          </listitem>
                          <listitem>
                            <para>For the CMO option: if the TS Control byte Page State bits are a reserved value then set H_PARM response
                            status in the specific translation specifier high register, set return code to H_PARTIAL and Continue; else If
                            the block segment encoding is an MPSS segment then set the page usage state for the large page per the
                            CMO Page State bits of the TS Control byte; else set the page usage state per the CMO Page State bits of the
                            TS specified page per the TS Control byte.</para>
                          </listitem>
                          <listitem>
                            <para>Establish the block plus high order virtual address</para>
                          </listitem>
                          <listitem>
                            <para>Establish the number of TLBs that the platform can invalidate in one operation from the associated page table
                            entry</para>
                          </listitem>
                          <listitem>
                            <para>Set the “anchored” flag to true;</para>
                          </listitem>
                        </itemizedlist>
                      </listitem>
                      <listitem>
                        <para>else:</para>

                        <itemizedlist>
                          <listitem>
                            <para>If the associated page table entry L||LP and segment size encoding does not match the established anchored
                            values then set the TSn response code to “Inconsistent Page/Segment Size“, set return code to H_PARTIAL
                            and Continue.</para>
                          </listitem>
                          <listitem>
                            <para>If the associated page table entry high order virtual address of the 8 page block does not match the established
                            anchored values then set the TSn response code to “Cross Boundary“, set return code to H_PARTIAL
                            and Continue.</para>
                          </listitem>
                          <listitem>
                            <para>If PTECOUNT is greater than the number of TLBs that the platform can invalidate in one operation, then set
                            the TSn response code to “Beyond Capacity“, set return code to H_PARTIAL and Continue.</para>
                          </listitem>
                          <listitem>
                            <para>For the CMO option: if the TS Control byte Page State bits are a reserved value then set H_PARM response
                            status in the specific translation specifier high register, set return code to H_PARTIAL and Continue; else if
                            the block segment size encoding is not MPSS then set the page usage state per the CMO Page State bits of
                            the TS Control byte.</para>
                          </listitem>
                        </itemizedlist>
                      </listitem>
                    </itemizedlist>
                  </listitem>
                  <listitem>
                    <para>Add the PTEX to the validated list of PTEX’s to be removed</para>
                  </listitem>
                  <listitem>
                    <para>Increment PTECOUNT</para>
                  </listitem>
                </itemizedlist>
              </listitem>
              <listitem>
                <para>The hypervisor resets the valid bit in the PTEs specified by the validated list of PTEX’s to be removed.</para>
              </listitem>
              <listitem>
                <para>The hypervisor issues a single instance of the PTE Synchronization sequence outlined in the <xref linkend="dbdoclet.50569387_99718" />
                architecture Book IIIS under “Deleting a Page Table Entry” using the proper tlbie instruction for the page size within a critical
                section protected by the proper lock (per large page bit in the specified PTE) to cover all the PTEs specified by
                the validated list of PTEX’s to be removed.</para>
              </listitem>
              <listitem>
                <para>The synchronized value of the old PTE RC bits, for the PTEs specified by the validated list of PTEX’s to be removed,
                ends up in bits 5 and 6 of the individual translation specifier high register along with success response status.</para>
              </listitem>
              <listitem>
                <para>Release acquired page table entry locks.</para>
              </listitem>
              <listitem>
                <para>Return the accumulated return code and TS values.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="sec_hash_page_table_resize_option">
          <title>Hash Page Table Resize Option</title>

          <para>The hash page table (HPT) for an operating system needs to be
            sized depending on the size of the partition's memory. The usual rule of
            thumb is that the HPT should be 1/64th of the size of memory (although
            Linux will typically work well with 1/128th or even less depending on
            available page sizes). An HPT which is too small will lead to poor performance,
            or even crashes, if the OS is unable to fit necessary bolted mappings into
            the table. An HPT which is too large wastes memory and leads to slower
            TLB misses due to increased cache misses on table walks.</para>

          <para>With the size of the HPT fixed at boot, a partition allowing memory
            reconfiguration must size the HPT according to the partition's maximum
            possible memory size. If the partition has a very large potential maximum
            memory size, but is unlikely to reach that in practice, this can lead to
            significant wastage of resources in the oversized hash table. By allowing
            a partition to change its HPT size at runtime, it can start with an HPT
            sized just for its initial memory, and change it if necessary when more
            memory is added dynamically.</para>

          <para>If the platform supports the Hash Page Table Resize Option, then it supports
          the two hcalls defined in this section, which allow an OS to request that its
          HPT should be resized. The resize operation is performed in two phases, the
          “prepare” phase and the “commit” phase. The prepare phase may take place
          concurrently with normal guest operation. The commit phase requires that the
          guest perform no concurrent updates or accesses to the HPT (which in practice
          requires no non-real mode memory accesses).</para>

          <para>
          During operation a partition may have a “Pending HPT”, a block of platform
          memory organized as a Power hash page table which may become the partition's
          HPT in future. The following data are associated with a Pending HPT:
            <itemizedlist>
              <listitem>
                <para>Does a Pending HPT currently exist?</para>
              </listitem>
              <listitem>
                <para>The Pending HPT's size</para>
              </listitem>
              <listitem>
                <para>Flags associated with the Pending HPT (this is for future
                  extension, no flags are currently defined)</para>
              </listitem>
              <listitem>
                <para>Whether the Pending HPT is fully prepared or not</para>
              </listitem>
            </itemizedlist>
          </para>

          <para>In order to prevent a partition from tying up platform resources
            indefinitely with a Pending HPT, the platform is permitted to discard a
            Pending HPT at any time. Operating systems should be prepared to deal
            with a failure of either hcall because of this.</para>

          <para>The platform is permitted to start a partition with its HPT sized
            for the current memory allocation, rather than the maximum memory for
            the partition, provided that if the OS indicates via the
            ibm,client-architecture-support call that it does not support HPT resizing,
            the platform must then resize the HPT according to the partition's maximum
            memory, using a reconfiguration reboot if necessary.</para>

          <section xml:id="sec_resize_hpt_prepare">
            <title>H_RESIZE_HPT_PREPARE</title>

            <para>This hcall controls the prepare phase of HPT resizing. After
              successful completion of this hcall, the partition has a Pending
              HPT which can be made the partition's current HPT.</para>

            <simplesect>
              <title>Syntax:</title>
              <programlisting><![CDATA[int64                  /* H_Success:     Expected Return code */
                       /* H_AUTHORITY:   partition may not resize its */
                       /*                HPT H_PARAMETER, one or more parameters */
                       /*                in error H_RESOURCE, insufficient resources */
                       /* H_PTEG_FULL:   two or more bolted HPTEs need the same slot */
                       /* H_LONG_BUSY_*: operation in progress but not complete. */
hcall ( const int64 H_RESIZE_HPT_PREPARE, /* Function Code */
        uint64 flags,                     /* Special function indications */
        int32 shift );                    /* Log base 2 of new HPT size */]]></programlisting>

            </simplesect>

            <simplesect>
              <title>Parameters:</title>

              <itemizedlist>
                <listitem>
                  <para>flags: 0, as no flags are currently defined.</para>
                </listitem>
                <listitem>
                  <para>shift: Log base 2 of the total size in bytes of the
                    requested new HPT, either 0 (used to discard a Pending HPT)
                    or else between 18 and 46.</para>
                </listitem>
              </itemizedlist>
            </simplesect>

            <simplesect>
              <title>Semantics:</title>

              <itemizedlist>
                <listitem>
                  <para>Check that the partition is permitted to resize its HPT, else
                    return H_AUTHORITY.</para>
                </listitem>
                <listitem>
                  <para>Check if there is a Pending HPT; if there is, then:
                    <itemizedlist>
                      <listitem>
                        <para>If the Pending HPT size and flags match the parameters requested in this call, then:
                          <itemizedlist>
                            <listitem>
                              <para>If the Pending HPT is not fully prepared, return
                                H_LONG_BUSY_xxx with an estimate of the time remaining
                                to complete preparation of the Pending HPT</para>
                            </listitem>
                            <listitem>
                              <para>If preparation of the Pending HPT has terminated
                                due to two bolted HPTEs needing to occupy the same
                                slot of the same HPTEG, then return H_PTEG_FULL</para>
                            </listitem>
                            <listitem>
                              <para>Else return H_SUCCESS</para>
                            </listitem>
                          </itemizedlist>
                        </para>
                      </listitem>
                      <listitem>
                        <para>Else discard the Pending HPT and continue</para>
                      </listitem>
                    </itemizedlist>
                  </para>
                </listitem>
                <listitem>
                  <para>If the flags parameter is non-zero, then return H_PARAMETER</para>
                </listitem>
                <listitem>
                  <para>If shift is zero, then return H_SUCCESS</para>
                </listitem>
                <listitem>
                  <para>If (shift &lt; 18) or (shift &gt; 46), then return H_PARAMETER</para>
                </listitem>
                <listitem>
                  <para>Check that the partition is permitted to have an HPT of 2shift
                    bytes; if not, return H_RESOURCE</para>
                </listitem>
                <listitem>
                  <para>Create a new Pending HPT of size 2shift bytes. Preparation of
                    the new HPT may continue asynchronously.</para>
                </listitem>
                <listitem>
                  <para>If the Pending HPT is not fully prepared, return
                    H_LONG_BUSY_xxx with an estimate of the time remaining to
                    complete preparation.</para>
                </listitem>
                <listitem>
                  <para>Else return H_SUCCESS.</para>
                </listitem>
              </itemizedlist>
            </simplesect>
          </section>

          <section xml:id="sec_resize_hpt_commit">
            <title>H_RESIZE_HPT_COMMIT</title>

            <para>This hcall executes the commit phase of HPT resizing, making the
              Pending HPT the partition's current HPT. The caller must ensure that
              while it is executing, none of the partition's virtual CPU threads
              will update or access the HPT; that is, all threads must be executing
              in real mode, or stopped.</para>

            <simplesect>
              <title>Syntax:</title>
              <programlisting><![CDATA[int64                  /* H_Success:     Expected Return code */
                       /* H_AUTHORITY:   partition is not permitted to resize its */
                       /*                HPT */
                       /* H_CLOSED:      there is no suitable pending HPT */
                       /* H_PTEG_FULL:   two or more bolted HPTEs need the same slot */
                       /* H_BUSY:        preparation of the Pending HPT has not */
                       /*                completed */
hcall ( const int64 H_RESIZE_HPT_COMMIT, /* Function Code */
        uint64 flags,                    /* Special function indications */
        int32 shift );                   /* Log base 2 of new HPT size */]]></programlisting>

            </simplesect>

            <simplesect>
              <title>Parameters:</title>

              <itemizedlist>
                <listitem>
                  <para>flags: 0, as no flags are currently defined.</para>
                </listitem>
                <listitem>
                  <para>shift: Log base 2 of the total size in bytes of the
                    requested new HPT, between 18 and 46.</para>
                </listitem>
              </itemizedlist>
            </simplesect>

            <simplesect>
              <title>Semantics:</title>

              <itemizedlist>
                <listitem>
                  <para>Check that the partition is permitted to resize its HPT,
                    else return H_AUTHORITY.</para>
                </listitem>
                <listitem>
                  <para>Check if there is a Pending HPT; if there is not, then
                    return H_CLOSED.</para>
                </listitem>
                <listitem>
                  <para>Check that the flags parameter is zero and the shift
                    parameter matches the size of the Pending HPT; if not, then
                    return H_CLOSED.</para>
                </listitem>
                <listitem>
                  <para>Check that the Pending HPT is fully prepared; if not,
                    return H_BUSY.</para>
                </listitem>
                <listitem>
                  <para>If preparation of the Pending HPT was terminated due to finding
                    two bolted HPTEs that need to occupy the same
                    slot of the same HPTEG, then return H_PTEG_FULL.</para>
                </listitem>
                <listitem>
                  <para>Ensure that all bolted HPTEs from the partition's existing HPT
                    also exist, correctly hashed, in the Pending HPT. HPTEs transferred
                    from the existing HPT must have the same slot within their HPTEG in
                    the Pending HPT as they did in the existing HPT. If the Pending HPT
                    is smaller than the existing HPT, it is possible that two bolted HPTEs
                    that are in the same slot of two separate HPTEGs in the existing HPT
                    need to be put into the same HPTEG in the Pending HPT. If this occurs,
                    return H_PTEG_FULL.</para>
                </listitem>
                <listitem>
                  <para>Discard the partition's existing HPT.</para>
                </listitem>
                <listitem>
                  <para>Make the Pending HPT be the partition's current HPT.</para>
                </listitem>
                <listitem>
                  <para>Mark the partition as having no Pending HPT.</para>
                </listitem>
                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </simplesect>
          </section>
        </section>

      </section>

      <section>
        <title>Translation Control Entry Access</title>
        <para>The Translation Control Entry (TCE) access hcall()s take as a
        parameters the Logical I/O Bus Number (LIOBN) that is the logical bus
        number value derived from the
        <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property associated with
        the particular IOA. For the format of the
        <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property, reference
        <xref linkend="LoPAR.DeviceTree" />.</para>

        <section xml:id="dbdoclet.50569344_38645">
          <title>H_GET_TCE</title>
          <para>This hcall() returns the contents of a specified Translation
          Control Entry.</para>

          <simplesect>
            <title>Syntax:</title>

            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_PARTIAL: RPN not relative to callers logical address */
                       /*   space */
                       /* H_PARAMETER: LIOBN or IOBA out of range */
                       /* H_RESCINDED: A specified parameter refers to a rescinded */
                       /*   shared logical resource/
                       /* H_Hardware: The hardware experienced a fault causing the */
                       /*   function to fail. */
hcall ( const uint64 H_GET_TCE, /* Return the contents of the specified TCE */
        uint32 LIOBN,  /* Logical I/O Bus Number for TCE table to be accessed */
        uint64 IOBA ); /* I/O Bus Address for indexing into the TCE table */]]></programlisting>

          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>LIOBN (Logical I/O Bus Number for TCE table to be
                accessed)</para>
              </listitem>

              <listitem>
                <para>IOBA (I/O Bus Address for indexing into the TCE table)</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>If the LIOBN, or IOBA are outside of the range of calling
                partition assigned values return H_PARAMETER.</para>

                <itemizedlist>
                  <listitem>
                    <para>If the Shared Logical Resource option is implemented and the
                    LIOBN, or IOBA represents a logical resource that has been rescinded by
                    the owner, return H_RESCINDED.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Load R4 with the specified TCE contents.</para>
              </listitem>

              <listitem>
                <para>If specified TCE&#8217;s Page Mapping and Control bits (see
                <xref linkend="LoPAR.Platform" />) specify &#8220;Page Fault&#8221; then
                return H_Success</para>
              </listitem>

              <listitem>
                <para>Reverse translate the TCE&#8217;s RPN field into its logical page
                number</para>
              </listitem>

              <listitem>
                <para>If the logical page number is owned by the calling partition then
                replace the RPN field of R4 with the logical page number and return
                H_Success.</para>
              </listitem>

              <listitem>
                <para>Logically OR the contents of R4 with 0xFFFFFFFFFFFFF000 placing
                the result into R4.</para>
              </listitem>

              <listitem>
                <para>Return H_PARTIAL.</para>
              </listitem>
            </itemizedlist>

          </simplesect>
          </section>

        <section xml:id="dbdoclet.50569344_44496">
          <title>H_PUT_TCE</title>
          <para>This hcall() enters the mapping of a single 4 K page into the
          specified Translation Control Entry.</para>

          <simplesect>
            <title>Syntax:</title>

            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Parameter: One or more of the parameters were out of */
                       /*   range */
                       /* H_RESCINDED: A specified parameter refers to a rescinded */
                       /*   shared logical resource */
                       /* H_Hardware: The function failed due to unrecoverable */
                       /*   hardware error */
hcall ( const uint64 H_PUT_TCE, /* Function Token */
        uint32 LIOBN,  /* Logical I/O Bus Number of TCE table to be accessed (from */
                       /*   dma window property) */
        uint64 IOBA,   /* I/O Bus Address for indexing into TCE table */
        uint64 TCE     /* TCE contents to be stored in the TCE table (contains */
                       /*   logical address of storage page to be mapped */
      );]]></programlisting>

          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>If the LIOBN or IOBA parameters are outside of the range of
                calling partition assigned values return H_PARAMETER.</para>

                <itemizedlist>
                  <listitem>
                    <para>If the Shared Logical Resource option is implemented and the
                    LIOBN, or IOBA represents a logical resource that has been rescinded by
                    the owner, return H_RESCINDED.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>If the Page Mapping and Control field of the TCE is not
                &#8220;Page Fault&#8221; (see
                <xref linkend="LoPAR.Platform" />)</para>

                <itemizedlist>
                  <listitem>
                    <para>Then if the logical address within the TCE parameter is outside
                    of the range of calling partition assigned values</para>

                    <itemizedlist>
                      <listitem>
                        <para>Then return H_PARAMETER.</para>
                      </listitem>

                      <listitem>
                        <para>Else translate the logical address within the TCE parameter into
                        the corresponding physical real address.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>The hypervisor stores the TCE resultant value in the TCE table
                specified by the LIOBN and IOBA parameters; returning H_Success. (In the
                &#8220;Page Fault&#8221; case the RPN remains untranslated.)</para>

                <para><emphasis role="bold">Software Note:</emphasis> The PA requires the OS to issue a sync instruction
                to proceed the signalling of an IOA to start an IO operation involving
                DMA to guarantee the global visibility of both DMA and TCE data. This
                hcall() does not include a sync instruction to guarantee global
                visibility of TCE data and in no way diminishes the requirement for the
                OS to issue it.</para>
              </listitem>
            </itemizedlist>

          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_31179">
          <title>H_STUFF_TCE</title>
          <para>This hcall() duplicates the mapping of a single 4 K page through
          out a contiguous range of Translation Control Entries. Thus, in
          initializing and/or invalidating many entries. To retain interrupt
          responsiveness this hcall() should be called with a count parameter of no
          more than 512, LoPAR architecture provides enforcement for this
          restriction to aid in client code debug.</para>

          <simplesect>
            <title>Syntax:</title>

            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Parameter: One or more of the parameters were out of */
                       /*   range */
                       /* H_RESCINDED: A specified parameter refers to a rescinded */
                       /*   shared logical resource */
                       /* H_P4: The count parameter is greater than 512 */
                       /* H_Hardware: The function failed due to unrecoverable */
                       /*   hardware error */
hcall ( const uint64 H_STUFF_TCE, /* Function Token */
        uint32 LIOBN,  /* Logical I/O Bus Number of TCE table to be accessed (from */
                       /*   dma window prop.) */
        uint64 IOBA,   /* The starting I/O Bus Address for indexing into TCE table */
        uint64 TCE,    /* TCE contents to be stored in the TCE table (contains */
                       /*   logical address of storage page to be mapped*/
        uint64 count );/* The number of consecutive TCEs to fill */]]></programlisting>

          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>If the LIOBN, or IOBA, are outside of the range of calling
                partition assigned values return H_PARAMETER.</para>

                <itemizedlist>
                  <listitem>
                    <para>If the Shared Logical Resource option is implemented and the
                    LIOBN, or IOBA represents a logical resource that has been rescinded by
                    the owner, return H_RESCINDED.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>If the count parameter is greater than 512 then return
                H_P4</para>
              </listitem>

              <listitem>
                <para>If the count parameter added to the TCE index specified by IOBA
                is outside of the range of the calling partition assigned values return
                H_PARAMETER.</para>
              </listitem>

              <listitem>
                <para>If the Page Mapping and Control field of the TCE is not
                &#8220;Page Fault&#8221; (see
                <xref linkend="LoPAR.Platform" />)</para>

                <itemizedlist>
                  <listitem>
                    <para>Then if the logical address within the TCE parameter is outside
                    of the range of calling partition assigned values</para>

                    <itemizedlist>
                      <listitem>
                        <para>Then return H_PARAMETER.</para>

                        <itemizedlist>
                          <listitem>
                            <para>If the Shared Logical Resource option is implemented and the
                            logical address&#8217;s page number represents a page that has been
                            rescinded by the owner, return H_RESCINDED.</para>
                          </listitem>
                        </itemizedlist>
                      </listitem>

                      <listitem>
                        <para>Else translate the logical address within the TCE parameter into
                        the corresponding physical real address.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>The hypervisor stores the TCE resultant value in the TCE table
                entries specified by the LIOBN, IOBA and count parameters; returning
                H_Success. (In the &#8220;Page Fault&#8221; case the RPN remains
                untranslated.)</para>
              </listitem>
            </itemizedlist>

            <para><emphasis role="bold">Implementation Note:</emphasis> The PA requires the OS to issue a sync
            instruction to proceed the signaling of an IOA to start an IO operation
            involving DMA to guarantee the global visibility of both DMA and TCE
            data. This hcall() does not include a sync instruction to guarantee
            global visibility of TCE data and in no way diminishes the requirement
            for the OS to issue it.</para>
          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_50921">
          <title>H_PUT_TCE_INDIRECT</title>
          <para>This hcall() enters the mapping of up to 512 4 K pages into the
          specified Translation Control Entry. The LIOBN parameter if positive is
          the cookie (LIOBN) of the specific TCE table to load. For the Multi-TCE
          Table (MTT) option, if the LIOBN parameter is negative, CNT = the
          absolute value of LIOBN (up to 128), and the first CNT 8 byte entries of
          the buffer referenced by the TCE parameter contains the TCE table cookies
          (LIOBNs) for the various TCE tables to load (up to a maximum of 128 TCE
          tables).</para>
          <para>
          <emphasis role="bold">Note:</emphasis> Users of the MTT option that are subject to
          partition migration should be prepared for the loss of support for the
          MTT option after partition migration.</para>

          <simplesect>
            <title>Syntax:</title>

            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Parameter: One or more of the parameters were out of */
                       /*   range */
                       /* H_RESCINDED: A specified parameter refers to a rescinded */
                       /*   shared logical resource */
                       /* H_Function: The functional extension to multiple LIOBNs */
                       /*   is not enabled */
                       /* H_Hardware: The function failed due to unrecoverable */
                       /*   hardware error */
hcall ( const uint64 H_PUT_TCE_INDIRECT, /* Function Token */
        int64 LIOBN,   /* Logical I/O Bus Number of TCE table to be accessed (from */
                       /*   dma window property) or if negative, the number of */
                       /*   LIOBN fields in the buffer */
        uint64 IOBA,   /* The starting I/O Bus Address for indexing into TCE table */
        uint64 TCE,    /* The logical address of a page of (4 K long on a 4 K */
                       /*   boundary) of TCE contents to be stored in the TCE table */
                       /*   (contains logical address of storage page to be mapped) */
        uint64 count );/* The number of consecutive TCEs to fill */]]></programlisting>

          </simplesect>
          <simplesect>
            <title>Semantics:</title>
            <para>/* Validate the input parameters */</para>

            <itemizedlist>
              <listitem>
                <para>If the LIOBN parameter is non-negative then do</para>

                <itemizedlist>
                  <listitem>
                    <para>If the count parameter is &gt; 512 then return
                    H_Parameter.</para>
                  </listitem>

                  <listitem>
                    <para>If the Shared Logical Resource option is implemented and the
                    LIOBN parameter represents a TCE table that has been rescinded by the
                    owner, return H_RESCINDED.</para>
                  </listitem>

                  <listitem>
                    <para>If the LIOBN parameter represents a TCE table that is not valid
                    for the calling partition, return H_Parameter.</para>
                  </listitem>

                  <listitem>
                    <para>Liobns[0] = the LIOBN parameter.</para>
                  </listitem>

                  <listitem>
                    <para>If the Shared Logical Resource option is implemented and any of
                    the I/O bus address range represented the IOBA parameter plus count pages
                    within the TCE table represented by the LIOBN parameter represents
                    rescinded resource, return H_RESCINDED.</para>
                  </listitem>

                  <listitem>
                    <para>If any of the I/O bus address range represented the IOBA
                    parameter plus count pages within the TCE table represented by the LIOBN
                    parameter is not valid for the calling partition then return
                    H_Parameter.</para>
                  </listitem>

                  <listitem>
                    <para>end</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Else do</para>

                <itemizedlist>
                  <listitem>
                    <para>If the MTT Option is not enabled return H_Function.</para>
                  </listitem>

                  <listitem>
                    <para>If the LIOBN parameter &lt; -128 then return H_Parameter.</para>
                  </listitem>

                  <listitem>
                    <para>If the sum of the count parameter plus |LIOBN| is &gt; 512 then
                    return H_Parameter.</para>
                  </listitem>

                  <listitem>
                    <para>end</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>If the Shared Logical Resource option is implemented and the TCE
                parameter represents a logical page address of a page that has been
                rescinded by the owner, return H_RESCINDED.</para>
              </listitem>

              <listitem>
                <para>If the TCE parameter represents the logical page address of a
                page that is not valid for the calling partition, return
                H_Parameter.</para>
              </listitem>

              <listitem>
                <para>Copy the contents of the page referenced by the TCE table to a
                temporary hypervisor page (Temp) for validation without the potential for
                caller manipulation.</para>
              </listitem>
            </itemizedlist>



            <para>/* Validate the indirect parameters */</para>

            <itemizedlist>
              <listitem>
                <para>VAL= 0</para>
              </listitem>

              <listitem>
                <para>If the LIOBN parameter is negative then do</para>

                <itemizedlist>
                  <listitem>
                    <para>For CNT = 1,|LIOBN|,1</para>

                    <itemizedlist>
                      <listitem>
                        <para>T = 8 byte entry Temp [VAL]</para>
                      </listitem>

                      <listitem>
                        <para>If the Shared Logical Resource option is implemented and T as an
                        LIOBN represents a TCE table that has been rescinded by the owner, return
                        H_RESCINDED.</para>
                      </listitem>

                      <listitem>
                        <para>If T as an LIOBN represents a TCE table that is not valid for the
                        calling partition, return H_Parameter.</para>
                      </listitem>

                      <listitem>
                        <para>Liobns[VAL+] = T.</para>
                      </listitem>

                      <listitem>
                        <para>If the Shared Logical Resource option is implemented and any of
                        the I/O bus address range represented the IOBA parameter plus count pages
                        within the TCE table represented by &#8220;T&#8221; as an LIOBN
                        represents a rescinded resource, return H_RESCINDED.</para>
                      </listitem>

                      <listitem>
                        <para>If any of the I/O bus address range represented the IOBA
                        parameter plus count pages within the TCE table represented by
                        &#8220;T&#8221; as an LIOBN is not valid for the calling partition then
                        return H_Parameter.</para>
                      </listitem>

                      <listitem>
                        <para>loop</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>

                  <listitem>
                    <para>end</para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </itemizedlist>



            <para>/* Translate the logical pages addresses to physical*/</para>

            <itemizedlist>
              <listitem>
                <para>for CNT = 1,count,1</para>

                <itemizedlist>
                  <listitem>
                    <para>T = 8 byte entry Temp [VAL+]</para>
                  </listitem>

                  <listitem>
                    <para>If the Page Mapping and Control field of the 8 byte entry
                    &#8220;T&#8221; is not &#8220;Page Fault&#8221; (see
                    <xref linkend="LoPAR.Platform" />) then do</para>

                    <itemizedlist>
                      <listitem>
                        <para>If the Shared Logical Resource option is implemented and the
                        value of &#8220;T&#8221; as a logical address represents a page that has
                        been rescinded by the owner, then return H_RESCINDED.</para>
                      </listitem>

                      <listitem>
                        <para>If &#8220;T&#8221; as a logical address is outside of the range
                        of calling partition assigned values then return H_PARAMETER.</para>
                      </listitem>

                      <listitem>
                        <para>Translate the logical address within the TCE buffer entry into
                        the corresponding physical real address.</para>
                      </listitem>

                      <listitem>
                        <para>Temp[CNT - 1] = translated physical real address.</para>
                      </listitem>

                      <listitem>
                        <para>end</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>

                  <listitem>
                    <para>loop</para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </itemizedlist>



            <para>/* Fill the TCE table(s) */</para>

            <itemizedlist>
              <listitem>
                <para>If LIOBN parameter is negative then VAL = |LIOBN| else VAL =
                1.</para>
              </listitem>

              <listitem>
                <para>For TABS = 1, VAL, 1</para>

                <itemizedlist>
                  <listitem>
                    <para>The TCE table to fill is that referenced by Liobns[VAL] as an
                    LIOBN.</para>
                  </listitem>

                  <listitem>
                    <para>INDEX = the page index within the TCE table represented by the
                    IOBA parameter.</para>
                  </listitem>

                  <listitem>
                    <para>For CNT = 1, count, 1</para>

                    <itemizedlist>
                      <listitem>
                        <para>TCE_TABLE [Liobns[VAL], INDEX+] = Temp [CNT-1]</para>
                      </listitem>

                      <listitem>
                        <para>Loop</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>

                  <listitem>
                    <para>Loop</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Return H_Success.</para>
              </listitem>
            </itemizedlist>

            <para><emphasis role="bold">Implementation Note:</emphasis> The PA requires the OS to issue a sync
            instruction to proceed the signaling of an IOA to start an IO operation
            involving DMA to guarantee the global visibility of both DMA and TCE
            data. This hcall() does not include a sync instruction to guarantee
            global visibility of TCE data and in no way diminishes the requirement
            for the OS to issue it.</para>
          </simplesect>
        </section>

      </section>

      <section>
        <title>Processor Register Hypervisor Resource Access</title>
        <para>Certain processor registers are architecturally hypervisor
        resources, in the following cases the hypervisor provides controlled
        write access services.</para>

        <section xml:id="dbdoclet.50569344_77407">
          <title>H_SET_SPRG0</title>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64 hcall ( const uint64 H_SET_SPRG0, uint64 value );]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>value: The value to be written into SPRG0. No parameter checking
                is done against this value.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_91084">
          <title>H_SET_DABR</title>
          <para><emphasis role="bold">Note:</emphasis> Implementations reporting compatibility to ISA versions less
          than 2.07 are required to implement this interface; however, this
          interface is being deprecated in favor of
          <xref linkend="dbdoclet.50569344_97588" /> for newer
          implementations.</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64 hcall ( const uint64 H_SET_DABR, uint64 value );]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>If the platform does not implement the extended DABR facility
                then:</para>

                <itemizedlist>
                  <listitem>
                    <para>Validate the value parameter else return H_RESERVED_DABR and the
                    value in the DABR is not changed:</para>

                    <itemizedlist>
                      <listitem>
                        <para>The DABR BT bit (Breakpoint Translation) is checked for a value
                        of 1.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Else (The platform does implement the extended DABR
                facility):</para>

                <itemizedlist>
                  <listitem>
                    <para>Load the DABRX register with 0b0011.</para>
                  </listitem>

                  <listitem>
                    <para>place the value parameter into the DABR.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Return H_Success.</para>
              </listitem>
            </itemizedlist>

          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_36623">
          <title>H_PAGE_INIT</title>

          <simplesect>
            <title>Syntax:</title>

            <programlisting><![CDATA[int64 hcall ( const uint64 H_PAGE_INIT,
              uint64 flags,
              addr64 destination,
              addr64 source );]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>flags: zero, copy, I-Cache-Invalidate, I-Cache-Synchronize, and
                for the CMO option: CMO Option flags as defined in
                <xref linkend="dbdoclet.50569344_92498" />.</para>
              </listitem>

              <listitem>
                <para>destination: The logical address of the start of the page to be
                initialized</para>
              </listitem>

              <listitem>
                <para>source: The logical address of the start of the page use as the
                source on a page copy initialization. This parameter is only checked and
                used if the copy flag is set.</para>
              </listitem>
            </itemizedlist>

          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>The logical addresses are checked, they must both point to the
                start of a 4 K system memory page associated with the partition or return
                H_Parameter.</para>

                <itemizedlist>
                  <listitem>
                    <para>If the Shared Logical Resource option is implemented and the
                    source/destination logical page number represents a page that has been
                    rescinded by the owner, return H_RESCINDED.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>If the zero flag is set, clear the destination page using a
                platform specific routine (usually a series of dcbz instructions).</para>
              </listitem>

              <listitem>
                <para>If the copy flag is set, execute a platform specific optimized
                copy of the full 4 K page from the source to the destination.</para>
              </listitem>

              <listitem>
                <para>If I-Cache-Invalidate flag is set, issue icbi instructions for
                all of the page&#8217;s cache lines</para>
              </listitem>

              <listitem>
                <para>If I-Cache-Synchronize flag is set, issue dcbst and icbi
                instructions for all of the page&#8217;s cache lines. Implementations may
                need to issue a sync instruction to complete the coherency management of
                the I-Cache.</para>
              </listitem>

              <listitem>
                <para>For the CMO option: set the page usage state per the CMO Option
                flags field of the flags parameter as defined in
                <xref linkend="dbdoclet.50569344_92498" />.</para>
              </listitem>

              <listitem>
                <para>Return H_Success</para>
              </listitem>
            </itemizedlist>

            <para><emphasis role="bold">Note:</emphasis> For the CMO option, the CMO option flags may be
            used to notify the platform of the page usage state of a page without
            regard to its hardware page table entry or lack there of independent of
            any other option flags.</para>
          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_51622">
          <title>H_SET_XDABR</title>
          <para><emphasis role="bold">Note:</emphasis> Implementations reporting compatibility to ISA versions less
          than 2.07 are required to implement this interface; however, this
          interface is being deprecated in favor of
          <xref linkend="dbdoclet.50569344_97588" /> for newer
          implementations.</para>
          <para>This hcall() provides support for the extended Data Address
          Breakpoint facility. It sets the contents of the Data Address Breakpoint
          Register (DABR) and its companion Data Address Breakpoint Register
          Extension (DABRX). A principal advantage of the extended DABR facility is
          that it allows setting breakpoints for LPAR addresses that the hypervisor
          had to preclude using the previous facility.</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Hardware: hardware experienced an unrecoverable error */
                       /* H_Parameter: invalid parameter value */
hcall ( const uint64 H_SET_XDABR, /* Function Token */
        uint64 value,  /* Value to be placed in DABR register */
        uint64 extended ); /* Value to be place in DABRX register */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>
            <itemizedlist>
              <listitem>
                <para>Validates the extended parameter else return H_Parameter:</para>

                <itemizedlist>
                  <listitem>
                    <para>Reserved Bits (0-59) are zero.</para>
                  </listitem>

                  <listitem>
                    <para>The HYP bit (61) is off.</para>
                  </listitem>

                  <listitem>
                    <para>The rest of the PRIVM field (Bits 62-63) is one of those
                    supported:</para>

                    <itemizedlist>
                      <listitem>
                        <para>0b01 Problem State</para>
                      </listitem>

                      <listitem>
                        <para>0b10 Privileged non-hypervisor</para>
                      </listitem>

                      <listitem>
                        <para>0b11 Privileged or Problem State</para>
                      </listitem>

                      <listitem>
                        <para>(Specifying neither Problem or Privileged state is not
                        supported)</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>
                </itemizedlist>
              </listitem>
              <listitem>
                <para>Load the validated extended parameter into the DABRX</para>
              </listitem>
              <listitem>
                <para>Load the value parameter into the DABR</para>
              </listitem>
              <listitem>
                <para>Return H_Success.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_97588">
          <title>H_SET_MODE</title>
          <para>This hcall() is used to set hypervisor processing resource mode
          registers such as breakpoints and watchpoints. The modes supported by the
          hardware processor are a function of the processor architectural level as
          reported in the
          <emphasis role="bold"><literal>&#8220;cpu-version&#8221;</literal></emphasis> property.
          <xref linkend="dbdoclet.50569344_68462" /> presents the valid parameter
          ranges for the architectural level reported in the
          <emphasis role="bold"><literal>&#8220;cpu-version&#8221;</literal></emphasis> property
          and the LoPAR architecture level as reported in the
          <emphasis role="bold"><literal>&#8220;/chosen&#8221;</literal></emphasis> property.</para>

          <para>Setting breakpoints: A breakpoint is set for a hardware tread.
          Should the hardware thread complete an instruction who's effective
          address matches that of the set breakpoint a trace interrupt is signaled.
          When setting the breakpoint resource, the mflags and value2 parameters
          are zero. The value1 parameter is the effective address of the breakpoint
          to be set.</para>
          <para>Setting watchpoints: A watchpoint is set for a hardware tread.
          Should the hardware thread attempt to access within the specified double
          word range of the effective address specified by the value1 parameter as
          qualified by the conditions specified in the value2 parameter a Data
          Storage type interrupt is signaled. When setting the watchpoint resource,
          the mflags parameter is zero. The value1 parameter is the effective
          double word address of the watchpoint to be set. The value2 parameter
          specifies the qualifying conditions for the access, these are a subset of
          the POWER ISA conditions that are relevant within the context of a
          logical partition. This subset includes the MRD field, DW, DR, WT, WTI,
          PNH, and PRO bits. All other value2 fields are zero.</para>
          <para>Setting Interrupt Vector Location Modes: The Alternate Interrupt
          Location (AIL) Mode for the calling partition is set. Since this function
          has partition wide scope, it may take longer for the hypervisor to
          perform the function on all processors than is permissible during a
          synchronous call; therefore, the call might return long busy. In that
          case the caller should repeat the call with the same parameters after the
          specified time period until the H_SUCCESS return code is received. A call
          with different parameters indicates the beginning of a new partition wide
          mode setting. The desired AIL mode is encoded in the two low order mflags
          bits (all other mflags bits are 0) while both value1 and value2
          parameters are zero.</para>

          <para>The POWER ISA requires that the setting the LPCR ILE bit be the same
          in all partition processors when not in hypervisor mode thus all partition
          processors need to be operating with MSR[EE] = 0 when changing LPCR ILE so
          that the OS can change the contents of the interrupt vectors prior to any
          interrupts being taken in the new mode.</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_UNSUPPORTED_Flag: invalid mflags bit * /
                       /* H_P2: invalid resource encoding * /
                       /* H_P3: invalid value1 * /
                       /* H_P4: invalid value2 * /
                       /* H_LongBusyOrder10mSec: not done yet * /
hcall ( const uint64 H_SET_MODE, /* Set the mode of the specified processing */
                       /*   resource per the specified value*/
        uint64 mflags, /* Processing resource specific flags*/
        uint64 resource, /* Processing resource identifier */
        uint64 value1, /* Value(s) to set the resource */
        uint64 value2 );]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>
            <para><literallayout>switch (resource) {
    case 0: /* not used /
        return H_P2;
        break;
    case 1: /* Completed Instruction Address Breakpoint Register */
        if value2 &lt;&gt; 0 the return H_P4;
        if mflags &lt;&gt; 0 then return H_UNSUPPORTED_FLAG;
        If low order two bits of value1 are 0b11 then return H_P3; /* not hypervisor
            instruction address */
        move value 1 into CIABR; /* note the value2 parameter is not used for this resource */
        break;
    case2: /* Watch point 0 registers */
        if mflags &lt;&gt; 0 then return H_UNSUPPORTED_FLAG;
        If value2 bit 61 == 0b1 then return H_P4; /* not hypervisor addresses */
        move value1 into DAWR0;
        move value2 into DAWRX0;
        break;
    case3: / * Address Translation Mode on Interrupt * /
        if value1 &lt;&gt; 0 then return H_P3;
        if value2 &lt;&gt; 0 then return H_P4;
        switch (mflags) {
        case 0: / * IR = DR = 0 * /
            Set LPCR AIL field of calling partition processors to 0b00;
            break;
        case 1: / * reserved * /
            return H_UNSUPPORTED_FLAG ( - 318);
            break;
        case 2: / * IR = DR = 1 interrupt vectors at E.A. 0X18000 * /
            Set LPCR AIL field of calling partition processors to 0b10;
            break;
        case 3: / * IR = DR = 1 interrupt vectors at E.A. 0XC000 0000 0000 4000 * /
            Set LPCR AIL field of calling partition processors to 0b11;
            break;
        default:
            return H_UNSUPPORTED_FLAG (value based on most convenient unsupported bit);
            break;
/* Starting with PAPR Version 2.8 add the following */
    case 4: / * Set the LPCR ILE bit. * /
        if (value1) return H_P3;
        if (value2) return H_P4;
        switch (mflags) {
        case 0:
            Marshal all partition processors into the hypervisor
            If any partition processors were not running MSR[EE] = 0 then
                Release all marshaled processors and return bad_mode
            Else
                On each partition processor set LPCR[ILE] = 0
            return H_Success;
        case 1:
            Marshal all partition processors into the hypervisor
            If any partition processors were not running MSR[EE] = 0 then
                Release all marshaled processors and return bad_mode
            Else
                On each partition processor set LPCR[ILE] = 1
            return H_Success;
        default:
            return H_UNSUPPORTED_FLAG (value based on most convenient unsupported bit);
            break;
    default:
    return H_P2;
    break; }</literallayout></para>

            <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_68462">
              <title>H_SET_MODE Parameters per ISA Level</title>
              <?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
              <tgroup cols="6">
                <colspec colname="c1" colwidth="10*" align="center" />
                <colspec colname="c2" colwidth="15*" align="center" />
                <colspec colname="c3" colwidth="15*" align="center" />
                <colspec colname="c4" colwidth="15*" align="center" />
                <colspec colname="c5" colwidth="15*" align="center" />
                <colspec colname="c6" colwidth="30*" align="center" />
                <thead valign="middle">
                  <row>
                    <entry>
                      <para>
                        <emphasis role="bold">PAPR level</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">Supported Resource Values</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">Values Supported mflags</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">Value 1</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">Value 2</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">Comments&#160;</emphasis>
                      </para>
                    </entry>
                  </row>
                </thead>
                <tbody valign="middle">
                  <row>
                    <entry morerows="6">
                      <para>2.7</para>
                    </entry>
                    <entry>
                      <para>1</para>
                    </entry>
                    <entry>
                      <para>None</para>
                    </entry>
                    <entry>
                      <para>Breakpoint Address</para>
                    </entry>
                    <entry>
                      <para>None</para>
                    </entry>
                    <entry>
                      <para>&#160;</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>2</para>
                    </entry>
                    <entry>
                      <para>None</para>
                    </entry>
                    <entry>
                      <para>Watchpoint Double Word Address</para>
                    </entry>
                    <entry>
                      <para>Watchpoint Qualifying Conditions</para>
                    </entry>
                    <entry>
                      <para>&#160;</para>
                    </entry>
                  </row>
                  <row>
                    <entry morerows="4">
                      <para>3</para>
                    </entry>
                    <entry>
                      <para>0</para>
                    </entry>
                    <entry>
                      <para>None</para>
                    </entry>
                    <entry>
                      <para>None</para>
                    </entry>
                    <entry>
                      <para>IR=DR=0 No offset</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>1</para>
                    </entry>
                    <entry>
                      <para>None</para>
                    </entry>
                    <entry>
                      <para>None</para>
                    </entry>
                    <entry>
                      <para>Reserved</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>2</para>
                    </entry>
                    <entry>
                      <para>None</para>
                    </entry>
                    <entry>
                      <para>None</para>
                    </entry>
                    <entry>
                      <para>IR=DR=1 offset 0x18000</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>3</para>
                    </entry>
                    <entry>
                      <para>None</para>
                    </entry>
                    <entry>
                      <para>None</para>
                    </entry>
                    <entry>
                      <para>IR=DR=1 offset 0xC000 0000 0000 4000</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>All Others</para>
                    </entry>
                    <entry>
                      <para>All Others</para>
                    </entry>
                    <entry>
                      <para>All Others</para>
                    </entry>
                    <entry>
                      <para>Reserved</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                       <para>2.8</para>
                    </entry>
                    <entry>
                      <para>All Others</para>
                    </entry>
                    <entry>
                      <para>All Others</para>
                    </entry>
                    <entry>
                      <para>All Others</para>
                    </entry>
                    <entry>
                      <para>All Others</para>
                    </entry>
                    <entry>
                      <para>Reserved</para>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>

            <variablelist>
             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_97588"
                xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                  <listitem>
                    <para>For implementations supporting POWER
                    ISA level 2.07 and beyond: the platform must implement the H_SET_MODE
                    hcall() per the syntax and semantics of section
                    <xref linkend="dbdoclet.50569344_97588" /> per the LoPAR level supported.</para>
                  </listitem>
             	</varlistentry>
            </variablelist>

          </simplesect>
        </section>

        <section>
          <title>Implementation Dependent Optimizations</title>

          <para>All platforms contain implementation specific switches and values that effect the performance of the platform. The default
          settings for switches and values are tuned during platform development to achieve the desired performance characteristics
          across a wide range of workloads. However, the performance of specific workloads might be further
          optimized by adjusting some of these implementation specific switches and values when those workloads are being
          run. Other of these switches and values might have negative effects on other platform workloads, so those switches and
          values are protected from modification lest innocent partitions become victims of one of their neighbors. LoPAR version
          2.8 and above provide the hcall()s defined below to set a subset of the implementaion specific switches and adjust a
          subset of the tuning values within a range that has been proven to be safe. The caller is expected to understand the
          switch banks and resources implemented by the specific platform and the functinality of each individual switch and resource.</para>

          <para>Special consideration is required of the caller of these functions during partition migration and micro-checkpoint/
          failover operations since the underlying implementation might change. During these operarations, the implementation
          dependent switches and values are set to their default values for the implementation that is receiving the
          partition. After a migration or failover event the availability of the Implementation Dependent Optimization hcall()s
          might change, along with the resources and/or switch banks that might be adjusted, and the supported values for those
          adjustments.</para>

          <section xml:id="sec_adjust_resource">
            <title>H_ADJUST_RESOURCE</title>

            <para>This hcall() is used to adjust the value of a given implementation dependent resource in contiguous unit steps between
            the minimum and maximum supported values. These steps are not necessarily uniform either in physical values set into
            the implementation dependent resource or the resultant effect they have on workload performance.</para>

            <simplesect>
              <title>Syntax:</title>
              <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Hardware: Hardware Error */
                       /* H_Parameter: Illegal Resource Value */
                       /* H_RESERVED: Reserved Resource value specified */
                       /* H_UNSUPPORTED: Resource value not supported on this */
                       /*   platform */
                       /* H_Constrained: Resource value adjusted to the */
                       /*   maximum supported value */
hcall ( const uint64 H_ADJUST_RESOURCE, /* Function Code */
        uint64 Resource, /* Resource to be adjusted */
                         /*   Defined Values: */
                         /*     0: Not used return H_PARAMETER */
                         /*     1: Medium Low Relative Thread Priority */
                         /*     2: Medium High Relative Thread Priority */
                         /*     All other values reserved.  Return H_RESERVED. */
        uint64 Value); /* Steps to adjust Resource may be positive or negative */
                       /* Value = 0 does not change resource but does return values */]]></programlisting>
            </simplesect>

            <simplesect>
              <title>Semantics:</title>
              <itemizedlist>
                <listitem>
                  <para>If the value of the Resource parameter is zero then return H_PARAMETER</para>
                </listitem>
                <listitem>
                  <para>If the value of the Resource parameter is greater than the maximum defined
                  value then return H_RESERVED</para>
                </listitem>
                <listitem>
                  <para>If the value of the Resource paramter is not supported on this implementation
                  then return H_UNSUPPORTED</para>
                </listitem>
                <listitem>
                  <para>RC = H_Success</para>
                </listitem>
                <listitem>
                  <para>Current = current value of the Resource</para>
                </listitem>
                <listitem>
                  <para>If Current + Value &gt; max supported value of Resource then</para>
                  <itemizedlist>
                    <listitem>
                      <para>{ RC = H_Constrained ;</para>
                    </listitem>
                    <listitem>
                      <para>Current = max supported value of Resource }</para>
                    </listitem>
                  </itemizedlist>
                </listitem>
                <listitem>
                  <para>If Current + Value &lt; min supported value of Resource then</para>
                  <itemizedlist>
                    <listitem>
                      <para>{ RC = H_Constrained ;</para>
                    </listitem>
                    <listitem>
                      <para>Current = min supported value of Resource }</para>
                    </listitem>
                  </itemizedlist>
                </listitem>
                <listitem>
                  <para>Set Resource to Current</para>
                </listitem>
                <listitem>
                  <para>On return:</para>
                  <itemizedlist>
                    <listitem>
                      <para>R3: Contains Return Code (RC)</para>
                    </listitem>
                    <listitem>
                      <para>R4: Contains the Resource value (Current) (Return codes H_Success &amp; H_Constrained)</para>
                    </listitem>
                    <listitem>
                      <para>R5: Contains the number of steps to minimum supported resource value</para>
                    </listitem>
                    <listitem>
                      <para>R6: Contains the number of steps to maximum Suppported resource value</para>
                    </listitem>
                  </itemizedlist>
                </listitem>
              </itemizedlist>
            </simplesect>
          </section>

          <section xml:id="sec_set_switches">
            <title>H_SET_SWITCHES</title>

            <para>This hcall() provides for the setting of an implementation dependent subset of the switches in an implementation dependent
            bank of switches.</para>

            <simplesect>
              <title>Syntax:</title>
              <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Hardware: Hardware Error */
                       /* H_Parameter: Illegal Bank Value */
                       /* H_RESERVED: Reserved Bank value specified */
                       /* H_UNSUPPORTED: Bank value not supported on this */
                       /*   implementation */
                       /* H_Constrained: Mask parameter specified one */
                       /*   or more switches whose settings are not */
                       /*   supported -- other switches are set */
hcall ( const uint64 H_SET_SWITCHES, /* Function Code */
        uint64 Bank,   /* The Bank of switches to be set */
                       /*   Defined Values: */
                       /*     0: Not used return H_PARAMETER */
                       /*     1: Workload Optimization Register - Core (WORC) */
                       /*     All other values reserved.  Return H_RESERVED. */
        uint64 Mask,   /* Specifies which switches are to be set */
                       /*   ( = 0 does not change the bank but does return values) */
        uint64 Setting); /* The setting of those switches specified by */
                         /*   the Mask parameter */]]></programlisting>
            </simplesect>

            <simplesect>
              <title>Semantics:</title>
              <itemizedlist>
                <listitem>
                  <para>If the value of the Bank parameter is zero then return H_PARAMETER</para>
                </listitem>
                <listitem>
                  <para>If the value of the Bank parameter is greater than the maximum defined
                  value then return H_RESERVED</para>
                </listitem>
                <listitem>
                  <para>If the value of the Bank paramter is not supported on this implementation
                  then return H_UNSUPPORTED</para>
                </listitem>
                <listitem>
                  <para>If (Mask &amp; not (Supported-bits-in[Bank]) ) then RC = H_Constrained
                  else RC = H_Success</para>
                </listitem>
                <listitem>
                  <para>Turn on the bits in switches[Bank] that are ones in all three of
                  Supported-bits-in[Bank], Mask, and Setting</para>
                </listitem>
                <listitem>
                  <para>Turn off the bits in switches[Bank] that are ones in both
                  Supported-bits-in[Bank] and Mask but are zeros in Setting</para>
                </listitem>
                <listitem>
                  <para>On return:</para>
                  <itemizedlist>
                    <listitem>
                      <para>R3: Contains Return Code (RC)</para>
                    </listitem>
                    <listitem>
                      <para>R4: Contains the Mask value representing all switches who's setting is supported for the bank</para>
                    </listitem>
                    <listitem>
                      <para>R5: Contains the Bank value (Return codes H_Success &amp; H_Constrained)</para>
                    </listitem>
                  </itemizedlist>
                </listitem>
              </itemizedlist>
            </simplesect>
          </section>
        </section>
      </section>

      <section>
        <title>Debugger Support hcall()s</title>
        <para>The real mode debugger needs to be able to get to its async port
        and beyond the real mode limit register without turning on virtual
        address translation. The following hcall()s provide that
        capability.</para>

        <section xml:id="dbdoclet.50569344_96762">
          <title>H_LOGICAL_CI_LOAD</title>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64 hcall ( const uint64 H_LOGICAL_CI_LOAD, uint64 size, uint64 addr );]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>size: The size of the cache inhibited load:</para>

                <itemizedlist>
                  <listitem>
                    <para>byte = 1</para>
                  </listitem>

                  <listitem>
                    <para>half = 2</para>
                  </listitem>

                  <listitem>
                    <para>full = 4</para>
                  </listitem>

                  <listitem>
                    <para>double=8</para>
                  </listitem>

                  <listitem>
                    <para>All other size values are illegal and returns H_Parameter</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>addr: The logical address of the cache inhibited location to be
                read. The hypervisor checks that the address is within the range of
                addresses valid for the partition, on a boundary equal to the requested
                length, is not to the location BA+4 within an interrupt management area,
                and mapped as cache inhibited (cache paradoxes are to be avoided)-- Else
                H_Parameter.</para>
              </listitem>

              <listitem>
                <para>On successful return (H_Success), the read value is low order
                justified in register R4.</para>
              </listitem>
            </itemizedlist>

          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_70927">
          <title>H_LOGICAL_CI_STORE</title>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64 hcall ( const uint64 H_LOGICAL_CI_STORE,
              uint64 size,
              uint64 addr,
              uint64 value );]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>size: The size of the cache inhibited store:</para>

                <itemizedlist>
                  <listitem>
                    <para>byte = 1</para>
                  </listitem>

                  <listitem>
                    <para>half = 2</para>
                  </listitem>

                  <listitem>
                    <para>full = 4</para>
                  </listitem>

                  <listitem>
                    <para>double=8</para>
                  </listitem>

                  <listitem>
                    <para>All other size values are illegal and returns H_Parameter</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>addr: The logical address of the cache inhibited location to be
                written. The hypervisor checks that the address is within the range of
                addresses valid for the partition, on a boundary equal to the requested
                length, is not to the location BA+4 within an interrupt management area,
                and mapped as cache inhibited (cache paradoxes are to be avoided).</para>
              </listitem>

              <listitem>
                <para>value The value to be written is low order justified in register
                R6.</para>
              </listitem>
            </itemizedlist>

          </simplesect>
        </section>
      </section>

      <section>
        <title>Virtual Terminal Support</title>
        <para>This section has been moved to
        <xref linkend="dbdoclet.50569352_15379" />.</para>
        <para>
        <emphasis role="bold">Architecture and Implementation Note:</emphasis> The requirement
        to provide the
        <emphasis role="bold"><literal>&#8220;ibm,termno&#8221;</literal></emphasis> property in the
        <emphasis role="bold"><literal>/rtas</literal></emphasis> node, has been removed (it is now necessary to
        look for
        <emphasis role="bold"><literal>vty</literal></emphasis> nodes and use their unit address from the
        <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property to get the same
        information). The
        <emphasis role="bold"><literal>&#8220;ibm,termno&#8221;</literal></emphasis> property called for
        sequential terminal numbers, but with the use of unit addresses from the
        <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property, such is not the
        case.</para>
      </section>

      <section>
        <title>Dump Support hcall()s</title>
        <para>To allow the OS to dump hypervisor data areas in support of field
        problem diagnosis the hcall-dump support function set contains the
        H_HYPERVISOR_DATA hcall(). This hcall() is enabled or disabled (default
        disabled) via the Hardware Management Console. If the hcall-dump function
        set is disabled an attempt to make a H_HYPERVISOR_DATA hcall() returns
        H_Function. When the function is enabled, the hcall-dump function set is
        specified in the
        <emphasis role="bold"><literal>&#8220;ibm,hypertas-functions&#8221;</literal></emphasis> property. The
        requester calls repeatedly starting with a control value of zero getting
        back 64 bytes per call and setting the control parameter on the next call
        to the previous call&#8217;s return code until the hcall() returns
        H_Parameter indicating that all hypervisor data has been dumped. The
        precise meaning of the sequence of data is implementation dependent. The
        H_HYPERVISOR_DATA hcall() need only return data in the firmware working
        storage that is not contained in the PFT or TCE tables since the contents
        of these tables are available to the OS.</para>

        <para>Starting with LoPAR Version 2.8 PAPR platforms support the
        H_CLEAR_HPT hcall() independent of Client Architecture support negotiation.</para>

        <section xml:id="dbdoclet.50569344_34502">
          <title>H_HYPERVISOR_DATA</title>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64 hcall ( const uint64 H_HYPERVISOR_DATA, uint64 control );]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>control: A value passed to establish the progress of the
                dump.</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>If the control value is zero, the data returned is the first
                segment of the hypervisor&#8217;s working storage, with a non-negative
                return code.</para>
              </listitem>

              <listitem>
                <para>If the control value is equal to the return code of the last
                H_HYPERVISOR_DATA call, and the return code is non-negative, the data
                returned in R4 through R11 is the next sequential segment of the
                hypervisor&#8217;s working storage. The contents of R4 through R11 are
                undefined if the return code is negative.</para>
              </listitem>
            </itemizedlist>

            <para><emphasis role="bold">Implementation Note:</emphasis> It is expected that the control
            value is be used by the H_HYPERVISOR_DATA routine as an offset into the
            hypervisor&#8217;s data area. For the expected implementation, hypervisor
            checks the value of the control parameter to insure that the resultant
            pointer is within hypervisor&#8217;s data area else it returns
            H_Parameter.</para>
          </simplesect>
        </section>

        <section xml:id="sec_clear_hpt">
          <title>H_CLEAR_HPT</title>

          <para>This hcall() clears the hash page table (HPT) for a partition in preparation for a restart. The Virtual Real
          Mode Area and Partition Adjunct mappings are exempted. The performance class of this hcall() is
          “Terminal”, that is, it is allowed to take as long as it needs to perform the operation in a single call,
          however, it is also allowed to return H_CONTINUE, at which time the caller needs to again make the call
          until it receives H_Success else the partition HPT might be left in an inconsistent state. Never the less, the
          reason for this hcall() is to optimize the performance of this function relative to a series of H_REMOVE
          calls, therefore, hypervisors are encouraged to perform portions of the function in parallel using as many
          partition processor threads as is practical.</para>

          <para>The hypervisor clears the partition’s HT entries (sets them to invalid) except for those entries mapping the
          VRMA, or a Partition Adjunct, performs a TLBIA on all partition processor threads, and returns H_Success
          on the calling thread.</para>

          <para>To avoid translation exceptions, attempting to access pages whose translations are being cleared, all OS
          processor threads should be operating MSR[IR] = MSR[DR] = MSR[PR] = 0b0. Any attempt to use one of
          the HPT access hcall(s) (See <xref linkend="sec_pft_access" />) during the
          clearing process might result in the an H_Busy return code, and/or the processor might be pressed into
          service clearing the HPT.</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success: Expected completion return code */
                       /* H_CONTINUE: The function has not completed, call again */
hcall ( const uint64 H_CLEAR_HPT);]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Disable other HPT access hcall()s</para>
              </listitem>

              <listitem>
                <para>For each HPT entry</para>

                <itemizedlist>
                  <listitem>
                    <para>If the entry does not map the VRMA or Partition Adjunct clear the V bit</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>For each partition processor perform a TLBIA</para>
              </listitem>

              <listitem>
                <para>Enable other HPT access hcall()s</para>
              </listitem>

              <listitem>
                <para>Return H_Success</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>
      </section>

      <section xml:id="dbdoclet.50569344_26787">
        <title>Interrupt Support hcall()s</title>

        <para><xref linkend="table_xive_legacy_vs_exploitation" />
          below describes legacy vs exploitation differences related to the client
          architecture, device tree and hcalls. The symbol @ESB refers to a logical
          real address returned from the hcall()
          <xref linkend="sec_int_get_source_info" xrefstyle="select: title nopage"/>. The symbol
          @TIMA refers to the logical real address in the
          <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
          property of the
          External Interrupt Virtualization Node.</para>

        <table frame="all" pgwide="1" xml:id="table_xive_legacy_vs_exploitation">
          <title>XIVE Legacy vs. Exploitation Mode Hypervisor Call Function Table</title>
          <tgroup cols="2">
            <colspec colname="c1" colwidth="50*" align="center" />
            <colspec colname="c2" colwidth="50*" align="center" />
            <thead valign="middle">
              <row>
                <entry>
                  <para>
                    <emphasis role="bold">Legacy</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Exploitation Mode</emphasis>
                  </para>
                </entry>
              </row>
            </thead>
            <tbody valign="middle">
              <row>
                <entry>
                  <para>Client Architecture Support<?linebreak?>
                    Option Vector 5 Byte 23 bits 0-1 undefined or 0b00</para>
                  <para>
                    <literal>/chosen</literal>
                    <emphasis role="bold"><literal>&#8220;ibm,architecture-vec&#8221;</literal></emphasis> Byte 23 bits 0-1 undefined or 0b00<footnote xml:id="fn_cas_option_vec_p9">
                      <para>See ibm,architecture vector 5, byte 23 in
                        <xref linkend="LoPAR.DeviceTree" />
                        for more details.
                      </para>
                    </footnote>
                  </para>
                </entry>
                <entry>
                  <para>Client Architecture Support<?linebreak?>
                    Option Vector 5 Byte 23 bits 0-1 undefined or 0b00</para>
                  <para>
                    <literal>/chosen</literal>
                    <emphasis role="bold"><literal>&#8220;ibm,architecture-vec&#8221;</literal></emphasis> Byte 23 bits 0-1 value 0b01<footnoteref linkend="fn_cas_option_vec_p9" />
                  </para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>“ibm,get-xive”</para>
                </entry>
                <entry>
                  <para>hcall() <xref linkend="sec_int_get_source_config" xrefstyle="select: title nopage" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>“ibm,set-xive”</para>
                </entry>
                <entry>
                  <para>hcall() <xref linkend="sec_int_set_source_config" xrefstyle="select: title nopage" /><?linebreak?>
                    hcall() <xref linkend="sec_int_set_queue_config" xrefstyle="select: title nopage" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>“ibm,int-off”</para>
                </entry>
                <entry>
                  <para>CI load double to @ESB + 0xD00<footnote xml:id="fn_xive_spec">
                    <para>See XIVE specification for details on the CI operations.</para></footnote>
                  </para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>“ibm,int-on”</para>
                </entry>
                <entry>
                  <para>CI load double to @ESB + 0xC00<footnoteref linkend="fn_xive_spec" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>“set-indicator” with indicator 9005</para>
                </entry>
                <entry>
                  <para>Same</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>“get-sensor-state” with indicator 9005</para>
                </entry>
                <entry>
                  <para>Same</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>H_EOI</para>
                </entry>
                <entry>
                  <para>CI load double to @ESB + 0xC00 if store EOI is not
                    enabled<footnoteref linkend="fn_xive_spec" /><?linebreak?>
                  CI store double to @ESB + 0x400 if store EOI is
                  enabled<footnoteref linkend="fn_xive_spec" /><?linebreak?>
                  CI store byte to @TIMA + 0x11 of pre-interrupt
                  CPPR<footnoteref linkend="fn_xive_spec" />
                </para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>H_CPPR</para>
                </entry>
                <entry>
                  <para>CI store byte to @TIMA + 0x11 of new CPPR<footnoteref linkend="fn_xive_spec" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>H_IPI</para>
                </entry>
                <entry>
                  <para>CI store byte to @ESB + 0x00<footnoteref linkend="fn_xive_spec" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para> H_IPOLL </para>
                </entry>
                <entry>
                  <para>CI load byte from @TIMA + 0x10<footnoteref linkend="fn_xive_spec" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>H_XIRR</para>
                </entry>
                <entry>
                  <para>CI load half word from @TIMA + 0x810<footnoteref linkend="fn_xive_spec" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>H_XIRR-X</para>
                </entry>
                <entry>
                  <para>Deprecated</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>H_VIO_SIGNAL</para>
                </entry>
                <entry>
                  <para>Same<footnote xml:id="fn_race_condition">
                    <para>The following are clarified in the hcall definition:</para>
                    <orderedlist spacing="compact">
                      <listitem>
                        <para>A race between a VIO virtual adapter generating a new
                          interrupt and a H_VIO_SIGNAL() or H_VIOCTL() hcall
                          could have multiple outcomes. H_VIO_SIGNAL()/H_VIOCTL()
                          wins and the interrupt does not occur, or the new interrupt
                          wins and one device interrupt occurs after H_VIO_SIGNAL()/H_VIOCTL()
                          call returns.</para>
                      </listitem>
                      <listitem>
                        <para>Interrupting events that occur while H_VIO_SIGNAL()/H_VIOCTL()
                          has disabled interrupts will never generate an interrupt.</para>
                      </listitem>
                    </orderedlist></footnote>
                  </para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>H_VIOCTL with sub functions:<?linebreak?>
                    DISABLE_ALL_VIO_INTERRUPTS<?linebreak?>
                    DISABLE_VIO_INTERRUPT<?linebreak?>
                    ENABLE_VIO_INTERRUPT</para>
                </entry>
                <entry>
                  <para>Same<footnoteref linkend="fn_race_condition" /></para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <table frame="all" pgwide="1" xml:id="table_hypervisor_call_functions_unique_to_xive_exploitation">
          <?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
          <title>Hypervisor Call Functions Unique to XIVE Exploitation</title>
          <tgroup cols="2">
            <colspec colname="c1" colwidth="60*"/>
            <colspec colname="c2" colwidth="40*"/>
            <thead valign="middle">
              <row>
                <entry align="center" >
                  <para>
                    <emphasis role="bold">Function Description</emphasis>
                  </para>
                </entry>
                <entry align="center" >
                  <para>
                    <emphasis role="bold">HCALL</emphasis>
                  </para>
                </entry>
              </row>
            </thead>
            <tbody valign="middle">
              <row>
                <entry>
                  <para>Get the ESB addresses for a LISN</para>
                </entry>
                <entry>
                  <para><xref linkend="sec_int_get_source_info" xrefstyle="select: title nopage" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Assign a target and priority to a LISN</para>
                </entry>
                <entry>
                  <para><xref linkend="sec_int_set_source_config" xrefstyle="select: title nopage" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Get the target and priority assigned to a LISN</para>
                </entry>
                <entry>
                  <para><xref linkend="sec_int_get_source_config" xrefstyle="select: title nopage" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Get the notification management page for a LISN</para>
                </entry>
                <entry>
                  <para><xref linkend="sec_int_get_queue_info" xrefstyle="select: title nopage" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Set/Reset an EQ for a target and priority</para>
                </entry>
                <entry>
                  <para><xref linkend="sec_int_set_queue_config" xrefstyle="select: title nopage" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Get the EQ set for a target and priority</para>
                </entry>
                <entry>
                  <para><xref linkend="sec_int_get_queue_config" xrefstyle="select: title nopage" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Set the OS reporting cache line pair for a target</para>
                </entry>
                <entry>
                  <para><xref linkend="sec_int_set_os_reporting_line" xrefstyle="select: title nopage" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Get the OS reporting cache line pair for a target </para>
                </entry>
                <entry>
                  <para><xref linkend="sec_int_get_os_reporting_line" xrefstyle="select: title nopage" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Load or store operation on the ESB page for a LISN</para>
                </entry>
                <entry>
                  <para><xref linkend="sec_int_esb" xrefstyle="select: title nopage" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Issue the requested sync</para>
                </entry>
                <entry>
                  <para><xref linkend="sec_int_sync" xrefstyle="select: title nopage" /></para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Reset interrupt state to the initial state</para>
                </entry>
                <entry>
                  <para><xref linkend="sec_int_reset" xrefstyle="select: title nopage" /></para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <para>Injudicious values written to the interrupt source controller may
        affect innocent partitions. The following hcall()s monitor the
        architected functions.</para>

        <section xml:id="dbdoclet.50569344_20734">
          <title>H_EOI</title>
          <para>
          <emphasis role="bold">Software Implementation Note:</emphasis> Issuing more H_EOI
          calls than actual interrupts may cause undesirable behavior, including
          but not limited to lost interrupts, and excessive phantom
          interrupts.</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64 hcall ( const uint64 H_EOI, uint64 xirr );]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>xirr: The low order 32 bits is the value to be written into the
                calling processor&#8217;s interrupt management area&#8217;s external
                interrupt request register (xirr).</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>If the platform implements the Platform Reserved Interrupt
                Priority Level Option, and the priority field of the xirr parameter
                matches one of the reserved interrupt priorities then return
                H_Resource.</para>
              </listitem>

              <listitem>
                <para>If the value of the xirr parameter is such that the low order 3
                bytes (xisr) is one of the interrupt source values assigned to the
                partition, and the high order byte xirr byte (cppr) is equal or less
                favored than the current cppr contents, then the value is written into
                the calling processor&#8217;s xirr causing the interrupt source
                controller to signal an &#8220;end of interrupt&#8221; (EOI) to the
                specified interrupt source logic, then hypervisor returns H_Success or
                H_Hardware (if an unrecoverable hardware error occurred). If the xirr
                value is not legal, hypervisor returns H_Parameter.</para>

                <itemizedlist>
                  <listitem>
                    <para>If the Shared Logical Resource option is implemented and the xirr
                    parameter represents a shared logical resource location that has been
                    rescinded by the owner, return H_RESCINDED.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>If the partition is not in XIVE legacy mode, the Hypervisor returns
                H_Function.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_29571">
          <title>H_CPPR</title>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64 hcall ( const uint64 H_CPPR, uint64 cppr );]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>cppr: The low order byte is the value to be written into the
                calling processor&#8217;s interrupt management area&#8217;s current
                processor priority register (cppr).</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>If the platform implements the Platform Reserved Interrupt
                Priority Level Option, and the priority field of the xirr parameter
                matches one of the reserved interrupt priorities then return
                H_Resource.</para>
              </listitem>

              <listitem>
                <para>The value of the cppr parameter is written into the calling
                processor&#8217;s cppr causing the interrupt source controller to reject
                any interrupt of equal or less favored priority. Then hypervisor returns
                H_Success or H_Hardware (if an unrecoverable hardware error
                occurred).</para>
              </listitem>

              <listitem>
                <para>If the partition is not in XIVE legacy mode, the Hypervisor returns
                H_Function.</para>
              </listitem>

            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_16166">
          <title>H_IPI</title>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64 hcall ( const uint64 H_IPI, uint64 server#, uint64 mfrr );]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>server#: The server number gotten from the
                <emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis>
                 property associated with the processor and/or thread
                to be interrupted.</para>
              </listitem>

              <listitem>
                <para>mfrr: The priority value the inter-processor interrupt to be
                signaled.</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>If the platform implements the Platform Reserved Interrupt
                Priority Level Option, and the priority field of the xirr parameter
                matches one of the reserved interrupt priorities then return
                H_Resource.</para>
              </listitem>

              <listitem>
                <para>If the value of the server# parameter specifies of one of the
                processors in the calling processor&#8217;s partition, then the value in
                the low order byte of the mfrr parameter is written into the mfrr
                register (BA+12) of the processor&#8217;s interrupt management area
                causing that interrupt source controller to signal an
                &#8220;inter-processor interrupt&#8221; (IPI) to the processor associated
                with the specified interrupt management area. Hypervisor then returns
                H_Success or H_Hardware (if an unrecoverable hardware error occurred). If
                the server# value is not legal, hypervisor returns H_Parameter.</para>

                <itemizedlist>
                  <listitem>
                    <para>If the Shared Logical Resource option is implemented and the
                    server# parameter represents a shared logical resource location that has
                    been rescinded by the owner, return H_RESCINDED.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>If the partition is not in XIVE legacy mode, the Hypervisor returns
                H_Function.</para>
              </listitem>

            </itemizedlist>

          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_23590">
          <title>H_IPOLL</title>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64 hcall ( const uint64 H_IPOLL, uint64 server# );]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>server#: The server number gotten from the
                <emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis>
                 property associated with the processor and/or tread
                to be interrupted.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>If the value of the server# parameter specifies of one of the
                processors in the calling processor&#8217;s partition, then hypervisor
                reads the 4 byte contents of the processor&#8217;s interrupt management
                area port at offset BA+0 into the low order 4 bytes of register R4 and
                the one byte of the mfrr (BA+12) into the low order byte of R5. Reading
                these addresses has no side effects and is used to poll for pending
                interrupts. Hypervisor then returns H_Success or H_Hardware (if an
                unrecoverable hardware error occurred). If the server# value is not
                legal, hypervisor returns H_Parameter.</para>

                <itemizedlist>
                  <listitem>
                    <para>If the Shared Logical Resource option is implemented and the
                    server# parameter represents a shared logical resource location that has
                    been rescinded by the owner, return H_RESCINDED.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>If the partition is not in XIVE legacy mode, the Hypervisor returns
                H_Function.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_26587">
          <title>H_XIRR / H_XIRR-X</title>
          <para>These hcall()s provide the same base function that is they return
          the interrupt source number associated with the external interrupt.
          H_XIRR-X further supplies the time stamp of the interrupt . Legacy
          implementations implement only H_XIRR, returning H_Function for a call to
          H_XIRR-X. POWER8 implementations also implement H_XIRR-X.</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64 hcall ( const uint64 H_XIRR );

int64                  /* H_Success: Expected Return code */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
                       /* H_Function: The calling OS is not in XIVE legacy mode */
hcall ( const uint64 H_XIRR-X,/* Accept an interrupt returning the external  */
                       /*   interrupt request register */
        uint8 cppr );]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>H_XIRR: no input parameters defined.</para>
              </listitem>

              <listitem>
                <para>H_XIRR-X: cppr: the internal current processor priority of the
                calling virtual processor. Valid values in the range of 0x00 - most
                favored to 0xFF - least favored less those values specified by the
                <emphasis role="bold"><literal>&#8220;ibm,plat-res-int-priorities&#8221;</literal></emphasis> property in
                the <emphasis role="bold"><literal>root</literal></emphasis> node).</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Hypervisor reads the 4 byte contents of the processor&#8217;s
                interrupt management area port at offset BA+4 into the low order 4 bytes
                of the register R4. Reading this address has the side effect of accepting
                the interrupt and raising the current processor priority to that of the
                accepted interrupt.</para>
              </listitem>

              <listitem>
                <para>Place the timestamp when the hypervisor first received the
                interrupt into R5.</para>
              </listitem>

              <listitem>
                <para>Hypervisor then returns H_Success or H_Hardware (if an
                unrecoverable hardware error occurred).</para>
              </listitem>

              <listitem>
                <para>If the partition is not in XIVE legacy mode, the Hypervisor returns
                H_Function.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="sec_int_get_source_info">
          <title>H_INT_GET_SOURCE_INFO</title>

          <para>The H_INT_GET_SOURCE_INFO hcall() is used to obtain the logical real
            address of the MMIO page through which the Event State Buffer entry
            associated with the value of the “lisn” parameter is managed.
            The initial state of the ESB PQ bits will be the architected off value
            of 0b01. The “lisn” parameter can come from several different properties
            or hcalls. For example, the “lisn” parameter value for I/O adapters is
            passed to a partition through the
            <emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis> and
            <emphasis role="bold"><literal>&#8220;interrupt-map&#8221;</literal></emphasis> properties
            in the device tree node describing the I/O adapter. Alternatively, for
            inter processor interrupts, the “lisn” parameter is a value the OS chooses
            from a range of LISNs from the
            <emphasis role="bold"><literal>&#8220;ibm,xive-lisn-ranges&#8221;</literal></emphasis> property.
            While for platform accelerators, the “lisn” parameter is a value returned
            by the allocating hcall(), H_ALLOCATE_VAS_WINDOW. Depending upon the specific
            Logical Interrupt Source, there might be either one or two page addresses
            assigned to the Logical Interrupt Source as indicated by the returned values
            of this hcall(). The hcall() returns four values in addition to the return code.
            The first value is the logical real address of the full function page address,
            which allows both trigger and reset functions. The second value is either the
            logical real address of the trigger only page, or the reserved value -1 (all ones).
            The value of -1 indicates that the Event Source Buffer does not have a trigger only page.
            <footnote>
              <para>See the XIVE specification for more details on the full function
                page versus the trigger only page.</para></footnote>
          </para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success:    Expected Return code */
                       /* H_Function:   The calling OS is not in exploitation mode */
                       /* H_Busy:       Call again to complete the function */
                       /* H LongBusyOrder*: Wait the indicated time and call again */
                       /* H_Hardware:   A hardware fault occurred which prevented */
                       /*               successful completion */
                       /* H_State:      H_INT_RESET is in progress */
                       /* H_Parameter:  A reserved flag is on */
                       /* H_P2:         The “lisn” parameter was invalid for the */
                       /*               calling partition */
hcall ( const uint64 H_INT_GET_SOURCE_INFO, /* Returns the logical real address of */
                                            /* the Event State Buffer */
        uint64 flags,
        uint64 lisn );                      /* associated with “lisn” */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>flags: bits 0-63 reserved</para>
              </listitem>

              <listitem>
                <para>“lisn” is per
                  <emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>,
                  <emphasis role="bold"><literal>&#8220;interrupt-map&#8221;</literal></emphasis>, or
                  <emphasis role="bold"><literal>&#8220;ibm,xive-lisn-ranges&#8221;</literal></emphasis> properties,
                  or as returned by the
                  <emphasis>ibm,query-interrupt-source-number</emphasis>
                  RTAS call, or as returned by the H_ALLOCATE_VAS_WINDOW hcall</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Return Values:</title>

            <itemizedlist>
              <listitem>
                <para>R4: “flags”:
                  <itemizedlist>
                    <listitem>
                      <para>Bits 0-59: Reserved</para>
                    </listitem>

                    <listitem>
                      <para>Bit 60: ESB hcall: ESB hcall==1, hcall() H_INT_ESB must be
                        used for Event State Buffer management</para>
                    </listitem>

                    <listitem>
                      <para>Bit 61: LSI: LSI==1, the interrupt associated with the
                        “lisn” is a LSI (Level Sensitive Interrupt), LSI==0, the
                        interrupt associated with the “lisn” is a MSI (Message Signaled Interrupt)</para>
                    </listitem>

                    <listitem>
                      <para>Bit 62: Trigger: Trigger==1, the full function page supports trigger</para>
                    </listitem>

                    <listitem>
                      <para>Bit 63: Store EOI Supported</para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>R5: Logical Real address of full function Event State Buffer
                  management page, -1 if ESB hcall flag is set to 1.</para>
              </listitem>

              <listitem>
                <para>R6: Logical Real Address of trigger only Event State Buffer
                  management page or -1 if ESB hcall flag is set to 1.</para>
              </listitem>

              <listitem>
                <para>R7: Power of 2 page size for the ESB management pages returned
                  in R5 and R6. For example, a 4K page size is represented by the value
                  of 12 (4K = 2<superscript>12</superscript>). There is a minimum page size of 4K.</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Verify that no reserved flag bits are on else return H_Parameter.</para>
              </listitem>

              <listitem>
                <para>Verify that a H_INT_RESET is not in progress else return H_State.</para>
              </listitem>

              <listitem>
                <para>Validate the “lisn” parameter per the list of interrupt sources
                  allocated to the calling partition else return H_P2.</para>
              </listitem>

              <listitem>
                <para>Load R4 with the return flags, setting the reserved bits to 0.</para>
              </listitem>

              <listitem>
                <para>Load R5 with the logical real address of the full function Event
                  State Buffer management page.</para>
              </listitem>

              <listitem>
                <para>If the associated Event State Buffer has two management pages
                  defined load the logical real address of the trigger only page into
                  R6 else load R6 with -1.</para>
              </listitem>

              <listitem>
                <para>Load R7 with the power of 2 page size of the ESB management pages.</para>
              </listitem>

              <listitem>
                <para>Return H_Success.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="sec_int_set_source_config">
          <title>H_INT_SET_SOURCE_CONFIG</title>

          <para>The H_INT_SET_SOURCE_CONFIG hcall() is used to assign a Logical Interrupt
            Source to a target. The Logical In- terrupt Source is designated with the
            “lisn” parameter and the target is designated with the “target” and
            “priority” parameters. Upon return from the hcall(), no additional interrupts
            will be directed to the old EQ. The old EQ should be investigated for
            nterrupts that occurred prior to or during the hcall().</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success:    Expected Return code */
                       /* H_Function:   The calling OS is not in exploitation mode */
                       /* H_Busy:       Call again to complete the function */
                       /* H LongBusyOrder*: Wait the indicated time and call again */
                       /* H_Hardware:   A hardware fault occurred which prevented */
                       /*               successful completion */
                       /* H_State:      H_INT_RESET is in progress */
                       /* H_Parameter:  A reserved flag is on */
                       /* H_P2:         The “lisn” parameter was invalid for the */
                       /*               calling partition */
                       /* H_P3:         The “target” parameter was invalid for the */
                       /*               calling partition */
                       /* H_P4:         The “priority” parameter was invalid */
hcall ( const uint64 H_INT_SET_SOURCE_CONFIG, /* Assigns */
        uint64 flags,
        uint64 lisn,                          /* source "lisn" */
        uint64 target,                        /* to the target */
        uint64 priority,                      /* and “priority” combination, */
        uint eisn );                          /* setting its associated "eisn" */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para> “flags”
                  <itemizedlist>
                    <listitem>
                      <para>Bits 0-61: Reserved</para>
                    </listitem>

                    <listitem>
                      <para>Bit 62: setEisn: setEisn==1, set the “eisn” in the EA</para>
                    </listitem>

                    <listitem>
                      <para>Bit63: M: m==1 masks the interrupt source in the hardware
                        interrupt control structure.<footnote>
                          <para>As defined in Section 3.7 "Processing an EAS" in
                            the XIVE Specification.</para></footnote>
                        An interrupt masked by this mechanism will be dropped, but
                        it's source state bits will still be set. There is no race-free
                        way of unmasking and restoring the source. Thus this should only
                        be used in interrupts that are also masked at the source, and
                        only in cases where the interrupt is not meant to be used for
                        a large amount of time be- cause no valid target exists for it
                        for example
                      </para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>“lisn” is per
                  <emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>,
                  <emphasis role="bold"><literal>&#8220;interrupt-map&#8221;</literal></emphasis>, or
                  <emphasis role="bold"><literal>&#8220;ibm,xive-lisn-ranges&#8221;</literal></emphasis> properties,
                  or as returned by the
                  <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call, or
                  as returned by the H_ALLOCATE_VAS_WINDOW hcall</para>
              </listitem>

              <listitem>
                <para>“target” is per
                  <emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis> or
                  <emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-gserver#s&#8221;</literal></emphasis></para>
              </listitem>

              <listitem>
                <para>“priority” is a valid priority not in
                  <emphasis role="bold"><literal>&#8220;ibm,plat-res-int-priorities&#8221;</literal></emphasis></para>
              </listitem>

              <listitem>
                <para>“eisn” is the guest EISN associated with the “lisn”</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Return Values:</title>

            <para>None</para>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Verify that no reserved flag bits are on else return H_Parameter.</para>
              </listitem>

              <listitem>
                <para>Verify that a H_INT_RESET is not in progress else return H_State.</para>
              </listitem>

              <listitem>
                <para>Validate the “lisn” parameter per the list of interrupt sources
                  allocated to the calling partition else return H_P2.</para>
              </listitem>

              <listitem>
                <para>If “priority” is not 0xFF
                  <itemizedlist>
                    <listitem>
                      <para>Validate the “target” parameter per the list of threads
                        allocated to the calling partition else return H_P3.</para>
                    </listitem>

                    <listitem>
                      <para>If the partition thread count is greater than the hardware
                        thread count, validate the “target” has a corresponding hardware
                        thread else return H_Not_Available.</para>
                    </listitem>

                    <listitem>
                      <para>Validate the “priority” parameter is a valid priority
                        and not in listed in the
                        <emphasis role="bold"><literal>&#8220;ibm,plat-res-int-priorities&#8221;</literal></emphasis>
                        property else return H_P4.</para>
                    </listitem>

                    <listitem>
                      <para>Fill the Event Assignment Structure associated with “lisn” with:
                        <itemizedlist>
                          <listitem>
                            <para>Block and Event Notification Descriptor Table Index
                              associated with “target”/”priority” pair.</para>
                          </listitem>

                          <listitem>
                            <para>Set the “M” bit to the value of the flags “M” bit.</para>
                          </listitem>

                          <listitem>
                            <para>If setEisn==1, store “eisn”.</para>
                          </listitem>

                          <listitem>
                            <para>Issue syncs required to ensure all in-flight
                              interrupts are complete.</para>
                          </listitem>
                        </itemizedlist>
                      </para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>Else
                  <itemizedlist>
                    <listitem>
                      <para>Reset the Event Assignment Structure associated with “lisn” by:
                        <itemizedlist>
                          <listitem>
                            <para>Issue syncs required to ensure all in-flight interrupts
                              are complete</para>
                          </listitem>

                          <listitem>
                            <para>Invalidating the Block and End Notification Descriptor
                              Table Index</para>
                          </listitem>

                          <listitem>
                            <para>Resetting the eisn</para>
                          </listitem>
                        </itemizedlist>
                      </para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>Return H_Success.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="sec_int_get_source_config">
          <title>H_INT_GET_SOURCE_CONFIG</title>

          <para>The H_INT_GET_SOURCE_CONFIG hcall() is used to determine to which
            target/priority pair is assigned to the specified Logical Interrupt Source.</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[
int64                  /* H_Success:    Expected Return code */
                       /* H_Function:   The calling OS is not in exploitation mode */
                       /* H_Busy:       Call again to complete the function */
                       /* H LongBusyOrder*: Wait the indicated time and call again */
                       /* H_Hardware:   A hardware fault occurred which prevented */
                       /*               successful completion */
                       /* H_State:      H_INT_RESET is in progress */
                       /* H_Parameter:  A reserved flag is on */
                       /* H_P2:         The “lisn” parameter was invalid for the */
                       /*               calling partition */
hcall ( const uint64 H_INT_GET_SOURCE_CONFIG, /* Returns the target and priority */
        uint64 flags,                         /* to which the */
        uint64 lisn );                        /* "lisn" is assigned */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>“flags”: bits 0-63 Reserved</para>
              </listitem>

              <listitem>
                <para> “lisn” is per
                  <emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>,
                  <emphasis role="bold"><literal>&#8220;interrupt-map&#8221;</literal></emphasis>, or
                  <emphasis role="bold"><literal>&#8220;ibm,xive-lisn-ranges&#8221;</literal></emphasis> properties,
                  or as returned by the
                  <emphasis>ibm,query-interrupt-source-number</emphasis> RTAS call, or as returned by the
                  H_ALLOCATE_VAS_WINDOW hcall</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Return Values:</title>

            <itemizedlist>
              <listitem>
                <para>R4: Target to which the specified Logical Interrupt Source is
                  assigned, else this is undefined.</para>
              </listitem>

              <listitem>
                <para>R5: Priority to which the specified Logical Interrupt Source is
                  assigned, else this is set to 0xFF (disabled).</para>
              </listitem>

              <listitem>
                <para>R6: EISN for the specified Logical Interrupt Source (this will
                  be equivalent to the LISN if not changed by H_INT_SET_SOURCE_CONFIG).</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Verify that no reserved flag bits are on else return H_Parameter.</para>
              </listitem>

              <listitem>
                <para>Verify that a H_INT_RESET is not in progress else return H_State.</para>
              </listitem>

              <listitem>
                <para>Validate the “lisn” parameter per the list of interrupt sources
                  allocated to the calling partition else return H_P2.</para>
              </listitem>

              <listitem>
                <para>Load R4 with the target associated with the “lisn” parameter.</para>
              </listitem>

              <listitem>
                <para>Load R5 with the priority associated with the “lisn” parameter.</para>
              </listitem>

              <listitem>
                <para>Load R6 with the EISN associated with the “lisn” parameter.</para>
              </listitem>

              <listitem>
                <para>Return H_Success.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="sec_int_get_queue_info">
          <title>H_INT_GET_QUEUE_INFO</title>

          <para>The H_INT_GET_QUEUE_INFO hcall() is used to get the logical real
            address of the notification management page7 associated with the
            specified target and priority.
          </para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success:    Expected Return code */
                       /* H_Function:   The calling OS is not in exploitation mode */
                       /* H_Busy:       Call again to complete the function */
                       /* H LongBusyOrder*: Wait the indicated time and call again */
                       /* H_Hardware:   A hardware fault occurred which prevented */
                       /*               successful completion */
                       /* H_State:      H_INT_RESET is in progress */
                       /* H_Parameter:  A reserved flag is on */
                       /* H_P2:         The “lisn” parameter was invalid for the */
                       /*               calling partition */
                       /* H_P3:         The "priority" parameter was invalid  */
hcall ( const uint64 H_INT_GET_QUEUE_INFO,/* Returns the logical real address of the */
        uint64 flags,                     /* notification management page associated */
        uint64 target,                    /* the "target" */
        uint64 priority );                /* and “priority” combination. */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>“flags”: bits 0-63 Reserved</para>
              </listitem>

              <listitem>
                <para>“target” is per
                  <emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis> or
                  <emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-gserver#s&#8221;</literal></emphasis></para>
              </listitem>

              <listitem>
                <para>“priority” is valid priority not in the
                  <emphasis role="bold"><literal>&#8220;ibm,plat-res-int-priorities&#8221;</literal></emphasis></para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Return Values:</title>

            <itemizedlist>
              <listitem>
                <para>R4: Logical real address of notification page</para>
              </listitem>

              <listitem>
                <para>R5: Power of 2 page size of the notification page</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Verify that no reserved flag bits are on else return H_Parameter.</para>
              </listitem>

              <listitem>
                <para>Verify that a H_INT_RESET is not in progress else return H_State.</para>
              </listitem>

              <listitem>
                <para>Validate the “target” parameter per the list of threads allocated
                  to the calling partition else return H_P2.</para>
              </listitem>

              <listitem>
                <para>If the partition thread count is greater than the hardware thread
                  count, validate the “target” has a corresponding hardware thread else
                  return H_Not_Available.</para>
              </listitem>

              <listitem>
                <para>Validate the “priority” parameter is a valid priority and not in
                  listed in the
                  <emphasis role="bold"><literal>&#8220;ibm,plat-res-int-priorities&#8221;</literal></emphasis>
                  property else return H_P3.</para>
              </listitem>

              <listitem>
                <para>Load R4 with the ESn page from the Event Notification Descriptor
                  Table associated with “target” and “priority”.</para>
              </listitem>

              <listitem>
                <para>Load R5 with the page size of the ESn page.</para>
              </listitem>

              <listitem>
                <para>Return H_Success.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="sec_int_set_queue_config">
          <title>H_INT_SET_QUEUE_CONFIG</title>

          <para>The H_INT_SET_QUEUE_CONFIG hcall() is used to set or reset an EQ for a
            given “target” and “priority”. It is also used to set the notification
            config associated with the EQ. An EQ size of 0 is used to reset the EQ
            config for a given target and priority. If resetting the EQ config, the
            END associated with the given “target” and “priority” will be changed to
            disable queuing.</para>

          <para>Upon return from the hcall(), no additional interrupts will be directed
            to the old EQ (if one was set). The old EQ (if one was set) should be
            investigated for interrupts that occurred prior to or during the hcall().</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success:    Expected Return code */
                       /* H_Function:   The calling OS is not in exploitation mode */
                       /* H_Busy:       Call again to complete the function */
                       /* H LongBusyOrder*: Wait the indicated time and call again */
                       /* H_Hardware:   A hardware fault occurred which prevented */
                       /*               successful completion */
                       /* H_State:      H_INT_RESET is in progress */
                       /* H_Parameter:  A reserved flag is on */
                       /* H_P2:         The “lisn” parameter was invalid for the */
                       /*               calling partition */
                       /* H_P3:         The "priority" parameter was invalid  */
hcall ( const uint64 H_INT_SET_QUEUE_CONFIG,/* Sets the Event Notification Descriptor
                                            /* parameters */
        uint64 flags,                       /* Per the flag request */
        uint64 target,                      /* and the specified “priority” */
        uint64 priority,                    /* and “priority” combination. */
        uint64 eventQueue,                  /* to a new EQ */
        uint64 eventQueueSize );            /* and power of 2 EQ size per */
                                            /* “ibm,xive-eq-sizes” */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>“flags”:
                  <itemizedlist>
                    <listitem>
                      <para>Bits 0-62: Reserved</para>
                    </listitem>

                    <listitem>
                      <para>Bit 63: Unconditional Notify (n) per the XIVE spec</para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>“target”: is per
                  <emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis> or
                  <emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-gserver#s&#8221;</literal></emphasis></para>
              </listitem>

              <listitem>
                <para>“priority”: is valid priority not in the
                  <emphasis role="bold"><literal>&#8220;ibm,plat-res-int-priorities&#8221;</literal></emphasis></para>
              </listitem>

              <listitem>
                <para>“eventQueue”: The logical real address of the start of the EQ</para>
              </listitem>

              <listitem>
                <para>“eventQueueSize”: The power of 2 EQ size per
                  <emphasis role="bold"><literal>&#8220;ibm,xive-eq-sizes&#8221;</literal></emphasis></para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Return Values:</title>

            <para>None</para>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Verify that no reserved flag bits are on else return H_Parameter.</para>
              </listitem>

              <listitem>
                <para>Verify that a H_INT_RESET is not in progress else return H_State.</para>
              </listitem>

              <listitem>
                <para>Validate the “target” parameter per the list of threads allocated
                  the calling partition else return H_P2.</para>
              </listitem>

              <listitem>
                <para>If the partition thread count is greater than the hardware thread
                  count, validate the “target” has a corresponding hardware thread else
                  return H_Not_Available.</para>
              </listitem>

              <listitem>
                <para>Validate the “priority” parameter is a valid priority and not in listed in the
                  <emphasis role="bold"><literal>&#8220;ibm,plat-res-int-priorities&#8221;</literal></emphasis>
                  property else return H_P3.</para>
              </listitem>

              <listitem>
                <para>Validate the “eventQueueSize” parameter per
                  <emphasis role="bold"><literal>&#8220;ibm,xive-eq-sizes&#8221;</literal></emphasis>,
                  else return H_P5.</para>
              </listitem>

              <listitem>
                <para>Validate that if “eventQueueSize” is not 0 then the calling partition owns the logical real address in “eventQueue” for the length of “eventQueueSize” else return H_P4.</para>
              </listitem>

              <listitem>
                <para>If “Unconditional Notify” = 0 notification is conditioned by the
                  notification page from H_INT_GET_QUEUE_INFO.</para>
              </listitem>

              <listitem>
                <para>If the “eventQueueSize” is not 0 then:
                  <itemizedlist>
                    <listitem>
                      <para>The memory pointed to by “eventQueue” must be zeroed by the OS.</para>
                    </listitem>

                    <listitem>
                      <para>The generation bit for the EQ will start at 1.</para>
                    </listitem>

                    <listitem>
                      <para>The EQ page offset counter will start at 0.</para>
                    </listitem>

                    <listitem>
                      <para>The EQ config will be set to “eventQueue” and “eventQueueSize”.</para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>If the “eventQueueSize” is 0 then:
                  <itemizedlist>
                    <listitem>
                      <para>The EQ config will be reset.</para>
                    </listitem>

                    <listitem>
                      <para>Queuing of interrupts will be disabled.</para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>Issue syncs required to ensure all in-flight interrupts are complete.</para>
              </listitem>

              <listitem>
                <para>Return H_Success.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="sec_int_get_queue_config">
          <title>H_INT_GET_QUEUE_CONFIG</title>

          <para>The H_INT_GET_QUEUE_CONFIG hcall() is used to get an EQ and the EQ size
            for a given target and priority. If requested via the “Debug” flag,
            this will also return the current generation value and event queue offset.
          </para>
          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success:    Expected Return code */
                       /* H_Function:   The calling OS is not in exploitation mode */
                       /* H_Busy:       Call again to complete the function */
                       /* H LongBusyOrder*: Wait the indicated time and call again */
                       /* H_Hardware:   A hardware fault occurred which prevented */
                       /*               successful completion */
                       /* H Not Available: Not enough resources available */
                       /* H_State:      H_INT_RESET is in progress */
                       /* H_Parameter:  A reserved flag is on */
                       /* H_P2:         The "target" parameter was invalid for the */
                       /*               calling partition */
                       /* H_P3:         The "priority" parameter was invalid  */
hcall ( const uint64 H_INT_GET_QUEUE_CONFIG,  /* Returns the EQ config */
        uint64 flags,                         /* information for the  */
        uint64 target,                        /* specified "target" */
        uint64 priority );                    /* and “priority” combination. */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>"flags":
                  <itemizedlist>
                    <listitem>
                      <para>Bits 0-62: Reserved</para>
                    </listitem>

                    <listitem>
                      <para>Bit 63: Debug: Return debug data</para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>“target”: is per
                  <emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis> or
                  <emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-gserver#s&#8221;</literal></emphasis></para>
              </listitem>

              <listitem>
                <para>“priority”: is valid priority not in the
                  <emphasis role="bold"><literal>&#8220;ibm,plat-res-int-priorities&#8221;</literal></emphasis></para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Return Values:</title>

            <itemizedlist>
              <listitem>
                <para>R4: “flags”:
                  <itemizedlist>
                    <listitem>
                      <para>Bit 0-62: Reserved</para>
                    </listitem>

                    <listitem>
                      <para>Bit 62: The value of Event Queue Generation Number (g) per
                        the XIVE spec if “Debug” = 1</para>
                    </listitem>

                    <listitem>
                      <para>Bit 63: The value of Unconditional Notify (n) per the XIVE spec</para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>R5: The logical real address of the start of the EQ</para>
              </listitem>

              <listitem>
                <para>R6: The power of 2 EQ size per
                  <emphasis role="bold"><literal>&#8220;ibm,xive-eq-sizes&#8221;</literal></emphasis></para>
              </listitem>

              <listitem>
                <para>R7: The value of Event Queue Offset Counter per XIVE spec if
                  “Debug” = 1, else 0</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Verify that no reserved flag bits are on else return H_Parameter.</para>
              </listitem>

              <listitem>
                <para>Verify that a H_INT_RESET is not in progress else return H_State.</para>
              </listitem>

              <listitem>
                <para>Validate the “target” parameter per the list of threads
                  allocated the calling partition else return H_P2.</para>
              </listitem>

              <listitem>
                <para>If the partition thread count is greater than the hardware thread
                  count, validate the “target” has a corresponding hardware thread
                  else return H_Not_Available.</para>
              </listitem>

              <listitem>
                <para>Validate the “priority” parameter is a valid priority and not in
                  listed in the
                  <emphasis role="bold"><literal>&#8220;ibm,plat-res-int-priorities&#8221;</literal></emphasis>
                  property else return H_P3.</para>
              </listitem>

              <listitem>
                <para>Load R4 with the return flags, setting the reserved bits to 0.</para>
              </listitem>

              <listitem>
                <para>Load R5 with the logical real address of the EQ associated with
                  “target” and “priority”. Set to -1 if no EQ has
                been specified</para>
              </listitem>

              <listitem>
                <para>Load R6 with the size of the EQ associated with the “target” and
                  “priority”. Set to 0 if no EQ has been specified.</para>
              </listitem>

              <listitem>
                <para>If “Debug” = 1
                  <itemizedlist>
                    <listitem>
                      <para>Load the event queue generation number into the return flags</para>
                    </listitem>

                    <listitem>
                      <para>Load R7 with the event queue offset counter</para>
                    </listitem>

                    <listitem>
                      <para>Use the appropriate hardware facility to get an atomic
                        view of the generation number and offset counter.</para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>Return H_Success.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="sec_int_set_os_reporting_line">
          <title>H_INT_SET_OS_REPORTING_LINE</title>

          <para>The H_INT_SET_OS_REPORTING_LINE hcall() is used to set the reporting
            cache line pair for the calling thread. The reporting cache lines will
            contain the OS interrupt context when the OS issues a CI store byte to
            @TIMA+0xC10 8 to acknowledge the OS interrupt. The reporting cache lines
            can be reset by inputting -1 in “reportingLine”. Issuing the CI store byte
            without reporting cache lines registered will result in the data not being
            accessible to the OS.</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success:    Expected Return code */
                       /* H_Busy:       Call again to complete the function */
                       /* H LongBusyOrder*: Wait the indicated time and call again */
                       /* H_Function:   The calling OS is not in exploitation mode */
                       /* H_Hardware:   A hardware fault occurred which prevented */
                       /*               successful completion */
                       /* H Not Available: Not enough resources available */
                       /* H_State:      H_INT_RESET is in progress */
                       /* H_Parameter:  A reserved flag is on */
                       /* H_P2:         The reporting cache line logical real */
                       /*               address/length is not owned by the caller or */
                       /*               is improperly aligned. */
hcall ( const uint64 H_INT_SET_OS_REPORTING_LINE, /* For calling thread */
        uint64 flags,                             /*   */
        uint64 reportingLine );                   /* set the reporting line */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>“flags”: bits 0-63 Reserved</para>
              </listitem>

              <listitem>
                <para>“reportingLine”: The logical real address of the reporting cache line pair</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Return Values:</title>

            <para>None</para>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Verify that no reserved flag bits are on else return H_Parameter.</para>
              </listitem>

              <listitem>
                <para>Verify that a H_INT_RESET is not in progress else return H_State.</para>
              </listitem>

              <listitem>
                <para>If the partition thread count is greater than the hardware thread count,
                  validate the “target” has a corresponding hardware thread else return
                  H_Not_Available.</para>
              </listitem>

              <listitem>
                <para>If the “reportingLine” is not -1
                  <itemizedlist>
                    <listitem>
                      <para>Validate the calling partition owns the logical real address
                        in “reportingLine” for two cache lines else return H_P2.</para>
                    </listitem>

                    <listitem>
                      <para>Validate that the “reportingLine” is cached aligned, else
                        return H_P2.</para>
                    </listitem>

                    <listitem>
                      <para>Set the “reportingLine” in the NVT associated with the input
                        “target”.</para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>If the “reportingLine” is -1
                  <itemizedlist>
                    <listitem>
                      <para>Reset the NVT’s reporting line.</para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>Return H_Success.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="sec_int_get_os_reporting_line">
          <title>H_INT_GET_OS_REPORTING_LINE</title>

          <para>The H_INT_GET_OS_REPORTING_LINE hcall() is used to get the logical real
            address of the reporting cache line pair set for the input “target”. If no
            reporting cache line pair has been set, -1 is returned.</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success:    Expected Return code */
                       /* H_Busy:       Call again to complete the function */
                       /* H LongBusyOrder*: Wait the indicated time and call again */
                       /* H_Function:   The calling OS is not in exploitation mode */
                       /* H_Hardware:   A hardware fault occurred which prevented */
                       /*               successful completion */
                       /* H Not Available: Not enough resources available */
                       /* H_State:      H_INT_RESET is in progress */
                       /* H_Parameter:  A reserved flag is on */
                       /* H_P2:         The “target” parameter was invalid for the */
                       /*               calling partition */
hcall ( const uint64 H_INT_GET_OS_REPORTING_LINE, /* For calling thread */
        uint64 flags,                             /*   */
        uint64 target );                          /* for the target */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>“flags”: bits 0-63 Reserved</para>
              </listitem>

              <listitem>
                <para>“target”: is per
                  <emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis></para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Return Values:</title>

            <itemizedlist>
              <listitem>
                <para>R4: The logical real address of the reporting line if set, else -1</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Verify that no reserved flag bits are on else return H_Parameter.</para>
              </listitem>

              <listitem>
                <para>Verify that a H_INT_RESET is not in progress else return H_State.</para>
              </listitem>

              <listitem>
                <para>Validate the “target” parameter per the list of threads allocated
                  the calling partition else return H_P2.</para>
              </listitem>

              <listitem>
                <para>Validate the thread indicated by “target” is online else
                  return H_Not_Available.</para>
              </listitem>

              <listitem>
                <para>If the partition thread count is greater than the hardware
                  thread count, validate the “target” has a corresponding hardware
                  thread else return H_Not_Available.</para>
              </listitem>

              <listitem>
                <para>Load R4 with the logical real address of the reporting line
                  associated with “target”. Load R4 with -1 if no reporting line has been set.</para>
              </listitem>

              <listitem>
                <para>Return H_Success.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="sec_int_esb">
          <title>H_INT_ESB</title>

          <para></para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success:    Expected Return code */
                       /* H_Busy:       Call again to complete the function */
                       /* H LongBusyOrder*: Wait the indicated time and call again */
                       /* H_Function:   The calling OS is not in exploitation mode */
                       /* H_Hardware:   A hardware fault occurred which prevented */
                       /*               successful completion */
                       /* H_State:      H_INT_RESET is in progress */
                       /* H_Parameter:  A reserved flag is on */
                       /* H_P2:         The “lisn” parameter was invalid for the */
                       /*               calling partition */
                       /* H_P3:         The “esbOffset” parameter is invalid */
hcall ( const uint64 H_INT_ESB, /* Issue the */
        uint64 flags,           /* load or store  */
        uint64 lisn,            /* for the lisn */
        uint64 esbOffset,       /* at the esbOffset */
        uint64 storeData );     /*  */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>“flags”:
                  <itemizedlist>
                    <listitem>
                      <para>bits 0-62: Reserved</para>
                    </listitem>

                    <listitem>
                      <para>bit 63: Store: Store=1, store operation, else load operation</para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>“lisn” is per
                  <emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>,
                  <emphasis role="bold"><literal>&#8220;interrupt-map&#8221;</literal></emphasis>, or
                  <emphasis role="bold"><literal>&#8220;ibm,xive-lisn-ranges&#8221;</literal></emphasis> properties, or as returned by the
                  <emphasis>ibm,query-interrupt-source-number</emphasis>
                  RTAS call, or as returned by the H_ALLOCATE_VAS_WINDOW hcall</para>
              </listitem>

              <listitem>
                <para>“esbOffset” is the offset into the ESB management page for the load or store operation</para>
              </listitem>

              <listitem>
                <para>“storeData” is the data to write for a store operation</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Return Values:</title>

            <itemizedlist>
              <listitem>
                <para>R4: The value of the load if load operation, else -1</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Verify that no reserved flag bits are on else return H_Parameter.</para>
              </listitem>

              <listitem>
                <para>Verify that a H_INT_RESET is not in progress else return H_State.</para>
              </listitem>

              <listitem>
                <para>Validate the “lisn” parameter per the list of interrupt sources
                  allocated to the calling partition else return H_P2.</para>
              </listitem>

              <listitem>
                <para>Validate the “esbOffset” parameter is valid per the XIVE Spec
                  else return H_P3.</para>
              </listitem>

              <listitem>
                <para>If bit 63 of flags is 0
                  <itemizedlist>
                    <listitem>
                      <para>Issue the load operation to the “esbOffset” of the ESB
                        management page associated with “lisn”.</para>
                    </listitem>

                    <listitem>
                      <para>Load R4 with the results of the load operation.</para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>If bit 63 of flags is 1
                  <itemizedlist>
                    <listitem>
                      <para>Issue the store operation to the “esbOffset” of the ESB
                        management page associated with “lisn”, storing “storeData”.</para>
                    </listitem>

                    <listitem>
                      <para>Load R4 with -1.</para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>Return H_Success.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="sec_int_sync">
          <title>H_INT_SYNC</title>

          <para>The H_INT_SYNC hcall() is used to issue hardware syncs that will
            ensure any in flight events for the input lisn are in the event queue.</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success:    Expected Return code */
                       /* H_Busy:       Call again to complete the function */
                       /* H LongBusyOrder*: Wait the indicated time and call again */
                       /* H_Function:   The calling OS is not in exploitation mode */
                       /* H_Hardware:   A hardware fault occurred which prevented */
                       /*               successful completion */
                       /* H_State:      H_INT_RESET is in progress */
                       /* H_Parameter:  A reserved flag is on */
hcall ( const uint64 H_INT_SYNC,  /* Issue VC syncs to ensure any in flight events */
        uint64 flags,             /*  */
        uint64 lisn );            /* are in the EQ for the input lisn */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>“flags”: bits 0-63 Reserved</para>
              </listitem>

              <listitem>
                <para>“lisn” is per
                  <emphasis role="bold"><literal>&#8220;interrupts&#8221;</literal></emphasis>,
                  <emphasis role="bold"><literal>&#8220;interrupt-map&#8221;</literal></emphasis>, or
                  <emphasis role="bold"><literal>&#8220;ibm,xive-lisn-ranges&#8221;</literal></emphasis> properties, or as returned by the
                  <emphasis>ibm,query-interrupt-source-number</emphasis>
                  RTAS call, or as returned by the H_ALLOCATE_VAS_WINDOW hcall</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Return Values:</title>

            <para>None</para>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Verify that no reserved flag bits are on else return H_Parameter.</para>
              </listitem>

              <listitem>
                <para>Verify that a H_INT_RESET is not in progress else return H_State.</para>
              </listitem>

              <listitem>
                <para>Validate the “lisn” parameter per the list of interrupt sources
                  allocated to the calling partition else return H_P2. </para>
              </listitem>

              <listitem>
                <para>Perform the appropriate hardware syncs to ensure any in flight
                  events for the input “lisn” are in the event queue.</para>
              </listitem>

              <listitem>
                <para>Return H_Success.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>

        <section xml:id="sec_int_reset">
          <title>H_INT_RESET</title>

          <para>The H_INT_RESET hcall() is used to reset all of the partition’s interrupt
            exploitation structures to their initial state. This means losing all p
            reviously set interrupt state set via H_INT_SET_SOURCE_CONFIG and
            H_INT_SET_QUEUE_CONFIG.
          </para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success:    Expected Return code */
                       /* H_Busy:       Call again to complete the function */
                       /* H LongBusyOrder*: Wait the indicated time and call again */
                       /* H_Function:   The calling OS is not in exploitation mode */
                       /* H_Hardware:   A hardware fault occurred which prevented */
                       /*               successful completion */
                       /* H_Parameter:  A reserved flag is on */
                       /* H_State:      H_INT_RESET is in progress on another thread */
                       /*               for this partition */
hcall ( const uint64 H_INT_RESET,   /* Reset all interrupt structures */
        uint64 flags );             /* to their initial state */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>“flags”: bits 0-63 Reserved</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Return Values:</title>

            <para>None</para>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Verify that no reserved flag bits are on else return H_Parameter.</para>
              </listitem>

              <listitem>
                <para>Block all other exploitation hcalls (they all will return H_STATE
                  if called while H_INT_RESET is in progress).</para>
              </listitem>

              <listitem>
                <para>Verify that no other threads are currently in the middle of an
                  H_INT_RESET for this partition else return H_STATE</para>
              </listitem>

              <listitem>
                <para>Reset the following:
                  <itemizedlist>
                    <listitem>
                      <para>All EAs</para>
                    </listitem>

                    <listitem>
                      <para>All ESB states</para>
                    </listitem>

                    <listitem>
                      <para>All ENDs
                        <itemizedlist>
                          <listitem>
                            <para>Specifically, including clearing out its EQ pointer and size</para>
                          </listitem>
                        </itemizedlist>
                      </para>
                    </listitem>
                  </itemizedlist>
                </para>
              </listitem>

              <listitem>
                <para>All OS Reporting LinesUnblock all other exploitation hcalls when finished.</para>
              </listitem>

              <listitem>
                <para>Return H_Success.</para>
              </listitem>
            </itemizedlist>
          </simplesect>
        </section>
      </section>

      <section xml:id="dbdoclet.50569344_19308">
        <title>Memory Migration Support hcall()s</title>
        <para>To assist an OS in memory migration, the following hcall() is
        provided. During the migration process, it is the responsibility of the
        OS to not change the DMA mappings referenced by the translations buffer
        (for example by using the H_GET_TCE, H_PUT_TCE hcall()s, or other DMA
        mapping hcall()s). Failure of the OS to serialize such DMA mapping access
        may result in undesirable DMA mappings within the caller&#8217;s
        partition (but not outside of the caller&#8217;s partition). Further, it
        is the responsibility of the OS to serialize calls to the H_MIGRATE_DMA
        service relative to the logical bus numbers referenced. Failure of the OS
        to serialize relative to the logical bus numbers may result DMA data
        corruption within the caller&#8217;s partition.</para>
        <para>On certain implementations, DMA read operations targeting the old
        page may still be in process for some time after the H_MIGRATE_DMA call
        returns; this requires that the OS not reuse/modify the data within the
        old page until the worst case DMA read access time has expired. The
        <emphasis role="bold"><literal>&#8220;ibm,dma-delay-time&#8221;</literal></emphasis> property (see
        <xref linkend="LoPAR.DeviceTree" />) gives the OS this implementation
        dependent delay value. Failure to observe this delay time may result in
        data corruption as seen by the caller&#8217;s I/O adapter(s).</para>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_19308"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option supporting the hcall-migrate function
                set:</emphasis> The platform must supply the
                <emphasis role="bold"><literal>&#8220;ibm,dma-delay-time&#8221;</literal></emphasis> property under the
                <emphasis role="bold"><literal>/rtas</literal></emphasis> node of the device tree.</para>
                <para>Memory pages may be simultaneously mapped by multiple DMA agents,
                with different translation table formats and operation characteristics.
                The H_MIGRATE_DMA hcall() atomically performs the memory migration
                process so that the new page contains the old page contents (as updated
                by any DMA write operations allowed during migration), with all DMA
                mappings and engines directed to access the new page. The entries in the
                mapping list contain the logical bus number associated with the mapping
                and the I/O address of the mapping. From these two data, the hcall()
                associates the using DMA agent, that agent&#8217;s DMA control
                procedures, the specific mapping table and mapping table entry.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_19308"
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option supporting the hcall-migrate function
                set:</emphasis> The platform must support migration of pages mapped for
                DMA using any of the platform supported DMA agents.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_19308"
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option supporting the hcall-migrate function
                set:</emphasis> All the platform&#8217;s DMA agents must support
                mechanisms that enable the platform to meet the syntax, semantics and
                requirements set forth in section 14.5.4.8.1.</para>
                <para>
                <emphasis role="bold">Implementation Note:</emphasis> The minimal hardware mechanisms
                to support the hcall-migrate function set are to quiesce DMA operation,
                flush outstanding data to their targets (both reads and writes), modify
                their DMA mapping and re-enable operation utilizing said modified DMA
                mapping without introducing unrecoverable operational failures. Provision
                for the hardware to direct DMA write operations to both old and new pages
                provides a significantly more robust implementation.</para>
                <para>It is the intent of this architecture to have all memory in the
                platform have the capability to be migrated. However, on the rare
                implementation that cannot meet that intent, the
                <emphasis role="bold"><literal>&#8220;ibm,no-h-migrate-dma&#8221;</literal></emphasis> property may be
                provided in
                <emphasis role="bold"><literal>memory</literal></emphasis> nodes for which H_MIGRATE_DMA cannot be
                implemented.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_19308"
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option supporting the hcall-migrate function
                set:</emphasis> If a memory node cannot support H_MIGRATE_DMA, then that
                <emphasis role="bold"><literal>memory</literal></emphasis> node must contain the
                <emphasis role="bold"><literal>&#8220;ibm,no-h-migrate-dma&#8221;</literal></emphasis> property.</para>
                <para>For the I/O Super Page option the I/O page size is an attribute of
                the specified LIOBN (I/O pages mapped by a given LIOBN are a uniform
                size), also the syntax and semantics of H_MIGRATE_DMA are extended to
                allow migration of I/O pages that are larger than 4K bytes and have more
                than 256 xlates translation entries. Specifying more than 256 translation
                entries requires a sequence of calls to H_MIGRATE_DMA with the same
                &#8220;newpage&#8221; address. Making a call in the sequence with a
                length parameter of zero terminates the operation - should this
                termination happen after the start of the physical migration, the
                resulting state of the calling partition&#8217;s memory is unpredictable.
                Failure to make a continuing call in the sequence for more than one
                second aborts the operation; again the resulting state of the calling
                partition&#8217;s memory is unpredictable.</para>
                <para>The introduction of super pages introduces the case where portions
                of the super page may be I/O mapped and thus require the use of
                H_MIGRATE_DMA to move the logical super page from one physical page to
                another even though the super page as a whole may not be I/O mapped. To
                handle this case, the LIOBN value of 0xFFFFFFFF is reserved to allow the
                specification, within an translations entry (passed to H_MIGRATE_DMA via
                the xlates parameter), of a super page that is not currently I/O mapped.
                In this case, the normally reserved byte at xlates entry offset 4 is used
                to specify the power of two size of the super page.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_19308"
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the I/O Super Page option:</emphasis> the platform must
                support the setting by the client of byte 3 bit 0 of the
                <emphasis role="bold"><literal>ibm,architecture.vec 5</literal></emphasis> as input to the
                <emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis> method.</para>
              </listitem>
         	</varlistentry>
        </variablelist>


        <section xml:id="dbdoclet.50569344_23386">
          <title>H_MIGRATE_DMA</title>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Parameter: a parameter is invalid, */
                       /* H_LongBusyOrder1msec, */
                       /* H_LongBusyOrder10msec, */
                       /* H_Function */
                       /* For the Shared Logical Resource Option: H_ H_RESCINDED */
                       /* For the I/O Super Page Option, the following additional */
                       /*   return codes are defined: */
                       /* H_CONTINUE: More translations are needed to complete the */
                       /*   request */
                       /* H_P3: The length parameter did not contain the next */
                       /*   expected value in the call sequence. */
                       /* H_Resource: Insufficient resources to perform the request */
                       /* H_MEM_PARM: The first xlate entry specifying the LIOBN of */
                       /*   0xFFFFFFFF contains an unsupported page size */
                       /*   specification or invalid logical real address. */
hcall ( const uint64 H_MIGRATE_DMA, /*Migrates a page mapped by one or more DMA  */
                       /*   mappings */
        uint64 newpage, /*Logical address of new DMA target page*/
        uint64 xlates, /*List of translations to current DMA target page*/
        uint64 length ); /*Length of translation list*/]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>newpage (The Logical address of the new page to be the target of
                the TCE translations)</para>
              </listitem>

              <listitem>
                <para>xlates (The Logical address of a list of translations against the
                target page the format of this list is:</para>

                <itemizedlist>
                  <listitem>
                    <para>List starts on a page (4 K) boundary.</para>
                  </listitem>

                  <listitem>
                    <para>Contains up to 256 translation entries:</para>

                    <itemizedlist>
                      <listitem>
                        <para>First 4 bytes of a translation entry is the logical bus number as
                        from either the:</para>

                        <itemizedlist>
                          <listitem>
                            <para><emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property</para>
                          </listitem>

                          <listitem>
                            <para>or the reserved LIOBN 0xFFFFFFFF.</para>
                          </listitem>
                        </itemizedlist>
                      </listitem>

                      <listitem>
                        <para>Next 12 bytes of a translation entry is the logical bus offset
                        (I/O bus address). The format of the I/O bus address is dependent upon
                        the DMA agent:</para>

                        <itemizedlist>
                          <listitem>
                            <para>For 32 bit PCI, the high order 8 bytes are reserved with the low
                            order 4 bytes containing a 4 K aligned address (low order 12 bits
                            =zero).</para>
                          </listitem>

                          <listitem>
                            <para>For 64 bit PCI, the high order 4 bytes are reserved with the low
                            order 8bytes containing a 4 K aligned address (low order 12 bits
                            =zero).</para>
                          </listitem>

                          <listitem>
                            <para>For the I/O Super Page option the very first translation entry
                            passed is for the largest I/O page to be migrated by this sequence of
                            calls; else all translation entries are for the single 4K byte logical
                            page being migrated. The first translation entry may either be a current
                            I/O mapping for the largest I/O page that the caller wishes to migrate,
                            or the first translation entry may use the reserved LIOBN number of
                            0xFFFFFFFF, with the next byte indicating the page size as 2**N where N
                            is the numeric value of the byte at offset 4 into the translation entry
                            with the low order 8 bytes of the translation entry being the logical
                            real address of the start of the page to be migrated (the low order N
                            bits = zero).</para>
                          </listitem>
                        </itemizedlist>
                      </listitem>
                    </itemizedlist>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>length (Number of entries in translation list is less than or
                equal to 256)</para>

                <itemizedlist>
                  <listitem>
                    <para>If the total number of translation entries in the xlates list is
                    less than or equal to 256 then the &#8220;length&#8221; parameter is the
                    number of translation entries.</para>
                  </listitem>

                  <listitem>
                    <para>For the I/O Super Page option and specifying more than 256
                    translation entries, the client makes a series of calls, each passing 256
                    translation entries with the &#8220;length&#8221; parameter being the
                    negative of the total number of translation entries yet to be passed
                    until there are less than or equal to 256 remaining then for the final
                    call in the initiating sequence the &#8220;length&#8221; parameter is
                    positive as above.</para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </itemizedlist>

          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>For the I/O Super Page option: determine if a migration operation
                is in process for this &#8220;newpage&#8221; address:</para>

                <itemizedlist>
                  <listitem>
                    <para>Then:</para>

                    <itemizedlist>
                      <listitem>
                        <para>If the previous hcall() for the migration operation was more than
                        1 second ago, return H_Aborted.</para>
                      </listitem>

                      <listitem>
                        <para>If the length parameter value is zero then abort the migration
                        operation and return H_TERM.</para>
                      </listitem>

                      <listitem>
                        <para>If the length parameter value is not the next expected in the
                        sequence return H_P3.</para>
                      </listitem>

                      <listitem>
                        <para>Record the new xlates</para>
                      </listitem>

                      <listitem>
                        <para>If the length parameter is less than zero return
                        H_CONTINUE.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>

                  <listitem>
                    <para>Else</para>

                    <itemizedlist>
                      <listitem>
                        <para>If the number of outstanding operations is more than an
                        implementation specific number as communicated in the
                        <emphasis role="bold"><literal>&#8220;ibm,vec-5&#8221;</literal></emphasis> property then return
                        H_Resource</para>
                      </listitem>

                      <listitem>
                        <para>If the length parameter is less than zero, initiate a new
                        migration operation for the &#8220;newpage&#8221; address. (Note
                        resources for the operation may be allocated at this point and freed when
                        the operation terminates either normally, in error, or via timeout.
                        Implementations may, in unusual cases, use a busy return code to wait for
                        the release of resources from an immanently completing operation.</para>
                      </listitem>

                      <listitem>
                        <para>The first xlate entry specifies the length and starting address
                        of the page to be migrated, if this specification is invalid (unsupported
                        length, the address is invalid for the partition, or not aligned to the
                        length) return H_MEM_PARM.</para>
                      </listitem>

                      <listitem>
                        <para>If the operation specifies more than an implementation specific
                        number of xlates as communicated in the
                        <emphasis role="bold"><literal>&#8220;ibm,vec-5&#8221;</literal></emphasis> property then return
                        H_Resource.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Check that the page to be migrated can be migrated, else
                H_PARAMETER.</para>
              </listitem>

              <listitem>
                <para>Check that the newpage is within the allocated logical page range
                of the calling partition and the address is aligned to the I/O page size
                of the first translation entry passed else H_PARAMETER.</para>

                <itemizedlist>
                  <listitem>
                    <para>If the Shared Logical Resource option is implemented and the
                    newpage parameter represents a shared logical resource location that has
                    been rescinded by the owner, return H_RESCINDED.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>The contents of the xlates buffer are checked.</para>

                <itemizedlist>
                  <listitem>
                    <para>This may be done as each entry is used, or it may be done prior
                    to starting the operation.</para>

                    <itemizedlist>
                      <listitem>
                        <para>If the former, then partial processing must be backed out in the
                        case of a detected parameter error.</para>
                      </listitem>

                      <listitem>
                        <para>If the later, then the translation entries must be copied into an
                        area that is not accessible by the calling OS to prevent parameter
                        corruption after they have been verified. The OS perceived reentrancy of
                        the function is not diminished if this option is chosen.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>

                  <listitem>
                    <para>The xlates buffer starts on a 4 K boundary within the
                    partition&#8217;s logical address range else H_PARAMETER.</para>
                  </listitem>

                  <listitem>
                    <para>The length parameter is between (for the I/O Super Page option:
                    the negative of the maximum number of xlate entries supported as
                    indicated in the
                    <emphasis role="bold"><literal>&#8220;ibm.architecture-vec-5&#8221;</literal></emphasis> property of the
                    <emphasis>/chosen</emphasis> device tree node else 1) and 256 else
                    H_PARAMETER.</para>
                  </listitem>

                  <listitem>
                    <para>For the I/O Super Page option: the length of the physical page to
                    be migrated is the length of the I/O page of the first translation entry;
                    else the length of the physical page to be migrated is 4K bytes.</para>
                  </listitem>

                  <listitem>
                    <para>Each translation originally references the same physical page, or
                    a portion there of, else H_PARAMETER.</para>
                  </listitem>

                  <listitem>
                    <para>Each logical bus offset is within the allocated range of the
                    calling partition else H_PARAMETER.</para>

                    <itemizedlist>
                      <listitem>
                        <para>If the Shared Logical Resource option is implemented and the
                        logical bus offset represents a shared logical resource location that has
                        been rescinded by the owner, return H_RESCINDED.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>

                  <listitem>
                    <para>Check the logical bus number:</para>

                    <itemizedlist>
                      <listitem>
                        <para>Is allocated to the calling partition else H_PARAMETER.</para>
                        <para>Or: If the Shared Logical Resource option is implemented and the
                        logical bus number represents a shared logical resource location that has
                        been rescinded by the owner, return H_RESCINDED.</para>
                      </listitem>

                      <listitem>
                        <para>For the I/O Super Page option: if the LIOBN implies a larger page
                        size than that specified by the first translation entry for this migrate
                        operation, place the index of the translation entry (0-255) into register
                        R4 and return H_PGSB_PARM.</para>
                      </listitem>

                      <listitem>
                        <para>If the LIOBN referenced an unsupported DMA agent, place the index
                        of the translation entry (0-255) into register R4 and return
                        H_Function.</para>
                      </listitem>

                      <listitem>
                        <para>If the logical bus number is not supported, return
                        H_PARAMETER.</para>
                      </listitem>
                    </itemizedlist>

                    <para><emphasis role="bold">Note:</emphasis> The following is written from the perspective
                    of a PCI DMA agent; other DMA agents may require a different sequence of
                    operations to achieve equivalent results.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>The hypervisor disables arbitration for the IOA(s) associated
                with the translation entries. (In some cases, where multiple IOAs share a
                given TCE range, arbitration must be disabled for multiple IOAs. The
                firmware assigned the bus address ranges to each IOA so knows which IOAs
                correspond to which translation.)</para>
              </listitem>

              <listitem>
                <para>Waits for outstanding DMA write activity to complete. (This is
                accomplished by doing a load from an appropriate register the bridge(s)
                closest to the IOA -- when the load completes (dependency on load data is
                satisfied) all DMA write activity has completed.)</para>
              </listitem>

              <listitem>
                <para>The hypervisor copies the contents of the 4 K page originally
                accessed by the TCE(s) to the page referenced by the newpage
                value.</para>
              </listitem>

              <listitem>
                <para>The hypervisor translates the logical address within the newpage
                parameter and stores the resultant value in the TCE table entries
                specified by the translation entries.</para>
              </listitem>

              <listitem>
                <para>Executes a sync operation to ensure that the new TCE data is
                visible.</para>
              </listitem>

              <listitem>
                <para>The hypervisor enables arbitration on the IOA(s) associated with
                the translation entities and returns H_Success.</para>
              </listitem>
            </itemizedlist>

            <para><emphasis role="bold">Implementation Notes:</emphasis></para>

            <orderedlist>
              <listitem>
                <para>The firmware should be written to minimize the arbitration
                disable time. The old page should be read into cache (possibly using the
                data cache touch operations) prior to disabling the arbitration.
                Implementation dependent algorithms can significantly improve the page
                copy time.</para>
              </listitem>

              <listitem>
                <para>The firmware does not have to serialize this hcall() with other
                hcall()s as long as it updates the TCE using atomic eight (8) byte write
                operations. However, if the OS does not serialize this call with
                H_PUT_TCE to the same TCE, and with other H_MIGRATE_DMA calls to the same
                IOA(s) the calling LPARs DMA buffers could be corrupted.</para>
              </listitem>

              <listitem>
                <para>To minimize the effect of such unsupported DMA agents, the
                platform designer should isolate such agents on their own bus with their
                own <emphasis role="bold"><literal>&#8220;ibm,dma-window&#8221;</literal></emphasis> property
                specification.</para>
              </listitem>
            </orderedlist>
          </simplesect>
        </section>
      </section>

      <section>
        <title>Performance Monitor Support hcall()s</title>
        <para />

        <section xml:id="dbdoclet.50569344_88471">
          <title>H_PERFMON</title>
          <para>To manage the Performance Monitor Function:</para>

          <simplesect>
            <title>Syntax:</title>
            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_HARDWARE: Hardware error */
                       /* H_PARAMETER: Unsupported mode bit */
                       /* H_BUSY: Try again */
                       /* H_RESOURCE: Conflicting resources in use */
hcall ( const uint64 H_PERFMON, /* Function code */
        uint64 mode-set, /* Platform Modes to enable */
        uint64 mode-reset ); /* Platform Modes to reset */]]></programlisting>
          </simplesect>

          <simplesect>
            <title>Parameters:</title>

            <itemizedlist>
              <listitem>
                <para>mode-set Platform specific modes to be set by this call</para>
              </listitem>

              <listitem>
                <para>mode-reset Platform specific modes to be reset by this
                call</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>mode-set bit(s) check for platform specific validity else
                H_PARAMETER</para>
              </listitem>

              <listitem>
                <para>mode-reset bit(s) check for platform specific validity else
                H_PARAMETER</para>
              </listitem>

              <listitem>
                <para>if any mode-set bits are set, activate corresponding mode(s) - if
                logically capable else H_RESOURCE</para>
              </listitem>

              <listitem>
                <para>if any mode-reset bits are on, deactivate corresponding mode(s) -
                if logically capable else H_RESOURCE</para>
              </listitem>

              <listitem>
                <para>place current state of platform specific modes in R4, return
                H_Success</para>
              </listitem>
            </itemizedlist>
          </simplesect>

          <simplesect>
            <title>Defined Perfmon mode bits:</title>
            <para>bit 0: 1= Enable Perfmon</para>
            <para>bit1: 0= Low threshold granularity 1= High threshold
            granularity</para>
          </simplesect>
        </section>
      </section>

      <section xml:id="dbdoclet.50569344_88592">
        <title>H_GET_DMA_XLATES_LIMITED</title>
        <para>This hcall returns the I/O bus address of the first entry defined
        for the specified LIOBN and the corresponding logical address within the
        range beginning with the Start logical address and less than the End
        logical addresses, the search is limited to the range of I/O bus
        addresses specified by the SIOBA and EIOBA parameters.</para>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_88592"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LRDR Option:</emphasis> The platform must implement the
                H_GET_DMA_XLATES_LIMITED hcall() per the syntax and semantics specified
                in section
                <xref linkend="dbdoclet.50569344_88592" />.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_88592"
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LRDR Option:</emphasis> The platform must present the
                <emphasis role="bold"><literal>&#8220;ibm,h-get-dma-xlates-limited-supported&#8221;</literal></emphasis> property in
                all PCI host bridge OpenFirmware nodes for which the
                H_GET_DMA_XLATES_LIMITED hcall() is supported for all child
                LIOBNs.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_PARAMETER: Invalid logical I/O bus number specified */
                       /* H_P2: Invalid starting logical address */
                       /* H_P3: Invalid ending logical address */
                       /* H_P4: Invalid start I/O Bus Address */
                       /* H_P5: Invalid end I/O Bus Address */
                       /* H_IN_PROGRESS: Call is in progress, end of table was not */
                       /*   reached */
                       /* H_PARTIAL: Partial completion */
                       /* H_PAGE_REGISTERED: Page match and last page of table */
hcall ( const uint64 H_GET_DMA_XLATES_LIMITED, /*Return I/O Bus and corresponding */
                       /*   logical address */
        uint32 LIOBN,  /*Logical I/O Bus Number of a translation table*/
        uint64 SLA,    /*Starting logical address of a range*/
        uint64 ELA,    /*Ending logical address of a range*/
        uint64 SIOBA,  /*Start I/O Bus Address*/
        uint64 EIOBA ); /*End I/O Bus Address */]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Parameters:</title>

          <itemizedlist>
            <listitem>
              <para>Register R4: Logical I/O Bus Number (LIOBN)</para>

              <itemizedlist>
                <listitem>
                  <para>Bits 0-31are reserved and set to zero.</para>
                </listitem>

                <listitem>
                  <para>Bits 32-63 contain a 32-bit unsigned binary integer that
                  identifies a translation which may have one or more entries that
                  translate to a page within a range specified by the Start and End logical
                  addresses.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Register R5: Start Logical Address (SLA)</para>
            </listitem>

            <listitem>
              <para>Register R6: End Logical Address (ELA)</para>
            </listitem>

            <listitem>
              <para>Register R7: Start I/O Bus Address (SIOBA) of the translation
              specified by the LIOBN</para>

              <itemizedlist>
                <listitem>
                  <para>The SIOBA register may specify a special value of -1 or a
                  starting IOBA</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Register R8: End I/O Bus Address (EIOBA) of the translation
              specified by the LIOBN</para>

              <itemizedlist>
                <listitem>
                  <para>The EIOBA register may specify a special value of -1 or an ending
                  IOBA</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>Check that the specified LIOBN is supported and allocated to the
              calling logical partition, else H_PARAMETER.</para>
            </listitem>

            <listitem>
              <para>Check that the specified start logical address (SLA) is within
              the allocated range of the calling logical partition, and is designated
              on a 4 K-byte boundary, else H_P2.</para>
            </listitem>

            <listitem>
              <para>Check that the End logical address (ELA) minus 4K is within the
              allocated range of the calling logical partition, and is designated on a
              4 K-byte boundary, else H_P3. (May point no further than one page beyond
              the maximum partition logical real address in order to stay within the
              partition yet include the last partition page in the range of the
              test.)</para>
            </listitem>

            <listitem>
              <para>Check that the specified starting logical address (SLA) is less
              than the specified ending logical address (ELA), else H_P2.</para>
            </listitem>

            <listitem>
              <para>Check that the page specified by the logical addresses within the
              specified range is within the allocated range of the calling logical
              partition and the address is 4 K-byte aligned else H_P2.</para>
            </listitem>

            <listitem>
              <para>Check the content of SIOBA</para>

              <itemizedlist>
                <listitem>
                  <para>If a value other than -1 is specified, check that the specified
                  start I/O bus address (SIOBA) is not outside of the range of IOBAs for
                  the specified LIOBN, else H_P4.</para>
                </listitem>

                <listitem>
                  <para>If the SIOBA specifies a value of -1, the hypervisor starts the
                  search at the lowest IOBA in the translation table, otherwise the search
                  starts at the address specified by the SIOBA.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Check the content of EIOBA</para>

              <itemizedlist>
                <listitem>
                  <para>If a value other than -1 is specified, check that the specified
                  ending I/O bus address (EIOBA) is not outside of the range of IOBAs for
                  the specified LIOBN, else H_P5.</para>
                </listitem>

                <listitem>
                  <para>If the EIOBA specifies a value of -1, the hypervisor ends the
                  search at the highest IOBA in the translation table, otherwise the search
                  ends at the address specified by the EIOBA.</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>

        </simplesect>

        <simplesect>
          <title>Outputs:</title>
          <para>Place the I/O bus address and corresponding logical address into
          the respective registers:</para>

          <itemizedlist>
            <listitem>
              <para>Register R4: I/O Bus Address (IOBA)</para>

              <itemizedlist>
                <listitem>
                  <para>This register contains a 64-bit unsigned binary integer that
                  specifies the I/O bus address of the page within the specified logical
                  address range for the specified LIOBN.</para>
                </listitem>

                <listitem>
                  <para>The IOBA is returned when the hcall() completes with either
                  H_PARTIAL, H_PAGE_REGISTERED, or H_IN_PROGRESS return codes.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Register R5: Corresponding Logical Address (CLA)</para>

              <itemizedlist>
                <listitem>
                  <para>This register contains a 64-bit unsigned binary integer that
                  designates the logical address of a page within the specified range that
                  corresponds to the I/O bus address.</para>
                </listitem>

                <listitem>
                  <para>If the hcall() completes with H_IN_PROGRESS return code, the
                  corresponding logical address (CLA) is not returned.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>When the hcall() completes with H_PARTIAL or H_PAGE_REGISTERED
              return code:</para>

              <itemizedlist>
                <listitem>
                  <para>The I/O bus address (IOBA) and corresponding logical address
                  (CLA) are returned.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>When the hcall() completes with H_PAGE_REGISTERED return
              code:</para>

              <itemizedlist>
                <listitem>
                  <para>The I/O bus address (IOBA) is for the final page of the
                  translation table for the specified LIOBN as limited by the EIOBA
                  parameter.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>When the hcall() completes with H_IN_PROGRESS return code:</para>

              <itemizedlist>
                <listitem>
                  <para>The current IOBA being searched against the specified range is
                  returned, but the corresponding logical address is not returned.</para>
                </listitem>

                <listitem>
                  <para>The hcall can be reissued by specifying the IOBA as the starting
                  IOBA without incrementing the IOBA by the resource page size.</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>


          <para><emphasis role="bold">Firmware Implementation Notes:</emphasis></para>

          <orderedlist>
            <listitem>
              <para>When the H_GET_DMA_XLATES_LIMITED hcall() is issued, the
              hypervisor searches the translation table designated by the specified
              LIOBN, from the entry for SIOBA through the entry for EIOBA in IOBA
              order, for the entries that translate to a page within a given range of
              logical addresses. If an entry is found, the hcall() completes with the
              H_PAGE_REGISTERED return code if the page found is the last entry in the
              translation table, or the H_PARTIAL return code for all other pages, and
              the IOBA with the corresponding logical address are returned in output
              registers R4 and R5 respectively.</para>
            </listitem>

            <listitem>
              <para>The hypervisor searches the translation table in IOBA order, and
              proceeds in that order until an entry that translates to a physical
              address within the specified range of logical addresses is found, in
              which case, the hcall() completes with H_PARTIAL or H_PAGE_REGISTERED
              return code, or H_Success, if the end of the translation table, as
              specified by the EIOBA parameter, is reached.</para>
            </listitem>
          </orderedlist>

          <para><emphasis role="bold">Software Implementation Notes:</emphasis></para>

          <orderedlist>
            <listitem>
              <para>When the hcall() completes with H_PARTIAL return code, the
              stored IOBA is incremented by the page size of the resource corresponding
              to the specified LIOBN, and then specified as the starting I/O bus
              address on a subsequent call where the hypervisor would then proceed with
              the search until the end of the translation table, specified by the EIOBA
              parameter, is reached. The caller can accumulate a full list of the IOBAs
              for the specified LIOBN that translate into the specified range of
              logical addresses, which then forms part of the xlate translation entries
              specified as an input to the H_MIGRATE_DMA function.</para>
            </listitem>

            <listitem>
              <para>When the hcall() completes with H_PAGE_REGISTERED return code,
              this indicates that page is contained in the specified range of logical
              addresses, and it is the last page of the translation table such that the
              search for that LIOBN is complete.</para>
            </listitem>

            <listitem>
              <para>If a value other than -1 is specified in the starting I/O bus
              address register, the program should check that the specified SIOBA value
              is not the same as the returned IOBA.</para>
            </listitem>
          </orderedlist>
        </simplesect>
      </section>
    </section>
  </section>

  <section xml:id="dbdoclet.50569344_74248">
    <title>RTAS Requirements</title>
    <para>RTAS function as specified in this architecture is still required for
    LoPAR LPAR partition. RTAS is instantiated via an OF client interface
    call. RTAS operates without memory translation, therefore, the OS should
    instantiate it within the RMA, however, the OF client interface does not
    enforce this limitation. The RTAS calling sequences remain unchanged.
    However, in LPAR configurations RTAS code is implemented differently than
    in non-LPAR systems. LPAR RTAS has a part which is replicated in each
    partition, and since RTAS has the capability to manipulate hardware system
    resources, RTAS has a part which is implemented in the hypervisor. In the
    hypervisor, there is a check of the RTAS parameters for validity before
    execution. Therefore, the function of the partition replicated RTAS call is
    to martial the arguments and make the required hidden hcall()s to the
    hypervisor. In a non-LPAR system, RTAS calls are assumed to be made with
    valid parameters. This cannot be assumed with LPAR. The LPAR RTAS operates
    by all the rules of non-LPAR RTAS relative to it running real, with real
    mode pointers to arguments and the same serialization requirement relative
    to a single partition. However, the hypervisor may not assume that the
    caller is following these serialization rules, failure on the part of the
    OS to properly serialize is allowed to cause unpredictable results within
    the scope of the calling partition but may not affect the proper operation
    of other platform partitions.</para>
    <para>The following is a list of RTAS functions that are not defined or
    implemented when the LPAR option is active:</para>

    <itemizedlist>
      <listitem>
        <para><emphasis>restart-rtas</emphasis></para>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_74248"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must implement the
                PowerPC External Interrupt option.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_74248"
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> The Firmware must initialize each
                processor&#8217;s interrupt management area&#8217;s CPPR to the most
                favored level and its MFRR to the least favored level before passing
                control of the processor to the OS.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_74248"
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> The RTAS rules of serialization of
                RTAS calls must only apply to a partition and not to the system.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_74248"
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> The hypervisor cannot trust the
                RTAS calls to have no errors, therefore, the hypervisor must check a
                partition&#8217;s RTAS call parameters for validity.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_74248"
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> RTAS must be instantiated within
                the RMA of partition storage.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry xml:id="dbdoclet.50569344_48079">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_74248"
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis>
                RTAS arguments must
                be within the RMA of partition storage unless specifically specified in the
                RTAS call definition.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_74248"
            xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the LPAR option:</emphasis> If one or more hcalls fail due to
                hardware error (return status -1), the platform must make available, prior
                to the completion of the next boot sequence, via an
                <emphasis>event-scan/check-exception</emphasis>, an error log indicating
                the hardware FRU responsible for such failures. Due to the asynchronous
                nature of error analysis, there is not a direct correlation between the log
                and a specific failing hcall(), indeed the error log may precede the
                failing hcall().</para>
              </listitem>
         	</varlistentry>
        </variablelist>

      </listitem>
    </itemizedlist>

  </section>
  <section xml:id="sec_of_req">
    <title>OF Requirements</title>
    <para>The hypervisor is initialized and configured prior to the loading of
    OF into the partition and boot of any client program (OS) in the partition
    by OF. The NVRAM data base that describes the platform&#8217;s partitioning
    is used to trigger the loading and initialization of the hypervisor. When
    Logical Partitioning is enabled, a copy of OF code is loaded into each
    partition where it builds the per partition device tree within the
    partition&#8217;s RAM. The per partition device tree contains only entries
    for platform components actually assigned to or used by the partition. The
    invocation of the subset of the OF Client interface specified below appears
    the same to the OS image regardless of the state of the LPAR option.</para>
    <para>A model of the boot sequence is as follows:</para>

    <orderedlist>
      <listitem>
        <para>Support processor runs chip tests and configures the CPU
        chips.</para>
      </listitem>

      <listitem>
        <para>The support processor loads the boot ROM image into System Memory
        along with the configuration information.</para>

        <orderedlist>
          <listitem>
            <para>POST code</para>
          </listitem>

          <listitem>
            <para>Initialization Firmware</para>
          </listitem>

          <listitem>
            <para>Hardware configuration reporting structures</para>
          </listitem>

          <listitem>
            <para>OF</para>
          </listitem>

          <listitem>
            <para>Hypervisor RTAS</para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>boot ROM executes POST and Initialization Firmware.</para>
      </listitem>

      <listitem>
        <para>Processor initialization code synchronizes the time bases of all
        platform processors to a small value (approaching zero).</para>
      </listitem>

      <listitem>
        <para>Initialization Firmware accesses the NVRAM Partition Database to
        determine if the LPAR option is enabled.</para>
      </listitem>

      <listitem>
        <para>Initialization Firmware initializes the hypervisor.</para>
      </listitem>

      <listitem>
        <para>The hypervisor configures itself using the hardware configuration
        reporting structures.</para>
      </listitem>

      <listitem>
        <para>The hypervisor configures the various partitions with resources as
        required by the NVRAM Partition Database.</para>
      </listitem>

      <listitem>
        <para>The hypervisor loads a copy of OF into each partition passing to
        OF a resource reporting structure known as the NACA/PACA.</para>
      </listitem>

      <listitem>
        <para>OF notices in the NACA/PACA that a specific partition table is
        specified.</para>
      </listitem>

      <listitem>
        <para>OF Scans the configuration and walks the buses to build the
        partition device tree.</para>
      </listitem>

      <listitem>
        <para>OF requests the specific partition table from the NVRAM Partition
        Database.</para>
      </listitem>

      <listitem>
        <para>OF loads RTAS into the partition&#8217;s memory.</para>
      </listitem>

      <listitem>
        <para>OF pulls in the configuration variables from the
        partition&#8217;s NVRAM area and uses them to determine the
        partition&#8217;s boot device.</para>
      </listitem>

      <listitem>
        <para>OF then loads the client program and starts executing it with one
        of the partition&#8217;s processors.</para>
      </listitem>

      <listitem>
        <para>The client program notices that it is running on a LPAR capable
        machine but does not have the hypervisor bit on in the MSR so must use
        hcall() routines for its PFT and TCE accesses. The presence of the
        <emphasis role="bold"><literal>&#8220;ibm,hypertas-functions&#8221;</literal></emphasis> property is a
        duplicate indication of LPAR mode.</para>
      </listitem>
    </orderedlist>

    <variablelist>
     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The OF code state must be retained
            after all partitions are initialized pending future boot requests.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The OF code must recognize that
            logical partitioning is required as opposed to a non-LPARed system.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The OF must generate the device
            tree for the partition within the partition&#8217;s RAM.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR combined with Dynamic Reconfiguration
            option:</emphasis> The
            <emphasis role="bold"><literal>&#8220;interrupt-ranges&#8221;</literal></emphasis> property for any
            reported interrupt source controller must report all possible interrupt
            source numbers.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The OF device tree for a partition
            must include in the root node, the
            <emphasis role="bold"><literal>&#8220;ibm,partition-no&#8221;</literal></emphasis> property.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The OF device tree for an LPAR
            capable model not running in a partition must include in the root node, the
            <emphasis role="bold"><literal>&#8220;ibm,partition-no&#8221;</literal></emphasis> property when the
            default partition number for the first partition created is not 1.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The
            <emphasis role="bold"><literal>&#8220;ibm,partition-no&#8221;</literal></emphasis> property value must be
            an integer in the range of 1 to 2<superscript>20</superscript>-1.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The OF device tree for a partition
            must include in the root node, the
            <emphasis role="bold"><literal>&#8220;ibm,partition-name&#8221;</literal></emphasis> property.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> When the platform does not provide
            a partition manager and the one and only partition in the system owns all
            the partition visible system resources, then the default value of the
            <emphasis role="bold"><literal>&#8220;ibm,partition-name&#8221;</literal></emphasis> property must be the
            content of the SE keyword (as displayed in the same form as the root node
            <emphasis role="bold"><literal>&#8220;system-id&#8221;</literal></emphasis> property) with a hyphen added
            between the plant of manufacture and sequence number.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The nodes of the OF device tree
            for a partition that represent platform resources that are not explicitly
            allocated for the control of the platform&#8217;s OS image must be marked
            &#8220;used-by-rtas&#8221;. This includes, but is not limited to, memory
            controllers, and IO bridges that are a part of the platform&#8217;s
            infrastructure common to more than one partition and commonly represented
            in the OF device tree. But does not include read only resources such as
            environmental sensors.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The OF must, at the OS&#8217;s
            request, load the required RTAS into the partition&#8217;s real addressable
            memory region.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The OF must use the
            partition&#8217;s segment of the NVRAM to establish the partition&#8217;s
            boot device and configuration variables.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The OF must load the client
            program and choose the partition&#8217;s processor on which to begin
            execution.</para>
            <para><emphasis role="bold">Note:</emphasis> It is the responsibility of the client program to recognize
            whether or not to use LPAR page management.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must initialize the
            time base of the first processor to a small (approaching zero) value prior
            to turning over control of the processor to a client program.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
          <listitem>
              <!-- FIXME: Where should the following requirement point, if anywhere? >
              <para>R1-14.7-15. <emphasis> (Merged into Requirement <xref linkend="error_section"/>11 SMP.htm#50569340_30040)</emphasis></para-->
              <para>Reserved</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The OF Client Interface must
            restrict access to only resources contained within the calling
            partition&#8217;s version of the device tree.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The OF Client Interface must
            prevent the calls of one partition&#8217;s client program from interfering
            with the operation of another partition&#8217;s client program.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The OF Client Interface must
            restrict its supported calls and methods to those specified in
            <xref linkend="dbdoclet.50569344_17015" />.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> Any hidden hcall()s which firmware
            may use to implement OF functions must check its parameters to insure
            compliance with all of the architecturally mandated OF requirements.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_of_req"
        xrefstyle="select: labelnumber nopage"/>-20.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The OF Client Interface functions
            &#8220;start-cpu&#8221; and &#8220;resume-cpu&#8221; must restrict their
            operation to processors assigned to the calling Client&#8217;s
            partition.</para>
          </listitem>
     	</varlistentry>
    </variablelist>

    <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_17015">
      <title>OF Client Interface Functions Supported under the LPAR
      Option</title>
      <?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
      <tgroup cols="4">
        <colspec colname="c1" colwidth="25*" align="center" />
        <colspec colname="c2" colwidth="25*" align="center" />
        <colspec colname="c3" colwidth="25*" align="center" />
        <colspec colname="c4" colwidth="25*" align="center" />
        <tbody valign="middle">
          <row>
            <entry>
              <para>test</para>
            </entry>
            <entry>
              <para>cannon</para>
            </entry>
            <entry>
              <para>child</para>
            </entry>
            <entry>
              <para>finddevice</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>getprop</para>
            </entry>
            <entry>
              <para>getproplen</para>
            </entry>
            <entry>
              <para>instance-to-package</para>
            </entry>
            <entry>
              <para>instance-to-path</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>nextprop</para>
            </entry>
            <entry>
              <para>package-to-path</para>
            </entry>
            <entry>
              <para>parent</para>
            </entry>
            <entry>
              <para>peer</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>setprop</para>
            </entry>
            <entry>
              <para>call-method</para>
            </entry>
            <entry>
              <para>test-method</para>
            </entry>
            <entry>
              <para>close</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>open</para>
            </entry>
            <entry>
              <para>read</para>
            </entry>
            <entry>
              <para>seek</para>
            </entry>
            <entry>
              <para>write</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>claim</para>
            </entry>
            <entry>
              <para>release</para>
            </entry>
            <entry>
              <para>boot</para>
            </entry>
            <entry>
              <para>enter</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>exit</para>
            </entry>
            <entry>
              <para>start-cpu</para>
            </entry>
            <entry>
              <para>milliseconds</para>
            </entry>
            <entry>
              <para>size(/chosen/nvram)</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>get-time</para>
            </entry>
            <entry>
              <para>&#160;</para>
            </entry>
            <entry>
              <para>instantiate-rtas</para>
            </entry>
            <entry>
              <para>&#160;</para>
            </entry>
          </row>
        </tbody>
      </tgroup>
    </table>
  </section>
  <section xml:id="sec_nvram_req">
    <title>NVRAM Requirements</title>
    <para>The NVRAM is divided into multiple partitions each containing
    different categories of data similar to files in a file system (these NVRAM
    partitions are not to be confused with LPAR partitions). Each NVRAM
    partition is structured with a self identifying header followed by its
    partition unique data. Many of these NVRAM partitions contain data only
    relevant to the platform firmware, while others contain data that either is
    for OS image use from boot to boot or is used to communicate operational
    parameters from the OS image to the platform. The platform firmware on LPAR
    supporting platforms structures the NVRAM as per
    <xref linkend="dbdoclet.50569344_34559" />. Each LPAR partition is assigned
    a region of NVRAM space. This includes space for LPAR partition specific
    configuration variables as well as the minimum 4 K space reserved for the
    OS image. The hypervisor restricts access for the LPAR partition, through
    logical address translation and range checking, to its assigned NVRAM
    region. Other regions of NVRAM are reserved for firmware use including, for
    instance, information about how the system should be partitioned.</para>

    <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_34559">
      <title>LPAR NVRAM Map</title>
      <?dbhtml table-width="60%" ?><?dbfo table-width="60%" ?>
      <tgroup cols="3">
        <colspec colname="c1" colwidth="33*" align="center" />
        <colspec colname="c2" colwidth="33*" align="center" />
        <colspec colname="c3" colwidth="33*" align="center" />
        <thead valign="middle">
          <row>
            <entry>
              <para>
                <emphasis role="bold">Real Address Range</emphasis>
              </para>
            </entry>
            <entry>
              <para>
                <emphasis role="bold">Per Partition NVRAM access routine rtas
                call Logical Address Range -- outside of legal range return
                0x00 and discard write data.</emphasis>
              </para>
            </entry>
            <entry>
              <para>
                <emphasis role="bold">Contents</emphasis>
              </para>
            </entry>
          </row>
        </thead>
        <tbody valign="middle">
          <row>
            <entry>
              <para>0x00 to F-1</para>
            </entry>
            <entry>
              <para>NA</para>
            </entry>
            <entry>
              <para>Firmware only partitions (Signatures 0x00 to 0x6F)</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>F to (F-1+P)</para>
            </entry>
            <entry>
              <para>0x00 to P</para>
            </entry>
            <entry>
              <para>Per LPAR partition copies of supported NVRAM partitions
              with signatures 0x70 to 0x7F</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>(F+P) to (F-1+2P)</para>
            </entry>
            <entry>
              <para>0x00 to P</para>
            </entry>
            <entry>
              <para>Per LPAR partition copies of supported NVRAM partitions
              with signatures 0x70 to 0x7F</para>
            </entry>
          </row>
          <row>
            <entry nameend="c3" namest="c1">
              <para>.<?linebreak?>.<?linebreak?>.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>(F+(P*(n-1)))</para>
              <para>to</para>
              <para>((F-1)+ nP)</para>
            </entry>
            <entry>
              <para>0x00 to P</para>
            </entry>
            <entry>
              <para>Per LPAR partition copies of supported NVRAM partitions
              with signatures 0x70 to 0x7F</para>
            </entry>
          </row>
        </tbody>
      </tgroup>
    </table>
    <para>&#160;</para>
    <table frame="all" pgwide="1">
      <title>NVRAM partitions on LPAR platforms</title>
      <tgroup cols="4">
        <colspec colname="c1" colwidth="25*" align="center" />
        <colspec colname="c2" colwidth="25*" align="center" />
        <colspec colname="c3" colwidth="25*" align="center" />
        <colspec colname="c4" colwidth="25*" align="center" />
        <thead valign="middle">
          <row>
            <entry>
              <para>
                <emphasis role="bold">Visible to:</emphasis>
              </para>
            </entry>
            <entry>
              <para>
                <emphasis role="bold">Partition Signatures</emphasis>
              </para>
            </entry>
            <entry>
              <para>
                <emphasis role="bold">Partition Name</emphasis>
              </para>
            </entry>
            <entry>
              <para>
                <emphasis role="bold">Comments</emphasis>
              </para>
            </entry>
          </row>
        </thead>
        <tbody valign="middle">
          <row>
            <entry>
              <para>Only to the Platform firmware</para>
            </entry>
            <entry>
              <para>0x00 - 0x6F</para>
            </entry>
            <entry>
              <para>&#160;</para>
            </entry>
            <entry>
              <para>&#160;</para>
            </entry>
          </row>
          <row>
            <entry morerows="1">
              <para>Only to Platform firmware and the OS image running in the
              owning LPAR Partition.</para>
              <para>The read and write NVRAM RTAS routines</para>
            </entry>
            <entry>
              <para>0x70</para>
            </entry>
            <entry>
              <para>Common</para>
            </entry>
            <entry>
              <para>This partition is duplicated per partition.</para>
            </entry>
          </row>
          <row>
            <entry>
              <para>0x7F</para>
            </entry>
            <entry>
              <para>0x7777777777777777-<?linebreak?>77777777</para>
            </entry>
            <entry>
              <para>This partition is duplicated per partition and is at least
              4 KB long when the OS is first installed.</para>
            </entry>
          </row>
        </tbody>
      </tgroup>
    </table>

    <variablelist>
     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_nvram_req"
        xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> Platform OF must locate
            configuration variables that the OS must manipulate to select options as to
            how the specific OS image interfaces or relates to the platform in the
            partition&#8217;s &#8220;system&#8221; partition signature (0x70) named
            &#8220;common&#8221;, specifically none may be located in the
            &#8220;OF&#8221; signature (0x50).</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_nvram_req"
        xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The NVRAM region assigned to an
            LPAR partition must contain, after any platform required NVRAM partitions
            have been allocated, a free space partition a minimum of 4 KB long prior to
            the installation of the partition&#8217;s OS image.</para>
          </listitem>
     	</varlistentry>
    </variablelist>
  </section>

  <section xml:id="sec_admin_app_comm_req">
    <title>Administrative Application Communication Requirements</title>
    <para>The platform needs to communicate with the an administrative
    application (outside of the scope of LoPAR) to manage the platform
    resources. The administrative application may run in an external computer
    such as a Hardware Management Console, or it may be integrated into a
    service partition. Many system facilities are not dedicated to an LPAR
    partition but are managed through the HMC and the administrative
    application.</para>

    <variablelist>
     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_admin_app_comm_req"
        xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must provide a
            communications means to the administrative application.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_admin_app_comm_req"
        xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must respond to
            messages received from the administrative application.</para>
          </listitem>
     	</varlistentry>
    </variablelist>
  </section>

  <section xml:id="sec_rtas_acc_hyp_rsc">
    <title>RTAS Access to Hypervisor Virtualized Resources</title>
    <para>All allolcatable platform resources are always assigned to a
    partition. There always exists a dummy partition that is never active.
    Resources assigned to partitions that are inactive may be reassigned to
    other partitions by mechanisms implemented in the Hardware Management
    Console.</para>

    <variablelist>
     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The nvram-fetch RTAS call must
            restricted access to only the LPAR partition&#8217;s assigned
            &#8220;OS&#8221;, &#8220;System&#8221; and &#8220;Error Log&#8221; nvram
            partitions.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The nvram-store RTAS call must
            restricted accss to only the LPAR partition&#8217;s assigned
            &#8220;OS&#8221;, &#8220;System&#8221; and &#8220;Error Log&#8221; nvram
            partitions.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The get-time-of-day RTAS call must
            return the LPAR partition&#8217;s specific time of day clock value.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The set-time-of-day RTAS call must
            set the LPAR partition&#8217;s specific time of day clock value.</para>
            <para><emphasis role="bold">Firmware Implementation Note:</emphasis> The model implementation keeps time of
            day on a partition basis. What is really changed is the offset from the
            hardware TOD clock which is not normally written (Only written if for some
            reason it is approaching its maximum value, such as after a battery
            failure).</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The event-scan RTAS call must
            report global events to each LPAR partition and LPAR partition local events
            only to the affected LPAR partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The check-exception RTAS call must
            report global events to each LPAR partition and LPAR partition local events
            only to the affected LPAR partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The rtas-last-error RTAS call must
            report only RTAS errors affecting the calling LPAR partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The
            <emphasis>ibm,read-pci-config</emphasis> RTAS calls must restrict access to
            only IOAs assigned to the calling LPAR partition, and if the configuration
            address is not available to the caller, must return a status of Success
            with all ones as the output value.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The ibm,write-pci-config RTAS
            calls must restrict access to only IOAs assigned to the calling LPAR
            partition, and if the configuration address is not available to the caller,
            must be ignored and must return a status of Success.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The ibm,write-pci-config RTAS
            calls must prevent changing of the firmware assigned interrupt message
            number on IOAs configured to use message signaled interrupts.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-11.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must virtualize the
            display-character RTAS call such that the operator can distinguish and
            selectively read messages from each partition without interference with
            messages from other partitions.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-12.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The set-indicator RTAS call must
            restrict access to only indicators assigned to the calling LPAR
            partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-13.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The effects of the
            <emphasis>system-reboot</emphasis> RTAS call must be restricted to only the
            calling LPAR partition.</para>
            <para><emphasis role="bold">Firmware Implementation Note:</emphasis> One standard OS response to a machine
            check is to reboot. Thus expecting the firmware to reset any error
            conditions such as in the I/O sub-system. When the I/O sub-system, or parts
            thereof, are shared among multiple partitions, the platform cannot allow
            the boot of one partition to prevent another partition from detecting that
            it was also affected by an I/O error.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-14.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must deliver machine
            check and other event notifications to all affected partitions before
            initiating recovery operations such as rebooting and resetting hardware
            fault isolation circuits.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-15.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The
            <emphasis>start-cpu</emphasis> RTAS call must be restricted to only the
            processors assigned to the calling LPAR partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-16.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The
            <emphasis>query-cpu-stopped-state</emphasis> RTAS call must be restricted to
            only the processors assigned to the calling LPAR partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-17.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The
            <emphasis>power-off</emphasis> and
            <emphasis>ibm,power-off-ups</emphasis> RTAS calls must deactivate the
            calling partition and not power off the platform if other partitions remain
            active.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-18.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The
            <emphasis>set-time-for-power-on</emphasis> RTAS call must activate the
            platform when the partition requesting the earliest activation time is to
            be activated.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-19.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The
            <emphasis>ibm,os-term</emphasis> RTAS call must adjust support processor
            surveillance to account for the termination of the LPAR partition&#8217;s
            OS.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry xml:id="dbdoclet.50569344_35543">
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-20.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis>
            The <emphasis>ibm,set-xive</emphasis> RTAS call must restrict access to only
            interrupt sources assigned to the calling LPAR partition by silently
            failing if the interrupt source is not owned by the calling partition
            (return success without modifying the state of the unowed interrupt
            logic).</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-21.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The
            <emphasis>ibm,set-xive</emphasis> RTAS call must restrict the written queue
            values to only interrupt processors assigned to the calling LPAR
            partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry xml:id="dbdoclet.50569344_75733">
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-22.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis>
            The <emphasis>ibm,get-xive</emphasis> RTAS call must restrict access to only
            interrupt sources assigned to the calling LPAR partition by silently
            failing if the interrupt source is not owned by the calling partition
            (return success with the least favored interrupt level, the interrupt
            server number is undefined -- possibly all ones).</para>
          </listitem>
     	</varlistentry>

     	<varlistentry xml:id="dbdoclet.50569344_77846">
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-23.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis>
            The <emphasis>ibm,int-on</emphasis> RTAS call must restrict access to only
            interrupt sources assigned to the calling LPAR partition by silently
            failing if the interrupt source is not owned by the calling partition
            (return success without modifying the state of the unowed interrupt
            logic).</para>
          </listitem>
     	</varlistentry>

     	<varlistentry xml:id="dbdoclet.50569344_77100">
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-24.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis>
            The <emphasis>ibm,int-off</emphasis> RTAS call must restrict access to only
            interrupt sources assigned to the calling LPAR partition by silently
            failing if the interrupt source is not owned by the calling partition
            (return success without modifying the state of the unowed interrupt
            logic).</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-25.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The
            <emphasis role="bold"><literal>ibm,configure-connector</literal></emphasis> RTAS call must restrict access
            to only Dynamic Reconfiguration Connectors assigned to the calling LPAR
            partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-26.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must either define or
            virtualize the power domains used by the set-power-level RTAS call such
            that power level settings do not affect other partitions.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-27.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The set-power-level and
            get-power-level RTAS calls must restrict access to only power domains
            assigned to the calling partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-28.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must restrict the
            availability of the ibm,exti2c RTAS call to at most one partition (like any
            IOA slot).</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-29.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The ibm,set-eeh-option RTAS call
            must restrict access to only IOAs assigned to the calling partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-30.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The ibm,set-slot-reset RTAS call
            must restrict access to only IOAs assigned to the calling partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-31.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The ibm,read-slot-reset-state2
            RTAS call must restrict access to only IOAs assigned to the calling
            partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-32.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The
            <emphasis>ibm,configure-bridge</emphasis> RTAS call must restrict access to
            only configuration addresses assigned to the calling partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-33.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The ibm,set-eeh-option RTAS call
            must restrict access to only IOAs assigned to the calling partition.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-34.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> The platform must restrict the
            ibm,open-errinjct, ibm,close-errinjct, and ibm,errinjct RTAS calls as well
            as the errinjct properties be available on at most one partition as defined
            by a platform wide firmware configuration variable.</para>
          </listitem>
     	</varlistentry>

     	<varlistentry>
        <term><emphasis role="bold">R1-<xref linkend="sec_rtas_acc_hyp_rsc"
        xrefstyle="select: labelnumber nopage"/>-35.</emphasis></term>
          <listitem>
            <para><emphasis role="bold">For the LPAR option:</emphasis> Any hidden hcall()s which firmware
            may use to implement RTAS functions must check its parameters to insure
            compliance with all of the architecturally mandated RTAS
            requirements.</para>
          </listitem>
     	</varlistentry>
    </variablelist>

  </section>

  <section xml:id="dbdoclet.50569344_27067">
    <title>Shared Processor LPAR Option</title>
    <para>The Shared Processor LPAR (SPLPAR) option allows the hypervisor to
    generate multiple virtual processors by time slicing a single physical
    processor. These multiple virtual processors may be assigned to one or more
    OS images. There are two primary customer advantages to SPLPAR over the
    standard LPAR. Most obviously, the assigned processing capacity of the
    partition can scale downwards to allow for more OS images to be supported
    on a single platform. The second customer advantage is that a SPLPAR
    platform can achieve higher processor utilization by providing partitions,
    that can use extra processing capacity, with the spare capacity ceded from
    other partitions. This allows the customer to take advantage of the
    variable nature of the instantaneous load on any one OS image to achieve an
    increase in the average utilization of the platform&#8217;s capacity. While
    the peak capacity (directly related to the platform cost) stays constant,
    the customer may see a significant improvement in the average capacity
    among all the platform&#8217;s workloads. However, since the peak capacity
    cannot be physically exceeded, the customer may experience a wider variance
    in performance when exercising the SPLPAR option.</para>
    <para>In principal, the OS images running on the virtual processors of an
    SPLPAR platform need not be aware that they are sharing their physical
    processors, however, in practice, they experience significantly better
    performance if they make a few optimizations. Specifically, if the OS
    images cedes their virtual processor to the platform when they are idle,
    and confers their processor to the holder of a spin lock for which the
    virtual processor must wait. Another significant change due to SPLPAR is
    that there may not be a fixed relationship between a virtual processor and
    the physical processor that actualizes it. In those cases, such physical
    information as location codes are undefined, affinity and associativity
    values are indistinguishable, relationships to secondary caches are
    meaningless, and any attempt by an OS to characterize the quality of its
    processor (such as running diagnostics or performance comparisons to other
    virtual processors) provide unreliable results. OF entities, that represent
    physical characteristics of a virtual processor that do not remain fixed,
    take on altered definitions/ requirements in an SPLPAR environment.</para>
    <para>To provide input to the capacity planning and quality of service
    tools, the hypervisor reports to an OS certain statistics, these include
    the minimum processor capacity that the OS can expect (the OS may cede any
    unused capacity back to the platform), the maximum processor capacity that
    the platform grants to the OS, the portion of spare capacity (up to the
    maximum) that the platform grants to the OS, and the maximum latency to a
    dispatch via an hcall().</para>
    <para>The OS image optionally registers a data area (VPA) for each virtual
    processor using the H_REGISTER_VPA hcall(). The hypervisor maintains a
    variable, within the data area, that is incremented each time the virtual
    processor is dispatched/preempted, such that the dispatch variable is
    always even when the virtual processor is dispatched and always odd when it
    is not dispatched. The achitectural intent for the usage of the dispatch
    count variable is describe below in the paragraph devoted to conferring the
    processor. Additionally this hcall() may register a trace buffer which the
    OS may activate to gain detailed information about virtual processor
    preemption and dispatching.</para>
    <para>Both the VPA and the trace log buffer contain statistics on how long
    the virtual processor has waited (not been dispatched on a physical
    processor). Architecturally, the virtual processor wait time is divided
    into three intervals:</para>

    <orderedlist>
      <listitem>
        <para>The time that the virtual processor waited to become logically
        ready to run again, for example:</para>

        <orderedlist>
          <listitem>
            <para>The time needed to resolve a fault</para>
          </listitem>

          <listitem>
            <para>The time needed to process a hypervisor preemption</para>
          </listitem>

          <listitem>
            <para>The time until a wake up event after voluntarily relinquishing the
            physical processor</para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>The time spent waiting after interval 1 until virtual processor
        capacity was available. Shared processor partitions are granted a quantum
        of virtual processor capacity (execution time) each dispatch wheel
        rotation; thus if the partition has used its capacity, the ready to run
        virtual processor has to wait until the next quantum is granted.</para>
      </listitem>

      <listitem>
        <para>The time spent waiting after interval 2 until the virtual
        processor was dispatched on a physical processor. This is arises from the
        fact that multiple ready to run virtual processors with virtual processor
        capacity may be competing for a single physical processor.</para>
      </listitem>
    </orderedlist>

    <para>Two other performance statistics are available via hcall()s these are
    the Processor Utilization Register, and Pool Idle Count returned by the
    H_PURR and H_PIC hcall()s respectively. These two statistics are counts in
    the same units as counted by the processor time base. Like the time base,
    the PUR and PIC are 64 bit values that are set to a numerically low value
    during system initialization. The difference between their values at the
    end and beginning of monitored operations provides data on virtual
    processor performance. The value of the PUR is a count of processor cycles
    used by the calling virtual processor. The PUR count is intended to provide
    an indication to the partition software of the computation load supported
    by the virtual processor. SPLPAR virtual processors are created by
    dispatching the virtual processor&#8217;s architectural state on one of the
    physical processors from a pool of physical processors. The value of the
    PIC is the summation of the physical processor pool idle cycles, that is
    the number of time base counts when the pool could not dispatch a virtual
    processor. The PIC count is intended to provide an indication to platform
    management software of the pool capacity to perform more work.</para>
    <para>A well behaved OS image normally cedes its virtual processor to the
    platform using the H_CEDE hcall() after it determines that it currently has
    run out of useful work. The H_CEDE hcall() gives up the virtual processor
    until either an external interrupt (including decrementer, and Inter
    Processor Interrupt) or another one of the partition&#8217;s processors
    executes an H_PROD hcall() see below. Note the decrementer appears to
    continue to run during the time that the virtual processor is ceded to the
    platform. The H_CEDE hcall() always returns to the next instruction,
    however, prior to executing the next instruction, any pending interrupt is
    taken. To simulate atomic testing for work, the H_CEDE call may be called
    with interrupts disabled, however, the H_CEDE call activates the virtual
    processor&#8217;s MSR<subscript>EE</subscript> bit to avoid going into a wait state with interrupts
    masked.</para>
    <para>A multi-processor OS uses two methods to initiate work on one
    processor from another, in both cases the requesting processor places a
    unit of work structure on a queue, and then either signals the serving
    processor via an Inter-Processor interrupt to service the work queue, or
    waits until the serving processor polls the work queue. The former method
    translates directly to the SPLPAR environment, the second method may
    experience significant performance degradation if the serving processor has
    ceded. To provide a solution to this performance problem, the SPLPAR
    provides the H_PROD hcall(). The H_PROD hcall() takes as a parameter the
    virtual processor number of the serving processor. Waking a potentially
    ceded or ceding processor is subject to many race conditions. The semantic
    of the H_PROD hcall() attempts to minimize these race conditions. First the
    H_CEDE and H_PROD hcall()s serialize on each other per target virtual
    processor. Secondly by having the H_PROD firmware set a per virtual
    processor memory bit before attempting to determine if the target virtual
    processor is preempted. If the processor is not preempted the H_PROD
    hcall() immediately returns, else the processor is dispatched and the
    memory bit is reset. If the processor was dispatched, and subsequently the
    virtual processor does a H_CEDE operation, the H_CEDE hcall() checks the
    virtual processor&#8217;s memory bit and if set, resets the bit and returns
    immediately (not ceding the physical processor to another virtual
    processor). An OS might choose to always do an H_PROD after an enqueue to a
    polled queue or it might qualify making the H_PROD hcall() with a status
    bit set by the by the target processor when it decides to cede its virtual
    processor.</para>
    <para>Locking in a SPLPAR environment presents a problem for
    multi-programming OSs, in that the virtual processor that is holding a lock
    may have been preempted. In that case, spinning, waiting for the lock,
    simply wastes time since the lock holder is in no position to release the
    lock -- it needs processor cycles and cannot get them for some period of
    time and the spinner is using up processor cycles waiting for the lock. The
    condition is known as a live lock, however, it eventually resolves itself.
    The SPLPAR optimization to alleviate this problem is to have the waiting
    virtual processor &#8220;confer&#8221; its processor cycles to the lock
    holder&#8217;s virtual processor until the lock holder has had a chance to
    run another dispatch time slice.</para>
    <para>As with the cede/prod pair of functions above, the confer function is
    subject to timing window races between the waiting process determining that
    the lock holder has been preempted and execution of the H_CONFER hcall()
    during which time the originally holding virtual processor may have been
    dispatched, released the lock and ceded the processor. To manage this
    situation, the H_CONFER takes two parameters, one that specifies the
    virtual processor(s) that are to receive the cycles and the second
    parameter (valid only when a single processor is specified) which
    represents the dispatch count of the holding virtual processor atomically
    captured when the waiting processor decided to confer its cycles to the
    waiting processor.</para>
    <para>The semantic of H_CONFER checks the processor parameter for validity,
    then if it is the &#8220;all processors&#8221; code proceeds to the
    description below. If the processor parameter refers to a valid virtual
    processor owned by the calling virtual processor&#8217;s partition, that is
    not dispatched, that has not conferred its cycles to all other processors,
    and who&#8217;s current dispatch count matches that of the second
    parameter, the time remaining from the calling processors time slice is
    conferred to the specified virtual processor.</para>
    <para>If the first parameter of H_CONFER specifies the &#8220;all
    processors&#8221; code, then it marks the calling virtual processor to
    confer all its cycles until all of the partition&#8217;s virtual
    processors, that have not ceded or conferred their cycles, have had a
    chance to run a dispatch time slice. The &#8220;all processors&#8221;
    version may be viewed as having the hypervisor record the dispatch counts
    for all the other platform processors in the calling virtual
    processor&#8217;s hypervisor owned &#8220;confer structure&#8221;, then
    prior to any subsequent dispatch of the calling processor, if the confer
    structure is not clear, the hypervisor does the equivalent of removing one
    entry from the confer structure and calling H_CONFER for the specific
    virtual processor. If the specific virtual processor confer is rejected
    (because the virtual processor is running, ceded, conferred, or the
    dispatch count does not match) then the next entry is tried until the
    confer structure is clear before the originally calling virtual processor
    is re-dispatched.</para>
    <para>Virtual processors may migrate among the physical processor pool from
    one dispatch cycle to the next. OF device tree properties that relate the
    characteristics of the specific physical processor such as location codes,
    and other vital product data cannot be consistent and are not reported in
    the nodes of type
    <emphasis role="bold"><literal>cpu</literal></emphasis> if the partition is running in SPLPAR mode. Most
    processor characteristics properties such as time base increment rate, are
    consistent for all processors in the system physical and virtual so are
    still reported via their standard properties. Additionally nodes of type

    <emphasis role="bold"><literal>L2</literal></emphasis> are not present in the tree since they are shared
    with other virtual processors making optimizations based upon their
    characteristics impossible. The Processor Identification Register (PIR)
    should not be accessed by the OS since from cycle to cycle the OS may get
    different readings, instead the virtual processor number (the number from
    the
    <emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis> property,
    contained in the nodes of type
    <emphasis role="bold"><literal>cpu</literal></emphasis>, associated with this virtual processor) is used
    as the processor number to be passed as parameters to RTAS and hcall()
    routines for managing interrupts etc.</para>
    <para>
    <emphasis role="bold">Software Note:</emphasis> When the client program (OS) first gets
    control during the boot sequence, the virtual processor number of the
    single processor that is operational is identified by the
    <emphasis role="bold"><literal>/chosen</literal></emphasis> node of the device tree. The
    <emphasis role="bold"><literal>cpu</literal></emphasis> nodes list the other virtual processors that the
    first processor may start. These are started one at a time, giving the
    virtual processor number as an input parameter to the call. As each
    processor starts, it starts executing a program that picks up its virtual
    processor number from a memory structure initialized by the processor that
    called the start-cpu function. The newly started processor then records the
    location of its per processor memory structure (where it saves its virtual
    processor number) in one of the SPRG registers.</para>

    <section xml:id="dbdoclet.50569344_85918">
      <title>Virtual Processor Areas</title>
      <para>The per processor areas are registered with the H_REGISTER_VPA
      hcall() that takes three parameters. The first parameter is a flags field
      that specifies the specific sub function to be performed, the second is
      the virtual processor number of one of the processors owned by the
      calling virtual processor&#8217;s partition for whom the area is being
      registered. The third parameter is the logical address, within the
      calling virtual processor&#8217;s partition, of the contiguous logically
      addressed storage area to be registered. Registered areas are aligned on
      a cache line (l1) size boundary and may not span an LMB boundary and for
      the CMO option may not span an entitlement granule boundary. The length
      of the area is provided to the hcall() in starting in byte offset 4 of
      the area being registered. The H_REGISTER _VPA hcall() registers various
      types of areas, and after verifying the parameters, initializes the
      structure&#8217;s variables.</para>
      <para>Per Virtual Processor Area: This area contains shared processor
      operating parameters as defined in
      <xref linkend="dbdoclet.50569344_46490" />. A shared processor LPAR aware
      OS registers this area early in its initialization. The other types of
      virtual processor areas can only be registered after the Per Virtual
      Processor Area has been successfully registered. The minimum length of
      the Per Virtual Processor Area is 640 bytes and the structure may not
      span a 4096 byte boundary.</para>
      <para>Dispatch Trace Log Buffer: This area is optionally registered by
      OS&#8217;s that desire to collect performance measurement data relative
      to its shared processor dispatching. The minimum size of this area is 48
      bytes while the maximum is 4 KB. See
      <xref linkend="dbdoclet.50569344_29153" /> for more details</para>
      <para>SLB Shadow Buffer: This area is optionally registered by OS&#8217;s
      that support the SLB-shadow function set. The structure may not span a
      4096 byte boundary. This function set allows the hypervisor to
      significantly reduce the overhead associated with virtual processor
      dispatch in a shared processor LPAR environment, and to provide enhanced
      recovery from SLB hardware errors. See
      <xref linkend="dbdoclet.50569344_66820" /> for more details.</para>
      <para>
      <emphasis role="bold">Software Note:</emphasis> Registering, deregistering or changing
      the value of a variable in one of the Virtual Processor Areas for a
      different virtual processor (i.e. changing a value in the VPA of
      processor A from processor B) may be problematic. In no cases is
      partition integrity be compromised, but results may be imprecise if such
      a change is made during the virtual processor preempt/dispatch window. If
      the owning processor is started, registration or deregistration should
      only be done by the owning processor, if the processor is stopped,
      registration or deregistration can safely be done by other processors.
      Also, for example, changing the number of persistent SLB Shadow Buffer
      entries cause uncertainty in the number of currently valid SLB entries in
      that virtual processor. In some cases, such as turning on and off
      dispatch tracing, such uncertainty may be acceptable.</para>

      <section>
        <title>Per Virtual Processor Area</title>
        <para>&#160;</para>
        <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_46490">
          <title>Per Virtual Processor Area</title>
          <tgroup cols="3">
            <colspec colname="c1" colwidth="15*" align="center" />
            <colspec colname="c2" colwidth="15*" align="center" />
            <colspec colname="c3" colwidth="70*" />
            <thead valign="middle">
              <row>
                <entry>
                  <para>
                    <emphasis role="bold">Byte Offset</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Length in Bytes</emphasis>
                  </para>
                </entry>
                <entry align="center">
                  <para>
                    <emphasis role="bold">Variable Description</emphasis>
                  </para>
                </entry>
              </row>
            </thead>
            <tbody valign="middle">
              <row>
                <entry>
                  <para>0x00</para>
                </entry>
                <entry>
                  <para>4</para>
                </entry>
                <entry>
                  <para>Descriptor: This field is supplied for OS identification
                  use, it may be set to any value that may be useful (such as a
                  pattern that may be identified in a dump) or it may be left
                  uninitalized.</para>
                  <para>Historic values include: 0xD397D781</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x04</para>
                </entry>
                <entry>
                  <para>2 (unsigned)</para>
                </entry>
                <entry>
                  <para>Size: The size of the registered structure (640)</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x6 - 0x17</para>
                </entry>
                <entry>
                  <para>18</para>
                </entry>
                <entry>
                  <para>Reserved for Firmware Use</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x18 - 0x1B</para>
                </entry>
                <entry>
                  <para>4</para>
                </entry>
                <entry>
                  <para>Physical Processor FRU ID</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x1C - 0x1F</para>
                </entry>
                <entry>
                  <para>4</para>
                </entry>
                <entry>
                  <para>Physical Processor on FRU ID</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x20 - 0x57</para>
                </entry>
                <entry>
                  <para>56</para>
                </entry>
                <entry>
                  <para>Reserved for Firmware Use</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x58 - 0x5F</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Virtual processor home node associativity changes
                  counters (changes in the 8 most important associativity
                  levels)</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x60 - 0xAF</para>
                </entry>
                <entry>
                  <para>80</para>
                </entry>
                <entry>
                  <para>Reserved for Firmware Use</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0xB0</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Cede Latency Specifier</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0xB1</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Maintain EBB registers:</para>
                  <para>=0 architected state of the event based branch facility may be
                  discarded at any time,</para>
                  <para>=1 architected state of the event based branch facility must be
                  maintained, all other values are reserved</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0xB2</para>
                </entry>
                <entry>
                  <para>6</para>
                </entry>
                <entry>
                  <para>Reserved For LoPAR Expansion</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0xB8</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Dispatch Trace Log Enable Mask: (Note this entry is valid
                  only if a Dispatch Trace Log Buffer has been registered). A
                  Trace Log Entry is created when the virtual processor is
                  dispatched following its preemption for an enabled
                  cause.</para>
                  <para>=0 no dispatch trace logging</para>
                  <para>Bit 7 =1 Trace voluntary (OS initiated) virtual processor
                  waits</para>
                  <para>Bit 6 =1 Trace time slice preempts</para>
                  <para>Bit 5 = 1 Trace virtual partition memory page
                  faults.</para>
                  <para>All other values are reserved</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0xB9</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Bits 0-6 Reserved</para>
                  <para>Bit 7 = 0 -- Dedicated processor cycle donation
                  disabled</para>
                  <para>Bit 7 = 1 -- Dedicated processor cycle donation
                  enabled.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0xBA</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Maintain FPRs:</para>
                  <para>=0 architected state of floating point registers may be
                  discarded at any time,</para>
                  <para>=1 architected state of floating point registers must be
                  maintained,</para>
                  <para>all other values are reserved</para>
                  <para><emphasis role="bold">Note:</emphasis> When set in conjunction with offset 0xFF the 128
                  bit VSX space is saved on processors supporting the VSX option
                  (<xref linkend="dbdoclet.50569387_99718" /> 2.06 and
                  beyond).</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0xBB</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Maintain PMCs:</para>
                  <para>=0 architected state of performance monitor counters may
                  be discarded at any time,</para>
                  <para>=1 architected state of performance monitor counters must
                  be maintained,</para>
                  <para>all other values are reserved</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0xBC-0xD7</para>
                </entry>
                <entry>
                  <para>28</para>
                </entry>
                <entry>
                  <para>Reserved For Firmware Use</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0xD8-0xDF</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Any non-zero value is taken by the firmware to be the OS,
                  estimate, in PURR units, of the cumulative number of cycles
                  that it has consumed on this virtual processor, while idle,
                  since it was initialized.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0xE0 - 0xFB</para>
                </entry>
                <entry>
                  <para>28</para>
                </entry>
                <entry>
                  <para>Reserved for Firmware Use</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0xFC</para>
                </entry>
                <entry>
                  <para>2 (unsigned)</para>
                </entry>
                <entry>
                  <para>Maintain #SLBs:</para>
                  <para>This number of Segment Lookaside Buffer Registers (up to
                  the platform implementation maximum) are maintained, all others
                  (up to the platform implementing maximum) may be discarded at
                  any time.</para>
                  <para>The value 0xFFFF maintains all SLBs</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0xFE</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Idle:</para>
                  <para>=0 The OS is busy on this processor</para>
                  <para>=1 The OS is idle on this processor</para>
                  <para>All other values are reserved</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0xFF</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Maintain VMX state:</para>
                  <para>=0 architected state of the processor&#8217;s VMX
                  facility, may be discarded at any time</para>
                  <para>=1 architected state of the processor&#8217;s VMX
                  facility, must be maintained</para>
                  <para>All other values are reserved</para>
                  <para><emphasis role="bold">Note:</emphasis> When set in conjunction with offset 0xBA the 128
                  bit VSX space is saved on processors</para>
                  <para>supporting the VSX option (<xref linkend="dbdoclet.50569387_99718" />
                  2.06 and beyond).</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x100</para>
                </entry>
                <entry>
                  <para>4 (unsigned)</para>
                </entry>
                <entry>
                  <para>Virtual Processor Dispatch Counter:</para>
                  <para>(Even when virtual processor is dispatched odd when it is
                  preempted/ceded/conferred)</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x104</para>
                </entry>
                <entry>
                  <para>4 (unsigned)</para>
                </entry>
                <entry>
                  <para>Virtual Processor Dispatch Dispersion Accumulator:</para>
                  <para>Incremented on each virtual processor dispatch if the
                  physical processor differs from that of the last
                  dispatch.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x108</para>
                </entry>
                <entry>
                  <para>8 (unsigned)</para>
                </entry>
                <entry>
                  <para>Virtual Processor Virtual Partition Memory Fault Counter:
                  Incremented on each Virtual Partition Memory page fault.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x110</para>
                </entry>
                <entry>
                  <para>8 (unsigned)</para>
                </entry>
                <entry>
                  <para>Virtual Processor Virtual Partition Memory Fault Time
                  Accumulator: Time, in Time Base units, that the virtual
                  processor has been blocked waiting for the resolution of
                  virtual Partition Memory page faults.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x118 - 0x11F</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Unsigned accumulation of PURR cycles expropriated by the
                  hypervisor when VPA byte offset 0xFE = 1</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x120 - 0x127</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Unsigned accumulation of SPURR cycles expropriated by the
                  hypervisor when VPA byte offset 0xFE = 1</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x128 - 0x12F</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Unsigned accumulation of PURR cycles expropriated by the
                  hypervisor when VPA byte offset 0xFE = 0</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x130 - 0x137</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Unsigned accumulation of SPURR cycles expropriated by the
                  hypervisor when VPA byte offset 0xFE = 0</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x138 - 0x13F</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Unsigned accumulation of PURR cycles donated to the
                  processor pool when VPA byte offset 0xFE = 1</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x140 - 0x147</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Unsigned accumulation of SPURR cycles donated to the
                  processor pool when VPA byte offset 0xFE = 1</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x148 - 0x14F</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Unsigned accumulation of PURR cycles donated to the
                  processor pool when VPA byte offset 0xFE = 0</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x150 - 0x157</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Unsigned accumulation of SPURR cycles donated to the
                  processor pool when VPA byte offset 0xFE = 0</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x158-0x15F</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Accumulated virtual processor wait interval 3 timebase
                  cycles. (waiting for physical processor availability)</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x160 - 0x167</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Accumulated virtual processor wait interval 2 timebase
                  cycles. (waiting for virtual processor capacity)</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x168 - 0x16F</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Accumulated virtual processor wait interval 1 timebase
                  cycles. (waiting for virtual processor ready to run)</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x170 - 0x177</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Reserved for Firmware Use</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x178 - 0x17F</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Reserved for Firmware Use</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x180 - 0x183</para>
                </entry>
                <entry>
                  <para>4</para>
                </entry>
                <entry>
                  <para>For the CMO option: The OS may report in this field as a
                  hint to the hypervisor the accumulated number, since the
                  virtual processor was started, of &#8216;page in&#8217;
                  operations initiated for pages that were previously swapped
                  out.&#8221;</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x184 - 0x187</para>
                </entry>
                <entry>
                  <para>4</para>
                </entry>
                <entry>
                  <para>Reserved for Firmware Use</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x188 - 0x18F</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Reserved for Firmware Use</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x190 - 0x197</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Reserved for Firmware Use</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x198 - 0x217</para>
                </entry>
                <entry>
                  <para>128</para>
                </entry>
                <entry>
                  <para>Reserved for Firmware Use</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x218 - 0x21F</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Dispatch Trace Log buffer index counter.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x220 - 0x27F</para>
                </entry>
                <entry>
                  <para>96</para>
                </entry>
                <entry>
                  <para>Reserved for Firmware Use</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_85918"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SPLPAR option:</emphasis> If the OS registers a Per
                Virtual Processor Area, it must correspond to the format specified in
                <xref linkend="dbdoclet.50569344_46490" />.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

      </section>

      <section xml:id="dbdoclet.50569344_29153">
        <title>Dispatch Trace Log Buffer</title>
        <para>The optional virtual processor dispatch trace log buffer is a
        circularly managed buffer containing individual 48 byte entries, with the
        first entry starting at byte offset 0. Therefore, the 4 byte registration
        size field is overwritten by the first Trace Log Buffer entry. (Note the
        hypervisor rounds down the dispatch trace log buffer length to a multiple
        of 48 bytes and wraps when reaching that boundary.) A vpa location
        <xref linkend="dbdoclet.50569344_46490" /> contains the index counter that
        the hypervisor increments each time that it makes a dispatch trace log
        entry such that it always indicates the next entry to be filled. The low
        order bits (modulo the buffer length divided by 48) of the counter
        provide the index of the next entry to be filled, therefore, the buffer
        wraps each (buffer length divided by 48 entries), while the high order
        counter bits indicate how many buffer wraps have occurred. Prior to
        enabling dispatch trace logging, the OS should initialize the vpa index
        counter to the value of 0. The format of dispatch trace log buffer
        entries is given in
        <xref linkend="dbdoclet.50569344_45462" />.</para>
        <para>The architectural intent is that OS trace tools keep a shadow index
        counter into the log buffer of the next entry to be filled by the
        hypervisor. Prior to making an entry of their own, such tools compare
        their index counters with that of the hypervisor from the vpa, if they
        are equal, no preempts/dispatches have occurred since the last OS trace
        hook. If the two index counters are not equal, then the OS trace tool
        processes the intermediate time stamps into the OS&#8217;s trace log,
        updating its dispatch trace log buffer index until all have been
        processed, then the new trace entry is added to the OS&#8217;s trace log.
        Note, because of races, the processor may be preempted just prior to the
        OS trace tool adding the new trace log entry, to handle this case, the OS
        trace tool can examine the dispatch trace log buffer index immediately
        after the adding of the new trace log entry and if needed adjust its own
        trace log. In the extremely unlikely event that the two counters are off
        by trace buffer length divided by forty eight or more counts, the OS
        trace tool can detect that a dispatch trace log buffer overflow has
        occurred, and trace data has been lost.</para>

        <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_45462">
          <title>Dispatch Trace Log Buffer Entry</title>
          <tgroup cols="3">
            <colspec colname="c1" colwidth="15*" align="center" />
            <colspec colname="c2" colwidth="15*" align="center" />
            <colspec colname="c3" colwidth="70*" />
            <thead valign="middle">
              <row>
                <entry>
                  <para>
                    <emphasis role="bold">Byte Offset</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Length in Bytes</emphasis>
                  </para>
                </entry>
                <entry align="center">
                  <para>
                    <emphasis role="bold">Variable Description</emphasis>
                  </para>
                </entry>
              </row>
            </thead>
            <tbody valign="middle">
              <row>
                <entry>
                  <para>0x0</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Reason Code for the virtual processor dispatch:</para>
                  <para>0: The virtual processor was dispatched at the external
                  interrupt vector location to handle an IOA interrupt, Virtual
                  interrupt, or interprocessor interrupt.</para>
                  <para>1: The virtual processor was dispatched to handle
                  firmware internal events.</para>
                  <para>2: The virtual processor was dispatched at the next
                  sequential instruction due to an H_PROD call by another
                  partition processor.</para>
                  <para>3: The virtual processor was dispatched at the DECR
                  interrupt vector due to a decrementer interrupt.</para>
                  <para>4: The processor was dispatched at location specified in
                  load module (boot) or at the system reset interrupt vector.
                  (virtual yellow button).</para>
                  <para>5: The virtual processor was dispatched to handle
                  firmware internal events</para>
                  <para>6: The virtual processor was dispatched at the next
                  sequential instruction to use cycles conferred from another
                  partition processor</para>
                  <para>7: The virtual processor was dispatched at the next
                  sequential instruction for its entitled time slice.</para>
                  <para>8: The virtual processor was dispatched at the faulting
                  instruction following a virtual partition memory page
                  fault.</para>
                  <para>10: The virtual processor was dispatched at the privileged
                  doorbell interrupt vector location to handle a privileged
                  doorbell interrupt.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x1</para>
                </entry>
                <entry>
                  <para>1</para>
                </entry>
                <entry>
                  <para>Reason Code for virtual processor preemption:</para>
                  <para>0: Not used (for compatibility with earlier versions of
                  the facility)</para>
                  <para>1: Firmware internal event</para>
                  <para>2: Virtual processor called H_CEDE</para>
                  <para>3: Virtual processor called H_CONFER</para>
                  <para>4: Virtual processor reached the end of its timeslice
                  (HDEC)</para>
                  <para>5: Partition Migration/Hibernation page fault</para>
                  <para>6: Virtual memory page fault</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x2 - 0x3</para>
                </entry>
                <entry>
                  <para>2</para>
                </entry>
                <entry>
                  <para>Processor index of the physical processor actualizing the
                  thread on this dispatch.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x4 - 0x7</para>
                </entry>
                <entry>
                  <para>4</para>
                </entry>
                <entry>
                  <para>Time Base Delta between enqueued to dispatcher and actual
                  dispatch on a physical processor</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x8 - 0xB</para>
                </entry>
                <entry>
                  <para>4</para>
                </entry>
                <entry>
                  <para>Time Base Delta between ready to run and enqueue to
                  dispatcher</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0xC - 0xF</para>
                </entry>
                <entry>
                  <para>4</para>
                </entry>
                <entry>
                  <para>Time Base Delta between waiting and ready to run
                  (preempt/fault resolution time)</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x10 - 0x17</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>Time Base Value at the time of dispatch/wait</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x18 - 0x1F</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>For virtual processor preemption reason codes 5 &amp; 6:
                  Logical real address of faulting page; else reserved.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x20 - 0x27</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>SRR0: At the time of preempt/wait</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>0x28 - 0x2F</para>
                </entry>
                <entry>
                  <para>8</para>
                </entry>
                <entry>
                  <para>SRR1: At the time of preempt/wait</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_29153"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SPLPAR option:</emphasis> If the OS registers a Dispatch
                Trace Log Buffer, it must correspond to the format specified in
                <xref linkend="dbdoclet.50569344_45462" />.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

      </section>

      <section xml:id="dbdoclet.50569344_66820">
        <title>SLB Shadow Buffer</title>
        <para>On platforms supporting the SLB-Buffer function set, the OS may
        optionally register an SLB shadow buffer area. When the OS takes this
        option, it allows the hypervisor to optimize the saving of SLB entries,
        thus reducing overhead and providing more processor capacity for the OS,
        and also allows the platform to recover from certain SLB hardware faults.
        When the OS registers an SLB shadow buffer for its virtual processor, the
        processor&#8217;s SLB is architecturally divided into three categories
        relative to their durability as depicted in
        <xref linkend="dbdoclet.50569344_63017" />.</para>
        <figure xml:id="dbdoclet.50569344_63017">
          <title>Processor SLB relationship to the OS registered VPA and SLB Shadow Buffer</title>
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/PAPR-20.gif" format="GIF"
              scalefit="1" />
            </imageobject>
            <imageobject role="fo">
              <imagedata contentdepth="100%" fileref="figures/PAPR-20.gif"
              format="GIF" scalefit="1" width="100%" />
            </imageobject>
          </mediaobject>
        </figure>
        <para>OS may dynamically change M and N (for (N+1)*16 &lt;= Length of SLB Shadow Buffer)</para>
        <para>Each category of SLB entries consists of 0-n contiguous
        SLBs.</para>
        <para>Persistent Entries: The first N (starting at SLB index 0, N
        specified by the numeric content of the first 4 bytes of the registered
        SLB Shadow Buffer) SLBs are maintained persistent across all virtual
        processor dispatches unless an unrecovered SLB error is noted. OS
        maintains a shadow copy of those SLB entries in the registered SLB shadow
        buffer. The OS sizes its SLB Shadow buffer for the largest number of
        persistent entries it can ever maintain. If the OS registers an SLB
        Shadow buffer, the hypervisor does not save the contents of the
        Persistent entries on virtual processor preempt, cede, or confer. The OS
        should minimally record as persistent the entries it needs to handle its
        SLB fault interrupts to fill in required Volatile (and potentially)
        Transient entries.</para>
        <para>Volatile Entries: The next M-N SLBs (beginning at the next higher
        SLB index after the last Persistent entry up through the entry specified
        by the &#8220;maintain#SLBs&#8221; parameter of the VPA) may disappear.
        The OS needs to be prepared to recover these entries via SLB fault
        interrupts. For performance optimization, the hypervisor normally
        maintains the state of these entries across H_DECR interrupts and most
        hcalls(), they may be lost on H_CEDE calls.</para>
        <para>Transient Entries: The platform makes no attempt to maintain the
        state of these entries and they may be lost at any time.</para>
        <para>The OS may dynamically change the number of Persistent entries by
        atomically changing the value of the 4 byte parameter at SLB Shadow
        Buffer offset 0.</para>
        <para>The hypervisor does not explicitly check the value of this
        parameter, however, the hypervisor limits the number of SLBs that it
        attempts to load from the shadow buffer to the lesser of the maximum
        number of SLB entries implemented by the platform, or the maximum number
        of entries containable in the SLB Shadow buffer length when it was
        registered.</para>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_66820"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SPLPAR option:</emphasis> If the OS
                registers an SLB Shadow Buffer, it must correspond to the format
                specified in
                <xref linkend="dbdoclet.50569344_63017" />.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

      </section>
    </section>

    <section>
      <title>Shared Processor LPAR OF Extensions</title>
      <para />

      <section>
        <title>Shared Processor LPAR Function Sets in
        <emphasis role="bold"><literal>&#8220;ibm,hypertas-functions&#8221;</literal></emphasis></title>

        <orderedlist>
          <listitem>
            <para>hcall-splpar</para>
          </listitem>

          <listitem>
            <para>hcall-pic</para>
          </listitem>

          <listitem>
            <para>SLB-Buffer</para>
          </listitem>
        </orderedlist>
      </section>

      <section xml:id="sec_dev_tree_variances">
        <title>Device Tree Variances</title>
        <para>If an SPLPAR implementation does not maintain a fixed relationship
        between the virtual processor that it reports to the OS image in the OF
        device tree properties and the physical processor that it uses to
        actualize the virtual processor, then OF entities that imply a fixed
        physical relationship are not reported. These may include those listed in

        <xref linkend="dbdoclet.50569344_32620" />.</para>

        <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_32620">
          <title>OF Variances due to SPLPAR</title>
          <tgroup cols="2">
            <colspec colname="c1" colwidth="25*" align="center" />
            <colspec colname="c2" colwidth="75*" />
            <thead valign="middle">
              <row>
                <entry>
                  <para>
                    <emphasis role="bold">Entity</emphasis>
                  </para>
                </entry>
                <entry align="center">
                  <para>
                    <emphasis role="bold">Variance to standard
                    definition</emphasis>
                  </para>
                </entry>
              </row>
            </thead>
            <tbody valign="middle">
              <row>
                <entry>
                  <para>
                  <emphasis role="bold"><literal>&#8220;ibm,loc-code&#8221;</literal></emphasis> property</para>
                </entry>
                <entry>
                  <para>If the physical relationship between virtual processors
                  and physical processors is not constant this property is
                  omitted from the virtual processor&#8217;s node. If missing,
                  the OS should not run diagnostics on the virtual
                  processor</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>
                  <emphasis role="bold"><literal>&#8220;l2-cache&#8221;</literal></emphasis> property</para>
                </entry>
                <entry>
                  <para>If the physical relationship between virtual processors
                  and physical processors is not constant the secondary cache
                  characteristics are not relevant and this property is omitted
                  from the virtual processor&#8217;s node.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Nodes named
                  <emphasis role="bold"><literal>l2-cache</literal></emphasis></para>
                </entry>
                <entry>
                  <para>If the physical relationship between virtual processors
                  and physical processors is not constant the secondary cache
                  characteristics are not relevant and this node is omitted from
                  the partition&#8217;s device tree.</para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>
                  <emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis> property</para>
                </entry>
                <entry>
                  <para>If the physical relationship between virtual processors
                  and physical processors is not constant the
                  <emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis> property reflects
                  the same domain for all virtual processors actualized by a
                  given physical processor pool. Note, even though the
                  associativity of virtual processors may be indistinguishable,
                  the associativity among other platform resources may be
                  relevant.</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_dev_tree_variances"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SPLPAR option:</emphasis> If the platform does not
                maintain a fixed relationship between its virtual processors and the
                physical processors that actualize them, then the platform must vary the
                device tree elements as outlined in
                <xref linkend="dbdoclet.50569344_32620" />.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

      </section>
    </section>

    <section>
      <title>Shared Processor LPAR Hypervisor Extensions</title>
      <para />

      <section xml:id="dbdoclet.50569344_67189">
        <title>Virtual Processor Preempt/Dispatch</title>
        <para>A new virtual processor is dispatched on a physical processor when
        one of the following conditions happens:</para>

        <itemizedlist>
          <listitem>
            <para>The physical processor is idle and a virtual processor was made
            ready to run (interrupt or prod)</para>
          </listitem>

          <listitem>
            <para>If the subfunction is a Register VPA or a Deregister VPA or SLB
            shadow buffer, verify that the proc-no parameter references an
            offline virtual proc or that the proc-no parameter matches the
            current virtual processor making the hcall, else return H_STATE
            </para>
          </listitem>

          <listitem>
            <para>The old virtual processor exhausted its time slice (HDECR
            interrupt).</para>
          </listitem>

          <listitem>
            <para>The old virtual processor ceded/conferred its cycles.</para>
          </listitem>
        </itemizedlist>

        <para>When one of the above conditions occurs, the hypervisor, by
        default, records all the virtual processor architected state including
        the Time Base and Decrementer values and sets the hypervisor timer
        services to wake the virtual processor per the setting of the
        decrementer. The virtual processor&#8217;s Processor Utilization Register
        value for this dispatch is computed. The VPA&#8217;s dispatch count is
        incremented (such that the result is odd). Then the hypervisor selects a
        new virtual processor to dispatch on the physical processor using an
        implementation dependent algorithm having the following characteristics
        given in priority order:</para>

        <orderedlist>
          <listitem>
            <para>The virtual processor is &#8220;ready to run&#8221; (has not
            ceded/conferred its cycles or exhausted its time slice).</para>
          </listitem>

          <listitem>
            <para>Ready to run virtual processors are dispatched prior to waiting
            in excess of their maximum specified latency.</para>
          </listitem>

          <listitem>
            <para>Of the non-latency critical virtual processors ready to run,
            select the virtual processor that is most likely to have its working set
            in the physical processor&#8217;s cache or for other reasons runs most
            efficiently on the physical processor.</para>
          </listitem>
        </orderedlist>

        <para>If no virtual processor is &#8220;ready to run&#8221; at this time,
        start accumulating the Pool Idle Count (PIC) of the total number of idle
        processor cycles in the physical processor pool.</para>
        <para>Optionally, flags in the VPA may be set by the OS to indicate to
        the hypervisor that selected architected state of the virtual processor
        need not be maintained (that is, the contents of these architected
        facilities may be lost at any time without notice). The hypervisor may
        then optimize its preempt/dispatch routines accordingly. Refer to
        <xref linkend="dbdoclet.50569344_46490" /> and SLB Shadow Buffer
        description for the definition of these flags and values. The hypervisor
        modifies any such OS setable and readable processor state that is not
        explicitly saved and restored on a virtual processor dispatch so as to
        prevent a covert channel between partitions.</para>
        <para>When the virtual processor is dispatched, the virtual
        processor&#8217;s &#8220;prod&#8221; bit is reset, the saved architected
        state of the virtual processor is restored from that saved when the
        virtual processor was preempted, ceded, or conferred, except for the time
        base which retains the current value of the physical processor and the
        decrementer which is reduced from the state saved value per current Time
        Base value minus saved Time Base value. The hypervisor sets up for
        computing the PUR value increment for the dispatch.</para>
        <para>At this time, the hypervisor increments the virtual
        processor&#8217;s VPA dispatch count (such that the value is even). The
        hypervisor checks the VPA&#8217;s dispatch log flag, if set, the
        hypervisor creates a pair of log entries in the dispatch log and stores
        the circular buffer index in the first buffer entry.</para>
        <para>If the virtual processor was signaled with an interrupt condition
        and the physical interrupt has been reset, then the hypervisor adjusts
        the virtual processor architected state to reflects that of a physical
        processor taking the same interrupt prior to executing the next
        sequential instruction and execution starts with the first instruction in
        the appropriate interrupt vector. If no interrupt has been signaled to
        the virtual processor or the physical interrupt is still active, then
        execution starts at the next sequential instruction following the
        instruction as noted by the hypervisor when the virtual processor ceded,
        conferred, or was preempted.</para>
        <para>The Platform allocates processor capacity to a partition&#8217;s
        virtual processors using the architectural metaphor of a &#8220;dispatch
        wheel&#8221; with a fixed implementation dependent rotation period. Each
        virtual processor receives a time slice each rotation of the dispatch
        wheel. The length of the time slice is determined by a number of
        parameters, the OS image has direct control, within constraints, over
        three of these parameters (number of virtual processors, Entitled
        Processor Capacity Percentage, Variable Processor Capacity Weight). The
        constraints are determined by partition and partition aggregate
        configurations that are outside the scope of this architecture. For
        reference, partition definitions provide the initial settings of these
        parameters while the aggregation configurations provide the constraints
        (including the degenerate case where an aggregation encapsulates only a
        single member LPAR).</para>
        <para>Entitled Processor Capacity Percentage: The percentage of a
        physical processor that the hypervisor guarantees to be available to the
        partition&#8217;s virtual processors (distributed in a uniform manner
        among the partition&#8217;s virtual processors -- thus the number of
        virtual processors affects the time slice size) each dispatch cycle.
        Capacity ceded or conferred from one partition virtual processor extends
        the time slices offered to other partition processors. Capacity ceded or
        conferred after all of the partition&#8217;s virtual processors have been
        dispatch is added to the variable capacity kitty. The initial, minimum
        and maximum constraint values of this parameter are determined by the
        partition configuration definition. The H_SET_PPP hcall() allows the OS
        image to set this parameter within the constraints imposed by the
        partition configuration definition minimum and maximums plus constraints
        imposed by partition aggregation.</para>
        <para>Variable Processor Capacity Weight: The unitless factor that the
        hypervisor uses to assign processor capacity in addition to the Entitled
        Processor Capacity Percentage. This factor may take the values 0 to 255.
        A virtual processor&#8217;s time slice may be extended to allow it to use
        capacity unused by other partitions, or not needed to meet the Entitled
        Processor Capacity Percentage of the active partitions. A partition is
        offered a portion of this variable capacity kitty equal to: (Variable
        Processor Capacity Weight for the partition) / (summation of Variable
        Processor Capacity Weights for all competing partitions). The initial
        value of this parameter is determined by the partition configuration
        definition. The H_SET_PPP hcall() allows the OS image to set this
        parameter within the constraints imposed by the partition configuration
        definition maximum. Certain partition definitions may not allow any
        variable processor capacity allocation.</para>
        <para>Unallocated Processor Capacity Percentage: The amount of processor
        capacity that is currently available within the constraints of the LPAR's
        current environment for allocation to Entitled Processor Capacity
        Percentage. Race conditions may change the current environment before a
        request for this capacity can be performed, resulting in a constrained
        return from such a request.</para>
        <para>Unallocated Variable Processor Capacity Weight: The amount of
        variable processor capacity weight that is currently available within the
        constraints of the LPAR's current environment for allocation to the
        partition's variable processor capacity weight. Race conditions may
        change the current environment before a request for this capacity can be
        performed, resulting in a constrained return from such a request.</para>
        <para>System Parameters readable via the
        <emphasis>ibm,get-system-parameter</emphasis> RTAS call (see
        <xref linkend="LoPAR.RTAS" />)
         communicate a variety of configuration and
        constraint parameters among which are determined by the partition
        definition.</para>
        <para>By means that are beyond the scope of this architecture, various
        partitions may be organized into aggregations, for example &#8220;LPAR
        groups&#8221;, for the purposes of load balancing. These aggregations may
        impose constraints such as: &#8220;The summation of the minimum available
        capacity for all virtual processors supported by the LPAR group cannot
        exceed 100% of the group&#8217;s configured capacity&#8221;.</para>

        <variablelist>
         	<varlistentry xml:id="dbdoclet.50569344_75506">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_67189"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SPLPAR option:</emphasis>
                The platform must dispatch each partition virtual processors each dispatch cycle unless
                prevented by the semantics of the H_CONFER hcall().</para>
              </listitem>
         	</varlistentry>

         	<varlistentry xml:id="dbdoclet.50569344_80231">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_67189"
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SPLPAR option:</emphasis>
                The summation of the processing capacity that the platform dispatches to the virtual
                processors of each partition must be at least equal to that partition's
                Entitled Processor Capacity Percentage unless prevented by the semantics
                of the H_CONFER and H_CEDE hcall()s.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry xml:id="dbdoclet.50569344_24187">
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_67189"
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SPLPAR option:</emphasis>
                The processing capacity that the platform dispatches to each of the partition's virtual
                processors must be substantially equal unless prevented by the semantics
                of the H_CONFER and H_CEDE hcall()s.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_67189"
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SPLPAR option:</emphasis> The platform must distribute
                processor capacity allocated to SPLPAR virtual processor actualization
                not consumed due to Requirements
                <xref linkend="dbdoclet.50569344_75506" />,
                <xref linkend="dbdoclet.50569344_80231" />, and
                <xref linkend="dbdoclet.50569344_24187" /> to partitions in strict
                accordance with the definition of Variable Processor Capacity Weight
                unless prevented by the LPAR's definition (capped) or the semantics of
                the H_CONFER and H_CEDE hcall()s.</para>
                <para><emphasis role="bold">Note:</emphasis> A value of 0 for a Variable Processor Capacity Weight
                effectively caps the partition at its Entitled Processor Capacity
                Percentage value.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_67189"
            xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SPLPAR option on platforms:</emphasis> The platform must
                increment the counters in VPA offsets 0x158-0x16F per their definitions
                in
                <xref linkend="dbdoclet.50569344_46490" />.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_67189"
            xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the SPLPAR option on platforms :</emphasis> To maintain
                compatibility across partition migration and firmware version levels the
                OS must be prepared for platform implementations that do not increment
                VPA offsets 0x158 - 0x16F.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

      </section>

      <section xml:id="dbdoclet.50569344_98622">
        <title>H_REGISTER_VPA</title>
        <para>Register Virtual Processor Areas (these include the parameter area
        known as the VPA, the Dispatch Trace Log Buffer, and if the SLB-Buffer
        function set is supported, the SLB Shadow Buffer). Note if the caller
        makes multiple registration requests for a given per virtual processor
        area for a given virtual processor, the last registration wins, and if
        the same memory area is registered for multiple processors, the area
        contents are unpredictable, however, LPAR isolation is not
        compromised.</para>
        <para>The syntax of the H_REGISTER_VPA hcall() is given below.</para>

        <simplesect>
          <title>Syntax:</title>
          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Parameter, */
                       /* H_RESCINDED: A specified parameter refers to a rescinded */
                       /*   shared logical resource */
                       /* H_RESOURCE -- a required resource was not available */
                       /*   (probable cause is registering a trace buffer without a */
                       /*   VPA or deregistering a VPA with a registered trace */
                       /*   buffer) */
                       /* H_Hardware -- a hardware event prevented operation */
                       /* H_MLENGTH_PARM: For the CMO option, the requested area to */
                       /*   be registered crossed a memory entitlement granule */
                       /*   boundary */
                       /* H_STATE: The proc-no parameter referenced a virtual */
                       /*   processor that was in an invalid state for registering */
                       /*   or deregistering the VPA or SLB shadow buffer */
hcall ( const unit64 H_REGISTER_VPA, /* Register the specified per virtual */
                       /*   Processor Area */
        uint64 flags   /* The sub functions for this hcall() are encoded in bits */
                       /*   16-18 */
                       /*   000 = Reserved */
                       /*   001 = Register Virtual Processor Area */
                       /*   010 = Register Dispatch Trace Log Buffer*/
                       /*   011 = Register SLB Shadow Buffer (if SLB-Buffer */
                       /*         function set is supported) */
                       /*   100 = Reserved */
                       /*   101 = Deregister Virtual Processor Area */
                       /*   110 = Deregister Dispatch Trace Log Buffer */
                       /*   111 = Reserved */
                       /*   111 = Deregister SLB Shadow Buffer (if SLB-Buffer /*
                       /*         function set is supported) */
        uint64 proc-no, /* Virtual Processor Number */
        uint64 vpa );  /* Logical Address of the VPA being registered */]]></programlisting>
        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>wVerify that the flags parameter is a supported value else return
              H_Parameter. (That the subfunction field (Bits 16-23) is one of the
              values supported by this call. Optionally that all other bits are zero.
              Callers should not set any bits other than those specifically defined,
              however, implementations are not required to check the value of bits
              outside of the subfunction field.)</para>
            </listitem>

            <listitem>
              <para>Verify that the proc-no parameter references a virtual processor
              owned by the calling virtual processor&#8217;s partition else return
              H_Parameter</para>
            </listitem>

            <listitem>
              <para>If the sub function is a register, verify that the addr parameter
              is an L1 cache line aligned logical address within the memory owned by
              the calling virtual processor&#8217;s partition else return
              H_Parameter.</para>

              <itemizedlist>
                <listitem>
                  <para>If the Shared Logical Resource option is implemented and the addr
                  parameter represents a shared logical resource location that has been
                  rescinded by the owner, return H_RESCINDED.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Case on subfunction in flags parameter:</para>
            </listitem>

            <listitem>
              <para>Register VPA:</para>

              <itemizedlist>
                <listitem>
                  <para>Verify that the size field (2 bytes) at offset 0x4 is at least
                  640 bytes else return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>Verify that the entire structure (per the size field and vpa)
                  does not span a 4096 byte boundary else return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>Record the specified processor&#8217;s vpa logical address for
                  access by other SPLPAR hypervisor functions.</para>
                </listitem>

                <listitem>
                  <para>Initialize the contents of the area per
                  <xref linkend="dbdoclet.50569344_85918" />.</para>
                </listitem>

                <listitem>
                  <para>Return H_Succes</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Register Dispatch Trace Log Buffer:</para>

              <itemizedlist>
                <listitem>
                  <para>Verify that the size field (4 bytes) at offset 0x4 is at least 48
                  bytes else return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>For the CMO option, verify that the entire structure (per the
                  size field and vpa parameter) does not span a memory entitlement granule
                  boundary else return H_MLENGTH_PARM.</para>
                </listitem>

                <listitem>
                  <para>Verify that a VPA has been registered for the specified virtual
                  processor else return H_RESOURCE.</para>
                </listitem>

                <listitem>
                  <para>Initialize the specified processor&#8217;s preempt/dispatch trace
                  log buffer pointers and index.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Register SLB Shadow Buffer (if SLB-Buffer function set is
              supported):</para>

              <itemizedlist>
                <listitem>
                  <para>Verify that the size field (4 bytes) at offset 0x4 is at least 8
                  bytes and that the entire structure (per the size and vpa parameters)
                  does not span a 4096 byte boundary else return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>Verify that a VPA has been registered for the specified virtual
                  processor else return H_RESOURCE.</para>
                </listitem>

                <listitem>
                  <para>Initialize the specified processor&#8217;s SLB Shadow buffer
                  pointers and set the maximum persistent SLB restore index to the lesser
                  of the maximum number of processor SLBs or the maximum number of entries
                  in the registered SLB Shadow buffer.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Deregister VPA:</para>

              <itemizedlist>
                <listitem>
                  <para>Verify that a Dispatch Trace Log buffer is not registered for the
                  specified processor else return H_RESOURCE.</para>
                </listitem>

                <listitem>
                  <para>Verify that an SLB Shadow buffer is not registered for the
                  specified processor else return H_RESOURCE.</para>
                </listitem>

                <listitem>
                  <para>Clear any partition memory pointer to the specified
                  processor&#8217;s VPA (note no check is made that a valid VPA
                  registration exists).</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Deregister Dispatch Trace Log Buffer:</para>

              <itemizedlist>
                <listitem>
                  <para>Clear any partition memory and/ or hypervisor pointer to the
                  specified processor&#8217;s Dispatch Trace Buffer (note no check is made
                  that a valid Dispatch Trace Buffer registration exists).</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Deregister SLB Shadow Buffer (if SLB-Buffer function set is
              supported):</para>

              <itemizedlist>
                <listitem>
                  <para>Clear any hypervisor pointer(s) to the specified
                  processor&#8217;s SLB Shadow buffer (note no check is made that a valid
                  SLB Shadow buffer registration exists).</para>
                </listitem>

                <listitem>
                  <para>Zero the hypervisor&#8217;s maximum persistent SLB restore index
                  for the specified processor.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Else Return H_Function.</para>
            </listitem>
          </itemizedlist>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_98622"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the SPLPAR option:</emphasis> The platform must implement
                  the H_REGISTER_PVA hcall() following the syntax and semantics of
                  <xref linkend="dbdoclet.50569344_98622" />.</para>
                </listitem>
           	</varlistentry>

           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_98622"
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the SLPAR plus SLB Shadow Buffer options:</emphasis> The
                  platform must register, and deregister the optional SLB Shadow buffer per
                  the syntax and semantics of
                  <xref linkend="dbdoclet.50569344_98622" />.</para>
                </listitem>
           	</varlistentry>

           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_98622"
              xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the SLPAR plus SLB Shadow Buffer options:</emphasis> The
                  platform must make persistent the SLB entries recorded by the OS within
                  the SLB Shadow buffer as described in
                  <xref linkend="dbdoclet.50569344_66820" />.</para>
                </listitem>
           	</varlistentry>
          </variablelist>

        </simplesect>
      </section>

      <section xml:id="dbdoclet.50569344_80840">
        <title>H_CEDE</title>
        <para>The architectural intent of this hcall() is to have the virtual
        processor, which has no useful work to do, enter a wait state ceding its
        processor capacity to other virtual processors until some useful work
        appears, signaled either through an interrupt or a prod hcall(). To help
        the caller reduce race conditions, this call may be made with interrupts
        disabled but the semantics of the hcall() enable the virtual
        processor&#8217;s interrupts so that it may always receive wake up
        interrupt signals. As a hint to the hypervisor, the cede latency
        specifier
        <xref linkend="dbdoclet.50569344_46490" /> indicates how long the OS can
        tolerate the latency to an H_PROD hcall() or interrupt, this may affect
        how the hypervisor chooses to use or even power down the actualizing
        physical processor in the mean time.</para>
        <para>
        <emphasis role="bold">Software Note:</emphasis> The floating point registers may not
        be preserved by this call if the &#8220;Maintain FPRs&#8221; field of the
        VPA =0, see
        <xref linkend="dbdoclet.50569344_46490" />.</para>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code upon return when more */
                       /*   work is potentially available */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_CEDE /*Cede the calling virtual processor’s cycles to the */
                       /*   platform */
      );]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>Enable the virtual processor&#8217;s MSR<subscript>EE</subscript>
              bit as if it was on at the time of the call.</para>
            </listitem>

            <listitem>
              <para>Serialize for the virtual processor&#8217;s control structure
              with H_PROD.</para>
            </listitem>

            <listitem>
              <para>If the virtual processor&#8217;s &#8220;prod&#8221; bit is set,
              then:</para>

              <itemizedlist>
                <listitem>
                  <para>Reset the virtual processor&#8217;s &#8220;prod&#8221;
                  bit.</para>
                </listitem>

                <listitem>
                  <para>Release the virtual processor&#8217;s control structure.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Record all the virtual processor architected state including the
              Time Base and Decrementer values.</para>
            </listitem>

            <listitem>
              <para>Set hypervisor timer services to wake the virtual processor per
              the setting of the decrementer.</para>
            </listitem>

            <listitem>
              <para>Mark the virtual processor as non-dispatchable until the
              processor is the target of an interrupt (system reset, external including
              decrementer or IPI) or PROD.</para>
            </listitem>

            <listitem>
              <para>Cede the time remaining in the virtual processor&#8217;s time
              slice preferentially to the virtual processor&#8217;s partition.</para>
            </listitem>

            <listitem>
              <para>Release the virtual processor&#8217;s control structure.</para>
            </listitem>

            <listitem>
              <para>Dispatch some other virtual processor</para>
            </listitem>

            <listitem>
              <para>Return H_Success.</para>
            </listitem>
          </itemizedlist>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_80840"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the SPLPAR option:</emphasis> The platform must implement
                  the H_CEDE hcall() following the syntax and semantics of
                  <xref linkend="dbdoclet.50569344_80840" />.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
        </simplesect>
      </section>

      <section xml:id="dbdoclet.50569344_29793">
        <title>H_CONFER</title>
        <para>The architectural intent of this hcall() is to confer the callers
        processor capacity to the holder of a lock or the initiator of an event
        that the caller is waiting upon. If the caller knows the identity of the
        lock holder then the holder&#8217;s virtual processor number is supplied
        as a parameter, if the caller does not know the identity of the lock
        holder then the &#8220;all processors&#8221; value of the proc parameter
        is specified. If the caller is conferring to the initiator of an event
        the proc parameter value of the calling processor. This call may be made
        with interrupts enabled or disabled. This call provides a reduced
        &#8220;kill set&#8221; of volatile registers, GPRs r0 and r4-r13 are
        preserved.</para>
        <para>
        <emphasis role="bold">Software Note:</emphasis> The floating point registers may not
        be preserved by this call if the &#8220;Maintain FPRs&#8221; field of the
        VPA =0, see
        <xref linkend="dbdoclet.50569344_46490" />.</para>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code upon return when more */
                       /*   work is potentially available */
                       /* H_Parameter: The specified processor is not owned by the */
                       /*   partition */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint32 H_CONFER, /* Confer the calling virtual processor’s cycles to */
                       /*   the specified processor */
        int32 proc,    /* Target Processor number -- minus 1 is all partition */
                       /*   processors */
        uint32 dispatch ); /* The dispatch number (ignored if proc=caller) */]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>Validate the proc number else return H_Parameter. Valid
              Values:</para>

              <itemizedlist>
                <listitem>
                  <para>-1 (all partition processors)</para>
                </listitem>

                <listitem>
                  <para>0 through N one of the processor numbers of the calling processor's
                  partition</para>
                </listitem>

                <listitem>
                  <para>The calling processor's number forces a confer until the calling
                  processor is PRODed</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>If the proc number is for a single processor and the single
              processor is not the calling processor, then</para>

              <itemizedlist>
                <listitem>
                  <para>If the dispatch parameter is not equal to the specified
                  processor&#8217;s hypervisor copy of the dispatch number or the
                  hypervisor copy of the dispatch number is even, then return
                  H_Success.</para>
                </listitem>

                <listitem>
                  <para>If the target processor has conferred its cycles to all others,
                  then return H_Success.</para>
                </listitem>
              </itemizedlist>

              <para><emphasis role="bold">Firmware Implementation Note:</emphasis> If one were to confer
              to a processor that had conferred to all, then a dead lock could occur,
              however, there are valid cases with nested locks were this could happen,
              therefore, the hypervisor call silently ignores the confer.</para>
            </listitem>

            <listitem>
              <para>Record all the virtual processor architected state including the
              Time Base and Decrementer values.</para>
            </listitem>

            <listitem>
              <para>If the MSR<subscript>EE</subscript> bit is on,
              set hypervisor timer services to wake
              the virtual processor per the setting of the decrementer.</para>
            </listitem>

            <listitem>
              <para>Mark the virtual processor as non-dispatchable until one of the
              following:</para>

              <itemizedlist>
                <listitem>
                  <para>System reset interrupt.</para>
                </listitem>

                <listitem>
                  <para>The MSR<subscript>EE</subscript> bit is
                  on and the virtual processor is the target
                  of an external interrupt (including decrementer or IPI).</para>
                </listitem>

                <listitem>
                  <para>The virtual processor is the target of a PROD operation.</para>
                </listitem>

                <listitem>
                  <para>The specified target processor (or all partition processors if
                  the proc parameter value is a minus 1) have had the opportunity of a
                  dispatch cycle.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Confer the time remaining in the virtual processor&#8217;s time
              slice to the virtual processor&#8217;s partition.</para>
            </listitem>

            <listitem>
              <para>Dispatch the/a partition target virtual processor.</para>
            </listitem>

            <listitem>
              <para>Return H_Success.</para>
            </listitem>
          </itemizedlist>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_29793"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the SPLPAR option:</emphasis> The platform must implement
                  the H_CONFER hcall() following the syntax and semantics of
                  <xref linkend="dbdoclet.50569344_29793" />.</para>
                </listitem>
           	</varlistentry>

           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_29793"
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the SPLPAR option:</emphasis> The platform must implement
                  the H_CONFER hcall() such that the only GPR that is modified by the call
                  is r3.</para>
                </listitem>
           	</varlistentry>
          </variablelist>

        </simplesect>
      </section>

      <section xml:id="dbdoclet.50569344_67798">
        <title>H_PROD</title>
        <para>Awakens the specific processor. This call provides a reduced
        &#8220;kill set&#8221; of volatile registers, GPRs r0 and r4-r13 are
        preserved.</para>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code upon return when more */
                       /*   work is potentially available */
                       /* H_Parameter: The specified processor is not owned by the */
                       /*   partition */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_PROD, /* Mark the target processor runable */
        int64 proc );  /* Target Processor number */]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>Verify that the target virtual processor specified by the proc
              parameter is owned by the calling virtual processor&#8217;s
              partition.</para>
            </listitem>

            <listitem>
              <para>Serialize for the Target Virtual Processor&#8217;s control
              structure with H_CEDE.</para>
            </listitem>

            <listitem>
              <para>Set &#8220;prod&#8221; bit in the target virtual
              processor&#8217;s control structure.</para>
            </listitem>

            <listitem>
              <para>If the target virtual processor is not ready to run, mark the
              target virtual processor ready to run.</para>
            </listitem>

            <listitem>
              <para>Release the target virtual processor&#8217;s control
              structure.</para>
            </listitem>

            <listitem>
              <para>Return H_Success.</para>
            </listitem>
          </itemizedlist>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_67798"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the SPLPAR option:</emphasis> The platform must implement
                  the H_PROD hcall() following the syntax and semantics of
                  <xref linkend="dbdoclet.50569344_67798" />.</para>
                </listitem>
           	</varlistentry>

           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_67798"
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the SPLPAR option:</emphasis> The platform must implement
                  the H_PROD hcall() such that the only GPR that is modified by the call is
                  r3.</para>
                </listitem>
           	</varlistentry>
          </variablelist>

        </simplesect>
      </section>

      <section xml:id="dbdoclet.50569344_61487">
        <title>H_GET_PPP</title>
        <para>This hcall() returns the partition&#8217;s performance parameters.
        The parameters are packed into registers:</para>

        <itemizedlist>
          <listitem>
            <para>Register R4 contains the Entitled Processor Capacity Percentage
            for the partition. In the case of a dedicated processor partition this
            value is 100* the number of processors owned by the partition.</para>
          </listitem>

          <listitem>
            <para>Register R5 contains the Unallocated Processor Capacity
            Percentage for the calling partition&#8217;s aggregation.</para>
          </listitem>

          <listitem>
            <para>Register R6 contains the aggregation numbers of up to 4 levels of
            aggregations that the partition may be a member.</para>

            <itemizedlist>
              <listitem>
                <para>Bytes 0-1: Reserved for future aggregation definition, and set to
                zero -- in the future this field may be given meaning.</para>
              </listitem>

              <listitem>
                <para>Bytes 2-3: Reserved for future aggregation definition, and set to
                zero -- in the future this field may be given meaning.</para>
              </listitem>

              <listitem>
                <para>Bytes 4-5: 16 bit binary representation of the &#8220;Group
                Number&#8221;.</para>
              </listitem>

              <listitem>
                <para>Bytes 6-7: 16 bit binary representation of the &#8220;Pool
                Number&#8221;. In the case of a dedicated processor partition the
                &#8220;Pool Number&#8221; is not applicable which is represented by the
                code 0xFFFF.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>Register R7 contains the platform resource capacities:</para>

            <itemizedlist>
              <listitem>
                <para>Bytes 0 Reserved for future platform resource capacity
                definition, set to zero -- in the future this field may be given
                meaning.</para>
              </listitem>

              <listitem>
                <para>Byte 1 is a bit field representing the capping mode of the
                partition&#8217;s virtual processor(s):</para>

                <itemizedlist>
                  <listitem>
                    <para>Bits 0-6 are reserved, and set to zero -- in the future these
                    bits may be given meaning as new capping modes are defined</para>
                  </listitem>

                  <listitem>
                    <para>Bit 7 -- The partition&#8217;s virtual processor(s) are capped at
                    their Entitled Processor Capacity Percentage. In the case of dedicated
                    processors this bit is set.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Byte 2: Variable Processor Capacity Weight. In the case of a
                dedicated processor partition this value is 0x00.</para>
              </listitem>

              <listitem>
                <para>Byte 3: Unallocated Variable Processor Capacity Weight for the
                calling partition&#8217;s aggregation.</para>
              </listitem>

              <listitem>
                <para>Bytes 4-5 16 bit unsigned binary representation of the number of
                processors active in the caller&#8217;s Processor Pool. In the case of a
                dedicated processor partition this value is 0x00.</para>
              </listitem>

              <listitem>
                <para>Bytes 6-7 16 bit binary representation of the number of
                processors active on the platform.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>When the value of the
            <emphasis role="bold"><literal>&#8220;ibm,partition-performance-parameters-level&#8221;</literal></emphasis> see
            <xref linkend="LoPAR.DeviceTree" />) is &gt;=1 then register R8 contains
            the processor virtualization resource allocations. In the case of a
            dedicated processor partition R8 contains 0:</para>

            <itemizedlist>
              <listitem>
                <para>Bytes 0-1: 16 bit unsigned binary representation of the number of
                physical platform processors allocated to processor
                virtualization.</para>
              </listitem>

              <listitem>
                <para>Bytes 2-4: 24 bit unsigned binary representation of the maximum
                processor capacity percentage that is available to the partition's
                pool.</para>
              </listitem>

              <listitem>
                <para>Bytes 5-7: 24 bit unsigned binary representation of the entitled
                processor capacity percentage available to the partition's pool.</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>


        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_GET_PPP /* Returns in R4 - R7 the Platform Performance */
                       /*   Parameters. */
      );]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
                  <para>Place the partition&#8217;s performance parameters for the
                  calling virtual processor&#8217;s partition into the respective
                  registers:</para>

              <itemizedlist>
                <listitem>
                      <para>R4: The calling partition&#8217;s Entitled Processor Capacity
                      Percentage</para>
                </listitem>

                <listitem>
                      <para>R5: The calling partition&#8217;s aggregation&#8217;s Unallocated
                      Processor Capacity Percentage.</para>
                </listitem>

                <listitem>
                      <para>R6: The aggregation numbers</para>
                </listitem>

                <listitem>
                      <para>R7: The platform resource capacities</para>
                </listitem>

                <listitem>
                      <para>R8: When
                      <emphasis role="bold"><literal>&#8220;ibm,partition-performance-parameters-level&#8221;</literal></emphasis> is
                      &gt;= 1 in the device tree, R8 is loaded with the processor
                      virtualization resource allocations</para>
                </listitem>

                <listitem>
                      <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_61487"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the SPLPAR option:</emphasis> The platform must implement
                  the H_GET_PPP hcall() following the syntax and semantics of
                  <xref linkend="dbdoclet.50569344_61487" />.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
        </simplesect>
      </section>

      <section xml:id="dbdoclet.50569344_14689">
        <title>H_SET_PPP</title>
        <para>This hcall() allows the partition to modify its entitled processor
        capacity percentage and variable processor capacity weight within limits.
        If one or both request parameters exceed the constraints of the calling
        LPAR&#8217;s environment, the hypervisor limits the set value to the
        constrained value and returns H_Constrained. The H_GET_PPP call may be
        used to determine the actual current operational values. By the
        hypervisor constraining the actual values, the calling partition does not
        need special authority to make the H_SET_PPP hcall().</para>
        <para>See
        <xref linkend="dbdoclet.50569344_67189" /> for definitions of these
        values.</para>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Parameter: One or both the input parameters were */
                       /*   invalid */
                       /* H_Constrained: One or both of the input parameters */
                       /*   exceeded the partition’s constraints */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_SET_PPP, /* Modifies the specified partition’s performance */
                       /*   parameters */
        uint64 entitled, /* Entitled Processor Capacity Percentage */
        uint8 variable /* Variable Processor Capacity Weight */
      );]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>Verify that the variable processor capacity weight is between 0
              and 255 else return H_Parameter.</para>
            </listitem>

            <listitem>
              <para>Verify that the capacities specified is within the constraints of
              the partition:</para>

              <itemizedlist>
                <listitem>
                  <para>If yes, atomically set the partition&#8217;s entitled and
                  variable capacity per the request and return H_Success.</para>
                </listitem>

                <listitem>
                  <para>If not set the partition&#8217;s entitled and variable capacity
                  as constrained by the partition&#8217;s configuration and return
                  H_Constrained.</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>

          <para><emphasis role="bold">Firmware Implementation Note:</emphasis> If the dispatch algorithm requires
          that the summation of variable capacities be updated, it is atomically
          updated with the set of the partition&#8217;s weight.</para>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_14689"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the SPLPAR option:</emphasis> The platform must implement
                  and make available to selected partitions, the H_SET_PPP hcall()
                  following the syntax and semantics of
                  <xref linkend="dbdoclet.50569344_14689" />.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
        </simplesect>
      </section>

      <section xml:id="dbdoclet.50569344_23727">
        <title>H_PURR</title>
        <para>The Processor Utilization of Resources Register (PURR) is
        compatibly read through the H_PURR hcall(). In those implementations
        running on processors that do not implement the register in hardware,
        firmware simulates the function. On platforms that present the property
        <emphasis role="bold"><literal>&#8220;ibm,rks-hcalls&#8221;</literal></emphasis> with bit 2 set (see
        <xref linkend="LoPAR.DeviceTree" />), this call provides a reduced
        &#8220;kill set&#8221; of volatile registers, GPRs r0 and r5-r13 are
        preserved.</para>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_PURR /* Returns in R4 the value of the Processor Utilization */
                       /*   Register */
      );]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>If the platform presents the
              <emphasis role="bold"><literal>&#8220;ibm,rks-hcall&#8221;</literal></emphasis> property with bit 2 set;
              then honor a kill set of volatile registers r3 &amp; r4.</para>
            </listitem>

            <listitem>
              <para>Compute the PURR value for the calling virtual processor up to
              the current point in time and place in R4</para>
            </listitem>

            <listitem>
              <para>Return H_Success.</para>
            </listitem>
          </itemizedlist>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_23727"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the SPLPAR option:</emphasis> The platform must implement
                  the H_PURR hcall() following the syntax and semantics of
                  <xref linkend="dbdoclet.50569344_98220" />.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
        </simplesect>
      </section>

      <section xml:id="dbdoclet.50569344_98220">
        <title>H_POLL_PENDING</title>
        <para>Certain implementations of the hypervisor steal processor cycles to
        perform administrative functions in the background. The purpose of the
        H_POLL_PENDING hcall() is to provide a OS, running atop such an
        implementation, with a hint of pending work so that it may more
        intelligently manage use of platform resources. The use of this call by
        an OS is totally optional since such an implementation also uses hardware
        mechanisms to ensure that the required cycles can be transparently
        stolen. It is assumed that the caller of H_POLL_PENDING is idle, if all
        threads of the processor are idle (as indicated by the idle flag at byte
        offset 0xFE of
        <xref linkend="dbdoclet.50569344_46490" />), the hypervisor may choose to
        perform a background administrative task. The hypervisor returns
        H_PENDING if there is pending administrative work, at the time of the
        call, that it could dispatch to the calling processor if the calling
        processor were ceded, if there is no such pending work, the return code
        is H_Success. Due to race conditions, this pending work may have grown or
        disappeared by the time the calling OS makes a subsequent H_CEDE
        call.</para>
        <para>There is NO architectural guarantee that ceding a processor exempts
        a virtual processor from preemption for a given period of time. That may
        indeed be the characteristic of a given implementation, but cannot be
        expected from all future implementations.</para>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: No pending platform work at this time */
                       /* H_PENDING There exists pending platform work */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_POLL_PENDING /* Poll for the presence of pending platform */
                       /*   work */
      );]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>Return H_PENDING if there is work pending that could be
              dispatched to the calling processor if it were ceded, else return
              H_Success.</para>
            </listitem>
          </itemizedlist>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_98220"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the SPLPAR option:</emphasis> The platform must implement
                  the H_POLL_PENDING hcall() following the syntax and semantics of
                  <xref linkend="dbdoclet.50569344_98220" />.</para>
                </listitem>
           	</varlistentry>
          </variablelist>

        </simplesect>
      </section>

    </section>

    <section>
      <title>Pool Idle Count Function Set</title>
      <para>The hcall-pic function set may be configured via the partition
      definition in none or any number of partitions as the weights
      administrative policy dictates.</para>

      <section xml:id="dbdoclet.50569344_39055">
        <title>H_PIC</title>
        <para />

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[
int64                  /* H_Success: Expected Return code */
                       /* H_Function: The function is not allowed from the calling */
                       /*   partition */
                       /* H_Authority: The calling partition is not authorized to */
                       /*   make the call at this time */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_PIC ); /*Returns in R4 the value of the Pool Idle Count */]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>Verify that calling partition has the authority to make the call
              else return H_Authority.</para>
            </listitem>

            <listitem>
              <para>Compute the PIC value for the processor pool implementing the
              calling virtual processor up to the current point in time and place into
              R4</para>
            </listitem>

            <listitem>
              <para>Place the number of processors in the caller&#8217;s processor
              pool in R5.</para>
            </listitem>

            <listitem>
              <para>When the value of the
              <emphasis role="bold"><literal>&#8220;ibm,partition-performance-parameters-level&#8221;</literal></emphasis> (see
              <xref linkend="LoPAR.DeviceTree" />) is &gt;=1 then:</para>

              <itemizedlist>
                <listitem>
                  <para>Place the summation of time base ticks for all platform
                  processors, allocated to the caller's processor pool, into register
                  R6.</para>
                </listitem>

                <listitem>
                  <para>Place the summation of all PURR ticks accumulated by all
                  dispatched (not idle) platform processor threads, allocated to the
                  caller's processor pool, into register R7.</para>
                </listitem>

                <listitem>
                  <para>Place the summation of all SPURR<footnote xml:id="pgfId-1197716">
                    <para>Machines that do not have a SPURR mechanism are assumed to run at
                    a constant speed, at which time the PURR value is substituted.</para>
                  </footnote> ticks accumulated by all dispatched (not idle) platform
                  processor threads, allocated to the caller's processor pool, into
                  register R8.</para>
                </listitem>

                <listitem>
                  <para>Place the caller's processor pool ID into low order two bytes of
                  register R9 (high order 6 bytes are reserved - set to 0x000000).</para>
                </listitem>

                <listitem>
                  <para>If the calling partition has the authority to monitor total
                  processor virtualization then:</para>

                  <itemizedlist>
                    <listitem>
                     <para>Place the summation of time base ticks for all platform physical
                      processors, allocated to processor virtualization, in register
                      R10.</para>
                    </listitem>

                    <listitem>
                      <para>Place the summation of all PURR ticks accumulated by all
                      dispatched (not idle) platform physical processor threads, allocated to
                      processor virtualization, in register R11.</para>
                    </listitem>

                    <listitem>
                      <para>Place the summation of all SPURR<emphasis><footnoteref linkend="pgfId-1197716" />
                      </emphasis> ticks accumulated by all dispatched (not idle) platform
                      physical processor threads, allocated to processor virtualization, in
                      register R12.</para>
                    </listitem>

                    <listitem>
                      <para>Else load R10, R11 and R12 with -1.</para>
                    </listitem>
                  </itemizedlist>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Return H_Success.</para>
            </listitem>
          </itemizedlist>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_39055"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the SPLPAR option:</emphasis> The platform must implement
                  and make available to selected partitions, the H_PIC hcall() following
                  the syntax and semantics of
                  <xref linkend="dbdoclet.50569344_39055" />.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
        </simplesect>
      </section>
    </section>


    <section xml:id="dbdoclet.50569344_90755">
      <title>Thread Join Option</title>
      <para />

      <section xml:id="dbdoclet.50569344_15933">
        <title>H_JOIN</title>
        <para>The H_JOIN hcall() performs the equivalent of a H_CONFER
        (proc=self) hcall() (see
        <xref linkend="dbdoclet.50569344_29793" />) unless called by the sole
        unjoined (active) processor thread, at which time the H_JOIN hcall()
        returns H_CONTINUE. H_JOIN is intended to establish a single threaded
        operating environment within a partition; to prevent external interrupts
        from complicating this environment, H_JOIN returns &#8220;bad_mode&#8221;
        if called with the processor MSR[EE] bit set to 1. Joined (inactive)
        threads are activated by H_PROD (see
        <xref linkend="dbdoclet.50569344_67798" />) which starts execution at the
        instruction following the hcall; or a system reset non-maskable interrupt
        which appears to interrupt between the hcall and the instruction
        following the hcall.</para>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Return value to all processor threads in the */
                       /*   calling partition except the final active processor */
                       /*   thread in the calling partition. */
                       /* bad_mode: MSR.EE=1 in addition to other illegal MSR bit */
                       /*   values. */
                       /* H_CONTINUE: Return value to final active processor thread */
                       /*   in the calling partition. */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function. */
hcall ( const uint64 H_JOIN /* Join active threads and return H_CONTINUE to final */
                       /*   calling thread. */
      );]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Semantics</title>

          <itemizedlist>
            <listitem>
              <para>If MSR.EE=1 return bad_mode.</para>
            </listitem>

            <listitem>
              <para>If other processor threads are active in the calling partition,
              then emulate H_CONFER (proc=self)</para>
            </listitem>

            <listitem>
              <para>Else return H_CONTINUE.</para>
            </listitem>
          </itemizedlist>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_15933"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the Thread Join option:</emphasis> The platform must
                  implement the H_JOIN hcall() following the syntax and semantics of
                  <xref linkend="dbdoclet.50569344_15933" />.</para>
                </listitem>
           	</varlistentry>

           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_15933"
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the Thread Join option:</emphasis> The platform must
                  implement the hcall-join and hcall-splpar function sets.</para>
                </listitem>
           	</varlistentry>

           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_15933"
              xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the Thread Join option:</emphasis> The platform must support
                  the H_PROD hcall even if the partition is operating in dedicated
                  processor mode.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
        </simplesect>
      </section>
    </section>

    <section xml:id="dbdoclet.50569344_56450">
      <title>Virtual Processor Home Node Option (VPHN)</title>
      <para>The SPLPAR option allows the platform to dispatch virtual
      processors on physical processors that due to the variable nature of work
      loads are temporarily free, thus improving the utilization of computing
      resources. However, SPLPAR implies inconsistent mapping of virtual to
      physical processors; defeating resource allocation software that attempts
      to optimize performance on platforms that implement the NUMA
      option.</para>
      <para>To bridge the gap between these two options, the VPHN option
      maintain a substantially consistent mapping of a given virtual processor
      to a physical processor or set of processors within a given associativity
      domain. Thus the OS can, when allocating computing resources, take
      advantage of this statistically consistent mapping to improve processing
      performance.</para>
      <para>VPHN mappings are substantially consistent but not static. For any
      given dispatch cycle, a best effort is made to dispatch the virtual
      processor on a physical processor within a targeted associativity domain
      (the virtual processor's home node). However, if processing capacity
      within the home node is not available, some other physical processor is
      assigned to meet the processing capacity entitlement. From time to time,
      to optimize the total platform performance, it may be necessary for the
      platform to change the home node of a given virtual processor.</para>
      <para>To enable the OS to determine the associativity domain of the home
      node of a virtual processor, platforms implementing the VPHN option
      provide the H_HOME_NODE_ASSOCIATIVITY hcall(). The presence of the
      hcall-vphn function set in the
      <emphasis role="bold"><literal>&#8220;ibm,hypertas-functions&#8221;</literal></emphasis> property
      indicates that the platform supports the VPHN option. The OS should be
      prepared for the support of the VPHN option to change with functions such
      partition migration, after which a call to H_HOME_NODE_ASSOCIATIVITY may
      end with a return code of H_FUNCTION. Additionally, the VPHN option
      defines a VPA field that the OS can poll to determine if the
      associativity domain of the home node has changed. When the home node
      associativity domain changes, the OS might choose to call the
      H_HOME_NODE_ASSOCIATIVITY hcall() and adjust its resource allocations
      accordingly.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_56450"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Virtual Processor Home Node option:</emphasis> The
              platform must support the H_HOME_NODE_ASSOCIATIVITY hcall() per the
              syntax and semantics specified in section
              <xref linkend="dbdoclet.50569344_30997" />.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_56450"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Virtual Processor Home Node option:</emphasis> For the
              OS to operate properly across such functions as partition migration, the
              OS must be prepared for the target platform to not support the Virtual
              Processor Home Node option.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_56450"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Virtual Processor Home Node option:</emphasis> The
              platform must support the &#8220;virtual processor home node
              associativity changes counters&#8221; field in the VPA per section
              <xref linkend="dbdoclet.50569344_26412" />.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_56450"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Virtual Processor Home Node option:</emphasis> The
              platform must support the &#8220;Form 1&#8221; of the
              <emphasis role="bold"><literal>&#8220;ibm,associativity-reference-points&#8221;</literal></emphasis> property per
              <xref linkend="LoPAR.Platform" />. The client program may call
              H_HOME_NODE_ASSOCIATIVITY hcall() with a valid identifier input parameter
              (such as from the device tree or from the
              <emphasis>ibm,configure-connector</emphasis> RTAS call) even if the
              corresponding virtual processor has not been started so that the client
              program can allocate resources optimally with respect to the to be
              started virtual processor.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

      <section xml:id="dbdoclet.50569344_30997">
        <title>H_HOME_NODE_ASSOCIATIVITY</title>
        <para>The H_HOME_NODE_ASSOCIATIVITY hcall() returns the associativity
        domain designation associated with the identifier input parameter. The
        client program may call H_HOME_NODE_ASSOCIATIVITY hcall() with a valid
        identifier input parameter (such as from the device tree or from the

        <emphasis>ibm,configure-connector</emphasis> RTAS call) even if the
        corresponding virtual processor has not been started so that the client
        program can allocate resources optimally with respect to the to be
        started virtual processor.</para>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Function: The function is not supported (support may */
                       /*   change following partition migration) */
                       /* H_Parameter: Unsupported flag parameter value */
                       /* H_P2: Invalid id parameter */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_HOME_NODE_ASSOCIATIVITY), /* Returns in R4-R9 the home node */
                       /*  associativity domain IDs */
        uint64 flags,  /* Type of id parameter */
                       /*   0x00 not used */
                       /*   0x01 proc-no as used in the H_REGISTER_VPA hcall */
                       /*   0x02 processor index as from byte offsets 0x2-0x3 of a */
                       /*        trace log entry */
        uint64 id );   /* processor id in the form specified by the flags parameter */]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Parameters:</title>

          <itemizedlist>
            <listitem>
              <para>Input:</para>

              <itemizedlist>
                <listitem>
                  <para>flags:</para>

                  <itemizedlist>
                    <listitem>
                      <para><emphasis role="bold">Note:</emphasis> this parameter does not share format with the flags
                      parameter of the Page Frame Table Access hcall()s.</para>
                    </listitem>

                    <listitem>
                      <para>Defined Values:</para>

                      <itemizedlist>
                        <listitem>
                          <para>0x0 Invalid</para>
                        </listitem>

                        <listitem>
                          <para>0x1 id parameter is as proc-no parameter of H_REGISTER_VPA
                          hcall()</para>
                        </listitem>

                        <listitem>
                          <para>0x2 id parameter is as processor index from byte offsets 0x2-0x3
                          of a trace log buffer entry</para>
                        </listitem>

                        <listitem>
                          <para>all other values reserved.</para>
                        </listitem>
                      </itemizedlist>
                    </listitem>
                  </itemizedlist>
                </listitem>

                <listitem>
                  <para>id: processor identifier per the form indicated by the flags
                  parameter.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Output:</para>

              <itemizedlist>
                <listitem>
                  <para>R3: return code</para>
                </listitem>

                <listitem>
                  <para>R4-R9: associativity domain identifier list of the specified
                  processor&#8217;s home node.</para>

                  <itemizedlist>
                    <listitem>
                      <para>Only the &#8220;primary&#8221; connection (as would be reported
                      in the first string of the
                      <emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis> property) is
                      reported.</para>
                    </listitem>

                    <listitem>
                      <para>The associativity domain numbers are reported in the sequence
                      they would appear in the
                      <emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis> property; starting
                      from the high order bytes of R4 proceeding toward the low order bytes of
                      R9.</para>
                    </listitem>

                    <listitem>
                      <para>Each of the registers R4-R9 is divided into 4 fields each 2 bytes
                      long.</para>
                    </listitem>

                    <listitem>
                      <para>The high order bit of each 2 byte field is a length
                      specifier:</para>

                      <itemizedlist>
                        <listitem>
                          <para>1: The associativity domain number is contained in the low order
                          15 bits of the field,</para>
                        </listitem>

                        <listitem>
                          <para>0: The associativity domain number is contained in the low order
                          15 bits of the current field concatenated with the 16 bits of the next
                          sequential field)</para>
                        </listitem>
                      </itemizedlist>
                    </listitem>

                    <listitem>
                      <para>All low order fields not required to specify the associativity
                      domain identifier list contain the reserved value of all ones.</para>
                    </listitem>
                  </itemizedlist>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>Verify that the &#8220;flags&#8221; parameter is valid else
              return H_Parameter.</para>
            </listitem>

            <listitem>
              <para>Verify that the &#8220;id&#8221; parameter is valid for the
              &#8220;flags&#8221; and the partition else return H_P2.</para>
            </listitem>

            <listitem>
              <para>Pack the associativity domain identifiers for the home node
              associated with the &#8220;id&#8221; parameter starting with the highest
              level reported in the
              <emphasis role="bold"><literal>&#8220;ibm,associativity&#8221;</literal></emphasis> property in the high
              order field of R4.</para>
            </listitem>

            <listitem>
              <para>All remaining fields through the low order field of R9 are filled
              with 0xFFFFFFFF.</para>
            </listitem>

            <listitem>
              <para>Return H_Success.</para>
            </listitem>
          </itemizedlist>

        </simplesect>
      </section>

      <section xml:id="dbdoclet.50569344_26412">
        <title>VPA Home Node Associativity Changes Counters</title>
        <para>For the VPHN option, the platform maintains within each VPA the
        Virtual Processor Home Node Associativity Change Counters field. See
        Table
        <xref linkend="dbdoclet.50569344_46490" />. This eight (8) byte field is
        maintained as 8 one byte long counters. The number of counters that are
        supported is implementation dependent up to 8, and corresponds to the
        entries in the form 1 of the
        <emphasis role="bold"><literal>&#8220;ibm,associativity-reference-points&#8221;</literal></emphasis> property. If
        the platform implements fewer than 8 associativity reference points, only
        the corresponding low offset counters within the field are used and the
        remaining high offset counters within the field are unused.</para>
        <para>Should the associativity of the home node of the virtual processor
        change, for each changed associativity level that corresponds to a level
        reported in the
        <emphasis role="bold"><literal>&#8220;ibm,associativity-reference-points&#8221;</literal></emphasis> property, the
        corresponding counter in the Virtual Processor Home Node Associativity
        Change Counters field is incremented.</para>
      </section>

    </section>
  </section>

  <section>
    <title>Virtualizing Partition Memory</title>
    <para>This section describes the various high level functions that are
    enabled by the virtualization of the logical real memory of a partition. In
    principle, virtualization of partition memory can be totally transparent to
    the partition software; however, partition software that is migration aware
    can cooperate with the platform to achieve higher performance, and enhanced
    functionality.</para>

    <section xml:id="sec_partition_migration_hibernation">
      <title>Partition Migration/Hibernation</title>
      <para>Virtualizing partition memory allows a partition to be moved via
      migration or hibernation. In the case of partition migration from one
      platform to another, the source and destination platforms cooperate to
      minimize the time that the partition is non-responsive; the goal is to be
      non-responsive no more than a few seconds. In the case of hibernation,
      the intent is to put the partition to sleep for an extended period;
      during this time the partition state is stored on secondary storage for
      later restoration.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_partition_migration_hibernation"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Migration and Partition Hibernation
              options:</emphasis> The platform must implement the Partition Suspension
              option (See
              <xref linkend="LoPAR.RTAS" />).</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_partition_migration_hibernation"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis> For the Partition Migration and Partition
              Hibernation options: </emphasis> The platform must implement the VASI
              option (See <xref linkend="sec_vasi"/>).
              </para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_partition_migration_hibernation"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Migration and Partition Hibernation
              options:</emphasis> The platform must implement the Update OF Tree
              option.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_partition_migration_hibernation"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Migration and Partition Hibernation
              options:</emphasis> The platform must implement the Version 6 Extensions
              of Event Log Format for all reported events (See
              <xref linkend="LoPAR.Error" />).</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_partition_migration_hibernation"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Migration and Partition Hibernation
              options:</emphasis> The platform must prevent the migration/hibernation of
              partitions that own dedicated platform resources in addition to
              processors and memory, this includes physical I/O resources, the BSR
              facility, physical indicators and sensors (virtualized I/O, indicators
              (such as tone) and sensors (such as EPOW) are allowed).</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_partition_migration_hibernation"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Migration and Partition Hibernation
              options:</emphasis> The platform must implement the Client Vterm
              option.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_partition_migration_hibernation"
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Migration and Partition Hibernation
              options:</emphasis> The platform
              <emphasis role="bold"><literal>&#8220;timebase-frequency&#8221;</literal></emphasis> must be 512 MHz. +/-
              50 parts per million.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_partition_migration_hibernation"
          xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Migration and Partition Hibernation
              options:</emphasis> The platform must present the
              <emphasis role="bold"><literal>&#8220;ibm,nominal-tbf&#8221;</literal></emphasis> property (See
              <xref linkend="LoPAR.DeviceTree" />) with the value of 512 MHz.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_partition_migration_hibernation"
          xrefstyle="select: labelnumber nopage"/>-9.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The platform
              must present the properties from
              <xref linkend="LoPAR.DeviceTree" />, as specified by
              <xref linkend="dbdoclet.50569344_83870" />, to a partition.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_partition_migration_hibernation"
          xrefstyle="select: labelnumber nopage"/>-10.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the Partition Suspension option:</emphasis> The presence and
              value of all properties in
              <xref linkend="dbdoclet.50569344_83870" /> must not change while a
              partition is suspended except for those properties described by
              <xref linkend="LoPAR.DeviceTree" />.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

      <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_83870">
        <title>Properties Related to the Partition Suspension Option</title>
        <tgroup cols="2">
          <colspec colname="c1" colwidth="35*" />
          <colspec colname="c2" colwidth="65*" />
          <thead valign="middle">
            <row>
              <entry align="center">
                <para>
                  <emphasis role="bold">Property Name</emphasis>
                </para>
              </entry>
              <entry align="center">
                <para>
                  <emphasis role="bold">Requirement</emphasis>
                </para>
              </entry>
            </row>
          </thead>
          <tbody valign="middle">
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;ibm,estimate-precision&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.
                <emphasis role="bold"><literal>&#8220;ibm,estimate-precision&#8221;</literal></emphasis> shall
                contain the &#8220;fre&#8221;, &#8220;fres&#8221;,
                frsqrte&#8221;, and &#8220;frsqrtes&#8221; instruction
                mnemonics.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;ibm,processor-page-sizes&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;reservation-granule-size&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;cache-unified&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present if the cache is physically or logically
                unified and thus does not require the architected instruction
                sequence for data cache stores to appear in the instruction
                cache (See &#8220;Instruction Storage&#8221; section of Book II
                of PA); else shall not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;i-cache-size&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;d-cache-size&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;i-cache-line-size&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;d-cache-line-size&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;i-cache-block-size&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;d-cache-block-size&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;i-cache-sets&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;d-cache-sets&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;timebase-frequency&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present if the timebase frequency can fit into
                the
                <emphasis role="bold"><literal>&#8220;timebase-frequency&#8221;</literal></emphasis> property;
                else shall not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;ibm,extended-timebase-frequency&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present if the timebase frequency cannot fit
                into the
                <emphasis role="bold"><literal> &#8220;timebase-frequency&#8221;</literal></emphasis> property; else
                shall not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;slb-size&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;cpu-version&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-server#s&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;l2-cache&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present if another level of cache exists; else
                shall not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;ibm,vmx&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present if VMX is present for the partition;
                else shall not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;clock-frequency&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present if the processor frequency can fit into
                the
                <emphasis role="bold"><literal>&#8220;clock-frequency&#8221;</literal></emphasis> property;
                else shall not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;ibm,extended-clock-frequency&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present if the processor frequency cannot fit
                into the
                <emphasis role="bold"><literal>&#8220;clock-frequency&#8221;</literal></emphasis> property; else shall
                not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;ibm,processor-storage-keys&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;ibm,processor-vadd-size&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;ibm,processor-segment-sizes&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;ibm,segment-page-sizes&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;64-bit&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;ibm,dfp&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present if DFP is present for the partition;
                else shall not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;ibm,purr&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present if a PURR is present; else shall not be
                present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;performance-monitor&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present if a Performance Monitor is present;
                else shall not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;32-64-bridge&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;external-control&#8221;</para>
              </entry>
              <entry>
                <para>Shall not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;general-purpose&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;graphics&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;ibm,platform-hardware-notification&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;603-translation&#8221;</para>
              </entry>
              <entry>
                <para>Shall not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;603-power-management&#8221;</para>
              </entry>
              <entry>
                <para>Shall not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;tlb-size&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;tlb-sets&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;tlb-split&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;d-tlb-size&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;d-tlb-sets&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;i-tlb-size&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;i-tlb-sets&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;64-bit-virtual-address&#8221;</para>
              </entry>
              <entry>
                <para>Shall not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;bus-frequency&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present if the bus frequency can fit into the
                <emphasis role="bold"><literal>&#8220;bus-frequency&#8221;</literal></emphasis> property; else
                shall not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;ibm,extended-bus-frequency&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present if the processor frequency cannot fit
                into the
                <emphasis role="bold"><literal>&#8220;bus-frequency&#8221;</literal></emphasis> property; else shall
                not be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;ibm,spurr&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present if an SPURR is present; else shall not
                be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;name&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;device_type&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;reg&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;status&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;ibm,pa-features&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>&#8220;ibm,negotiated-pa-features&#8221;</para>
              </entry>
              <entry>
                <para>Shall be present</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;ibm,ppc-interrupt-gserver#s&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;ibm,tbu40-offset&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;ibm,pi-features &#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>
                  <emphasis role="bold"><literal>&#8220;ibm,pa-optimizations&#8221;</literal></emphasis>
                </para>
              </entry>
              <entry>
                <para>Shall be present</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>
      <para><emphasis role="bold">Note on <xref linkend="dbdoclet.50569344_83870" />:</emphasis> The values of the
      properties in Table
      <xref linkend="dbdoclet.50569344_83870" /> shall be consistent with
      implementation and design of the processor and the platform upon boot as
      well as before and after partition suspension.</para>
      <para>
      <emphasis role="bold">Programming Note:</emphasis> The
      <emphasis role="bold"><literal>&#8220;cpu-version&#8221;</literal></emphasis> property may contain a
      logical processor version value. Therefore, code designed to handle
      processor errata should read the
      <emphasis role="bold"><literal>&#8220;ibm,platform-hardware-notification&#8221;</literal></emphasis> property of
      the root node to obtain the physical processor version numbers allowed in
      the platform.</para>
    </section>

    <section xml:id="dbdoclet.50569344_39908">
      <title>Virtualizing the Real Mode Area</title>
      <para>PA requires implementations to provide a Real Mode Area of memory
      that is accessed when not in hypervisor state (either MSR[HV] = 0, or
      MSR[HV] = 1 and MSR[PR] = 1) and the OS address translation mechanism is
      disabled (MSR[IR] = 0 or MSR[DR] = 0). PA provides mechanisms to allow
      the RMA to consist of discontiguous pages of selectable sizes. Such an
      RMA is known as a virtualized RMA. The H_VRMASD hcall() allows the OS to
      change the characteristics of the mappings the address translation
      mechanism uses to access a virtualized RMA.</para>

      <section xml:id="dbdoclet.50569344_74652">
        <title>H_VRMASD</title>
        <para>The caller may need to invoke the H_VRMASD hcall() multiple times
        for it to return with a return code of H_Success. Upon receiving a return
        code of H_LongBusyOrder10mSec, the caller should attempt to invoke
        H_VRMASD in 10 mSec with the same Page_Size_Code value used on the
        previous H_VRMASD hcall(). Invoking H_VRMASD with a different
        Page_Size_Code value indicates that the caller wants to transition to the
        Page_Size_Code value of the most recent H_VRMASD call.</para>
        <para>When changing the page size used to map the VRMA using the H_VRMASD
        hcall(), the caller is responsible for establishing HPT entries for any
        potential real mode accesses prior to calling H_VRMASD with a new value
        of Page_Size_Code, and maintaining any HPT entries for the old value of
        Page_Size_Code until the hcall() returns H_Success.</para>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_74652"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the VRMA option:</emphasis> The platform must include the
                <emphasis role="bold"><literal>&#8220;ibm,vrma-page-sizes&#8221;</literal></emphasis> property (See
                <xref linkend="LoPAR.DeviceTree" />) in the
                <emphasis role="bold"><literal>/cpu</literal></emphasis> node.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_74652"
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the VRMA option:</emphasis> The platform must implement the
                H_VRMASD hcall() following the syntax and semantics of
                <xref linkend="dbdoclet.50569344_74652" />.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_74652"
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the VRMA option:</emphasis> In order to prevent a storage
                exception, the calling partition must establish page table mappings for
                the Real Mode Area using entries with a page size corresponding to the
                new Page_Size_Code value prior to making an H_VRMASD hcall() and must
                maintain the old page table mappings using the page size corresponding to
                the old Page_Size_Code value until the H_VRMASD hcall() returns
                H_Success.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_LongBusyOrder10mSec: Retry calling the hcall() in 10 */
                       /*   milliseconds.
                       /* H_Parameter: PAGE_SIZE_CODE parameter is invalid.*/
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   preventing the function. */
hcall ( const uint64 H_VRMASD, /* Change the page mapping characteristics of the */
                       /*   VRMA */
        uint64 Page_Size_Code ); /* Contains a VRMASD field value */]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Parameters:</title>
          <itemizedlist>
            <listitem>
              <para>Page_Size_Code: A supported VRMASD field value. Supported VRMASD
              field values are described by the
              <emphasis role="bold"><literal>&#8220;ibm,vrma-page-sizes&#8221;</literal></emphasis> property.</para>
            </listitem>
          </itemizedlist>
        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>Verify that the Page_Size_Code parameter corresponds to a
              supported VRMASD field value; else return H_Parameter.</para>
            </listitem>

            <listitem>
              <para>If the Real Mode Area page size specified by the Page_Size_Code
              parameter does not match the operating RMA page size of the partition,
              then set the operating RMA page size of the partition to the value
              specified by the Page_Size_Code parameter and initiate the transition of
              the operating RMA page size of all active processing threads to the value
              specified by the Page_Size_Code parameter.</para>
            </listitem>

            <listitem>
              <para>If all active threads have transitioned to the partition
              operating RMA page size, then return H_Success; else return
              H_LongBusyOrder10mSec.</para>
            </listitem>
          </itemizedlist>
        </simplesect>
      </section>
    </section>

    <section xml:id="dbdoclet.50569344_44716">
      <title>Cooperative Memory Over-commitment Option (CMO)</title>
      <para>The over-commitment of logical memory is accomplished by the
      platform reassigning pages of memory among the partitions to create the
      appearance of more memory than is actually present. This is commonly
      known as paging. While paging can, in certain cases, be accomplished
      transparently, significantly better memory utilization and platform
      performance can be achieved with cooperation from the partition
      OS.</para>
      <para>CMO introduces the following LoPAR terms:</para>

      <variablelist>
        <varlistentry>
          <term><emphasis role="bold">Expropriation:</emphasis></term>
            <listitem>
              <para>The act of the platform disassociating a physical
              page from a logical page.</para>
            </listitem>
			  </varlistentry>

        <varlistentry>
          <term><emphasis role="bold">Subvention:</emphasis></term>
            <listitem>
              <para>The act of the platform associating a physical page
              with a logical page.</para>
            </listitem>
			  </varlistentry>

        <varlistentry>
          <term><emphasis role="bold">Loaned Memory:</emphasis></term>
            <listitem>
              <para>Logical real memory that a partition lends to the
              hypervisor for reuse. The partition should not gratuitously access loaned
              memory as such accesses are likely to experience a significant
              delay.</para>
            </listitem>
			  </varlistentry>

        <varlistentry>
          <term><emphasis role="bold">Memory entitlement:</emphasis></term>
            <listitem>
              <para>The amount of memory that the platform
              guarantees that the partition is able to I/O map at any given
              time.</para>
            </listitem>
			  </varlistentry>
      </variablelist>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_44716"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the CMO option:</emphasis> The partition must be running
              under the SPLPAR option.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_44716"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the CMO option:</emphasis> The platform must transparently
              (except for time delays) handle all effects of any memory expropriation
              that it may introduce unless the CMO option is explicitly enabled by the
              setting of architecture.vec option vector 5 byte 4 bit 0 (See
              <xref linkend="LoPAR.DeviceTree" /> for details).</para>
              <para>The CMO option consists of the following LoPAR extensions:</para>

              <itemizedlist>
                <listitem>
                  <para>Define
                  <emphasis role="bold"><literal>ibm,architecture.vec-5</literal></emphasis> option Byte 4 bit 0 as
                  &#8220;Client supports cooperative logical real memory
                  over-commitment&#8221;.</para>
                </listitem>
                <listitem>
                  <para>Define page usage states to assist the platform in selecting good
                  victim pages and mechanisms to set such states.</para>
                </listitem>
                <listitem>
                  <para>Extend the syntax and semantics defined for the I/O mapping
                  hcall()s</para>

                  <itemizedlist>
                    <listitem>
                      <para>Return codes (H_LongBusyOrder1msec, H_LongBusyOrder10msec, and
                      H_NOT_ENOUGH_RESOURCES)</para>
                    </listitem>

                    <listitem>
                      <para>Return parameter extension for memory entitlement
                      management</para>
                    </listitem>
                  </itemizedlist>
                </listitem>
                <listitem>
                  <para>Define a simulated Special Uncorrectable memory Error machine
                  check for the case where a page can not be restored due to an
                  error.</para>
                </listitem>
              </itemizedlist>
            </listitem>
       	</varlistentry>

       	<varlistentry xml:id="dbdoclet.50569344_97073">
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_44716"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the CMO option:</emphasis> The architected interface syntax
              and semantics of all LoPAR hcall()s and RTAS calls except as explicitly
              modified per the CMO option architecture must remain invariant when
              operating in CMO mode; any accommodation to memory over-commitment by
              these firmware functions (potentially any function that takes a logical
              real address as an input parameter) is handled transparently.</para>
              <para><emphasis role="bold">Note:</emphasis> Requirement
              <xref linkend="dbdoclet.50569344_97073" /> specifically applies to the
              debugger support hcall()s.</para>
              <para>For maximum performance benefit, an OS that indicates via the
              <emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis> interface that it
              supports the CMO option will strive to maintain in the
              &#8220;loaned&#8221; state (See
              <xref linkend="dbdoclet.50569344_99399" />), the amount of logical memory
              indicated by the value returned in R9 from the H_GET_MPP hcall (See
              <xref linkend="dbdoclet.50569344_90056" />), as well as provide page
              usage state information via the interfaces defined in
              <xref linkend="dbdoclet.50569344_36783" /> and
              <xref linkend="dbdoclet.50569344_80884" />.</para>
              <para>The Extended Cooperative Memory Over-commitment Option (XCMO)
              provides additional features to manage page coalescing. These features
              are activated via setting architecture.vec vector 5 byte 4 bit 1 to the
              value of 1 in the
              <emphasis role="bold"><literal>ibm,client-architecture-support</literal></emphasis> interface. Given that
              the platform supports the XCMO option, the CC flag for page frame table
              Accesses see
              <xref linkend="dbdoclet.50569344_11209" /> and the H_GET_MPP_X hcall() see

              <xref linkend="dbdoclet.50569344_73194" /> may be used by the OS. An OS
              might understand that a given page is a great candidate for page
              coalescing perhaps because the page contains OS and or common library
              code which is likely to be duplicated in other partitions; if so it might
              choose to set the Coalesce Candidate (CC) flag in the page table access
              or H_PAGE_INIT hcall()s as a hint to the hypervisor. Should a given
              logical page be mapped multiple times with conflicting Coalesce Candidate
              hints, the value in the last mapping made takes precedence.</para>
              <para>For a variety of reasons outside the scope of LoPAR, a platform
              supporting the XCMO option for a given platform might not actually
              perform page coalescing. If this is the case, the first return value from
              the H_GET_MPP_X hcall() see
              <xref linkend="dbdoclet.50569344_73194" /> is the reserved value
              zero.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_44716"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the XCMO Option:</emphasis> The platform must implement the
              CMO Option.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_44716"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para><emphasis>Reserved for Compatibility</emphasis> For the XCMO Option: The
              platform must implement the CC (Coalesce Candidate) flag bit see
              <xref linkend="dbdoclet.50569344_11209" />.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_44716"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the XCMO Option:</emphasis> The platform must implement the
              H_GET_MPP_X hcall() see
              <xref linkend="dbdoclet.50569344_73194" />.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_44716"
          xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
            <listitem>
              <para>For the XCMO Option with the Partition Migration and
              Partition Hibernation options: to ensure proper operation after partition
              migration or hibernation, the OS must stop setting the CC flag bit see
              <xref linkend="dbdoclet.50569344_11209" /> and stop calling the
              H_GET_MPP_X hcall() see
              <xref linkend="dbdoclet.50569344_73194" /> prior to calling
              <emphasis>ibm,suspend-me</emphasis> RTAS and not do so again until after
              the OS has determined that the XCMO option is supported on the
              destination platform.</para>
            </listitem>
       	</varlistentry>
      </variablelist>


      <section xml:id="dbdoclet.50569344_55095">
        <title>CMO Background (Informative)</title>
        <para>The following information is provided to be informative of the
        architectural intent. Implementations may vary, but should make a best
        effort to achieve the goals described.</para>
        <para>Ideally, the hypervisor does not expropriate any logical memory
        pages that it must later read in from disk; this is based upon the belief
        that the OS is in a better position to determine its working set relative
        to the available memory and page its memory than the hypervisor thus,
        when possible, the OS pager should be used. The ideal is approximated,
        since it cannot be achieved in all cases. The &#8220;Overage&#8221; is
        defined as the amount of logical address space that cannot be backed by
        the physical main storage pool. The overage is equal to the summation of
        the logical address space for all partitions using a given VRM main
        storage pool (the main storage that the hypervisor uses to back logical
        memory pages for a set of partitions) plus the high water mark of the
        hypervisor free page list (the free list high water mark is some
        implementation dependent ratio of the pool size) less the size of the VRM
        main storage pool.</para>
        <para>If the summation of the space freed by page coalescing and page
        donation is equal to the overage, in the steady state the hypervisor need
        not page. In reality the system is seldom, if ever, in the steady state,
        but with the free list pages the hypervisor has enough buffer space to
        take up most of the transient cases.</para>
        <para>Page coalescing is a transparent operation where in the hypervisor
        detects duplicate pages, directs all user reads to a single copy and may
        reclaim the other duplicate physical memory pages. Should the page owner
        change a coalesced page the hypervisor needs to transparently provide the
        page owner with a unique copy of the page. Read only pages are more
        likely to remain identical for a longer period of time and are thus
        better coalescing candidates.</para>
        <para>To set the value for the partition's page donation, the algorithm
        needs to be &#8220;fair&#8221; and responsive to the partition's
        &#8220;weight&#8221; so that more important work can be helped along. To
        be &#8220;fair&#8221;, the donation needs to be somewhat proportional to
        the partition's size since donating x pages is likely to cause greater
        pain to a small partition than a large one; yet the reason for
        &#8220;weight&#8221; is to cause greater pain to certain partitions
        relative to others.</para>
        <para>Thus the initial donation for a partition is set at the partition's
        logical address space size as a percentage of the total pool logical
        space subscription times the overage.</para>
        <para>Each implementation dependent time interval (say single digit
        seconds or so), the hypervisor randomly selects 100 pages from each
        partition and monitors how many of them were accessed during the next
        interval. This, after normalization to account for partition CPU
        utilization relative to its recent maximum, becomes an estimate of the
        partition's page utilization. It is expected that a partition with higher
        page utilization has a higher page fault rate and a lower percentage of
        its working set resident -- thus experiences more pain from VRM.</para>
        <para>The page utilization method described above may over estimate
        memory pressure in certain cases; specifically it may be slow to realize
        that the partition has gone idle. An idle partition reduces its CPU
        utilization which after normalization makes it appear that the partition
        memory pressure has risen rather than lowered. For this reason, the
        results of the page utilization method is further compared with the OS
        reported count of faults against pages that were previously swapped out
        as reported in offsets 0x180 - 0x183 of the VPA for each of the
        partition processors. The partition fault count when normalized with
        respect to processor cycles allows comparisons among the reported values
        from other partitions. Since the partition fault count is OS reported,
        and thus can not be trusted, it can not be the primary value used to
        determine page allocation, but since if the OS is misreporting the
        statistic, it is likely to be high, the memory pressure estimate derived
        from the OS reported fault counts can be used to reduce (but not
        increase) the partition memory allocation. Note since the hint might not
        be reported by a given OS, a filter should be put in place to detect that
        the OS is not reporting faults and appropriate default values
        substituted.</para>
        <para>This initial donation is then modified over time to force the pain
        of higher page utilization upon lower weight partitions based upon
        comparing the following ratios:</para>
        <para>A: The average partition page utilization over the last interval of
        all partitions in the pool / the partition's page utilization over the
        last interval</para>
        <para>B: The partition's weight/average partition weight of all
        partitions in the pool</para>
        <para>If A &gt; B Increase the partition's donation by 1/256 of the
        partition's logical address space (limited to the partition&#8217;s
        logical address size)</para>
        <para>If A &lt; B Reduce the partition's donation by 1/256 of the
        partition's logical address space provided that the summation of all
        donations &gt;= Overage.</para>
        <para>The hypervisor maintains a per partition count of loaned pages
        (incremented when a page is removed from the PFT with a
        &#8220;loaned&#8221; state and decremented when/if the page state is
        changed) thus it can keep track of how well a partition is doing against
        the donation request that has been made of it. Partitions that do not
        respond to donation requests need
        to have their pages stolen to make up the difference. Pages that
        are &#8220;unused&#8221; or &#8220;loaned&#8221; are automatically
        applied to the free list. &#8220;Loaned&#8221; pages are expected to
        raise the partition's free list low water mark so that the OS only
        reclaims them in a transient situation which will then result in the OS
        paging out some of its own virtual memory to restore the total donation
        in the steady state. When the platform free list gets to the low water
        mark, pages are expropriated starting with the partition that has the
        greatest percentage discrepancy between its loaned plus expropriated
        count and is donation tax. The algorithm used is implementation
        dependent. The following is given for reference and is loosely based upon
        the AIX method.</para>

        <orderedlist>
          <listitem>
            <para>For this algorithm, pages that are newly restored are marked as
            &#8220;referenced&#8221; and all &#8220;unused&#8221; have already been
            harvested</para>
          </listitem>

          <listitem>
            <para>Step through the partition logical address space until either
            the hypervisor free list has gotten to its high water mark or the
            partition has been taxed to its donation.</para>

            <orderedlist>
              <listitem>
                <para>If the page is I/O mapped and not expropriatable, continue to
                the next page.</para>
              </listitem>

              <listitem>
                <para>If this is the first pass through the address space on this
                harvest, and the page is marked critical, continue to the next
                page.</para>
              </listitem>

              <listitem>
                <para>If the page is marked &#8220;referenced&#8221;, clear the
                reference bit and continue to the next page.</para>
              </listitem>

              <listitem>
                <para>If the page is backed in the VPM paging space and not modified
                since then, expropriate the page and continue to the next page.</para>
              </listitem>

              <listitem>
                <para>Queue the page to be copied into the VPM paging space.</para>
              </listitem>
            </orderedlist>
          </listitem>
        </orderedlist>

        <para>Thus partitions that keep up with their page donations seldom, if
        ever, experience a hypervisor page in delay. Those that do not keep up,
        will not get a free lunch and will be taxed up to the value of their
        assigned donation, with the real possibility that they will experience
        the pain of hypervisor page in delays.</para>
      </section>

      <section xml:id="dbdoclet.50569344_99399">
        <title>CMO Page Usage States</title>
        <para>The CMO option defines a number of page states that are set by the
        cooperating OS using the flags parameter of the HPT hcall()s. The
        platform uses these page states to estimate the overhead associated with
        expropriating the specific page.</para>
        <para>
        <emphasis role="bold">Note:</emphasis> that the first two definitions below represent
        base background page states; the 3rd definition is the foreground state
        of I/O mapped which is acquired as result of an I/O mapping hcall (such
        as H_PUT_TCE); and the last two are caller specifiable state
        modifiers/extended semantics of the base states.</para>

        <variablelist>
          <varlistentry>
              <term><emphasis role="bold">Unused</emphasis></term>
              <listitem>
                <para>The page contains no information that is needed in
                the future, its contents need not be maintained by the platform, normally
                set only when the page is unmapped.<footnote xml:id="pgfId-1229079">
                  <para>Expropriation of &#8220;Unused&#8221; pages should be a low
                  overhead operation. However, the OS is likely to reuse these pages
                  which means that a clean free page will have to be assigned to the
                  corresponding logical address.</para>
                </footnote></para>
              </listitem>
          </varlistentry>

          <varlistentry>
              <term><emphasis role="bold">Active</emphasis></term>
              <listitem>
                <para>The page retains data that the OS has no
                reasonable way to regenerate. This is the state traditionally assumed by
                the OS when mapping a page.<footnote xml:id="pgfId-1229083">
                  <para>&#8220;Active&#8221; pages should be expropriated only as a last
                  resort since they must be paged out and paged back in on a subsequent
                  access.</para>
                </footnote></para>
              </listitem>
          </varlistentry>

          <varlistentry>
              <term><emphasis role="bold">I/O Mapped</emphasis></term>
              <listitem>
                <para>The page is mapped for access by another
                agent. This state is the side effect of registration and/or I/O mapping
                functions. The page returns to its background state automatically when
                unmapped or deregistered.<footnote xml:id="pgfId-1229087">
                  <para>Pages in the I/O Mapped state normally may not be expropriated
                  since they are potentially the target of physical DMA
                  operations.</para>
                </footnote></para>
              </listitem>
          </varlistentry>

          <varlistentry>
              <term><emphasis role="bold">Critical</emphasis></term>
              <listitem>
                <para>The page is critical to the performance of the
                OS, and the hypervisor should avoid expropriating such pages while other
                pages are available.<footnote xml:id="pgfId-1229091">
                  <para>Expropriating pages marked &#8220;Critical&#8221; may result in
                  the OS being unable to meet its performance goals.</para>
                </footnote></para>
              </listitem>
          </varlistentry>

          <varlistentry>
              <term><emphasis role="bold">Loaned</emphasis></term>
              <listitem>
                <para>The page contains no information and the OS
                warrants that it will not gratuitously access this page such that the
                hypervisor may expect to use it for an extended period of time. When the
                OS does access the page, it is likely that the access will result in a
                subvention delay.<footnote xml:id="pgfId-1229095">
                  <para>Expropriating pages in the &#8220;Loaned&#8221; state should
                  result in the lowest overhead.</para>
                </footnote></para>
              </listitem>
          </varlistentry>
        </variablelist>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_99399"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the CMO option:</emphasis> The platform must at partition
                boot initialize the page usage state of all platform pages to
                &#8220;Active&#8221;.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_99399"
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the CMO option:</emphasis> The platform must preserve data
                in pages that are in the &#8220;Active&#8221; state.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_99399"
            xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the CMO option:</emphasis> When the OS accesses a page in
                the &#8220;Unused&#8221; state, the platform must present either the
                preserved page data or all zeros.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_99399"
            xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the CMO option:</emphasis> When the OS specifies as input to
                an I/O mapping or the H_MIGRATE_DMA hcall() a page in either the
                &#8220;Unused&#8221; or &#8220;Loaned&#8221; states, the platform must
                upgrade the page&#8217;s background page state to
                &#8220;Active&#8221;.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

        <section xml:id="dbdoclet.50569344_36783">
          <title>Setting CMO Page Usage States using HPT hcall() flags
          Parameter</title>
          <para>The CMO option defines additional flags parameter combinations for
          the HPT hcall()s that take a flags parameter. Turning on flags bit 28
          activates the changing of page state. Leaving bit 28 at the legacy value
          of zero maintains the page state setting, thus allowing legacy code to
          operate unmodified with all pages remaining in the initialized
          &#8220;Active&#8221; state.</para>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_36783"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the CMO option:</emphasis> The platform must extend the
                  syntax and semantics of the HPT access hcall()s that take a flags
                  parameter, see
                  <xref linkend="dbdoclet.50569344_14599" />, to set the page usage state
                  of the specified page per
                  <xref linkend="dbdoclet.50569344_92498" />.</para>
                </listitem>
           	</varlistentry>
          </variablelist>

          <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_14599">
            <title>HPT hcall()s extended with CMO flags</title>
            <?dbhtml table-width="50%" ?><?dbfo table-width="50%" ?>
            <tgroup cols="1">
              <colspec colname="c1" colwidth="100*" align="center" />
              <thead valign="middle">
                <row>
                  <entry>
                    <para>
                      <emphasis role="bold">hcall</emphasis>
                    </para>
                  </entry>
                </row>
              </thead>
              <tbody valign="middle">
                <row>
                  <entry>
                    <para>
                      <xref linkend="dbdoclet.50569344_80550" />
                    </para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>
                      <xref linkend="dbdoclet.50569344_61580" />
                    </para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>
                      <xref linkend="dbdoclet.50569344_50644" />
                    </para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>
                      <xref linkend="dbdoclet.50569344_53301" />
                    </para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>
                      <xref linkend="dbdoclet.50569344_35125" />
                    </para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>
                      <xref linkend="dbdoclet.50569344_34458" />
                    </para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>
                      <xref linkend="dbdoclet.50569344_36623" />
                    </para>
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>

          <para/>

          <table frame="all" xml:id="dbdoclet.50569344_92498">
            <title>CMO Page Usage State flags Definition</title>
            <?dbhtml table-width="60%" ?><?dbfo table-width="60%" ?>
            <tgroup cols="4">
              <colspec colname="c1" colwidth="20*" align="center" />
              <colspec colname="c2" colwidth="20*" align="center" />
              <colspec colname="c3" colwidth="20*" align="center" />
              <colspec colname="c4" colwidth="40*" />
              <thead valign="middle">
                <row>
                  <entry>
                    <para>
                      <emphasis role="bold">Flag bit 28</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Flag bits 29 - 30</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Flag bit 31</emphasis>
                    </para>
                  </entry>
                  <entry align="center">
                    <para>
                      <emphasis role="bold">Comments</emphasis>
                    </para>
                  </entry>
                </row>
              </thead>
              <tbody valign="middle">
                <row>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>Don&#8217;t Care</para>
                  </entry>
                  <entry>
                    <para>Don&#8217;t Care</para>
                  </entry>
                  <entry>
                    <para>Inhibit Page State Change</para>
                  </entry>
                </row>
                <row>
                  <entry morerows="5">
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>00</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>Set page state to Active</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>00</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>Set page State to Active Critical</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>01</para>
                  </entry>
                  <entry>
                    <para>both 0 and 1</para>
                  </entry>
                  <entry>
                    <para>Reserved</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>10</para>
                  </entry>
                  <entry>
                    <para>both 0 and 1</para>
                  </entry>
                  <entry>
                    <para>Reserved</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>11</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>Set page state to Unused</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>11</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>Set page state to Unused Loaned</para>
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>
        </section>

        <section xml:id="dbdoclet.50569344_80884">
          <title>Setting CMO Page Usage States with H_BULK_REMOVE</title>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_80884"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the CMO option:</emphasis> The platform must extend the
                  syntax and semantics of the H_BULK_REMOVE hcall (see
                  <xref linkend="dbdoclet.50569344_23009" />) to set the page usage state
                  of the specified pages per
                  <xref linkend="dbdoclet.50569344_69345" />.</para>
                </listitem>
           	</varlistentry>
          </variablelist>

          <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_69345">
            <title>H_BULK_REMOVE Translation Specifier control/status
            Byte Extended Definition for CMO Option</title>
            <tgroup cols="9">
              <colspec colname="c1" colwidth="5*" align="center" />
              <colspec colname="c2" colwidth="5*" align="center" />
              <colspec colname="c3" colwidth="5*" align="center" />
              <colspec colname="c4" colwidth="5*" align="center" />
              <colspec colname="c5" colwidth="5*" align="center" />
              <colspec colname="c6" colwidth="5*" align="center" />
              <colspec colname="c7" colwidth="5*" align="center" />
              <colspec colname="c8" colwidth="5*" align="center" />
              <colspec colname="c9" colwidth="60*" align="center" />
              <thead valign="middle">
                <row>
                  <entry>
                    <para>
                      <emphasis role="bold">0</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">1</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">2</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">3</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">4</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">5</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">6</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">7</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Bit Numbers</emphasis>
                    </para>
                  </entry>
                </row>
              </thead>
              <tbody valign="middle">
                <row>
                  <entry nameend="c2" namest="c1">
                    <para>type code</para>
                  </entry>
                  <entry nameend="c9" namest="c3">
                    <para>&#160;</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>r0</para>
                  </entry>
                  <entry>
                    <para>r0</para>
                  </entry>
                  <entry>
                    <para>r0</para>
                  </entry>
                  <entry>
                    <para>r0</para>
                  </entry>
                  <entry>
                    <para>r0</para>
                  </entry>
                  <entry>
                    <para>r0</para>
                  </entry>
                  <entry>
                    <para>Unused</para>
                  </entry>
                </row>
                <row>
                  <entry nameend="c9" namest="c1">
                    <para>&#160;</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry nameend="c4" namest="c3">
                    <para>
                      <emphasis role="bold">page state</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>r0</para>
                  </entry>
                  <entry>
                    <para>r0</para>
                  </entry>
                  <entry nameend="c8" namest="c7">
                    <para>req. mod.</para>
                  </entry>
                  <entry>
                    <para>Request</para>
                  </entry>
                </row>
                <row>
                  <entry morerows="7" nameend="c2" namest="c1">
                    <para>&#160;</para>
                  </entry>
                  <entry morerows="3" nameend="c4" namest="c3">
                    <para>&#160;</para>
                  </entry>
                  <entry morerows="3" nameend="c6" namest="c5">
                    <para>&#160;</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>Absolute</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>andcon</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>APVN</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>not used</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>
                      <emphasis role="bold">0</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">0</emphasis>
                    </para>
                  </entry>
                  <entry nameend="c9" namest="c5">
                    <para>
                      <emphasis role="bold">Inhibit page usage state change</emphasis>
                    </para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>
                      <emphasis role="bold">0</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">1</emphasis>
                    </para>
                  </entry>
                  <entry nameend="c9" namest="c5">
                    <para>
                      <emphasis role="bold">Reserved</emphasis>
                    </para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>
                      <emphasis role="bold">1</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">0</emphasis>
                    </para>
                  </entry>
                  <entry nameend="c9" namest="c5">
                    <para>
                      <emphasis role="bold">For CMO option set page usage state to
                      &#8220;Unused&#8221; if Success</emphasis>
                    </para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>
                      <emphasis role="bold">1</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">1</emphasis>
                    </para>
                  </entry>
                  <entry nameend="c9" namest="c5">
                    <para>
                      <emphasis role="bold">For CMO option set page usage state to
                      &#8220;Loaned&#8221; if Success</emphasis>
                    </para>
                  </entry>
                </row>
                <row>
                  <entry nameend="c9" namest="c1">
                    <para>&#160;</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry nameend="c4" namest="c3">
                    <para>return code</para>
                  </entry>
                  <entry nameend="c9" namest="c5">
                    <para>Response</para>
                  </entry>
                </row>
                <row>
                  <entry morerows="3" nameend="c2" namest="c1">
                    <para>&#160;</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>R</para>
                  </entry>
                  <entry>
                    <para>C</para>
                  </entry>
                  <entry morerows="3">
                    <para>r</para>
                  </entry>
                  <entry morerows="3">
                    <para>r</para>
                  </entry>
                  <entry>
                    <para>Success</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry morerows="2">
                    <para>r</para>
                  </entry>
                  <entry morerows="2">
                    <para>r</para>
                  </entry>
                  <entry>
                    <para>Not Found</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>H_PARM</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>H_HW</para>
                  </entry>
                </row>
                <row>
                  <entry nameend="c9" namest="c1">
                    <para>&#160;</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry nameend="c8" namest="c3">
                    <para>Reserved (to be zero)</para>
                  </entry>
                  <entry>
                    <para>End of String</para>
                  </entry>
                </row>
                <row>
                  <entry nameend="c9" namest="c1">
                    <para>Legion R=Reference Bit, C=Change Bit, r=reserved ignore,
                    r0=reserved to be zero</para>
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>
        </section>
      </section>

      <section xml:id="sec_cmo_io_ext">
        <title>CMO Extensions for I/O Mapping Hcall()s</title>
        <para>If an OS were to map an excessive amount of its memory for
        potential physical DMA access, little of its memory would be left for
        paging; conversely, if the OS was totally prevented from I/O mapping its
        memory, it could not do I/O operations. The CMO option introduces the
        concept of memory entitlement. The partition&#8217;s memory entitlement
        is the amount of memory that the platform guarantees that the partition
        is able to I/O map at any given time. A given page may be mapped multiple
        times through different LIOBNs yet it only counts once against the
        partition&#8217;s I/O mapping memory entitlement. The syntax of certain
        I/O mapping hcall()s is extended to return the change in the
        partition&#8217;s I/O mapped memory total. The entitlement is intended to
        be used to ensure forward progress of I/O operations.</para>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_cmo_io_ext"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the CMO option:</emphasis> When the partition is operating
                in CMO mode, the platform must extend the syntax and semantics of the I/O
                mapping hcall()s specified in
                <xref linkend="dbdoclet.50569344_18483" /> as per the specifications in
                <xref linkend="dbdoclet.50569344_94392" /> and
                <xref linkend="dbdoclet.50569344_49996" />.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

        <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_18483">
          <title>I/O Mapping hcall()s Modified by the CMO
          Option.</title>
          <?dbhtml table-width="60%" ?><?dbfo table-width="60%" ?>
          <tgroup cols="2">
            <colspec colname="c1" colwidth="40*" align="center" />
            <colspec colname="c2" colwidth="60*" align="center" />
            <thead valign="middle">
              <row>
                <entry>
                  <para>
                    <emphasis role="bold">hcall()</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Base Definition on</emphasis>
                  </para>
                </entry>
              </row>
            </thead>
            <tbody valign="middle">
              <row>
                <entry>
                  <para>H_PUT_TCE</para>
                </entry>
                <entry>
                  <para>
                    <xref linkend="dbdoclet.50569344_44496" />
                  </para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>H_STUFF_TCE</para>
                </entry>
                <entry>
                  <para>
                    <xref linkend="dbdoclet.50569344_31179" />
                  </para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>H_PUT_TCE_INDIRECT</para>
                </entry>
                <entry>
                  <para>
                    <xref linkend="dbdoclet.50569344_50921" />
                  </para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>
        <para>
        <emphasis role="bold">Note:</emphasis> The I/O mapping hcalls H_PUT_RTCE and
        H_PUT_RTCE_INDIRECT do not change the number of pages that are I/O mapped
        since they simply create copies of the I/O mappings that already
        exist.</para>

        <section xml:id="dbdoclet.50569344_94392">
          <title>CMO I/O Mapping Extended Return Codes</title>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_94392"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the CMO option:</emphasis> The platform must ensure that the
                  DMA agent operating through the I/O mappings established by the hcall()s
                  specified in
                  <xref linkend="dbdoclet.50569344_18483" /> can appear to successfully
                  access the associated page data of any expropriated page referenced by
                  the input parameters of the hcall() prior to returning the code
                  H_Success.</para>
                </listitem>
           	</varlistentry>

           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_94392"
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the CMO option:</emphasis> The platform must either extend
                  the return code set for the hcall()s specified in
                  <xref linkend="dbdoclet.50569344_18483" /> to include H_LongBusyOrder1msec
                  and/or H_LongBusyOrder10msec or transparently suspend the calling virtual
                  processor for cases where the function is delayed pending the restoration
                  of an expropriated page.</para>
                </listitem>
           	</varlistentry>

           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_94392"
              xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the CMO option:</emphasis> The platform must extend the
                  return code set for the hcall()s specified in
                  <xref linkend="dbdoclet.50569344_18483" /> to include
                  H_NOT_ENOUGH_RESOURCES for cases where the function would cause more
                  memory to be I/O mapped than the caller is entitled to I/O map and the
                  platform is incapable of honoring the request.</para>
                </listitem>
           	</varlistentry>
          </variablelist>

        </section>

        <section xml:id="dbdoclet.50569344_49996">
          <title>CMO I/O Mapping Extended Return Parameter</title>
          <para>The syntax and semantics of the hcall()s in
          <xref linkend="dbdoclet.50569344_18483" /> are extended when the partition
          is operating in CMO mode by returning in register R4 the change in the
          partition&#8217;s total number of I/O mapped memory bytes due to the
          execution of the hcall(). The number may be positive (increase in the
          amount of memory mapped) negative or zero (the page was/remains mapped
          for I/O access by another agent).</para>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_49996"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the CMO option:</emphasis> The platform must extend the
                  syntax and semantics of the hcall()s specified in
                  <xref linkend="dbdoclet.50569344_18483" /> when operating in CMO mode, to
                  return in register R4 the change to the total number of bytes that were
                  I/O mapped due to the hcall().</para>
                </listitem>
           	</varlistentry>
          </variablelist>
        </section>
      </section>

      <section xml:id="dbdoclet.50569344_22106">
        <title>H_SET_MPP</title>
        <para>This hcall() sets, within limits, the partition&#8217;s memory
        performance parameters. If the request parameter exceeds the constraint
        of the calling LPAR&#8217;s environment, the hypervisor limits the value
        set to the constrained value and returns H_Constrained. The memory weight
        is architecturally constrained to be within the range of 0-255.</para>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Constrained: The input parameter exceeds the */
                       /*   partition’s constraints*/
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_SET_MPP, /* Sets the Memory Performance Parameters within */
                       /*   constraints. */
        uint64 entitled, /* I/O mapping memory entitlement in bytes */
        uint8 variable /* The memory weight used to determine the page victim */
                       /*   partition */
      );]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>Verify that the memory performance parameters specified are
              within the constraints of the partition:</para>

              <itemizedlist>
                <listitem>
                  <para>If yes, atomically set the partition&#8217;s memory performance
                  parameters per the request and return H_Success.</para>
                </listitem>

                <listitem>
                  <para>If not, set the partition&#8217;s memory performance parameters
                  as constrained by the partition&#8217;s configuration and return
                  H_Constrained.</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_22106"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the CMO option:</emphasis> The platform must initially set
                  the partition memory performance parameters to their configured maximums
                  at partition boot time.</para>
                </listitem>
           	</varlistentry>

           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_22106"
              xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the CMO option:</emphasis> The platform must implement the
                  H_SET_MPP hcall() following the syntax and semantics of
                  <xref linkend="dbdoclet.50569344_22106" />.</para>
                </listitem>
           	</varlistentry>

           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_22106"
              xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the CMO option:</emphasis> The platform must constrain the
                  partition memory weight to the range 0-255.</para>
                </listitem>
           	</varlistentry>
          </variablelist>
        </simplesect>
      </section>

      <section xml:id="dbdoclet.50569344_90056">
        <title>H_GET_MPP</title>
        <para>This hcall() reports the partition&#8217;s memory performance
        parameters. The returned parameters are packed into registers.</para>

        <section>
          <title>Command Overview</title>

          <simplesect>
            <title>Syntax:</title>

            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_GET_MPP /*Returns in R4 - R10 the Memory Performance */
                       /*   Parameters. */
      );]]></programlisting>

          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Place the partition&#8217;s memory performance parameters for the
                calling virtual processor&#8217;s partition into the respective
                registers:</para>

                <itemizedlist>
                  <listitem>
                    <para>R4: The number of bytes of main storage that the calling
                    partition is entitled to I/O map. In the case of a dedicated memory
                    partition this shall be the size of the partition&#8217;s logical address
                    space.</para>
                  </listitem>

                  <listitem>
                    <para>R5: The number of bytes of main storage that the calling
                    partition has I/O mapped. In the case of a dedicated memory partition
                    this is not applicable which is represented by the code -1.</para>
                  </listitem>

                  <listitem>
                    <para>R6: The calling partition&#8217;s virtual partition memory
                    aggregation identifier numbers, up to 4 levels:</para>

                    <itemizedlist>
                      <listitem>
                        <para>Bytes 0-1: Reserved for future aggregation definition, and set to
                        zero -- in the future this field may be given meaning.</para>
                      </listitem>

                      <listitem>
                        <para>Bytes 2-3: Reserved for future aggregation definition, and set to
                        zero -- in the future this field may be given meaning.</para>
                      </listitem>

                      <listitem>
                        <para>Bytes 4-5: 16 bit binary representation of the &#8220;Group
                        Number&#8221;.</para>
                      </listitem>

                      <listitem>
                        <para>Bytes 6-7: 16 bit binary representation of the &#8220;Pool
                        Number&#8221;. In the case of a dedicated memory partition the
                        &#8220;Pool Number&#8221; is not applicable which is represented by the
                        code 0xFFFF.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>

                  <listitem>
                    <para>R7: Collection of short memory performance parameters for the
                    calling partition:</para>

                    <itemizedlist>
                      <listitem>
                        <para>Byte 0: Memory weight (0-255). In the case of a dedicated
                        processor partition this is not applicable which is represented by the
                        code 0.</para>
                      </listitem>

                      <listitem>
                        <para>Byte 1: Unallocated memory weight for the calling
                        partition&#8217;s aggregation.</para>
                      </listitem>

                      <listitem>
                        <para>Bytes 2-7: Unallocated I/O mapping entitlement for the calling
                        partition&#8217;s aggregation divided by 4096.</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>

                  <listitem>
                    <para>R8: The calling partition&#8217;s memory pool main storage size
                    in bytes. In the case of a dedicated processor partition this is not
                    applicable which is represented by the code -1.</para>
                  </listitem>

                  <listitem>
                    <para>R9: The signed difference between the number of bytes of logical
                    storage that are currently on loan from the calling partition and the
                    partition&#8217;s overage allotment (a positive number indicates a
                    request to the partition to loan the indicated number of bytes else they
                    will be expropriated as needed).</para>
                  </listitem>

                  <listitem>
                    <para>R10: The number of bytes of main storage that is backing the
                    partition logical address space. In the case of a dedicated processor
                    partition this is the size of the partition&#8217;s logical address
                    space.</para>
                  </listitem>

                  <listitem>
                    <para>Return H_Success.</para>
                  </listitem>
                </itemizedlist>
              </listitem>
            </itemizedlist>

            <variablelist>
             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_90056"
                xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                  <listitem>
                    <para><emphasis role="bold">For the CMO option:</emphasis> The platform must implement the
                    H_GET_MPP hcall() following the syntax and semantics of
                    <xref linkend="dbdoclet.50569344_90056" />.</para>
                  </listitem>
             	</varlistentry>
            </variablelist>
          </simplesect>
        </section>

        <section xml:id="dbdoclet.50569344_73194">
          <title>H_GET_MPP_X</title>
          <para>This hcall() provides additional information over and above (not
          duplication of) that which is returned by the H_GET_MPP hcall()
          <xref linkend="dbdoclet.50569344_90056" />. The syntax of this hcall() is
          specifically designed to be seamlessly extensible and version to version
          compatible both from the view of the caller and the called on an
          invocation by invocation basis. To this end, all return registers (R3
          (return code) through R10) are defined from the outset, some are defined
          as reserved and are set to zero upon return by the hcall(). The caller is
          explicitly prohibited from assuming that any reserved register contains
          the value zero, so that there will be no incompatibility with future
          versions of the hcall() that return non-zero values in those registers.
          New definitions for returned values will define the value zero to
          indicate a benign or unreported setting.</para>

          <simplesect>
            <title>Syntax:</title>

            <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Hardware The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
                       /* H_Function: The platform does not implement the hcall() */
hcall ( const H_GET_MPP_X /* Returns in R4-R10 extended Memory Performance */
                       /*   Parameters */
      );]]></programlisting>

          </simplesect>

          <simplesect>
            <title>Semantics:</title>

            <itemizedlist>
              <listitem>
                <para>Place the partition&#8217;s extended memory performance
                parameters for the calling virtual processor&#8217;s partition into the
                respective registers:</para>

                <itemizedlist>
                  <listitem>
                    <para>R4: The number of bytes of the calling partition&#8217;s logical
                    real memory coalesced because they contained duplicated data.</para>
                  </listitem>

                  <listitem>
                    <para>R5: If the calling partition is authorized to see pool wide
                    statistics (set by means that are beyond the scope of LoPAR) then The
                    number of bytes of logical real memory coalesced because they contained
                    duplicated data in the calling partition&#8217;s memory pool else set to
                    zero.</para>
                  </listitem>

                  <listitem>
                    <para>R6:: If the calling partition is authorized to see pool wide
                    statistics (set by means that are beyond the scope of LoPAR) then PURR
                    cycles consumed to coalesce data else set to zero.</para>
                  </listitem>

                  <listitem>
                    <para>R7: If the calling partition is authorized to see pool wide
                    statistics (set by means that are beyond the scope of LoPAR) then SPURR
                    cycles consumed to coalesce data else set to zero.</para>
                  </listitem>

                  <listitem>
                    <para>R8: If the calling partition is authorized to see pool
                    wide statistics (set by means that are beyond the scope of LoPAR)
                    then, the total number of the calling partition’s
                    memory pool bytes currently in use backing the pool's partition
                    logical memory (this value represents the net usage
                    after any and all savings from deduplication or any other future
                    means the hypervisor may employ) else set to 0.</para>
                  </listitem>

                  <listitem>
                    <para>R9: Reserved shall be set to zero - shall not be read by
                    the caller</para>
                  </listitem>

                  <listitem>
                    <para>R10: Reserved shall be set to zero - shall not be read by
                    the caller</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Return H_Success:</para>
              </listitem>
            </itemizedlist>

            <variablelist>
             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_73194"
                xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                  <listitem>
                    <para><emphasis role="bold">For the XCMO option:</emphasis> If the platform coalesces memory
                    pages that contain duplicated data it must implement the H_GET_MPP_X
                    hcall() following the syntax and semantics of
                    <xref linkend="dbdoclet.50569344_73194" />.</para>
                  </listitem>
             	</varlistentry>

             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_73194"
                xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                  <listitem>
                    <para><emphasis role="bold">For the XCMO option:</emphasis> the caller must be prepared for
                    H_GET_MPP_X to return H_Function or to have a return parameter that was
                    previously non-zero be consistently returned with the value zero if the
                    caller wishes to operate properly in a partition migration or fail-over
                    environment.</para>
                  </listitem>
             	</varlistentry>
            </variablelist>
          </simplesect>
        </section>
      </section>

      <section xml:id="sec_restoration_failure_int">
        <title>Restoration Failure Interrupt</title>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="sec_restoration_failure_int"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the CMO option:</emphasis> When the platform experiences an
                unrecoverable error restoring the association of a physical page with an
                expropriated logical page following an attempted access of the
                expropriated page by the partition, the platform must signal a Machine
                Check Interrupt by returning to the partition&#8217;s interrupt vector at
                location 0x0200. Note the subsequent firmware assisted NMI and check
                exception processing returns a VPM SUE error log (See
                <xref linkend="LoPAR.Error" />).</para>
              </listitem>
         	</varlistentry>
        </variablelist>
      </section>

      <section xml:id="dbdoclet.50569344_47885">
        <title>H_MO_PERF</title>
        <para>This hcall() applies an artificial memory over-commitment to the
        specified pool while monitoring the pool performance for overload,
        removing the applied over-commitment if an overload trigger point is
        reached. The overload trigger point is designed to double as a dead man
        switch, eventually ending the over-commitment condition should the
        experiment terminate ungracefully. Only the partition that is authorized
        to run platform diagnostics is authorized to make this call.</para>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
                       /* H_AUTHORITY: The caller lacked the authority to make this */
                       /*   call */
                       /* H_Parameter: The Pool number parameter is invalid */
hcall ( const uint64 H_MO_PERF, /*Returns the accumulated pool memory and */
                       /*   performance load */
        uint16 pool,   /* Pool number being loaded */
        int mem,       /* The change to the accumulated “bench” from the memory pool */
        int lows       /* The change to the accumulated permissible pool memory low */
                       /*   events */
      );]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Semantics:</title>
          <para>This description is based upon the architectural model of
          <xref linkend="dbdoclet.50569344_55095" />, and must be adjusted to
          achieve the intent for the specific implementation.</para>

          <itemizedlist>
            <listitem>
              <para>Validate that the caller has the required authority; else return
              H_AUTHORITY.</para>
            </listitem>

            <listitem>
              <para>Validate that the pool parameter references an active memory pool
              else; return H_Parameter.</para>
            </listitem>

            <listitem>
              <para>Raise the pool&#8217;s free list low water mark above its base
              value by the signed amount in the mem parameter. (The result is
              constrained to not less than the base low water mark value and no more
              then the amount of memory in the pool.)</para>
            </listitem>

            <listitem>
              <para>Change the permissible pool memory low event counter by the
              signed value of the lows parameter.</para>
            </listitem>

            <listitem>
              <para>Return in R4 the accumulated rise in the pool&#8217;s free list
              low water mark above its base value.</para>
            </listitem>

            <listitem>
              <para>Return in R5 the current value of the permissible pool memory low
              event counter.</para>
            </listitem>

            <listitem>
              <para>On each subsequent low memory event (page allocation where the
              free list is at or below the low water mark), the permissible pool memory
              low event counter is decremented. Should the counter ever reach zero, the
              pool&#8217;s free list low water mark is returned to its base
              value.</para>
            </listitem>
          </itemizedlist>
        </simplesect>
      </section>

      <section xml:id="dbdoclet.50569344_20827">
        <title>Expropriation/Subvention Notification Option
        </title>
        <para>The Expropriation/Subvention Notification Option (ESN) sub option
        of the CMO option allows implementing platforms to notify supporting
        OS&#8217;s of delays due to their access of an expropriated VPM page
        (such as would be experienced during a &#8220;page in&#8221; operation).
        With an expropriation notification, the OS may block the affected process
        and dispatch another rather than having the platform block the virtual
        processor that happened to be running the affected process. An
        expropriation notification is paired with a subsequent subvention
        notification signaled when the original access succeeds. Additionally new
        page states allow the OS to indicate pages that it can restore itself,
        thus relieving the platform from the burden of making copies of those
        pages when they are expropriated and potentially side stepping the
        &#8220;double paging problem&#8221; wherein the platform pages in a page
        in response to a touch operation in preparation for an OS page in only to
        have the OS immediately discard the page data without looking at
        it.</para>
        <para>The ESN option includes the following LoPAR extensions:</para>

        <itemizedlist>
          <listitem>
            <para>Define augmented CMO page states</para>
          </listitem>

          <listitem>
            <para>Define the per partition Subvention Notification Structure
            (SNS)</para>
          </listitem>

          <listitem>
            <para>Define H_REG_SNS hcall() to register the SNS</para>
          </listitem>

          <listitem>
            <para>Define Expropriation Notification field definitions within the
            VPA</para>
          </listitem>

          <listitem>
            <para>Define expropriation and subvention event interrupts.</para>
          </listitem>
        </itemizedlist>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_20827"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the ESN option:</emphasis> The partition must be running
                under the CMO option.</para>
              </listitem>
         	</varlistentry>

         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_20827"
            xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the ESN option:</emphasis> The platform must ignore/disable
                all other ESN option functions and features unless the OS has
                successfully registered the Subvention Notification Structure via the
                H_REG_SNS hcall. See
                <xref linkend="dbdoclet.50569344_76215" /> for details.</para>
              </listitem>
         	</varlistentry>
        </variablelist>

        <section>
          <title>ESN Augmentation of CMO Page Usage States</title>
          <para>The ESN option augments the set of page states defined by the CMO
          option that are set by the cooperating OS using the flags parameter of
          the HPT hcall()s. The platform uses these page states to estimate the
          overhead associated with expropriating the specific page.</para>
          <para>
          <emphasis role="bold">Active</emphasis>- An Expropriation notification on this
          type of page allows the OS to put the using process to sleep, until the
          page is restored, as signaled by a corresponding subvention notification,
          at which time the affected instruction is retried.</para>
          <para>
          <emphasis role="bold">Expendable</emphasis>- the page retains data that the OS
          can regenerate, for example, a text page that is backed up on disk;
          usually the page is mapped read only. A reflected expropriation
          notification on this type of page requires the OS to restore the page
          - thus the platform presents somewhat different interrupt status
          from that used by an Active page.<footnote xml:id="pgfId-1238755">
            <para>Expropriating an &#8220;Expendable&#8221; page should result in
            lower overhead than expropriating an &#8220;Active&#8221; page since
            the contents need not be paged out before the page is reused.</para>
          </footnote><footnote xml:id="pgfId-1238768">
            <para>An Expendable page that is Bolted while not illegal has to be
            treated as an &#8220;Active&#8221; page since an access to a Bolted
            page may not result in an expropriation notification.</para>
          </footnote></para>
          <para>
          <emphasis role="bold">Latent</emphasis>- the page contains data that the OS can
          regenerate unless the contents have been modified - at which time
          the page state appears to be &#8220;Active&#8221;, this is similar to
          &#8220;Expendable&#8221; for pages mapped read/write. For example, a page
          of a mapped file. Expropriation Notification is like &#8220;Active&#8221;
          or &#8220;Expendable&#8221; above.</para>
          <para>
          <emphasis role="bold">Loaned</emphasis>- When the OS does access the page, it
          is likely that the access will result in an expropriation
          notification</para>

          <table frame="all" pgwide="1">
            <title>ESN Augmentation of CMO Page Usage State flags
            Definition</title>
            <?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
            <tgroup cols="4">
              <colspec colname="c1" colwidth="23*" align="center" />
              <colspec colname="c2" colwidth="23*" align="center" />
              <colspec colname="c3" colwidth="23*" align="center" />
              <colspec colname="c4" colwidth="31*" align="center" />
              <thead valign="middle">
                <row>
                  <entry>
                    <para>
                      <emphasis role="bold">Flag bit 28</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Flag bits 29 - 30</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Flag bit 31</emphasis>
                    </para>
                  </entry>
                  <entry>
                    <para>
                      <emphasis role="bold">Comments</emphasis>
                    </para>
                  </entry>
                </row>
              </thead>
              <tbody valign="middle">
                <row>
                  <entry morerows="3">
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>01</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>Set page state to Latent<footnote xml:id="pgfId-1242417">
                      <para><emphasis role="bold">Note:</emphasis> If Expropriation Notification is disabled, or the
                      bolted bit (HPT bit 59) is set to 1, the page state to Active
                      (Active Critical if flag bit 31=1).</para>
                    </footnote></para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>01</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>Set page State to Latent Critical<footnoteref linkend="pgfId-1242417" /></para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>10</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>Set page state to Expendable<footnoteref linkend="pgfId-1242417" /></para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>10</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>Set page state to Expendable Critical<footnoteref linkend="pgfId-1242417" /></para>
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>
        </section>

        <section xml:id="dbdoclet.50569344_74545">
          <title>Expropriation Notification</title>
          <para>Under the ESN option, notice of an attempt to access an
          expropriated page is given when the Expropriation Interrupt is enabled in
          the virtual processor VPA. Additionally the virtual processor VPA
          Expropriation Correlation Number and Expropriation Flags fields are set
          to allow the affected program to determine when the access may succeed
          and if the program needs to restore data to the Subvened page, see
          details in
          <xref linkend="dbdoclet.50569344_29538" />. Once the VPA has been
          updated, the platform presents an Expropriation Fault interrupt to the
          affected virtual processor see details in
          <xref linkend="dbdoclet.50569344_24622" />.</para>

          <section xml:id="dbdoclet.50569344_29538">
            <title>ESN VPA Fields</title>

            <variablelist xml:id="dbdoclet.50569344_55223">
             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_29538"
                xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                  <listitem>
                    <para>For the ESN
                    option: The platform must support the VPA field definitions of
                    <xref linkend="dbdoclet.50569344_36138" />,
                    <xref linkend="dbdoclet.50569344_87521" />, and
                    <xref linkend="dbdoclet.50569344_63708" />.</para>
                  </listitem>
             	</varlistentry>
            </variablelist>

            <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_36138">
              <title>VPA Byte Offset 0xB9</title>
              <?dbhtml table-width="60%" ?><?dbfo table-width="60%" ?>
              <tgroup cols="9">
                <colspec colname="c1" colwidth="5*" align="center" />
                <colspec colname="c2" colwidth="5*" align="center" />
                <colspec colname="c3" colwidth="5*" align="center" />
                <colspec colname="c4" colwidth="5*" align="center" />
                <colspec colname="c5" colwidth="5*" align="center" />
                <colspec colname="c6" colwidth="5*" align="center" />
                <colspec colname="c7" colwidth="5*" align="center" />
                <colspec colname="c8" colwidth="5*" align="center" />
                <colspec colname="c9" colwidth="60*" align="center" />
                <thead valign="middle">
                  <row>
                    <entry>
                      <para>
                        <emphasis role="bold">0</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">1</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">2</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">3</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">4</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">5</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">6</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">7</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">Bit Number</emphasis>
                      </para>
                    </entry>
                  </row>
                </thead>
                <tbody valign="middle">
                  <row>
                    <entry morerows="3" nameend="c6" namest="c1">
                      <para>Reserved (0)</para>
                    </entry>
                    <entry>
                      <para>&#160;</para>
                    </entry>
                    <entry>
                      <para>0</para>
                    </entry>
                    <entry>
                      <para>Dedicated processor cycle donation inhibited</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>&#160;</para>
                    </entry>
                    <entry>
                      <para>1</para>
                    </entry>
                    <entry>
                      <para>Dedicated processor cycle donation enabled</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>0</para>
                    </entry>
                    <entry>
                      <para>&#160;</para>
                    </entry>
                    <entry>
                      <para>Expropriation interrupt disabled</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>1</para>
                    </entry>
                    <entry>
                      <para>&#160;</para>
                    </entry>
                    <entry>
                      <para>Expropriation interrupt enabled</para>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>
            <para>&#160;</para>
            <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_87521">
              <title>Firmware Written VPA Starting at Byte Offset
              0x178</title>
              <tgroup cols="8">
                <colspec colname="c1" colwidth="12*" align="center" />
                <colspec colname="c2" colwidth="12*" align="center" />
                <colspec colname="c3" colwidth="12*" align="center" />
                <colspec colname="c4" colwidth="12*" align="center" />
                <colspec colname="c5" colwidth="12*" align="center" />
                <colspec colname="c6" colwidth="12*" align="center" />
                <colspec colname="c7" colwidth="12*" align="center" />
                <colspec colname="c8" colwidth="12*" align="center" />
                <thead valign="middle">
                  <row>
                    <entry>
                      <para>
                        <emphasis role="bold">0x178 F</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">0x179</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">0x17A</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">0x17B</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">0x17C</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">0x17D</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">0x17E</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">0x17</emphasis>
                      </para>
                    </entry>
                  </row>
                </thead>
                <tbody valign="middle">
                  <row>
                    <entry morerows="1">
                      <para>Reserved for firmware locks</para>
                    </entry>
                    <entry morerows="1" nameend="c5" namest="c2">
                      <para>Reserved</para>
                    </entry>
                    <entry>
                      <para>&#160;</para>
                    </entry>
                    <entry nameend="c8" namest="c7">
                      <para>Expropriation Correlation</para>
                      <para>Number Field</para>
                    </entry>
                  </row>
                  <row>
                    <entry nameend="c8" namest="c6">
                      <para>Expropriation Flags -- See
                      <xref linkend="dbdoclet.50569344_63708" />.</para>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>
            <para>
            <emphasis role="bold">Note:</emphasis> The Expropriation Flags and Expropriation
            Correlation Number Fields are volatile with respect to Expropriation
            Notifications thus it should be saved by the OS before executing any
            instruction that may access unbolted pages.</para>

            <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_63708">
              <title>Expropriation Flags at VPA Byte Offset 0x17D</title>
              <?dbhtml table-width="60%" ?><?dbfo table-width="60%" ?>
              <tgroup cols="9">
                <colspec colname="c1" colwidth="5*" align="center" />
                <colspec colname="c2" colwidth="5*" align="center" />
                <colspec colname="c3" colwidth="5*" align="center" />
                <colspec colname="c4" colwidth="5*" align="center" />
                <colspec colname="c5" colwidth="5*" align="center" />
                <colspec colname="c6" colwidth="5*" align="center" />
                <colspec colname="c7" colwidth="5*" align="center" />
                <colspec colname="c8" colwidth="5*" align="center" />
                <colspec colname="c9" colwidth="60*" align="center" />
                <thead valign="middle">
                  <row>
                    <entry>
                      <para>
                        <emphasis role="bold">0</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">1</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">2</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">3</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">4</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">5</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">6</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">7</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">Bit Number</emphasis>
                      </para>
                    </entry>
                  </row>
                </thead>
                <tbody valign="middle">
                  <row>
                    <entry morerows="1" nameend="c7" namest="c1">
                      <para>Reserved (0)</para>
                    </entry>
                    <entry>
                      <para>0</para>
                    </entry>
                    <entry>
                      <para>The Subvened page data is/will be zero</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>1</para>
                    </entry>
                    <entry>
                      <para>The Subvened page data will be restored.</para>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>
          </section>

          <section xml:id="dbdoclet.50569344_24622">
            <title>Expropriation Interrupt</title>
            <para>When the platform is running with real memory over-commitment,
            eventually a partition virtual processor will access a stolen page. The
            transparent solution is to block the virtual processor until the platform
            has restored the page. By enabling the Expropriation Interrupt via the
            Expropriation Interrupt Enable field of the VPA (see
            <xref linkend="dbdoclet.50569344_29538" />) the cooperating OS indicates
            that it is prepared to make use of its virtual processors for other
            purposes during the page restoration and/or restore the contents of
            &#8220;expendable&#8221; and unmodified &#8220;latent&#8221;
            pages.</para>

            <variablelist>
             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_24622"
                xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                  <listitem>
                    <para><emphasis role="bold">For the ESN option:</emphasis> When the partition accesses an
                    expropriated page and either the page was bolted (PTE bit 59=1) or the
                    Expropriation Interrupt Enable bit of the affected virtual
                    processor&#8217;s VPA is off see
                    <xref linkend="dbdoclet.50569344_29538" />, then the platform must
                    recover the page transparently without an Expropriation Interrupt.</para>
                  </listitem>
             	</varlistentry>

             	<varlistentry xml:id="dbdoclet.50569344_55988">
                <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_24622"
                xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                  <listitem>
                    <para><emphasis role="bold">For the ESN option:</emphasis>
                    When the partition accesses an expropriated page and the summation of the
                    partition&#8217;s in use subvention event queue entries plus outstanding
                    subvention events is equal to or greater than the size of the
                    partition&#8217;s subvention event queue, the platform must recover the
                    page prior to issuing any associated Expropriation Interrupt.</para>
                    <para>
                    <emphasis role="bold">Note:</emphasis> Requirement
                    <xref linkend="dbdoclet.50569344_55988" /> prevents the overflow of the
                    subvention queue.</para>
                  </listitem>
             	</varlistentry>

             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_24622"
                xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
                  <listitem>
                    <para><emphasis role="bold">For the ESN option:</emphasis> When the partition accesses an
                    expropriated &#8220;Unused&#8221; or &#8220;Expendable&#8221; page, the
                    platform must, unless prevented by
                    <xref linkend="dbdoclet.50569344_55223" />, set bit 7 of the affected
                    processor&#8217;s Expropriation Flags VPA byte (see
                    <xref linkend="dbdoclet.50569344_63708" />) to 0b0; else the platform
                    must set the bit to 0b1.</para>
                  </listitem>
             	</varlistentry>

             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_24622"
                xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
                  <listitem>
                    <para><emphasis role="bold">For the ESN option:</emphasis> When the partition accesses an
                    expropriated page and the platform associates a physical page with the
                    logical page prior to returning control to the affected virtual
                    processor, the platform must, unless prevented by
                    <xref linkend="dbdoclet.50569344_55223" />, set the Expropriation
                    Correlation Number field of the affected virtual processor&#8217;s VPA to
                    0x0000 (see
                    <xref linkend="dbdoclet.50569344_87521" />).</para>
                  </listitem>
             	</varlistentry>

             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_24622"
                xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
                  <listitem>
                    <para><emphasis role="bold">For the ESN option:</emphasis> When the partition accesses an
                    expropriated page, the platform is not prevented by
                    <xref linkend="dbdoclet.50569344_55223" />, does not associate a physical
                    page with the logical page prior to returning control to the affected
                    virtual processor, and the restoration of the logical page has NOT
                    previously been reported to the OS with an expropriation notification,
                    the platform must, set the Expropriation Correlation Number field of the
                    VPA to a non-zero unique value for all outstanding recovering pages for
                    the affected partition.</para>
                  </listitem>
             	</varlistentry>

             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_24622"
                xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
                  <listitem>
                    <para><emphasis role="bold">For the ESN option:</emphasis> When the partition accesses an
                    expropriated page, the platform is not prevented by
                    <xref linkend="dbdoclet.50569344_55223" />, does not associate a physical
                    page with the logical page prior to returning control to the affected
                    virtual processor, and the restoration of the logical page has previously
                    been reported to the OS with an expropriation notification, the platform
                    must set the Expropriation Correlation Number field of the VPA to the
                    same value as was supplied with the previous expropriation notification
                    event associated with the outstanding recovering page for the affected
                    partition.</para>
                  </listitem>
             	</varlistentry>

             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_24622"
                xrefstyle="select: labelnumber nopage"/>-7.</emphasis></term>
                  <listitem>
                    <para><emphasis role="bold">For the ESN option:</emphasis> When the partition performs an
                    instruction fetch from an expropriated page, the platform must, unless
                    prevented by
                    <xref linkend="dbdoclet.50569344_55223" />, signal the affected virtual
                    processor with an Expropriation Interrupt by returning to the affected
                    virtual processor&#8217;s interrupt vector at location 0x0400 with the
                    processor&#8217;s MSR, SRR0 and SRR1 registers set as if the instruction
                    fetch had experienced a translation fault type of Instruction Storage
                    Interrupt except that SRR1 bit 46 (Trap) is set to a one.</para>
                  </listitem>
             	</varlistentry>

             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_24622"
                xrefstyle="select: labelnumber nopage"/>-8.</emphasis></term>
                  <listitem>
                    <para><emphasis role="bold">For the ESN option:</emphasis> When the partition performs a
                    load or store instruction that accesses an expropriated page, the
                    platform must, unless prevented by
                    <xref linkend="dbdoclet.50569344_55223" />, signal the affected virtual
                    processor with an Expropriation Interrupt by returning to the affected
                    virtual processor&#8217;s interrupt vector at location 0x0300 with the
                    processor&#8217;s MSR, DSISR, DAR, SRR0 and SRR1 registers set as if the
                    storage access had experienced a translation fault type of Data Storage
                    Interrupt except that SRR1 bit 46 (Trap) is set to a one.</para>
                  </listitem>
             	</varlistentry>
            </variablelist>

          </section>
        </section>

        <section xml:id="sec_esn_subvention">
          <title>ESN Subvention Event Notification</title>
          <para>ESN uses an event queue within the Subvention Notification
          Structure (SNS) to notify the OS of page subvention operations.
          Subvention events have a two byte SNS-EQ entry which has the value of the
          expropriation correlation number from the associated expropriation
          notification event</para>

          <variablelist>
           	<varlistentry>
              <term><emphasis role="bold">R1-<xref linkend="sec_esn_subvention"
              xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                <listitem>
                  <para><emphasis role="bold">For the ESN option:</emphasis> The platform must implement the
                  structures, syntax and semantics described in
                  <xref linkend="dbdoclet.50569344_11473" />,
                  <xref linkend="dbdoclet.50569344_76215" />, and
                  <xref linkend="dbdoclet.50569344_25427" />.</para>
                </listitem>
           	</varlistentry>
          </variablelist>


          <section xml:id="dbdoclet.50569344_11473">
            <title>SNS Memory Area</title>

            <variablelist>
             	<varlistentry>
                <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_11473"
                xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                  <listitem>
                    <para>For the ESN option: The platform
                    must support the 4K byte aligned SNS not spanning its page boundary
                    defined by
                    <xref linkend="dbdoclet.50569344_57741" />.</para>
                  </listitem>
             	</varlistentry>
            </variablelist>

            <table frame="all" pgwide="1" xml:id="dbdoclet.50569344_57741">
              <title>Subvention Notification Structure</title>
              <?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
              <tgroup cols="4">
                <colspec colname="c1" colwidth="25*" align="center" />
                <colspec colname="c2" colwidth="25*" align="center" />
                <colspec colname="c3" colwidth="25*" align="center" />
                <colspec colname="c4" colwidth="25*" align="center" />
                <thead valign="middle">
                  <row>
                    <entry>
                      <para>
                        <emphasis role="bold">Access</emphasis>
                      </para>
                    </entry>
                    <entry nameend="c3" namest="c2">
                      <para>
                        <emphasis role="bold">Offset</emphasis>
                      </para>
                    </entry>
                    <entry>
                      <para>
                        <emphasis role="bold">Usage</emphasis>
                      </para>
                    </entry>
                  </row>
                </thead>
                <tbody valign="middle">
                  <row>
                    <entry morerows="2">
                      <para>Written by OS Read by Hypervisor</para>
                    </entry>
                    <entry morerows="2">
                      <para>0x00</para>
                    </entry>
                    <entry>
                      <para>Bit</para>
                    </entry>
                    <entry>
                      <para>Notification Control</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>0</para>
                    </entry>
                    <entry>
                      <para>Notification Trigger</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>1-7</para>
                    </entry>
                    <entry>
                      <para>Reserved</para>
                    </entry>
                  </row>
                  <row>
                    <entry morerows="2">
                      <para>Written by Hypervisor Read by OS</para>
                    </entry>
                    <entry morerows="2">
                      <para>0x01</para>
                    </entry>
                    <entry>
                      <para>Bit</para>
                    </entry>
                    <entry>
                      <para>Event Queue State</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>0</para>
                    </entry>
                    <entry>
                      <para>0 = Operational</para>
                      <para>1 = Overflow</para>
                    </entry>
                  </row>
                  <row>
                    <entry>
                      <para>1-7</para>
                    </entry>
                    <entry>
                      <para>Reserved</para>
                    </entry>
                  </row>
                  <row>
                    <entry morerows="2">
                      <para>Set to non-zero by Hypervisor Read and cleared to zero by
                      OS</para>
                    </entry>
                    <entry nameend="c3" namest="c2">
                      <para>0x02-0x02</para>
                    </entry>
                    <entry>
                      <para>First SNS EQ Entry</para>
                    </entry>
                  </row>
                  <row>
                    <entry nameend="c4" namest="c2">
                      <para>.</para>
                      <para>.</para>
                      <para>.</para>
                    </entry>
                  </row>
                  <row>
                    <entry nameend="c3" namest="c2">
                      <para>(SNS Length -2) - SNS Length - 1)</para>
                    </entry>
                    <entry>
                      <para>Last SNS EQ Entry</para>
                    </entry>
                  </row>
                </tbody>
              </tgroup>
            </table>
          </section>

          <section xml:id="dbdoclet.50569344_76215">
            <title>SNS Registration (H_REG_SNS)</title>

            <simplesect>
              <title>Syntax:</title>

              <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Function: The function is not allowed from the calling */
                       /*   partition */
                       /* H_RESCINDED: The Address parameter refers to a rescinded */
                       /*   shared logical resource */
                       /* H_Parameter: The Address parameter is invalid (4K aligned */
                       /*   in the caller’s memory) */
                       /* H_P2: The Length parameter is odd or not within the */
                       /*   limits of: (256 <= Length <= distance to Page Boundary) */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_REG_SNS, /* Registers the SNS structure returning virtual */
                       /*   interrupt parameters */
        int64 Address, /* Logical address of the SNS structure */
        uint64 Length ); /* Length of the SNS structure */]]></programlisting>

            </simplesect>

            <simplesect>
              <title>Semantics:</title>

              <itemizedlist>
                <listitem>
                  <para>If the Address parameter is -1 then deregister any previously
                  registered SNS for the partition, disable ESN functions and return
                  H_Success. (Care is required on the part of the OS not to create any
                  Restoration Paradox Failures prior to registering a new SNS. See
                  <xref linkend="dbdoclet.50569344_37304" /> for details.)</para>
                </listitem>

                <listitem>
                  <para>If the Shared Logical Resource option is implemented and the
                  Address parameter represents a shared logical resource that has been
                  rescinded, then return H_RESCINDED.</para>
                </listitem>

                <listitem>
                  <para>If the Address parameter is not 4K aligned in the valid logical
                  address space of the caller, then return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If the Length parameter is less than 256 or the Address plus
                  Length spans the page boundary of the page containing the starting
                  logical address, then return H_P2.</para>
                </listitem>

                <listitem>
                  <para>Register the SNS structure for the calling partition by saving
                  the partition specific information:</para>

                  <itemizedlist>
                    <listitem>
                      <para>Record the SNS starting address</para>
                    </listitem>

                    <listitem>
                      <para>Record the SNS ending address</para>
                    </listitem>

                    <listitem>
                      <para>Record the next EQ entry to fill address (SNS starting address
                      +2)</para>
                    </listitem>

                    <listitem>
                      <para>Set the SNS interrupt toggle = SNS Notification Trigger</para>
                    </listitem>

                    <listitem>
                      <para>Set the SNS Event Queue State to &#8220;Operational&#8221;</para>
                    </listitem>
                  </itemizedlist>
                </listitem>
              </itemizedlist>
            </simplesect>

            <simplesect>
              <title>Return:</title>

              <itemizedlist>
                <listitem>
                  <para>R3: H_Success</para>
                </listitem>

                <listitem>
                  <para>R4: Value to be passed in the &#8220;unit address&#8221;
                  parameter of the H_VIO_SIGNAL hcall() to enable/disable the virtual
                  interrupt associated with the transition of the SNS from empty to
                  non-empty.</para>
                </listitem>

                <listitem>
                  <para>R5: Interrupt source number associated with the SNS empty to
                  non-empty virtual interrupt.</para>
                </listitem>
              </itemizedlist>

            </simplesect>
          </section>

          <section xml:id="dbdoclet.50569344_25427">
            <title>SNS Event Processing</title>
            <para>The following sequence is used by the platform to post an SNS
            event. The SNS-EQ used corresponds to the EEN event type. This sequence
            refers to fields described in
            <xref linkend="dbdoclet.50569344_57741" />.</para>

            <orderedlist>
              <listitem>
                <para>If the SNS EQ overflow state is set, exit.</para>
                <para>/* An EQ overflow drops all new events until software recovers the
                EQ*/</para>
              </listitem>

              <listitem>
                <para>Using atomic update protocol, store the event identifier into
                the location indicated by the SNS next EQ entry to fill pointer if the
                original contents of the location were zero; else set the associated EQ
                overflow state and exit.</para>
                <para>/* The value of zero is reserved for an unused entry -- an EQ
                overflow drops the new event */</para>
              </listitem>

              <listitem>
                <para>Increment the SNS next EQ entry to fill pointer by the size of
                the EQ entry (2) modulo the size of the EQ</para>
                <para>/* Adjust fill pointer */</para>
              </listitem>

              <listitem>
                <para>If the SNS interrupt toggle = SNS Notification Trigger then
                exit.</para>
                <para>/* Exit on no event queue transition */</para>
              </listitem>

              <listitem>
                <para>Invert the SNS interrupt toggle.</para>
                <para>/* Remember event queue transition */</para>
              </listitem>

              <listitem>
                <para>If the SNS interrupt is enabled, signal a virtual interrupt to
                the associated partition.</para>
                <para>/* Signal transition when enabled */</para>
              </listitem>
            </orderedlist>
          </section>

          <section xml:id="sec_esn_int">
            <title>ESN Interrupts</title>
            <para>The ESN option may generate several interrupts to the partition OS.
            Defined in this section are those in addition to the Expropriation
            Notification interrupts defined above.</para>

            <section>
              <title>Subvention Notification Queue Transition
              Interrupt</title>

              <variablelist>
               	<varlistentry>
                  <term><emphasis role="bold">R1-<xref linkend="sec_esn_int"
                  xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                    <listitem>
                      <para>For the ESN option: When the
                      platform has restored the association of a physical page with the logical
                      page that caused an Expropriation Notification interrupt with a non-zero
                      Expropriation Correlation Number, the platform must post the
                      corresponding Expropriation Correlation Number to the Subvention Event
                      Queue see
                      <xref linkend="dbdoclet.50569344_25427" />.</para>
                    </listitem>
               	</varlistentry>
              </variablelist>
            </section>

            <section xml:id="dbdoclet.50569344_37304">
              <title>Restoration Paradox Failure</title>
              <para>Restoration Paradox Failures result in an unrecoverable memory
              failure machine check.</para>

              <variablelist>
               	<varlistentry>
                  <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_37304"
                  xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
                    <listitem>
                      <para><emphasis role="bold">For the ESN option:</emphasis> When the platform finds that
                      Expropriation Notification has been disabled after it has discarded the
                      contents of an &#8220;Expendable&#8221; page, it must treat any access to
                      such a page as an unrecoverable error restoring the association of a
                      physical page with the expropriated logical page.</para>
                    </listitem>
               	</varlistentry>
              </variablelist>
            </section>
          </section>
        </section>
      </section>
    </section>

    <section xml:id="dbdoclet.50569344_12342">
      <title>Virtual Partition Memory Pool Statistics Function
      Set</title>
      <para>The hcall-vpm-pstat function set may be configured via the
      partition definition in none or any number of partitions as the VPM
      administrative policy dictates.</para>

      <section xml:id="dbdoclet.50569344_30144">
        <title>H_VPM_PSTAT</title>
        <para>This hcall() returns statistics on the physical shared memory pool.
        Since these statistics can be manipulated by the processing of a single
        partition, there is a risk of creating a covert channel through this
        call. To mitigate this risk, the call is contained in a separate function
        set that can be protected by authorization methods outside the scope of
        LoPAR.</para>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Function: The function is not allowed from the calling */
                       /*   partition */
                       /* H_Authority: The calling partition is not authorized to */
                       /*   make the call at this time */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_VPM_PSTAT /* Returns the memory pool performance statistics */
      );]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Parameters:</title>

          <itemizedlist>
            <listitem>
              <para>Input: None</para>
            </listitem>

            <listitem>
              <para>Output:</para>

              <itemizedlist>
                <listitem>
                  <para>R4: Total VM Pool Page Faults</para>
                </listitem>

                <listitem>
                  <para>R5: Total Page Fault Wait Time (Time Base Ticks)</para>
                </listitem>

                <listitem>
                  <para>R7: Total Pool Physical Memory</para>
                </listitem>

                <listitem>
                  <para>R8: Total Pool Physical Memory that is I/O mapped</para>
                </listitem>

                <listitem>
                  <para>R9: Total Logical Real Memory that is Virtualized by the VM
                  Pool</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>Verify that calling partition has the authority to make the call
              else return H_Authority.</para>
            </listitem>

            <listitem>
              <para>Report the statistics for the memory pool used to instantiate the
              virtual real memory of the calling partition.</para>

              <itemizedlist>
                <listitem>
                  <para>Place in R4 the summation of the virtual partition memory page
                  faults against the memory pool since the initialization of the
                  pool.</para>
                </listitem>

                <listitem>
                  <para>Place in R5 the summation of timebase ticks spent waiting for the
                  page faults indicated in R4.</para>
                </listitem>

                <listitem>
                  <para>Place in R6 the total amount of physical memory in the memory
                  pool.</para>
                </listitem>

                <listitem>
                  <para>Place in R7 the summation of the entitlement of all active
                  partitions served by the memory pool.</para>
                </listitem>

                <listitem>
                  <para>Place in R8 the summation of the I/O mapped memory of all active
                  partition served by the memory pool.</para>
                </listitem>

                <listitem>
                  <para>Place in R9 the summation of the logical real memory of all
                  active partitions served by the memory pool.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Return H_Success.</para>
            </listitem>
          </itemizedlist>
        </simplesect>
      </section>
    </section>
  </section>

  <section>
    <title>Logical Partition Control Modes</title>
    <para>Selected logical partition control modes may be modified by the
    client program.</para>

    <section>
      <title>Secondary Page Table Entry Group (PTEG) Search</title>
      <para>The page table search algorithm, described by the
      <xref linkend="dbdoclet.50569387_99718" />, consists of searching for a
      Page Table Entry (PTE) in up to two PTEGs. The first PTEG searched is the
      &#8220;primary PTEG&#8221;. If a PTE match does not occur in the primary
      PTEG, the hardware may search the &#8220;secondary PTEG&#8221;. If a PTE
      match is not found in the searched PTEGs, the hardware signals a
      translation exception.</para>
      <para>Code is not required to place any PTEs in secondary PTEGs.
      Therefore, if a PTE match does not occur in a primary PTEG there is no
      need for the hardware to search a secondary PTEG to determine that a
      search has failed. The &#8220;Secondary Page Table Entry Group&#8221; bit
      of
      <emphasis role="bold"><literal>&#8220;ibm,client-architecture-support&#8221;</literal></emphasis> allows
      code to indicate that there is no need to search secondary PTEGs to
      determine that a PTE search has failed.</para>
    </section>

    <section xml:id="sec_memory_table_translation_option">
      <title>Memory Table Translation Option Exploitation</title>

      <para>Starting with platforms build upon POWER processors supporting ISA level 3.0,
      the platform supports the In-Memory Table Translation option. This option allows
      the memory management unit to perform effective to physical address translation
      based off of a single tree of in-memory translation tables, rooted by a single
      physical memory address pointer. The option also supports two level radix tree
      page tables as well as traditional POWER hash page tables. As initially configured,
      partitions that use hash page tables run with legacy Segment Lookaside Buffers
      (LPCR [UPRT] = FALSE). To fully exploit the In-Memory Table Translation option,
      the hash page table client program registers a process table from its own memory
      which sets (LPCR [UPRT] = TRUE). On the other hand, radix page table client programs
      need to register a process table before they turn on address translation.</para>

      <para>Each guest partition in the system, may register, within the tree of in-memory
      translation tables, its own table (process table) which controls translation of its
      process effective addresses to guest virtual / real. The process table is then used
      by nest memory management unit for nest accelerator and CAPI attached device accesses, a
      nd optionally for processor memory management unit translations. Additionally the
      platform might support the client program to directly invalidate cached process
      table translation data (when the client program modifies the in-memory table).
      If the platform does not support the client program directly issuing process
      table cache invalidate instructions, then the client program must use the set
      of in-memory table cache invalidate hcall()s in sections
      <xref linkend="sec_clean_slb" /> and <xref linkend="sec_invalidate_pid" />.</para>

      <para><emphasis role="bold">Note:</emphasis>
      The CAS option vector processing associated with the In-Memory
      Table Translation option (vector 5 byte 23) carries a special semantic.</para>

      <section xml:id="sec_clean_slb">
        <title>H_CLEAN_SLB</title>

        <para>The Segment Lookaside Buffers (SLB) are a software managed
        coherency cache of the per process segment table. The client may
        directly issue instructions to clear the SLB on the issuing processor;
        however, clearing entries on other processors or the nest memory
        management unit requires hypervisor assistance. The H_CLEAN_SLB hcall()
        provides the client program with the means for clearing SLB
        contents that might be stale. The platform provides through the flags parameter
        options as to the scope of the entries that are cleaned, these include:</para>

        <itemizedlist>
          <listitem>
            <para>Clean the nest MMU SLBs of all entries associated with a
            specified caller process (esid parameter is set to zero).</para>
          </listitem>

          <listitem>
            <para>Clean all platform SLBs of a specific ESID for a specified caller
            process (flags parameter C and B fields specify SLB Class and Size respectively).</para>
          </listitem>
        </itemizedlist>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_LongBusyOrder1mSec – repeat the call with the same */
                       /*   parameters until it returns H_Success */
                       /* H_Parameter: Invalid flags parameter setting */
                       /* H_P3: The rb parameter is invalid */
                       /* H_Hardware: A hardware event prevented operation */
hcall ( const uint64 H_CLEAN_SLB, /* Globally invalidate the specified SLB entries */
        uint64 flags,  /* Option bit vector: */
                       /*   Bit 47: C If flags[62:63] = 10 then C (Segment Class) */
                       /*               else 0b0 */
                       /*   Bit 55: B If flags[62:63] = 10 then Segment Size */
                       /*               (0=256 M 1 = 1T) else 0b0 */
                       /*   Bits 62-63: 00 Reserved (H_Parameter) */
                       /*               01 PID from Nest */
                       /*               10 Global ESID/PID */
                       /*               11 Reserved (H_Parameter) */
                       /*   All others Reserved (=0b0 else H_Parameter)*/
        uint32 pid,    /* Process Identifier per the contents of the pid SPR */
        uint64 esid);  /* If flags[62:63] = 10 then */
                       /* ESID/C/B fields per the POWER ISA slbieg */
                       /* instruction rb specification else zero. */]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>If a reserved flags bit == TRUE return H_Parameter</para>
            </listitem>

            <listitem>
              <para>If flags[62] == flags[63] return H_Parameter</para>
            </listitem>

            <listitem>
              <para>If flags[63] and esid &lt;&gt; 0 return H_P3</para>
            </listitem>

            <listitem>
              <para>Validate that the calling partition is not mounting a denial of
              service attack else return H_LongBusyOrder1mSec.</para>
            </listitem>

            <listitem>
              <para>Perform the following sequence:</para>
              <itemizedlist spacing="compact" mark="none">
                <listitem>
                  <para>ptesync</para>
                </listitem>
                <listitem>
                  <para>If flags[62] then slbieg with RS = pid parameter ||
                  caller’s LPID, RB= esid || C || 0b0 || B || 0b0 || 0x000000</para>
                </listitem>
                <listitem>
                  <para>If flags[63] then slbiag with RS = pid parameter || caller’s LPID</para>
                </listitem>
                <listitem>
                  <para>eieio</para>
                </listitem>
                <listitem>
                  <para>slbsync</para>
                </listitem>
                <listitem>
                  <para>ptesync</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Return H_SUCCESS.</para>
            </listitem>
          </itemizedlist>
        </simplesect>
      </section>

      <section xml:id="sec_invalidate_pid">
        <title>H_INVALIDATE_PID</title>

        <para>The H_INVALIDATE_PID hcall() invalidates any system translate lookaside
        buffer entries from the caller’s specified (pid parameter) process table entry.</para>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_LongBusyOrder1mSec – repeat the call with the same */
                       /*   parameters until it returns H_Success */
                       /* H_Parameter: Invalid flags parameter setting */
                       /* H_Hardware: A hardware event prevented operation */
hcall ( const uint64 H_INVALIDATE_PID, /* Invalidate the specified process table */
                                       /*   entry */
        uint64 flags,  /* Option bit vector [63] = TRUE for Radix else FALSE */
                       /* Bit 62 = TRUE to invalidate entries for all caller pids*/
        uint64 pid);   /* Process Identifier per the contents of the pid SPR */]]></programlisting>
        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>If flags [0:61] &lt;&gt; 0 return H_Parameter</para>
            </listitem>

            <listitem>
              <para>Validate that the calling partition is not mounting a denial of
              service attack else return H_LongBusyOrder1mSec.</para>
            </listitem>

            <listitem>
              <para>RB = 0x400 /* Invalidation Selector (IS) = 01 (Invalidate matching PID.) */</para>
            </listitem>

            <listitem>
              <para>If flags[62] then RB = RB + RB /* Invalidation Selector
              (IS) = 10 (Invalidate matching LPID.) */</para>
            </listitem>

            <listitem>
              <para>Perform the following sequence:</para>
              <itemizedlist spacing="compact" mark="none">
                <listitem>
                  <para>ptesync</para>
                </listitem>
                <listitem>
                  <para>tlbie (RIC=2, PRS=1, R=flags[63]), RS=pid||caller’s_LPID, RB</para>
                </listitem>
                <listitem>
                  <para>eieio</para>
                </listitem>
                <listitem>
                  <para>tlbsync</para>
                </listitem>
                <listitem>
                  <para>ptesync</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Return H_SUCCESS.</para>
            </listitem>
          </itemizedlist>
        </simplesect>
      </section>

      <section xml:id="sec_register_process_table">
        <title>H_REGISTER_PROCESS_TABLE</title>

        <para>This hcall() is used by the client program to manage the its virtual
        address translation mode including registration of its process table. The
        calling program needs to be prepared for the change in address translation
        that is being requested, for instance, the calling program might choose to
        be running with relocation off and with all other processors either spinning
        with relocation off or in the stopped state.</para>

        <para>The caller might need to invoke the H_REGISTER_PROCESS_TABLE hcall()
        multiple times for it to return with a return code of H_Success. Upon
        receiving a return code of H_LongBusyOrder10mSec, the caller should attempt
        to invoke H_REGISTER_PROCESS_TABLE in 10mSec with the same parameter values
        used on the previous H_REGISTER_PROCESS_TABLE hcall(). Invoking
        H_REGISTER_PROCESS_TABLE with a different parameter values indicates
        that the caller wants to transition to the parameter values of the most
        recent H_REGISTER_PROCESS_TABLE call.</para>

        <para>The platform may implement a subset of the functions implied by the
        flags parameter definition below. This subset is reported in the value of
        byte 23 of the
        <emphasis role="bold"><literal>&#8220;ibm,architecture-vec-5&#8221;</literal></emphasis>
        property of the
        <emphasis role="bold"><literal>/chosen</literal></emphasis> node. A
        request for an unimplemented function results in an H_Parameter return code.</para>

        <simplesect>
          <title>Syntax:</title>

          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_LongBusyOrder1mSec – repeat the call with the same */
                       /*   parameters until it returns H_Success */
                       /* H_Parameter: Invalid flags parameter setting */
                       /* H_Hardware: A hardware event prevented operation */
hcall ( const uint64 H_REGISTER_PROCESS_TABLE, /* Set translation mode */
        uint64 flags,  /* Option bit vector */
                       /* 0-58: Reserved */
                       /* 59-60: Process Table Control */
                       /*        0X Maintain current process table registration */
                       /*        10 Deregister current process table */
                       /*        11 Register a new process table */
                       /* 61-62: Effective to Virtual Translation
                       /*        00: HPT via SLB */
                       /*        01: HPT via Process Table */
                       /*        1X: Radix: */
                       /* 63: Guest translation shoot down */
                       /*        0 Via hcall() */
                       /*        1 Via partition wide instructions */
                       /* If flags 59:60 <> 0b11 then the following parameters shall */
                       /*   be = 0 else */
        uint64 base,   /* Base address of the process table */
                       /* For flags 61 = 0 the VSID number of a one terabyte */
                       /* segment (right justified in the register) */
                       /* For flags 61 = 1 the 4K aligned guest real address */
        uint64 page_size, /* For flags 61 = 0 Size of the pages within the table */
                       /* encoded as per the L||LP device tree encoding */
                       /* else = 0 */
        uint64 table_size); /* Size of the process table in bytes */
                       /* Encoded as the integer */
                       /* (log2 (total table length in bytes)) – 12 */
                       /* (table_size <= 24) */]]></programlisting>

        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>Validate that no reserved flags parameter bits are TRUE and that the
              defined bits setting is supported else RETURN H_Parameter.</para>
            </listitem>

            <listitem>
              <para>If “flags” indicate change to process table (flags[59] is TRUE) then:</para>

              <itemizedlist>
                <listitem>
                  <para>If “flags” indicate deregistration (flags[58] is FALSE) then set
                  Partition_Table[calling-partition,word_2] to a platform dependent
                  benign value; else – Based upon the mode specified in “flags[61-62]”:</para>

                  <itemizedlist>
                    <listitem>
                      <para>Validate “base” parameter else RETURN to H_P2</para>
                    </listitem>

                    <listitem>
                      <para>Validate “page_size” parameter relative to platform
                      support else RETURN H_P3</para>
                    </listitem>

                    <listitem>
                      <para>Validate (0 => “table_size” parameter &lt;=24) else RETURN H_P4</para>
                    </listitem>

                    <listitem>
                      <para>Set Partition_Table[calling-partition,word_2] to the value
                      specified by the “flags[61-62]”, “base”, “page_size”, and “table_size” parameters.</para>
                    </listitem>

                    <listitem>
                      <para>Endif</para>
                    </listitem>
                  </itemizedlist>
                </listitem>

                <listitem>
                  <para>Endif</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>If “flags” indicate HPT/SLB mode (flags[61-62] is 0b00) then set
              LPCR[UPRT] to FALSE else set LPCR[UPRT] to TRUE</para>
            </listitem>
          </itemizedlist>
        </simplesect>

        <simplesect>
          <title>Input parameters:</title>

          <para>The “flags” parameter communicates the desired operation. The “base”
          parameter specifies the VSID number of a one terabyte segment (right
          justified in the register). The “page_size” parameter specifies the size
          of the pages within the table encoded as per the L||LP encoding used by the
          HPT hcalls that is presented in the page size info in the device tree. The
          “table_size” parameter specifies the total size of the process table encoded
          as the integer (log2 (total table length in bytes)) – 12 (table_size &lt;= 24).</para>
        </simplesect>
      </section>
    </section>
  </section>

  <section xml:id="dbdoclet.50569344_18587">
    <title>Partition Energy Management Option (PEM)</title>
    <para>This section describes the functional interfaces that are available
    to assist the partition Operating System optimize trade offs between energy
    consumption and performance requirements.</para>

    <section xml:id="dbdoclet.50569344_35233">
      <title>Long Term Processor Cede</title>
      <para>To enable the hypervisor to effectively reduce the power draw from
      unused partition processors, the concept of cede wakeup latency is
      introduced with the Partition Energy Management Option. A one byte cede
      latency specifier VPA field communicates the maximum latency class that
      the OS can tolerate on wakeup from H_CEDE. In general the longer the
      wakeup latency the greater the savings that can be made in power drawn by
      the processor during a cede operation. However, due to implementation
      restrictions, the platform might be unable to take full advantage of the
      latency that the OS can tolerate thus the cede latency specifier is
      considered a hint to the platform rather than a command. The platform may
      not exceed the latency state specified by the OS. Calling H_CEDE
      <xref linkend="dbdoclet.50569344_80840" />, with value of the cede
      latency specifier set to zero denotes classic H_CEDE behavior. Calling
      H_CEDE with the value of the cede latency specifier set greater than zero
      allows the processor timer facility to be disabled (so as not to cause
      gratuitous wake-ups - the use of H_PROD, or other external
      interrupt is required to wake the processor in this case). An External
      interrupt might not awake the ceded process at some of the higher (above
      the value 1) cede latency specifier settings. Platforms that implement
      cede latency specifier settings greater than the value of 1 implement the
      cede latency settings system parameter see
      <xref linkend="LoPAR.RTAS" />. The hypervisor is then free to take energy
      management actions with this hint in mind.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_35233"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the PEM option:</emphasis> The platform must honor the OS
              set cede latency specifier value per the definition of
              <xref linkend="dbdoclet.50569344_35233" />.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_35233"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the PEM option:</emphasis> The platform must map any OS set
              cede latency specifier value into one of its implemented values that does
              not exceed the latency class set by the OS.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_35233"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the PEM option:</emphasis> The platform must implement the
              cede latency specifier values of 0 and 1 per
              <xref linkend="dbdoclet.50569344_35233" />.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_35233"
          xrefstyle="select: labelnumber nopage"/>-4.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the PEM option:</emphasis> If the platform implements cede
              latency specifier values greater than 1 it must implement the cede
              latency settings values sequentially without holes.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_35233"
          xrefstyle="select: labelnumber nopage"/>-5.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the PEM option:</emphasis> If the platform implements cede
              latency specifier values greater than 1 each sequential cede latency
              settings value must represent a cede wake up latency not less than its
              predecessor, and no less restrictive than its predecessor.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_35233"
          xrefstyle="select: labelnumber nopage"/>-6.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the PEM option:</emphasis> If the platform implements cede
              latency specifier values greater than 1 it must implement the cede
              latency settings system parameter see
              <xref linkend="LoPAR.RTAS" />.</para>
            </listitem>
       	</varlistentry>
      </variablelist>
    </section>

    <section xml:id="dbdoclet.50569344_66904">
      <title>H_GET_EM_PARMS</title>
      <para>This hcall() returns the partition&#8217;s energy management
      parameters. The return parameters are packed into registers.</para>
      <para><emphasis role="bold">Programming Note:</emphasis> On platforms that implement the
      partition migration option, after partition migration:

        <orderedlist>
          <listitem>
            <para>The support for this hcall() might change, the caller should be
            prepared to receive an H_Function return code indicating the platform
            does not implement this hcall().</para>
          </listitem>

          <listitem>
            <para>Fields that were defined as &#8220;reserved&#8221; might contain
            data; calling code should be tested to ensure that it ignores fields
            defined as &#8220;reserved&#8221; at the time of its design, and that it
            operates properly when encountering &#8220;zeroed&#8221; defined fields
            that indicate that the field does not contain useful data.</para>
          </listitem>
        </orderedlist>
      </para>

      <para><emphasis role="bold">Implementation Note:</emphasis> To aid the testing of calling
      code, implementations would do well to include debug tools that seed
      reserved return fields with random data.</para>

      <simplesect>
        <title>Syntax:</title>

        <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const uint64 H_GET_EM_PARMS /* Returns in R4 – R9 the Platform Energy */
                       /*   Management Parameters. */
      );]]></programlisting>

      </simplesect>

      <simplesect>
        <title>Parameters: (on return)</title>
        <para />
        <informalfigure>
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/PAPR-22.gif" format="GIF"
              scalefit="1" />
            </imageobject>
            <imageobject role="fo">
              <imagedata contentdepth="100%" fileref="figures/PAPR-22.gif"
              format="GIF" scalefit="1" width="100%" />
            </imageobject>
          </mediaobject>
        </informalfigure>
        <para>&#160;</para>
        <informalfigure>
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/PAPR-23.gif" format="GIF"
              scalefit="1" />
            </imageobject>
            <imageobject role="fo">
              <imagedata contentdepth="100%" fileref="figures/PAPR-23.gif"
              format="GIF" scalefit="1" width="100%" />
            </imageobject>
          </mediaobject>
        </informalfigure>

        <itemizedlist>
          <listitem>
            <para>Status Codes (bit offset within 2 byte field): Bits 0:5 Reserved
            (zero)</para>
          </listitem>

          <listitem>
            <para>Bits 6:8 Energy Management major code:</para>

            <itemizedlist>
              <listitem>
                <para>0b000: Non-floor modes:</para>

                <itemizedlist>
                  <listitem>
                    <para>Bits 9:15 Energy Management minor code:</para>


                    <itemizedlist>
                      <listitem>
                        <para>0x00: The energy management policy for this aggregation level is
                        not specified.</para>
                      </listitem>

                      <listitem>
                        <para>0x01: Maximum Performance (Energy Management enabled -
                        performance may exceed nominal)</para>
                      </listitem>

                      <listitem>
                        <para>0x02: Nominal Performance (Energy Management Disabled)</para>
                      </listitem>

                      <listitem>
                        <para>0x03: Static Power Saving Mode</para>
                      </listitem>

                      <listitem>
                        <para>0x04: Deterministic Performance (Energy Management enabled
                        - consistent performance on a given workload independent of
                        environmental factors and component variances)</para>
                      </listitem>

                      <listitem>
                        <para>0x05 - 0x7F Reserved</para>
                      </listitem>
                    </itemizedlist>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>0b001: Dynamic Power Management:</para>

                <itemizedlist>
                  <listitem>
                    <para>Bits 9:15 Performance floor as a percentage of nominal (0% -
                    100%).</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>0b010:0b111 Reserved</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>

        <para><emphasis role="bold">Implementation Note:</emphasis> Status Code Fields are
        determined by means outside the scope of LoPAR. Platform designs may
        define a hierarchy of aggregations in which lower levels by default
        inherit the energy management policy of their parent.</para>

        <informalfigure>
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/PAPR-24.gif" format="GIF"
              scalefit="1" />
            </imageobject>
            <imageobject role="fo">
              <imagedata contentdepth="100%" fileref="figures/PAPR-24.gif"
              format="GIF" scalefit="1" width="100%" />
            </imageobject>
          </mediaobject>
        </informalfigure>

      <itemizedlist>
        <listitem>
            <para>Bytes 0:3 four byte Power Draw Status/Limit for the
            platform</para>

          <itemizedlist>
            <listitem>
                <para>Bit 0: Power Draw Limit is hard/soft: 0 = Soft, 1 = Hard</para>
            </listitem>

            <listitem>
                <para>Bits 1:7 Reserved.</para>
            </listitem>

            <listitem>
                <para>Bits 8:31 unsigned binary Power Draw Limit times 0.1 watts</para>
            </listitem>
          </itemizedlist>
        </listitem>
      </itemizedlist>

        <informalfigure>
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/PAPR-25.gif" format="GIF"
              scalefit="1" />
            </imageobject>
            <imageobject role="fo">
              <imagedata contentdepth="100%" fileref="figures/PAPR-25.gif"
              format="GIF" scalefit="1" width="100%" />
            </imageobject>
          </mediaobject>
        </informalfigure>
        <para>&#160;</para>
        <informalfigure>
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/PAPR-26.gif" format="GIF"
              scalefit="1" />
            </imageobject>
            <imageobject role="fo">
              <imagedata contentdepth="100%" fileref="figures/PAPR-26.gif"
              format="GIF" scalefit="1" width="100%" />
            </imageobject>
          </mediaobject>
        </informalfigure>

        <itemizedlist>
          <listitem>
            <para>The total processor energy consumed by the calling partition
            since boot in Joules times 2**-16. The value zero indicates that the
            platform does not support reporting this parameter.</para>
          </listitem>
        </itemizedlist>

        <informalfigure>
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/PAPR-27.gif" format="GIF"
              scalefit="1" />
            </imageobject>
            <imageobject role="fo">
              <imagedata contentdepth="100%" fileref="figures/PAPR-27.gif"
              format="GIF" scalefit="1" width="100%" />
            </imageobject>
          </mediaobject>
        </informalfigure>

        <itemizedlist>
          <listitem>
            <para>The total memory energy consumed by the calling partition since
            boot in Joules times 2**-16. The value zero indicates that the platform
            does not support reporting this parameter.</para>
          </listitem>
        </itemizedlist>

        <informalfigure>
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/PAPR-28.gif" format="GIF"
              scalefit="1" />
            </imageobject>
            <imageobject role="fo">
              <imagedata contentdepth="100%" fileref="figures/PAPR-28.gif"
              format="GIF" scalefit="1" width="100%" />
            </imageobject>
          </mediaobject>
        </informalfigure>

        <itemizedlist>
          <listitem>
            <para>The total I/O energy consumed by the calling partition since boot
            in Joules times 2**-16. The value zero indicates that the platform does
            not support reporting this parameter.</para>
          </listitem>
        </itemizedlist>
      </simplesect>

      <simplesect>
        <title>Semantics:</title>

        <itemizedlist>
          <listitem>
            <para>Place the partition&#8217;s performance parameters for the
            calling virtual processor&#8217;s partition into the respective
            registers:</para>

            <itemizedlist>
              <listitem>
                <para>R4: Energy Management Status Codes</para>
              </listitem>

              <listitem>
                <para>R5: Power Draw Limits (Platform and Group)</para>
              </listitem>

              <listitem>
                <para>R6: Power Draw Limits (Pool and Partition)</para>
              </listitem>

              <listitem>
                <para>R7: Partition Processor Energy Consumption</para>
              </listitem>

              <listitem>
                <para>R8: Partition Memory Energy Consumption</para>
              </listitem>

              <listitem>
                <para>R9: Partition I/O Energy Consumption</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>Return H_Success.</para>
          </listitem>
        </itemizedlist>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_66904"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PEM option:</emphasis> The platform must implement the
                H_GET_EMP hcall() following the syntax and semantics of
                <xref linkend="dbdoclet.50569344_66904" />.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
      </simplesect>
    </section>

    <section xml:id="dbdoclet.50569344_61969">
      <title>H_BEST_ENERGY</title>
      <para>This hcall() returns a hint to the caller as to the probable impact
      toward the goal of minimal platform energy consumption for a given level
      of computing capacity that would result from releasing or activating
      various computing resources. The returned value is a unitless priority,
      the lower the returned value; the more likely the goal will be achieved.
      The accuracy of the returned hint is implementation dependent, and is
      subject to change based upon actions of other partitions; thus the
      implementation can only provide a &#8220;best effort&#8221; to be
      &#8220;substantially correct&#8221;. Implementation dependent support for
      this hcall() and supported resource codes might change during partition
      suspension as in partition hibernation or migration; the client program
      should be coded to gracefully handle H_Function, H_UNSUPPORTED, and
      H_UNSUPPORTED_FLAG return codes.</para>
      <para>H_BEST_ENERGY may be used in one of two modes,
      &#8220;inquiry&#8221; or &#8220;ordered&#8221; specified by the setting
      of bit 54 of the eflags parameter. It is intended that ordered mode be
      used when the client program is largely indifferent to the specific
      resource instance to be released or activated. In ordered mode,
      H_BEST_ENERGY returns a list of resource instances in the order from the
      best toward worst to choose to release/activate to achieve minimal energy
      consumption starting with an initial resource instance in the ordered
      list (if the specified initial resource is the reserved value zero the
      returned list starts with the resource having the greatest probability of
      minimizing energy consumption). It is intended that inquiry mode be used
      when the client program wishes to compare the energy advantage of making
      a resource selection from among a set of candidate resource instances. In
      inquiry mode, H_BEST_ENERGY returns the unitless priority of
      releasing/acquiring each of the specified resource instances. It is
      expected that in the vast majority of cases, the client code will receive
      data on a sufficient number of resource instances in one H_BEST_ENERGY
      call to make its activate/release decision; however, in those rare cases
      where more information is needed, a series of H_BEST_ENERGY calls can be
      made to accumulate information on an arbitrary number of computing
      resource instances.</para>
      <para>Platforms may optionally support &#8220;buffered ordered&#8221;
      return data mode. If the platform supports &#8220;buffered ordered&#8221;
      return data mode, a &#8220;b&#8221; suffix appears at the end of the list
      that terminates the hcall-best-energy-1 function set entry. If the
      &#8220;buffered ordered&#8221; return data mode is supported the caller
      may specify the &#8220;B&#8221; bit in the eflags parameter and supply in
      P3 the logical address of a 4K byte aligned return buffer.</para>
      <para>The probable effects of a given resource instance selection might
      vary depending upon the intention of the client program to take other
      actions. These other actions include the ability to reactivate a released
      resource within a given time latency and number of resources the client
      program intends to activate/release as a group. The eflags parameter to
      H_BEST_ENERGY contains fields that convey hints to the platform of the
      client program intentions in these areas; implementations might take
      these hints into consideration as appropriate. The high order four (4)
      bytes of the eflags parameter contain the unsigned required reactivation
      latency in time base ticks (the reserved value of all zeros indicates an
      unspecified reactivation latency).</para>
      <para>Calling H_BEST_ENERGY with the eflags &#8220;refresh&#8221; flag
      (bit 54) equal to a one causes the hypervisor to compute the relative
      unitless priority value (1 being the best to activate/release with
      increasing numbers being poorer choices from the perspective of potential
      energy savings) for each instance of the specified resource that is owned
      by the calling partition. If the hypervisor can not distinguish a
      substantially different estimate for the various resource instances the
      call returns H_Not_Available. If the &#8220;refresh&#8221; flag is equal
      to a zero, the list as previously computed is used. Care should be
      exercised when using the non-refresh version to ensure that the state of
      the partition&#8217;s owned resource list has been initialized at some
      point and has not changed due to resource instance activation/release
      (including dynamic reconfiguration) activities by other partition threads
      else the results of the H_BEST_ENERGY call are unpredictable (ranging
      from inaccurate prediction values up to and including error code
      responses).</para>
      <para>The return values for H_BEST_ENERGY are passed in registers.
      Following standard convention, the return code is in R3. Register R4
      contains the response count. If the call is made in &#8220;inquiry&#8221;
      mode the response count equals the number of non-zero requested resource
      instance entries in the call. If the call is made in
      &#8220;ordered&#8221; mode, the response count contains the number of
      entries in the ordered list from the first entry returned until the worst
      choice entry. If the response count is &lt;= 8 (512 for ordered buffer
      mode) then the response count also indicates how many resource instances
      are being reported by this call, if the response count is &gt;8 (512 for
      ordered buffer mode) then this call reports eight (512 for ordered buffer
      mode) resource instances. Each response consists of three fields: bytes 0
      -- 2 are reserved, byte 3 contains the unitless priority for selecting
      the indicated resource instance, and bytes 4 -- 7 contain the resource
      instance identifier value corresponding to that passed in the
      <emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis> property.</para>
      <para>In order to represent more accurately the significance of certain
      priority values relative to others, the platform might leave holes in the
      ranges of reported priority values. As an example there may be a gap of
      several priority numbers between the value associated with a resource
      that can be powered down versus one that can only be placed in an
      intermediate energy mode, and yet again another gap to a resource that
      represents a necessary but not sufficient condition for reducing energy
      consumption.</para>

      <simplesect>
        <title>Syntax:</title>

        <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
                       /* H_Function: The hcall() is not supported */
                       /* H_Busy: The hcall() is not complete call again */
                       /* H_Not_Available: Differentiated energy estimates are not */
                       /*   available for this resource */
                       /* H_UNSUPPORTED_FLAG: Unsupported eflags parameter bits */
                       /*   (32 -- 39 & 48 -- 56) */
                       /* H_UNSUPPORTED: The specified resource code is not */
                       /*   supported by this implementation */
                       /* H_P2 -- H_P9: Invalid resource identifier value for the */
                       /*   calling partition */
hcall ( uconst64 H_BEST_ENERGY,
        int64 eflags,  /* Bits 0 -- 31 Required wakeup latency in time base ticks. */
                       /* Bits 32 -- 39 Reserved for expansion */
                       /* Bits 40 -- 47 1 Byte count of the number of resources */
                       /*   that the caller intends to activate / release */
                       /* Bits 48 -- 51 Reserved for expansion */
                       /* Bit 52 = 0b0 return in registers = 0b1 ordered buffer */
                       /*   mode */
                       /* Bit 53 = 0b0 use established list = 0b1 refresh list */
                       /* Bit 54 = 0b0 inquiry; = 0b1 ordered */
                       /* Bit 55 = 0b0 release; = 0b1 activate resource */
                       /* Bits 56 -- 63 resource code: */
                       /*   0 Reserved */
                       /*   1 Processor */
                       /*   2 Memory LMB */
        int64 P2,      /* The parameters P2 -- P9 are all the same format, */
                       /*   except in ordered buffer mode when P3 contains the */
                       /*   logical address of a 4K byte aligned caller partition */
                       /*   memory buffer. */
        int64 P3,      /* On input they contain either the reserved value of zero */
        int64 P4,      /*   or the resource instance identifier value as reported */
        int64 P5,      /*   in the “ibm,my-drc-index” property. */
        int64 P6,      /* In “inquiry” mode they list resource instances */
        int64 P7,      /*   queried; from the contents of P2 up to the first */
        int64 P8,      /*   parameter containing all zeros – from there on to P9 */
        int64 P9 );    /*   all the rest are ignored. */]]></programlisting>

      </simplesect>

      <simplesect>
        <title>Parameters: (on entry)</title>
        <para />
        <informalfigure>
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/PAPR-29.gif" format="GIF"
              scalefit="1" />
            </imageobject>
            <imageobject role="fo">
              <imagedata contentdepth="100%" fileref="figures/PAPR-29.gif"
              format="GIF" scalefit="1" width="100%" />
            </imageobject>
          </mediaobject>
        </informalfigure>
        <para>&#160;</para>
        <informalfigure>
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/PAPR-30.gif" format="GIF"
              scalefit="1" />
            </imageobject>
            <imageobject role="fo">
              <imagedata contentdepth="100%" fileref="figures/PAPR-30.gif"
              format="GIF" scalefit="1" width="100%" />
            </imageobject>
          </mediaobject>
        </informalfigure>
        <para>&#160;</para>
        <informalfigure>
          <mediaobject>
            <imageobject role="html">
              <imagedata fileref="figures/PAPR-31.gif" format="GIF"
              scalefit="1" />
            </imageobject>
            <imageobject role="fo">
              <imagedata contentdepth="100%" fileref="figures/PAPR-31.gif"
              format="GIF" scalefit="1" width="100%" />
            </imageobject>
          </mediaobject>
        </informalfigure>
      </simplesect>

      <simplesect>
        <title>(on return)</title>
        <itemizedlist>
          <listitem>
            <para>R3: Return code</para>
          </listitem>
          <listitem>
            <para>R4: Response Count Value &lt;8 indicate the number of returned
            values in registers starting with R5. The contents of registers after the
            last returned value as indicated by the Response Count Value are
            undefined.</para>
          </listitem>
          <listitem>
            <para>R5 -- R12 Bytes 0-2 Reserved</para>
          </listitem>
          <listitem>
            <para>Byte 3: 1 - 255 -- unitless priority value relative to
            lowest total energy consumption for selecting the corresponding resource
            ID.</para>
          </listitem>
          <listitem>
            <para>Bytes 4-7 Resource instance ID to be used as input to dynamic
            reconfiguration RTAS calls as would the value presented in the
            <emphasis role="bold"><literal>&#8220;ibm,my-drc-index&#8221;</literal></emphasis> property.</para>
          </listitem>
        </itemizedlist>
      </simplesect>

      <simplesect>
        <title>Semantics:</title>

        <itemizedlist>
          <listitem>
            <para>If the resource code in the eflags parameter is not supported
            return H_UNSUPPORTED</para>
          </listitem>

          <listitem>
            <para>If other binary eflags values are not valid then return
            H_UNSUPPORTED_FLAG with the specific value being (-256 - the bit
            position of the highest order unsupported bit that is a one);</para>
          </listitem>

          <listitem>
            <para>If the eflags parameter &#8220;refresh&#8221; bit is zero and the
            list has not been refreshed since the last return of H_Not_Available then
            return H_Not_Available.</para>
          </listitem>

          <listitem>
            <para>If the eflags parameter &#8220;refresh&#8221; bit is a one
            then:</para>

            <itemizedlist>
              <listitem>
                <para>If energy estimates for the partition owned resources are
                substantially indistinguishable then return H_Not_Available.</para>
              </listitem>

              <listitem>
                <para>Assign a priority value to each resource of the type specified in
                the resource code owned by the calling partition relative to the probable
                effect that selecting the specified resource to activate/release (per
                eflags code) within the specified latency requirements would have on
                achieving minimal platform energy consumption. (1 being the best
                increasing values being worse - implementations may choose to use
                an implementation dependent subset of the available values)</para>
              </listitem>

              <listitem>
                <para>Order the specified resources owned by the calling partition
                starting with those having a priority value of 1; setting the resource
                pointer to reference that starting resource.</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>If the eflags parameter bit 54 is a one (&#8220;ordered&#8221;)
            then</para>

            <itemizedlist>
              <listitem>
                <para>If P2 == 0 then set pointer to best resource in ordered
                list</para>
              </listitem>

              <listitem>
                <para>Else</para>

                <itemizedlist>
                  <listitem>
                    <para>If P2 &lt;&gt; the drc-index of one of the resources in the
                    ordered list then return H_P2</para>
                  </listitem>

                  <listitem>
                    <para>Else set pointer to the resource corresponding to P2</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Set R4 to the number of resources in the ordered list from the
                pointer to the end</para>
              </listitem>

              <listitem>
                <para>If eflags &#8220;B&#8221; bit == 0b0 then /* this assumes that
                the ordered buffer option is supported */:</para>

                <itemizedlist>
                  <listitem>
                    <para>If R4 &gt; 8 set count to 8 else set count to R4</para>
                  </listitem>

                  <listitem>
                    <para>Load &#8220;count&#8221; registers starting with R5 with the
                    priority value and resource IDs of the &#8220;count&#8221; resource
                    instances from the ordered list starting with the resource instance
                    referenced by &#8220;pointer&#8221;.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Else</para>

                <itemizedlist>
                  <listitem>
                    <para>If P3 does not contain the 4K aligned logical address of a
                    calling partition memory page then return H_P3</para>
                  </listitem>

                  <listitem>
                    <para>If R4 &gt; 512 set count to 512 else set count to R4</para>
                  </listitem>

                  <listitem>
                    <para>Load &#8220;count&#8221; 8 byte memory fields starting with
                    logical address in R3 with the priority value and resource IDs of the
                    &#8220;count&#8221; resource instances from the ordered list starting
                    with the resource instance referenced by &#8220;pointer&#8221;.</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Return H_SUCCESS</para>
              </listitem>
            </itemizedlist>
          </listitem>

          <listitem>
            <para>Else /* &#8220;inquiry&#8221; mode */</para>

            <itemizedlist>
              <listitem>
                <para>Set R4 to zero</para>
              </listitem>

              <listitem>
                <para>For each input parameter P2 -- P9 or until the input parameter is
                zero</para>

                <itemizedlist>
                  <listitem>
                    <para>If the input parameter Px &lt;&gt; the drc-index of one of the
                    resources in the ordered list then return H_Px</para>
                  </listitem>

                  <listitem>
                    <para>Fill in byte 3 of the register containing Px with the priority
                    value of the resource instance corresponding to the drc-index (bytes 4 --
                    7) of the register.</para>
                  </listitem>

                  <listitem>
                    <para>Increment R4</para>
                  </listitem>
                </itemizedlist>
              </listitem>

              <listitem>
                <para>Return H_SUCCESS</para>
              </listitem>
            </itemizedlist>
          </listitem>
        </itemizedlist>

        <variablelist>
         	<varlistentry>
            <term><emphasis role="bold">R1-<xref linkend="dbdoclet.50569344_61969"
            xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
              <listitem>
                <para><emphasis role="bold">For the PEM option:</emphasis> The platform must implement the
                H_BEST_ENERGY hcall() following the syntax and semantics of
                <xref linkend="dbdoclet.50569344_61969" />.</para>
              </listitem>
         	</varlistentry>
        </variablelist>
      </simplesect>
    </section>
  </section>

  <section xml:id="dbdoclet.50569344_93738">
    <title>Platform Facilities</title>
    <para>This section documents the hypervisor interfaces to optional platform
    facilities such as special purpose coprocessors.</para>

    <section xml:id="dbdoclet.50569344_74640">
      <title>H_RANDOM</title>
      <para>If the platform supports a random number generator platform
      facility the
      <emphasis role="bold"><literal>&#8220;ibm,hypertasfunctions&#8221;</literal></emphasis> property of the
      <emphasis role="bold"><literal>/rtas</literal></emphasis> node contains the function set specification
      &#8220;hcall-random&#8221; and the following hcall() is supported.</para>

      <simplesect>
        <title>Syntax:</title>
        <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Hardware The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const H_RANDOM ); /* Returns a random number in R4 */]]></programlisting>
      </simplesect>
    </section>

    <section>
      <title>Co-Processor Facilities</title>
      <para>If the platform supports a co-processor platform facility the
      <emphasis role="bold"><literal>&#8220;ibm,hypertas-functions&#8221;</literal></emphasis> property of the
      <emphasis role="bold"><literal>/rtas</literal></emphasis> node contains
      the function set specification &#8220;hcall-cop&#8221; and the following
      hcall()s are supported.</para>
      <para>For asynchronous coprocessor operations the caller may either
      specify an interrupt source number to signal at completion or the caller
      may poll the completion code in the CSB. The hypervisor and caller need
      to take into account the processor storage models with explicit memory
      synchronization to ensure that the rest of the return data from the
      operation is visible prior to setting the CSB completion code, and that
      any operation data that might have been fetched prior to the setting of
      the CSB completion code is discarded.</para>
      <para><emphasis role="bold">Note:</emphasis> The H_MIGRATE_DMA hcall() does not handle data pages subject
      to co-processor access, it is the caller&#8217;s responsibility to make
      sure that outstanding co-processor operations do not target pages that
      are being migrated by H_MIGRATE_DMA.</para>

      <section xml:id="dbdoclet.50569344_29950">
        <title>H_COP_OP</title>
        <para>The architectural intent of this hcall() is to initiate a
        co-processor operation. Co-processor operations may complete with either
        synchronous or asynchronous notification. In synchronous notification,
        all platform resources associated with the operation are allocated and
        released between the call to H_COP_OP and the subsequent return. In
        asynchronous notification, operation associated platform resources may
        remain allocated after the return from H_COP_OP, but are subsequently
        recovered prior to setting the completion code in the CSB. For the
        partition migration option no asynchronous notification operation may be
        outstanding at the time the partition is suspended.</para>

        <simplesect>
          <title>Syntax:</title>
          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_RH_PARM: Invalid resource id handle for the caller */
                       /* H_UNSUPPORTED_FLAG: Reserved flags field bit is non-zero */
                       /* H_ST_PARM: Invalid operation specification.*/
                       /* H_OP_MODE: Function code invalid in synchronous */
                       /*   notification */
                       /* H_TOO_BIG: The specified Input stream is too long */
                       /*   or can not be completed synchronously */
                       /* H_OVERLAP: There exists an unsupported overlap among */
                       /*   passed buffer areas */
                       /* H_NOT_ENOUGH_RESOURCES: For the CMO option and */
                       /*   asynchronousoperations the memory entitlement */
                       /*   is exhausted */
                       /* H_RESCINDED: a data/status area references a */
                       /*   rescinded shared logical resource */
                       /* H_P2: Invalid in parameter */
                       /* H_P3: Invalid inlen parameter */
                       /* H_P4: Invalid out parameter */
                       /* H_P5: Invalid outlen parameter */
                       /* H_P6 Invalid csbcpb parameter */
                       /* H_SG_LIST: Invalid Scatter/Gather List element */
                       /* H_Resource: Insufficient hypervisor resources to perform */
                       /*   function */
                       /* H_Busy: The hardware is busy user may call back later */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const H_COP_OP,
        uint64 flags,  /* sub functions and modifiers: */
                       /* Bit Number(s) */
                       /*   0 - 38 = 0b0s Reserved for function expansion */
                       /*   39 = 1 on Asymmetric Encryption operations indicating */
                       /*        that the High order 16 bits of the “in” parameter */
                       /*        contain the “Rc” field specifying the encoded */
                       /*        operand length while the remainder of the “in” */
                       /*        and “inlen” parameter bits are reserved and should */
                       /*        be 0b0 */
                       /*   40-41 Notification of operation */
                       /*        00 Synchronous: Hypervisor waits for completion */
                       /*        01 Reserved */
                       /*        10 Asynchronous: Hypervisor returns after start */
                       /*        11 Async Notify: Hypervisor starts with interrupt */
                       /*   42-55 For Async Notify = index of the interrupt */
                       /*        descriptor to be used to signal completion */
                       /*        else =0x0000 */
                       /*   56-63 FC field */
        uint32 rid,    /* Resource identifier as from the “ibm,resource-id” property*/
        int64 in,      /* Input data block logical real address */
        int64 inlen,   /* If non negative the length of the input data block, */
                       /* If negative the length of the input data descriptor list */
                       /*   in bytes */
        int64 out,     /* Output data block logical real address */
        int64 outlen,  /* If non negative the length of the output data block, */
                       /* If negative the length of the output data descriptor list */
                       /*   in bytes */
        uint64 csbcpb  /* The logical real address of the 4k naturally aligned */
                       /*   storage block containing the CSB & optional FC field */
                       /*   specific CPB */
      );]]></programlisting>
        </simplesect>

        <simplesect>
          <title>Syntax:</title>

          <itemizedlist>
            <listitem>
              <para>Flags:</para>

              <itemizedlist>
                <listitem>
                  <para>Reserved (bits 0-- 38)</para>
                </listitem>

                <listitem>
                  <para>&#8220;Rc&#8221; (bit 39) On Asymmetric Encryption operations the
                  &#8220;Rc&#8221; bit indicates that the high order 16 bits of the
                  &#8220;in&#8221; parameter contain the &#8220;Rc&#8221; field specifying
                  the encoded operand length while the remainder of the &#8220;in&#8221;
                  and &#8220;inlen&#8221; parameter bits are reserved and should be
                  0b0</para>
                </listitem>

                <listitem>
                  <para>Notification of Operation (bits 40-- 41):</para>

                  <itemizedlist>
                    <listitem>
                      <para>00 Synchronous: In this mode the hypervisor synchronously waits
                      for the coprocessor operation to complete. To preserve Interrupt service
                      times of the caller and quality of service for other callers, the length
                      of synchronous operations is restricted (see inlen parameter).</para>
                    </listitem>

                    <listitem>
                      <para>01 Reserved</para>
                    </listitem>

                    <listitem>
                      <para>10 Asynchronous: In this mode the hypervisor starts the
                      coprocessor operation and returns to the caller. The caller may poll for
                      operation completion in the CSB.</para>
                    </listitem>

                    <listitem>
                      <para>11 Async Notify: In this mode the hypervisor starts the
                      coprocessor operation as with the Asynchronous notification above however
                      the operation is flagged to generate a completion interrupt to the
                      interrupt source number given in the
                      <emphasis role="bold"><literal>&#8220;ibm,copint&#8221;</literal></emphasis> property. When the interrupt
                      is signaled the caller may check the operation completion status in the
                      CSB.</para>
                    </listitem>
                  </itemizedlist>
                </listitem>

                <listitem>
                  <para>Interrupt descriptor index for Async Notify (bits 42-- 55)</para>
                </listitem>

                <listitem>
                  <para>FC field: The FC field is the co-processor name specific function
                  code (bits 56-- 63)</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Resource identifier (bits 32-- 63(as from the
              <emphasis role="bold"><literal>&#8220;ibm,resource-id&#8221;</literal></emphasis> property))</para>

              <itemizedlist>
                <listitem>
                  <para>in/inlen and out/outlen parameters:</para>
                </listitem>

                <listitem>
                  <para>If the *len parameter is non-negative; the respective in/out
                  parameter is the logical real address of the start of the respective
                  buffer. The starting address plus the associated length may not extend
                  beyond the bounds of a 4K page owned by the calling partition. For
                  synchronous notification operations, the parameter values may not exceed
                  an implementation specified maximum; in some cases these are communicated
                  by the values of the
                  <emphasis role="bold"><literal>&#8220;ibm,maxsync-cop&#8221;</literal></emphasis> property of the device
                  tree node that represents the co-processor to the partition.</para>
                </listitem>

                <listitem>
                  <para>If the *len parameter is negative; the respective in/out
                  parameter is the logical real address of the start of a scatter/gather
                  list that describes the buffer with a length equal to the absolute value
                  of the *len parameter. The starting address of the scatter/gather list
                  plus the associated length may not extend beyond the bounds of a 4K page
                  owned by the calling partition. Further the scatter/gather list shall be
                  a multiple of 16 bytes in length not to exceed the value of the
                  <emphasis role="bold"><literal>&#8220;ibm,max-sg-len&#8221;</literal></emphasis> property of the device tree
                  node that represents the coprocessor to the partition. Each 16 byte entry
                  in the scatter gather list consists of an 8 byte logical real address of
                  the start of the respective buffer segment. The starting address plus the
                  associated length may not extend beyond the bounds of a 4K page owned by
                  the calling partition. For synchronous notification operations, the
                  summation of the buffer segment lengths for the in scatter/gather list
                  may be limited; in some cases these limitations are communicated by the
                  value of the
                  <emphasis role="bold"><literal>&#8220;ibm,max-sync-cop&#8221;</literal></emphasis> property of the device
                  tree node that represents the coprocessor to the partition.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>csbcpb: logical real address of the 4K naturally aligned memory
              block used to house the co-processor status block and FC field dependent
              co-processor parameter block.</para>
            </listitem>

            <listitem>
              <para>Output parameters on return</para>

              <itemizedlist>
                <listitem>
                  <para>R3 contains the standard hcall() return code: if the return code
                  is H_Success then the contents of the 4K naturally aligned page specified
                  by the csbspb parameter are filled from the hypervisor csb and cpb with
                  addresses converted from real to calling partition logical real</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>The hypervisor checks that the resource identifier parameter is
              valid for the calling partition else returns H_RH_PARM.</para>
            </listitem>

            <listitem>
              <para>The hypervisor checks that for the coprocessor type specified by
              the validated resource identifier parameter there are no non-zero
              reserved bits within the function expansion field of the flags parameter
              else returns H_UNSUPPORTED_FLAG for the highest order non-zero
              unsupported flag.</para>
            </listitem>

            <listitem>
              <para>If the operation notification is asynchronous, check that there
              are sufficient resources to initiate and track the operation else return
              H_Resource.</para>
            </listitem>

            <listitem>
              <para>The hypervisor checks that the flag parameter notification field
              is not a reserved value and FC field is valid for the specified
              coprocessor type else returns H_ST_PARM</para>
            </listitem>

            <listitem>
              <para>If the notification field is &#8220;synchronous&#8221; the
              hypervisor checks that the FC field is valid for synchronous operations
              else return H_OP_MODE.</para>
            </listitem>

            <listitem>
              <para>The hypervisor builds the CRB CCW field per the coprocessor type
              specified by the validated resource identifier parameter and by copying
              the coprocessor type defined number of FC field bits from the low order
              flags parameter FC field to the corresponding low order bits of CCW byte
              3.</para>
            </listitem>

            <listitem>
              <para>If the resource ID is an asymmetric encryption then (If the Flags
              Parameter &#8220;Rc&#8221; bit is on then check the High order 16 bits of
              the &#8220;in&#8221; parameter for a valid &#8220;Rc&#8221; encoding and
              transfer to the CRB starting at byte 16 else return H_P2) else Validate
              the inlen/in parameters and build the source DDE</para>

              <itemizedlist>
                <listitem>
                  <para>Verify that the &#8220;in&#8221; parameter represents a valid
                  logical real address within the caller&#8217;s partition else return
                  H_P2</para>
                </listitem>

                <listitem>
                  <para>If the &#8220;inlen&#8221; parameter is non-negative:</para>

                  <itemizedlist>
                    <listitem>
                      <para>Verify that the logical real address of (in + inlen) is a valid
                      logical real address within the same 4K page as the &#8220;in&#8221;
                      parameter else return H_P3.</para>
                    </listitem>

                    <listitem>
                      <para>If the operation notification is synchronous verify that the
                      combination of parameter values request a sufficiently short operation
                      for synchronous operation else return H_TOO_BIG.</para>
                    </listitem>
                  </itemizedlist>
                </listitem>

                <listitem>
                  <para>If the &#8220;inlen&#8221; parameter is negative:</para>

                  <itemizedlist>
                    <listitem>
                      <para>Verify that the absolute value of inlen meet all of the follow
                      else return H_P3:</para>

                      <itemizedlist>
                        <listitem>
                          <para>Is &lt;= the value of
                          <emphasis role="bold"><literal>&#8220;ibm,max-sg-len&#8221;</literal></emphasis></para>
                        </listitem>

                        <listitem>
                          <para>Is an even multiple of 16</para>
                        </listitem>

                        <listitem>
                          <para>That in + the absolute value of inlen represents a valid logical
                          real address within the same 4K caller partition page as the in
                          parameter.</para>
                        </listitem>
                      </itemizedlist>
                    </listitem>

                    <listitem>
                      <para>Verify that each 16 byte scatter gather list entry meets all of
                      the following else return H_SG_LIST:</para>

                      <itemizedlist>
                        <listitem>
                          <para>Verify that the first 8 bytes represents a valid logical real
                          address within the caller&#8217;s partition.</para>
                        </listitem>

                        <listitem>
                          <para>Verify that the logical real address represented by the sum of
                          the first 8 bytes and the second 8 bytes is a valid logical real address
                          within the same 4K byte page as the first 8 bytes.</para>
                        </listitem>
                      </itemizedlist>
                    </listitem>

                    <listitem>
                      <para>If the operation notification is synchronous verify that the sum
                      of all the scatter gather length fields (second 8 bytes of each 16 byte
                      entry) request a sufficiently short operation for synchronous operation
                      else return H_TOO_BIG.</para>
                    </listitem>
                  </itemizedlist>
                </listitem>

                <listitem>
                  <para>For the Shared Logical Resource Option if any of the memory
                  represented by the in/inlen parameters have been rescinded then return
                  H_RESCINDED.</para>
                </listitem>

                <listitem>
                  <para>Fill in the source DDE list from the converted the in/inlen
                  parameters.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Validate the outlen/out parameters and build the target
              DDE</para>

              <itemizedlist>
                <listitem>
                  <para>Verify that the &#8220;out&#8221; parameter represents a valid
                  logical real address within the caller&#8217;s partition else return
                  H_P4</para>
                </listitem>

                <listitem>
                  <para>If the &#8220;outlen&#8221; parameter is non-negative verify that
                  the logical real address of (out + outlen) is a valid logical real
                  address within the same 4K page as the &#8220;out&#8221; parameter
                  and for symmetric cryptography operations that outlen =&gt; inlen else
                  return H_P5.</para>
                </listitem>

                <listitem>
                  <para>If the &#8220;outlen&#8221; parameter is negative:</para>

                  <itemizedlist>
                    <listitem>
                      <para>Verify that the absolute value of outlen meet all of the follow
                      else return H_P5:</para>

                      <itemizedlist>
                        <listitem>
                          <para>Is &lt;= the value of
                          <emphasis role="bold"><literal>&#8220;ibm,max-sg-len&#8221;</literal></emphasis></para>
                        </listitem>

                        <listitem>
                          <para>Is an even multiple of 16</para>
                        </listitem>

                        <listitem>
                          <para>That out + the absolute value of outlen represents a valid
                          logical real address within the same 4K caller partition page as the out
                          parameter</para>
                        </listitem>
                      </itemizedlist>
                    </listitem>

                    <listitem>
                      <para>Verify that each 16 byte scatter gather list entry meets all of
                      the following else return H_SG_LIST:</para>

                      <itemizedlist>
                        <listitem>
                          <para>Verify that the first 8 bytes represents a valid logical real
                          address within the caller&#8217;s partition.</para>
                        </listitem>

                        <listitem>
                          <para>Verify that the logical real address represented by the sum of
                          the first 8 bytes and the second 8 bytes is a valid logical real address
                          within the same 4K page as the first 8 bytes.</para>
                        </listitem>

                        <listitem>
                          <para>Accumulate the sum of the second 8 bytes of each scatter gather list entry.</para>
                        </listitem>
                      </itemizedlist>
                    </listitem>

                    <listitem>
                      <para>Verify that for symmetric cryptography operations the accumulated sum
                      of the second 8 bytes of each scatter gather list entry =>the input data length
                      else return H_P5.</para>
                    </listitem>
                  </itemizedlist>
                </listitem>

                <listitem>
                  <para>For the Shared Logical Resource Option if any of the memory
                  represented by the out/outlen parameters have been rescinded then return
                  H_RESCINDED.</para>
                </listitem>

                <listitem>
                  <para>Fill in the destination DDE list from the converted the
                  out/outlen parameters.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>If the operation notification is asynchronous then verify that
              the input and output buffers do not overlap else return H_OVERLAP (makes
              the operations transparently restartable)</para>
            </listitem>

            <listitem>
              <para>Check that the csbcpb parameter is page aligned within the
              calling address space of the calling partition else return H_P6</para>
            </listitem>

            <listitem>
              <para>If the operation specifies a CPB and the specified CPB is invalid
              for the operation then return H_ST_PARM.</para>
            </listitem>

            <listitem>
              <para>Set the CRB CSB address field &amp; C bit to indicate a valid
              CCB</para>
            </listitem>

            <listitem>
              <para>If the operation notification is asynchronous notify,
              then:</para>

              <itemizedlist>
                <listitem>
                  <para>Check that the flags parameter interrupt index value is within
                  the defined range for the validated rid and is not currently in use for
                  another outstanding COP operation else return H_INTERRUPT.</para>
                </listitem>

                <listitem>
                  <para>Set the CRB CM field to command a completion interrupt,.</para>
                </listitem>

                <listitem>
                  <para>Set the job id field in the Co-processor Completion Block to
                  command the signaling via the interrupt source number contained the
                  interrupt specifier indicated by the interrupt index value.</para>
                </listitem>

                <listitem>
                  <para>For the CMO option, if the number of entitlement granules pinned
                  for this operation causes the partition memory entitlement to be
                  exhausted then return H_NOT_ENOUGH_RESOURCES; else pin and record the
                  entitlement granules used by this operation, and increment the partition
                  consumed memory entitlement for the number of entitlement granules pinned
                  for this operation.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Set the completion code field in the passed (via csbcpb
              parameter) CSB to invalid (it is subsequently set to valid at the end of
              the operation just after the rest of the contents of the 4k naturally
              aligned page specified by the csbcpb parameter are filled).</para>
            </listitem>

            <listitem>
              <para>Issue icswx</para>
            </listitem>

            <listitem>
              <para>If busy response to icswx implementation dependent (may be null)
              retry after backoff based upon some usage equality/priority mechanisms
              else return H_Busy.</para>
            </listitem>

            <listitem>
              <para>If the operation notification is asynchronous then Return
              H_Success</para>
            </listitem>

            <listitem>
              <para>Wait for completion posting in CSB (CSB valid bit. 1)</para>
            </listitem>

            <listitem>
              <para>The contents of the 4K naturally aligned page specified by the
              csbcpb parameter are filled from the hypervisor csb and cpb with
              addresses converted from real to calling partition logical real</para>
            </listitem>

            <listitem>
              <para>Return H_Success.</para>
            </listitem>
          </itemizedlist>

        </simplesect>
      </section>

      <section xml:id="dbdoclet.50569344_73950">
        <title>H_STOP_COP_OP</title>
        <para>The architectural intent of this hcall() is to terminate a
        previously initiated co-processor operation.</para>

        <simplesect>
          <title>Syntax:</title>
          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_RH_PARM: Invalid resource id handle for the caller */
                       /* H_Parameter: Reserved flags field bit is non-zero */
                       /* H_RESCINDED: a data/status area references a rescinded */
                       /*   shared logical resource */
                       /* H_P3: Invalid csbcpb parameter */
                       /* H_Busy: The hardware is busy user may call back later */
                       /* H_Hardware: The hcall() experienced a hardware fault */
                       /*   potentially preventing the function */
hcall ( const H_STOP_COP_OP,
        uint64 flags,  /* sub functions and modifiers: Bits 0-- 63 reserved */
        uint32 rid,    /* identifier as from the “ibm,resource-id” property */
        uint64 csbcpb  /* The logical real address of the 4k page aligned storage */
                       /*   block containing the CSB & optional FC field specific */
                       /*   CPB */
      );]]></programlisting>
        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>Check the rid parameter for validity for the caller else return
              H_RH_PARM</para>
            </listitem>
            <listitem>
              <para>If any reserved flags parameter bits are non zero then return
              H_Parameter.</para>
            </listitem>
            <listitem>
              <para>Check the csbcpb parameter for pointing within the caller&#8217;s
              partition and 4K aligned else return H_P3</para>
            </listitem>
            <listitem>
              <para>For the shared logical resource option if the csbcpb parameter
              references a rescinded shared logical resource then return
              H_RESCINDED</para>
            </listitem>
            <listitem>
              <para>If the csbcpb parameter is not associated with an outstanding
              coprocessor operation then return H_NOT_ACTIVE.</para>
            </listitem>
            <listitem>
              <para>Send a kill operation to the coprocessor handling the outstanding
              operation</para>
            </listitem>
            <listitem>
              <para>Wait for the outstanding kill operation to complete.</para>
            </listitem>
            <listitem>
              <para>For the CMO option, unpin any entitlement granules still pinned
              for this operation and decrement the consumed partition memory
              entitlement for the number of entitlement granules pinned for this
              operation.</para>
            </listitem>
            <listitem>
              <para>Return H_Success.</para>
            </listitem>
          </itemizedlist>
        </simplesect>
      </section>
    </section>

    <section xml:id="sec_mui_opt">
      <title>Memory Usage Instrumentation Option (MUI)</title>

      <para>The MUI Option enables the platform to generate statistics on
      page reference affinity, age, access rate, and
      reference history pattern. Client programs can
      query and act upon this information in order to guide
      decisions for improving memory utilization and placement in a system.</para>

      <para>The MUI Option consists of a number of distinct per page measures
      as described in <xref linkend="table_mui_measures" />.</para>

      <table xml:id="table_mui_measures">
        <title>Memory Usage Instrumentation Measures</title>
        <tgroup cols="3">
          <colspec colname="c1" colwidth="15*" />
          <colspec colname="c2" colwidth="15*" align="center" />
          <colspec colname="c3" colwidth="70*" />
          <thead valign="middle">
            <row>
              <entry align="center">
                <para>Name</para>
              </entry>

              <entry>
                <para>Abbreviation</para>
              </entry>

              <entry align="center">
                <para>Description</para>
              </entry>
            </row>
          </thead>
          <tbody valign="middle">
            <row>
              <entry>
                <para>Reference History Bit Array</para>
              </entry>

              <entry>
                <para>HBA</para>
              </entry>

              <entry>
                <para>Measures dormancy patterns – a list of bits each representing a time
                interval, if the bit is a one the page was reference during the
                corresponding interval.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Page Table Entry Update Time</para>
              </entry>

              <entry>
                <para>PUT</para>
              </entry>

              <entry>
                <para>The timestamp of the last HBA interval during which the
                corresponding page experienced a TLB miss during a reference.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Access Count Array</para>
              </entry>

              <entry>
                <para>ACA</para>
              </entry>

              <entry>
                <para>The count of the corresponding page access used to compute page
                access rate.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Page Age Counter</para>
              </entry>

              <entry>
                <para>PAC</para>
              </entry>

              <entry>
                <para>A saturating count representing the length of time since the page
                statistics were reset.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Page Age Granule</para>
              </entry>

              <entry>
                <para>PAG</para>
              </entry>

              <entry>
                <para>The update cycle period of the Page Age Counter in seconds.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Affinity Log Array</para>
              </entry>

              <entry>
                <para>ALA</para>
              </entry>

              <entry>
                <para>A sampled list of affinity domains that have accessed the page.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>Affinity Log Sample Period</para>
              </entry>

              <entry>
                <para>ALSP</para>
              </entry>

              <entry>
                <para>The period that each Affinity Log Array entry represents in seconds.</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <para>Client programs monitor and manage the MUI state through the extensions to the H_ENTER
      (see <xref linkend="dbdoclet.50569344_61580" />), H_RETURN_PAGEINFO, H_MEMSTAT_CTRL,
      H_RESET_MEMSTATS, and H_BULK_READ_HBA hcall()s. The data returned by the
      H_RETURN_PAGEINFO and H_BULK_READ_HBA hcall()s generally reflect actual values. However,
      should a logical page be faulted back into a partition when Active Memory Sharing (AMS) is in use, its
      MUI state is cleared/set to a fixed value. MUI state is also subject to loss during events that move physical
      memory such as: dynamic reconfiguration, partition mobility, and fail-over.</para>

      <para><xref linkend="dbdoclet.50569344_11209" /> bit for managing the MUI behavior of pages are detailed below in <xref linkend="table_mui_opt_flags_pft"/>.</para>

      <table xml:id="table_mui_opt_flags_pft">
        <title>MUI Option Flags in Page Frame Table Access flags Detailed Description</title>
        <tgroup cols="4">
          <colspec colname="c1" colwidth="10*" />
          <colspec colname="c2" colwidth="20*" />
          <colspec colname="c3" colwidth="10*" align="center" />
          <colspec colname="c3" colwidth="60*" />
          <thead valign="middle">
            <row>
              <entry align="center">
                <para>Bit(s)</para>
              </entry>
              <entry align="center">
                <para>Name</para>
              </entry>
              <entry>
                <para>Encoding</para>
              </entry>
              <entry align="center">
                <para>Description</para>
              </entry>
            </row>
          </thead>
          <tbody>
            <row>
              <entry morerows="3">
                <para>43:44</para>
              </entry>
              <entry morerows="3">
                <para>Reference History Bit Array (HBA)</para>
              </entry>
              <entry>
                <para>0b00</para>
              </entry>
              <entry>
                <para>Disable HBA updates</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>0b01</para>
              </entry>
              <entry>
                <para>Enable HBA updates, set PUT to previous time, but do
                not change current HBA content (as in adding an alias to
                a logical real page)</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>0b10</para>
              </entry>
              <entry>
                <para>Enable HBA updates, set PUT to previous time, and set
                the HBA to the configured Initial Setting.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>0b11</para>
              </entry>
              <entry>
                <para>Reserved – return H_UNSUPPORTED_FLAG</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>45</para>
              </entry>
              <entry>
                <para>Affinity-Clear</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>Resets Affinity Log Array when entering a PTE.</para>
              </entry>
            </row>
            <row>
              <entry>
                <para>46</para>
              </entry>
              <entry>
                <para>Page-Age-Clear</para>
              </entry>
              <entry>
                <para>&#160;</para>
              </entry>
              <entry>
                <para>Resets Page Age Counter when entering a PTE.</para>
              </entry>
            </row>
          </tbody>
        </tgroup>
      </table>

      <para>The parameters to Memory Usage Instrumentation hcall()s that specify a given logical page or page range
      take the form of an index into the partition’s logical real memory space as if it were a set of 4K pages, the
      logical page index being the logical real address of the starting byte of the 4K page, right shifted 12 bits.</para>

      <para>It is expected that the MUI function will evolve over time, as will the syntax of the MUI hcalls(). The
      following requirements ensure forward compatibility over this expected evolution.</para>

      <variablelist>
       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_mui_opt"
          xrefstyle="select: labelnumber nopage"/>-1.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the MUI option:</emphasis>
              the platform must for all MUI hcall()s fill all reserved return parameter
              registers with all zeros.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_mui_opt"
          xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the MUI option:</emphasis>
              to avoid future incompatibility, the caller of MUI hcall()s must ignore
              the contents of all reserved return parameter registers.</para>
            </listitem>
       	</varlistentry>

       	<varlistentry>
          <term><emphasis role="bold">R1-<xref linkend="sec_mui_opt"
          xrefstyle="select: labelnumber nopage"/>-3.</emphasis></term>
            <listitem>
              <para><emphasis role="bold">For the MUI option:</emphasis>
              to avoid future incompatibility, the caller of MUI hcall()s must fill all
              reserved input parameter fields with zeros.</para>
            </listitem>
       	</varlistentry>
      </variablelist>

      <section xml:id="sec_memstat_ctrl">
        <title>H_MEMSTAT_CTRL</title>

        <para>This hcall() configures Memory Usage Instrumentation, and returns the current configuration. Note
        supplying a value of all zeros returns the current configuration settings of the Memory Usage
        Instrumentation facility.</para>

        <simplesect>
          <title>Syntax:</title>
          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Not_Found if attempt to enable a feature not supported */
                       /* H_UNSUPPORTED_FLAG if the reserved flags are set */
hcall ( const uint64 H_MEMSTAT_CTRL, uint64 flags);]]></programlisting>
        </simplesect>

        <simplesect>
          <title>Parameters:</title>

          <itemizedlist>
            <listitem>
              <para>Input:</para>

              <itemizedlist>
                <listitem>
                  <para>R4: flags</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Output:</para>

              <itemizedlist>
                <listitem>
                  <para>R3: Return code</para>
                </listitem>

                <listitem>
                  <para>R4: Config</para>
                </listitem>

                <listitem>
                  <para>R5::R10: Reserved</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>

          <table>
            <title>Memory Usage Instrumentation Configuration encoding flags/config</title>
            <tgroup cols="33">
              <colspec colname="c1" colwidth="3*" align="center"/>
              <colspec colname="c2" colwidth="3*" align="center"/>
              <colspec colname="c3" colwidth="3*" align="center"/>
              <colspec colname="c4" colwidth="3*" align="center"/>
              <colspec colname="c5" colwidth="3*" align="center"/>
              <colspec colname="c6" colwidth="3*" align="center"/>
              <colspec colname="c7" colwidth="3*" align="center"/>
              <colspec colname="c8" colwidth="3*" align="center"/>
              <colspec colname="c9" colwidth="3*" align="center"/>
              <colspec colname="c10" colwidth="3*" align="center"/>
              <colspec colname="c11" colwidth="3*" align="center"/>
              <colspec colname="c12" colwidth="3*" align="center"/>
              <colspec colname="c13" colwidth="3*" align="center"/>
              <colspec colname="c14" colwidth="3*" align="center"/>
              <colspec colname="c15" colwidth="3*" align="center"/>
              <colspec colname="c16" colwidth="3*" align="center"/>
              <colspec colname="c17" colwidth="3*" align="center"/>
              <colspec colname="c18" colwidth="3*" align="center"/>
              <colspec colname="c19" colwidth="3*" align="center"/>
              <colspec colname="c20" colwidth="3*" align="center"/>
              <colspec colname="c21" colwidth="3*" align="center"/>
              <colspec colname="c22" colwidth="3*" align="center"/>
              <colspec colname="c23" colwidth="3*" align="center"/>
              <colspec colname="c24" colwidth="3*" align="center"/>
              <colspec colname="c25" colwidth="3*" align="center"/>
              <colspec colname="c26" colwidth="3*" align="center"/>
              <colspec colname="c27" colwidth="3*" align="center"/>
              <colspec colname="c28" colwidth="3*" align="center"/>
              <colspec colname="c29" colwidth="3*" align="center"/>
              <colspec colname="c30" colwidth="3*" align="center"/>
              <colspec colname="c31" colwidth="3*" align="center"/>
              <colspec colname="c32" colwidth="3*" align="center"/>
              <colspec colname="c33" colwidth="3*" align="center"/>
              <thead>
                <row>
                  <entry><para>&#160;</para></entry>
                  <entry><para>0</para></entry>
                  <entry><para>1</para></entry>
                  <entry><para>2</para></entry>
                  <entry><para>3</para></entry>
                  <entry><para>4</para></entry>
                  <entry><para>5</para></entry>
                  <entry><para>6</para></entry>
                  <entry><para>7</para></entry>
                  <entry><para>8</para></entry>
                  <entry><para>9</para></entry>
                  <entry><para>10</para></entry>
                  <entry><para>11</para></entry>
                  <entry><para>12</para></entry>
                  <entry><para>13</para></entry>
                  <entry><para>14</para></entry>
                  <entry><para>15</para></entry>
                  <entry><para>16</para></entry>
                  <entry><para>17</para></entry>
                  <entry><para>18</para></entry>
                  <entry><para>19</para></entry>
                  <entry><para>20</para></entry>
                  <entry><para>21</para></entry>
                  <entry><para>22</para></entry>
                  <entry><para>23</para></entry>
                  <entry><para>24</para></entry>
                  <entry><para>25</para></entry>
                  <entry><para>26</para></entry>
                  <entry><para>27</para></entry>
                  <entry><para>28</para></entry>
                  <entry><para>29</para></entry>
                  <entry><para>30</para></entry>
                  <entry><para>31</para></entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry><para>0</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry namest="c18" nameend="c25"><para>Flags = RRRRRRRR config = PAG</para></entry>
                  <entry namest="c26" nameend="c33"><para>Flags = RRRRRRRR config = ALSP</para></entry>
                </row>
                <row>
                  <entry><para>1</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry namest="c14" nameend="c15"><para>ALA</para></entry>
                  <entry namest="c16" nameend="c17"><para>ACA</para></entry>
                  <entry namest="c18" nameend="c19"><para>HBA</para></entry>
                  <entry><para>R</para></entry>
                  <entry><para>R</para></entry>
                  <entry namest="c22" nameend="c27"><para>Initial Setting</para></entry>
                  <entry namest="c28" nameend="c33"><para>HUC</para></entry>
                </row>
              </tbody>
            </tgroup>
          </table>

          <table>
            <title>Encoded values for Reference History Bit Array (HBA) (flags/config)</title>
            <tgroup cols="3">
              <colspec colname="c1" colwidth="10*" align="center"/>
              <colspec colname="c2" colwidth="10*" align="center"/>
              <colspec colname="c3" colwidth="80*"/>
              <thead>
                <row>
                  <entry>
                    <para>Bit 0</para>
                  </entry>
                  <entry>
                    <para>Bit 1</para>
                  </entry>
                  <entry align="center">
                    <para>Comment</para>
                  </entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>No operation<?linebreak?>Do not change the HBA configuration or update cycle time, simply return
                    current settings.</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>Disable HBA updates</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>Enable an HBA update on the first TLB miss per HBA update cycle, and set the HBA per
                    the configured Initial Setting. (Note: If the platform does not support this setting,
                    H_MEMSTAT_CTRL returns H_RT_PARM, and the value of the HBA field in the
                    returned memory instrumentation configuration “out” parameter is 0b00.)</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>Enable an HBA update on the first access* per HBA update cycle and force a TLB miss
                    per HBA update cycle, and set the HBA per the configured Initial Setting. (Note: If the
                    platform does not support this setting, H_MEMSTAT_CTRL returns H_RT_PARM, and
                    the value of the HBA field in the returned memory instrumentation configuration “out”
                    parameter is 0b00.)</para>
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>

          <para><emphasis role="bold">Implmentation Note:</emphasis>
          This may be approximated by performing a TLBIA once per HBA update cycle;
          thus forcing a TLB miss on the first subsequent page access.</para>

          <para>The Initial Setting field (flags/config): is a 6 bit field that defines the number of high order HBA bits that
          are preloaded to a 1 when the HBA is initialized (for instance when the page is assigned a new virtual
          address through H_ENTER). This field allows the software to bias the page statistics so that the page will
          not be chosen as a victim before it can establish its own usage statistics.</para>

          <para>HBA Update Cycle Field (HUC) (flags/config): is a 6 bit field that defines the update cycle period in
          microseconds multiplied by the power of two specified in the 6 bit field. The range of supported HUC
          values is given in the <emphasis role="bold"><literal>&#8220;ibm,mui-ranges&#8221;</literal></emphasis>
          property. Note: If the platform does not support this setting, or
          the supplied value, H_MEMSTAT_CTRL returns H_RT_PARM, and the value of the HUC field in the
          returned memory instrumentation configuration “config” parameter is the reserved value 0b111111.</para>

          <table>
            <title>Encoded values for Access Count Array (ACA) (flags/config)</title>
            <tgroup cols="3">
              <colspec colname="c1" colwidth="10*" align="center"/>
              <colspec colname="c2" colwidth="10*" align="center"/>
              <colspec colname="c3" colwidth="80*"/>
              <thead>
                <row>
                  <entry>
                    <para>Bit 0</para>
                  </entry>
                  <entry>
                    <para>Bit 1</para>
                  </entry>
                  <entry align="center">
                    <para>Comment</para>
                  </entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>No operation<?linebreak?>Do not change, simply return current setting of ACA configuration.</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>Disable ACA updates<?linebreak?>Note: This setting will prevent the partition from seeing ACA
                    data, however, the platform may still accumulate such data for other purposes.</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>Enable ACA updates<?linebreak?>Note: If the platform does not support this setting, H_MEMSTAT_CTRL returns
                    H_RT_PARM and the value of the ACA field in the returned memory instrumentation
                    configuration “config” parameter is 0b00.</para>
                    <para>On enable the platform is not required to initialize the counters except to preclude a covert
                    channel as in the case of page reassignment between partitions.)</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>Reserved:<?linebreak?>Note: If the caller supplies this value, H_MEMSTAT_CTRL returns
                    H_RT_PARM and the value of the ACA field in the returned memory instrumentation
                    configuration “config” parameter is 0b11.</para>
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>

          <table>
            <title>Encoded values for Affinity Log Array (ALA) (flags/config)</title>
            <tgroup cols="3">
              <colspec colname="c1" colwidth="10*" align="center"/>
              <colspec colname="c2" colwidth="10*" align="center"/>
              <colspec colname="c3" colwidth="80*"/>
              <thead>
                <row>
                  <entry>
                    <para>Bit 0</para>
                  </entry>
                  <entry>
                    <para>Bit 1</para>
                  </entry>
                  <entry align="center">
                    <para>Comment</para>
                  </entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>No operation<?linebreak?>Do not change, simply return current setting of ALA configuration</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>Disable ALA updates<?linebreak?>Note: This setting will prevent the partition from seeing ALA data,
                    however, the platform may still accumulate such data for other purposes.</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>0</para>
                  </entry>
                  <entry>
                    <para>Enable ALA updates<?linebreak?>Note: If the platform does not support this setting,
                    H_MEMSTAT_CTRL returns H_RT_PARM and the value of the ALA field in the
                    returned memory instrumentation configuration “config” parameter is 0b00.</para>
                    <para>On enable the platform is not required to initialize the counters except to preclude a covert
                    channel as in the case of page reassignment between partitions.)</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>1</para>
                  </entry>
                  <entry>
                    <para>Reserved:<?linebreak?>Note: If the caller supplies this value, H_MEMSTAT_CTRL returns
                    H_RT_PARM and the value of the ALA field in the returned memory instrumentation
                    configuration “config” parameter is 0b11.</para>
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>

          <para>The Page Age Granule (PAG) and Affinity Log Sample Period (ALSP) fields (config only): are 8 bit fields
          that define these periods in seconds. Note: On input these are reserved fields, any value other than all
          zeros causes H_MEMSTAT_CTRL to return H_UNSUPPORTED_FLAG.</para>
        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>Returns H_UNSUPPORTED_FLAG if a “flags” parameter reserved bit is non-zero (contents of
              R4 are undefined).</para>
            </listitem>

            <listitem>
              <para>Returns H_RT_PARM if a defined field of the “flags” parameter is either not supported or invalid
              along with the current memory usage instrumentation configuration settings in register R4.</para>
            </listitem>

            <listitem>
              <para>Otherwise sets requested memory usage instrumentation configuration, returns H_Success along
              with the current memory usage instrumentation configuration settings in register R4.</para>
            </listitem>
          </itemizedlist>
        </simplesect>
      </section>

      <section xml:id="sec_reset_memstats">
        <title>H_RESET_MEMSTATS</title>

        <para>Resets page age, affinity log, and/or PUT/HBA for up to 6 logical real pages as specified by the logical
        page index parameters.</para>

        <simplesect>
          <title>Syntax:</title>
          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Function if feature not enabled */
                       /* H_UNSUPPORTED_FLAG if the reserved flags are set */
                       /* H_Parameter if ptx_lpn values do not access within the PFT */
hcall ( const uint64 H_RESET_MEMSTATS, uint64 flags, int64 lpx1, int64 lpx2,
        int64 lpx3, int64 lpx4, int64 lpx5, int64 lpx6);]]></programlisting>
        </simplesect>

        <simplesect>
          <title>Parameters:</title>

          <itemizedlist>
            <listitem>
              <para>Input:</para>
              <itemizedlist>
                <listitem>
                  <para>flags:</para>
                  <itemizedlist>
                    <listitem>
                      <para>bits 0::60: Reserved</para>
                    </listitem>
                    <listitem>
                      <para>bit 61: HBA (History Bit Array): Set Bit Array to configured Initial Setting.</para>
                    </listitem>
                    <listitem>
                      <para>bit 62: PAC (Page Age Counter)</para>
                    </listitem>
                    <listitem>
                      <para>bit 63: ALA (Affinity Log Array)</para>
                    </listitem>
                  </itemizedlist>
                </listitem>

                <listitem>
                  <para>lpx1::lpx6: Logical page index(s) to be used</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Output:</para>
              <itemizedlist>
                <listitem>
                  <para>R3: Return code</para>
                </listitem>
                <listitem>
                  <para>R4::R10: Reserved</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>If (Flags AND HBA) and Reference History Bit Array not enabled, returns H_Not_Available.</para>
            </listitem>
            <listitem>
              <para>If (Flags AND ALA) and the Affinity Log Array not enabled, returns H_Not_Available.</para>
            </listitem>
            <listitem>
              <para>If (Flags AND PAA) and reference rate array not enabled, returns H_Not_Available.</para>
            </listitem>
            <listitem>
              <para>If (Flags AND ACA) and reference rate array not enabled, returns H_Not_Available.</para>
            </listitem>
            <listitem>
              <para><literallayout>for each of lpx1..6
  Exits for each if lpx is FFFF_FFFF_FFFF_FFFF.

  If the lpx is not owned by the calling partition, return H_P(2..7)
    If AMS mode and page is paged out move on as stats are reset on a page in
  If (Flags AND ALA)
    Reset the affinity log array for the lpx
  If (Flags AND Page-Age)
    Clear the page age counter for the lpx
  If (Flags AND HBA)
    Sets the configured Number of Ref Bits in the Reference History Bit Array for the lpx </literallayout></para>
            </listitem>
            <listitem>
              <para>Return H_Success.</para>
            </listitem>
          </itemizedlist>
        </simplesect>
      </section>

      <section xml:id="sec_return_pageinfo">
        <title>H_RETURN_PAGEINFO</title>

        <para>The H_RETURN_PAGEINFO hcall() returns the page usage information for a range of logical pages or a
        list of specific logical pages. The results are returned in a 4K aligned buffer, the data for each logical page
        occupying one 32 byte record, all other contents of the buffer are volatile and undefined.</para>

        <para>The range of logical pages is restricted to a single LMB boundary (the list of specific logical pages does not
        have his restriction). If this restriction is violated, the H_RETURN_PAGEINFO hcall() returns H_P4.</para>

        <para>The RETURN of a page range might take longer than is allowable for a single call, or it might select more
        pages than can be contained in the return buffer. Should either of these cases happen the
        H_RETURN_PAGEINFO hcall() returns H_CONTINUE, along with the current results, and the value of
        the lpx0 parameter for continuing the RETURN on a subsequent call from the termination point of the prior
        call.</para>

        <para>The caller may specify a filter to further qualify the pages for which data is returned. For the CMO option
        if the logical page has been paged out by the platform, the page is filtered out of the returned data.</para>

        <simplesect>
          <title>Syntax:</title>
          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Parameter: An undefined flags option specified. */
                       /* H_P2: The buffer parameter is invalid (4K aligned in */
                       /*   caller’s range) */
                       /* H_P3: The lpx0 parameter is invalid */
                       /* H_P4: The lpx1 parameter is invalid */
                       /* H_P5: The lpx2 parameter is invalid */
                       /* H_P6: The lpx3 parameter is invalid */
                       /* H_P7: The lpx4 parameter is invalid */
                       /* H_CONTINUE_RETURN: incomplete intermediate results */
                       /*   returned */
hcall ( const uint64 H_RETURN_PAGEINFO,
        uint64 flags,  /* RETURN match criteria */
        uint64 buffer, /* RETURN results */
        uint64 lpx0,   /* Beginning of RETURN */
        uint64 lpx1,   /* Continuation/End of RETURN list */
        uint64 lpx2,
        uint64 lpx3,
        uint64 lpx4);  /* End of RETURN list */]]></programlisting>
        </simplesect>

        <simplesect>
          <title>Parameters:</title>

          <itemizedlist>
            <listitem>
              <para>Input:</para>
              <itemizedlist>
                <listitem>
                  <para>flags:</para>
                  <table>
                    <title>H_MEMSTAT_CTRL Flag Layout</title>
                    <tgroup cols="33">
                      <colspec colname="c1" colwidth="3*" align="center"/>
                      <colspec colname="c2" colwidth="3*" align="center"/>
                      <colspec colname="c3" colwidth="3*" align="center"/>
                      <colspec colname="c4" colwidth="3*" align="center"/>
                      <colspec colname="c5" colwidth="3*" align="center"/>
                      <colspec colname="c6" colwidth="3*" align="center"/>
                      <colspec colname="c7" colwidth="3*" align="center"/>
                      <colspec colname="c8" colwidth="3*" align="center"/>
                      <colspec colname="c9" colwidth="3*" align="center"/>
                      <colspec colname="c10" colwidth="3*" align="center"/>
                      <colspec colname="c11" colwidth="3*" align="center"/>
                      <colspec colname="c12" colwidth="3*" align="center"/>
                      <colspec colname="c13" colwidth="3*" align="center"/>
                      <colspec colname="c14" colwidth="3*" align="center"/>
                      <colspec colname="c15" colwidth="3*" align="center"/>
                      <colspec colname="c16" colwidth="3*" align="center"/>
                      <colspec colname="c17" colwidth="3*" align="center"/>
                      <colspec colname="c18" colwidth="3*" align="center"/>
                      <colspec colname="c19" colwidth="3*" align="center"/>
                      <colspec colname="c20" colwidth="3*" align="center"/>
                      <colspec colname="c21" colwidth="3*" align="center"/>
                      <colspec colname="c22" colwidth="3*" align="center"/>
                      <colspec colname="c23" colwidth="3*" align="center"/>
                      <colspec colname="c24" colwidth="3*" align="center"/>
                      <colspec colname="c25" colwidth="3*" align="center"/>
                      <colspec colname="c26" colwidth="3*" align="center"/>
                      <colspec colname="c27" colwidth="3*" align="center"/>
                      <colspec colname="c28" colwidth="3*" align="center"/>
                      <colspec colname="c29" colwidth="3*" align="center"/>
                      <colspec colname="c30" colwidth="3*" align="center"/>
                      <colspec colname="c31" colwidth="3*" align="center"/>
                      <colspec colname="c32" colwidth="3*" align="center"/>
                      <colspec colname="c33" colwidth="3*" align="center"/>
                      <thead>
                        <row>
                          <entry morerows="1"><para>&#160;</para></entry>
                          <entry namest="c2" nameend="c9"><para>0</para></entry>
                          <entry namest="c10" nameend="c17"><para>1</para></entry>
                          <entry namest="c18" nameend="c25"><para>2</para></entry>
                          <entry namest="c26" nameend="c33"><para>3</para></entry>
                        </row>
                        <row>
                          <entry><para>0</para></entry>
                          <entry><para>1</para></entry>
                          <entry><para>2</para></entry>
                          <entry><para>3</para></entry>
                          <entry><para>4</para></entry>
                          <entry><para>5</para></entry>
                          <entry><para>6</para></entry>
                          <entry><para>7</para></entry>
                          <entry><para>0</para></entry>
                          <entry><para>1</para></entry>
                          <entry><para>2</para></entry>
                          <entry><para>3</para></entry>
                          <entry><para>4</para></entry>
                          <entry><para>5</para></entry>
                          <entry><para>6</para></entry>
                          <entry><para>7</para></entry>
                          <entry><para>0</para></entry>
                          <entry><para>1</para></entry>
                          <entry><para>2</para></entry>
                          <entry><para>3</para></entry>
                          <entry><para>4</para></entry>
                          <entry><para>5</para></entry>
                          <entry><para>6</para></entry>
                          <entry><para>7</para></entry>
                          <entry><para>0</para></entry>
                          <entry><para>1</para></entry>
                          <entry><para>2</para></entry>
                          <entry><para>3</para></entry>
                          <entry><para>4</para></entry>
                          <entry><para>5</para></entry>
                          <entry><para>6</para></entry>
                          <entry><para>7</para></entry>
                        </row>
                      </thead>
                      <tbody>
                        <row>
                          <entry><para>0</para></entry>
                          <entry namest="c2" nameend="c3"><para>Ar</para></entry>
                          <entry namest="c4" nameend="c33"><para>Accesses / Second</para></entry>
                        </row>
                        <row>
                          <entry><para>1</para></entry>
                          <entry namest="c2" nameend="c32"><para>RESERVED</para></entry>
                          <entry><para>R</para></entry>
                        </row>
                      </tbody>
                    </tgroup>
                  </table>

                  <table>
                    <title>H_MEMSTAT_CTRL Flag Sub-field Layout</title>
                    <tgroup cols="5">
                      <colspec colname="c1" colwidth="10*" align="center"/>
                      <colspec colname="c2" colwidth="10*" align="center"/>
                      <colspec colname="c3" colwidth="10*" align="center"/>
                      <colspec colname="c4" colwidth="10*" align="center"/>
                      <colspec colname="c5" colwidth="60*"/>
                      <thead>
                        <row>
                          <entry>
                            <para>Word</para>
                          </entry>
                          <entry>
                            <para>Byte</para>
                          </entry>
                          <entry>
                            <para>Bit</para>
                          </entry>
                          <entry>
                            <para>Name</para>
                          </entry>
                          <entry align="center">
                            <para>Comment</para>
                          </entry>
                        </row>
                      </thead>
                      <tbody valign="middle">
                        <row>
                          <entry morerows="2">
                            <para>0</para>
                          </entry>
                          <entry morerows="1">
                            <para>0</para>
                          </entry>
                          <entry>
                            <para>0-1</para>
                          </entry>
                          <entry>
                            <para>Ar</para>
                          </entry>
                          <entry>
                            <para>Access Rate Filter Control<?linebreak?>
                            0b00 Do not filter based upon Access Rate (ignore flags bits 2-31)<?linebreak?>
                            0b01 Reserved (Returns H_Parameter if this condition value is set)<?linebreak?>
                            0b10 Select if page access per second is greater than the value in bits 2::31. Note if the
                            specified value is greater than the MUI facilities’ maximum access rate capacity per the
                            <emphasis role="bold"><literal>&#8220;ibm,mui-ranges&#8221;</literal></emphasis>
                            property this condition will not be met.<?linebreak?>
                            0b11 Reserved (Returns H_Parameter if this condition value is set)</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>2-7</para>
                          </entry>
                          <entry namest="c4" nameend="c5" morerows="1">
                            <para>Accesses per second</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>1-3</para>
                          </entry>
                          <entry>
                            <para>All</para>
                          </entry>
                        </row>
                        <row>
                          <entry morerows="2">
                            <para>1</para>
                          </entry>
                          <entry>
                            <para>0-2</para>
                          </entry>
                          <entry>
                            <para>All</para>
                          </entry>
                          <entry morerows="1">
                            <para>Reserved</para>
                          </entry>
                          <entry morerows="1">
                            <para>Reserved (Returns H_Parameter if this condition value is set)</para>
                          </entry>
                        </row>
                        <row>
                          <entry morerows="1">
                            <para>3</para>
                          </entry>
                          <entry>
                            <para>0-6</para>
                          </entry>
                        </row>
                        <row>
                          <entry>
                            <para>7</para>
                          </entry>
                          <entry>
                            <para>R</para>
                          </entry>
                          <entry>
                            <para>0: Returns page usage data for up to 5 pages specified one each in parameters
                            lpn0::lpn4</para>
                            <para>1: Returns page usage data for the range from the logical page in parameter lpn0
                            through lpn1</para>
                          </entry>
                        </row>
                      </tbody>
                    </tgroup>
                  </table>
                </listitem>
                <listitem>
                  <para>buffer: 4kB-aligned output buffer</para>
                  <para><emphasis role="bold">Implementation Note:</emphasis>
                  This buffer is output only and may be initialized with dcbz
                  instructions to preclude memory error handling.</para>
                </listitem>
                <listitem>
                  <para>lpx0: The logical page number index for the first page.</para>
                </listitem>
                <listitem>
                  <para>lpx1: For page Range option, the last logical page number index. For the list option,
                  and not the list terminator value (-1) continue to return page usage data for the
                  logical page number specified, else terminate the call.</para>
                </listitem>
                <listitem>
                  <para>lpx1::lpx4: For the list option, and not the list terminator value (-1) continue to return page
                  usage data for the logical page number specified, else terminate the call</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Output:</para>
              <itemizedlist>
                <listitem>
                  <para>R3: Return Code</para>
                </listitem>
                <listitem>
                  <para>R4: Number of matching entry records in destination buffer</para>
                </listitem>
                <listitem>
                  <para>R5: For the range RETURN option, if the return code is H_CONTINUE this value is
                  the value of the lpn0 parameter for a subsequent call to continue the RETURN.</para>
                </listitem>
                <listitem>
                  <para>R6::R10: Reserved</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>

          <table>
            <title>Buffer Record Format</title>
            <tgroup cols="3">
              <colspec colname="c1" colwidth="15*"/>
              <colspec colname="c2" colwidth="15*"/>
              <colspec colname="c3" colwidth="70*"/>
              <thead>
                <row>
                  <entry align="center">
                    <para>Field Name</para>
                  </entry>
                  <entry align="center">
                    <para>Byte Offset</para>
                  </entry>
                  <entry align="center">
                    <para>Description</para>
                  </entry>
                </row>
              </thead>
              <tbody>
                <row>
                  <entry>
                    <para>lpx</para>
                  </entry>
                  <entry>
                    <para>0::7</para>
                  </entry>
                  <entry>
                    <para>The logical page number index of the selected page</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>access_rate</para>
                  </entry>
                  <entry>
                    <para>8::15</para>
                  </entry>
                  <entry>
                    <para>Accesses per second</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>affinity_log</para>
                  </entry>
                  <entry>
                    <para>16::23</para>
                  </entry>
                  <entry>
                    <para>Eight single byte integers. One integer for each of the past
                    eight ALSP intervals. The non-zero integer value
                    representing one of the masters that referenced the page
                    during the period. A zero value indicating that valid data is
                    not available for the represented period. The associativity list
                    for the referencing master is found in the
                    <emphasis role="bold"><literal>&#8220;ibm,muiassociativity-mapping&#8221;</literal></emphasis>
                    property.</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>Reserved</para>
                  </entry>
                  <entry>
                    <para>24::29</para>
                  </entry>
                  <entry>
                    <para>&#160;</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>flags</para>
                  </entry>
                  <entry>
                    <para>30</para>
                  </entry>
                  <entry>
                    <para>Bit 0 is a 1 if the page is AMS paged out (CMO option) else 0<?linebreak?>
                    Bit 1 is a 1 if the access_rate value is valid else 0<?linebreak?>
                    Bit 2 is a 1 if the affinity_log value is valid else 0<?linebreak?>
                    Bit 3 is a 1 if the age value is valid else 0<?linebreak?>
                    Bits 4::7 Reserved</para>
                  </entry>
                </row>
                <row>
                  <entry>
                    <para>age</para>
                  </entry>
                  <entry>
                    <para>31</para>
                  </entry>
                  <entry>
                    <para>Page age in units of the Page Age Granule</para>
                  </entry>
                </row>
              </tbody>
            </tgroup>
          </table>
        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>If any reserved flags bits are set return H_Parameter.</para>
            </listitem>
            <listitem>
              <para>Returns H_Function if function does not exist.</para>
            </listitem>
            <listitem>
              <para>Returns H_P2 if buffer is not 4k aligned or if the logical page number is outside of the caller’s
              range.</para>
            </listitem>
            <listitem>
              <para>count = 0; /* number of entries matching in dest */</para>
            </listitem>
            <listitem>
              <para><literallayout>if (Range_Search = 1) // lpn0..lpn1 range case
  {
  if(lpx0 is not a page owned by the calling partition) return H_P3;
  if(lpx1 is less than lpx0 or outside of the LMB containing lpx0) return H_P4;
  dest = buffer;
  for(mem=lpx0; (mem&lt;=lpx1) &amp;&amp; (count &lt; 128); mem++)
    {
    If (hit (mem, filter)) /* returns true if the logical page mem matches the selection criteria */
      { /* per the definition of the filter parameter above */
      fillrecord (dest, mem) ; /* fills in a record per {cross reference to table {BRF}} */
      count++ ;
      Increment dest to next record (+32 bytes);
      }
    }
  R4 = count ; R5 = mem;
  If (mem > lpx1) then return H_Success else return H_CONTINUE;
  }</literallayout></para>
            </listitem>
            <listitem>
              <para><literallayout>if (Range_Search = 0) // memory buffer case
  {
  dest = buffer; count = 0;
  for each of lpx0..4
    Exits for each if the LPX is FFFF_FFFF_FFFF_FFFF.
    if (the LPX is not a page owned by the calling partition) return H_P(3..7);
    if (hit (the LPX, filter)) /* returns true if the logical page mem matches the selection criteria */
      { /* per the definition of the filter parameter above */
      fillrecord (dest, lpnx) ; /* fills in a record per {cross reference to table {BRF}} */
      count++ ;
      Increment dest to next record (+32 bytes);
      }
  R4 = count; return H_Success;
  }</literallayout></para>
            </listitem>
          </itemizedlist>
        </simplesect>
      </section>

      <section xml:id="sec_bulk_read_hba">
        <title>H_BULK_READ_HBA</title>

        <para>H_BULK_READ_HBA returns the Reference History Bit Array entry for multiple pages in one call. The
        returned values present the reference history for up to 64 HUC intervals. Starting with the high order bit
        representing the most recent HUC interval, the returned value contains a one in the corresponding bit
        position if the page was accessed during that interval. Due to hardware limitations, the system might not
        have data for a full 64 intervals; in that case low order bits are zero filled.</para>

        <simplesect>
          <title>Syntax:</title>
          <programlisting><![CDATA[int64                  /* H_Success: Expected Return code */
                       /* H_Parameter: An undefined flags option specified. */
                       /* H_P2..H_p7: Corresponding lpx1..lpx6 invalid (not owned */
                       /*   by calling partition */
                       /* H_Function if feature not enabled */
hcall ( const uint64 H_BULK_READ_HBA, uint64 flags, int64 lpx1, int64 lpx2,
        int64 lpx3, int64 lpx4, int64 lpx5, int64 lpx6);]]></programlisting>
        </simplesect>

        <simplesect>
          <title>Parameters:</title>

          <itemizedlist>
            <listitem>
              <para>Input:</para>
              <itemizedlist>
                <listitem>
                  <para>flags: bits 0::63: Reserved</para>
                </listitem>

                <listitem>
                  <para>lpx1::lpx6: The logical page number index to be used to index into appropriate position in
                  HBA. HBA value for a given LPX is returned in the same argument register.</para>
                </listitem>
              </itemizedlist>
            </listitem>

            <listitem>
              <para>Output:</para>
              <itemizedlist>
                <listitem>
                  <para>R3: Return code</para>
                </listitem>

                <listitem>
                  <para>R4: Reserved</para>
                </listitem>

                <listitem>
                  <para>R5: HBA corresponding to lpx1</para>
                </listitem>

                <listitem>
                  <para>R6: HBA corresponding to lpx2</para>
                </listitem>

                <listitem>
                  <para>R7: HBA corresponding to lpx3</para>
                </listitem>

                <listitem>
                  <para>R8: HBA corresponding to lpx4</para>
                </listitem>

                <listitem>
                  <para>R9: HBA corresponding to lpx5</para>
                </listitem>

                <listitem>
                  <para>R10: HBA corresponding to lpx6</para>
                </listitem>
              </itemizedlist>
            </listitem>
          </itemizedlist>
        </simplesect>

        <simplesect>
          <title>Semantics:</title>

          <itemizedlist>
            <listitem>
              <para>If Reference History is not enabled, returns H_Function.</para>
            </listitem>
            <listitem>
              <para>If a reserved flags bit is set return appropriate H_UNSUPPORTED_FLAG value.</para>
            </listitem>
            <listitem>
              <para><literallayout>for each of lpx1..6
  Exits for each if the LPX is FFFF_FFFF_FFFF_FFFF.
    If lpn1..6 not owned by the calling partition, return H_P2..7 as appropriate
    Load HBA corresponding to the LPX into the high-order bits of R5-R10
      (corresponding to lpx1..6), zero out remaining lower bits of the register
      and shift the register right (zero insert) by the difference between the current
      time and the page’s PUT timestamp.
    // end of for each lpx1..6</literallayout></para>
            </listitem>
            <listitem>
              <para>Return H_Success.</para>
            </listitem>
          </itemizedlist>
        </simplesect>
      </section>
    </section>
  </section>

  <section xml:id="sec_coherent_platform_facilities">
    <title>Coherent Platform Facilities</title>
    <para>This section documents the hypervisor interface to optional coherent
      platform facilities. If the platform supports a coherent platform facility, the
      <emphasis role="bold"><literal>&#8220;ibm,hypertas-functions&#8221;</literal></emphasis>
      property of the
      <emphasis role="bold"><literal>/rtas</literal></emphasis>
      node contains the function set specification “hcall-ca” and the following
      hcall()s are supported.
</para>

    <section xml:id="sec_attach_ca_process">
      <title>H_ATTACH_CA_PROCESS</title>
      <para>The architectural intent of this hcall is to attach a process element to a
        coherent platform function. The process element describes the environment in
        which a coherent platform function will operate for a given workload.
      </para>

      <simplesect>
        <title>Syntax:</title>
        <programlisting><![CDATA[int64                 /* H_Success:   The process info is attached to the coherent */
                      /*              platform function and the work can now be */
                      /*              submitted to the coherent platform function. */
                      /* H_Parameter: An incorrect parameter was supplied. */
                      /* H_Resource:  The coherent platform function does not have */
                      /*              enough additional resource to attach the */
                      /*              process. Retry the operation after process */
                      /*              elements have been detached or terminated. */
                      /* H_Hardware:  A hardware event prevented the attach */
                      /*              operation. */
                      /* H_Busy or H_LongBusy: If the hcall requires more */
                      /*              execution time, Busy will be returned and */
                      /*              the OS is required to call back until Busy */
                      /*              is no longer returned. */
                      /* H_Function:  The function is not supported. */
                      /* H_State:     The coherent platform function is not in a */
                      /*              valid state to perform the attach process. */
                      /* H_Authority: The partition does not have authority to */
                      /*              perform this hcall; the coherent platform */
                      /*              facilities may need to be licensed. */
                      /* R4 contains the continue-token for the next call on H_Busy */
                      /*   or a 8-byte process-token (described in Process Token */
                      /*   Format) used to identify this process on the */
                      /*   H_CONTROL_CA_FUNCTION and H_DETACH_CA_PROCESS calls on */
                      /*   H_Success. */
                      /* If “ibm,process-mmio” is defined and set to 1 for the */
                      /*   coherent platform function, R5 contains the process MMIO */
                      /*   space address on H_Success. */
                      /* If “ibm,process-mmio” is defined and set to 1 for the */
                      /*   coherent platform function, R6 contains the process MMIO */
                      /*   space length on H_Success. */
hcall ( const uint64 H_ATTACH_CA_PROCESS, /* Attach a process */
        uint64 unit-address,               /* Address as specified in the “reg” of */
                                           /*   coherent-platform-function node */
        uint64 process-element-struct,     /* Real address of Process Element */
                                           /*   Structure */
        uint64 continue-token);            /* Value of 0 first call, value returned */
                                           /*   in R4 on H_Busy */

// Version 1
Process Element Structure
{
    uint64 version;                                 // Must be set to 1.
    uint64 csrpValid : 1;                           // bit  0
    uint64 problemState : 1;                        // bit  1
    uint64 secondarySegmentTableSearchEnabled : 1;  // bit  2
    uint64 tagsActive : 1;                          // bit  3
    uint64 userState : 1;                           // bit  4
    uint64 translationEnabled : 1;                  // bit  5
    uint64 sixtyFourBit : 1;                        // bit  6
    uint64 isPrivilegedProcess : 1;                 // bit  7
    uint64 reservedFlags : 56;                      // bits 8:63
    uint8 reserved0[12];
    uint32 pslVirtualIsn;
    uint8 applicationVirtualIsnBitmap[256];
    uint8 reserved1[144];
    uint32 threadId;
    uint32 processId;
    uint32 csrpUpper;
    uint32 csrpLower : 20;                          // bits 0:19
    uint32 csrpLimit : 12;                          // bits 20:31
    uint32 aurpB : 2;                               // bits 0:1
    uint32 aurpKs : 1;                              // bit  2
    uint32 aurpKp : 1;                              // bit  3
    uint32 aurpN : 1;                               // bit  4
    uint32 aurpL : 1;                               // bit  5
    uint32 aurpC : 1;                               // bit  6
    uint32 aurpTA : 1;                              // bit  7
    uint32 aurpLP : 2;                              // bits 8:9
    uint32 aurpReserved0 : 22;                      // bits 10:31
    uint32 aurpReserved1: 18;                       // bits 0:17
    uint32 aurpVaUpper : 14;                        // bits 18:31
    uint64 aurpVaLower : 57;                        // bits 0:56
    uint64 aurpReserved2 : 6;                       // bits 57:62
    uint64 aurpValid : 1;                           // bit  63
    uint32 sstpB : 2;                               // bits 0:1
    uint32 sstpKs : 1;                              // bit  2
    uint32 sstpKp : 1;                              // bit  3
    uint32 sstpN : 1;                               // bit  4
    uint32 sstpL : 1;                               // bit  5
    uint32 sstpC : 1;                               // bit  6
    uint32 sstpTA : 1;                              // bit  7
    uint32 sstpLP : 2;                              // bits 8:9
    uint32 sstpReserved0 : 10;                      // bits 10:19
    uint32 sstpSegTableSize : 12;                   // bits 20:31
    uint32 sstpReserved1 : 18;                      // bits 0:17
    uint32 sstpVaUpper : 14;                        // bits 18:31
    uint64 sstpVaLower : 56;                        // bits 0:55
    uint64 sstpReserved2 : 7;                       // bits 56:62
    uint64 sstpValid : 1;                           // bit  63
    uint64 amr;
    uint8 reserved3[4];
    uint64 workElementDescriptor;
    uint8 reserved4[12];]]></programlisting>

        <table frame="all" pgwide="1" xml:id="table_process_token_format">
          <?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
          <title>Process Token Format</title>
          <tgroup cols="2">
            <colspec colname="c1" colwidth="50*" align="center" />
            <colspec colname="c2" colwidth="50*" align="center" />
            <thead valign="middle">
              <row>
                <entry>
                  <para>
                    <emphasis role="bold">Bytes 0-3</emphasis>
                  </para>
                </entry>
                <entry>
                  <para>
                    <emphasis role="bold">Bytes 4-7</emphasis>
                  </para>
                </entry>
              </row>
            </thead>
            <tbody valign="middle">
              <row>
                <entry>
                  <para>Platform firmware use (opaque to OS)</para>
                </entry>
                <entry>
                  <para>CAIA process element index (128 byte offset into Scheduled Process Area)</para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </table>

      </simplesect>

      <simplesect>
        <title>Parameters:</title>
        <itemizedlist>
          <listitem>
            <para>uint64 unit-address: Unit Address per the device tree
              <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
              property, element 0, of the coherent platform function</para>
          </listitem>

          <listitem>
            <para>uint64 process-element-struct: Logical real address of the process
              element structure. This memory must remain pinned and unchanged throughout
              the duration of the H_ATTACH_CA_PROCESS call. All fields in the structure
              have big-endian byte ordering and MSB 0 bit ordering.</para>
          </listitem>

          <listitem>
            <para>uint64 continue-token: Used to continue a process attach if H_Busy is
              returned. Set to zero on first call. If H_Busy is returned then call
              again but use the value returned in R4 from the previous call as the
              value of continue-token.</para>
          </listitem>
        </itemizedlist>
      </simplesect>

      <simplesect>
        <title>Semantics:</title>
        <itemizedlist>
          <listitem>
            <para>Verify that coherent platform facilities are licensed to be used,
              else return H_Authority.</para>
          </listitem>

          <listitem>
            <para>Verify that the unit-address parameter is valid else return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>Verify the process-element-struct parameter:
              <itemizedlist>
                <listitem>
                  <para>Verify that the process-element-struct is 8 byte aligned and
                    does not cross a 4096 byte boundary, else return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>Verify that the Process Element structure version is supported,
                    else return H_Parameter.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>Verify that if the isPrivilegedProcess bit is set in the process element,
              that the coherent platform function is allowed (via
              <emphasis role="bold"><literal>&#8220;ibm,privileged-function&#8221;</literal></emphasis>
              F property), else return H_Authority.</para>
          </listitem>

          <listitem>
            <para>Verify that if the aurpValid bit is set to 1, that the coherent
              platform function supports AUR (via
              <emphasis role="bold"><literal>&#8220;ibm,supports-aur&#8221;</literal></emphasis>
              OF property), else return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>Verify that if the csrpValid bit is set to 1, that the coherent platform
              function supports CSRP (via
              <emphasis role="bold"><literal>&#8220;ibm,supports-csrp&#8221;</literal></emphasis>
              OF property), else return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>Verify there is adequate space to attach the process for the coherent
              platform function else return H_Resource.</para>
          </listitem>

          <listitem>
            <para>Verify that the coherent platform function is in a state that allows
              attaching of new processes and if necessary has been downloaded via
              H_DOWNLOAD_CA_FUNCTION, else return H_State.</para>
          </listitem>

          <listitem>
            <para>Verify that the sum of the pslVirtualIsn and application
              virtual ISN values are greater than or equal to the
              <emphasis role="bold"><literal>&#8220;ibm,min-ints-per-process&#8221;</literal></emphasis>
              property for the coherent-platform-function and less than or equal to the
              <emphasis role="bold"><literal>&#8220;ibm,max-ints-per-process&#8221;</literal></emphasis>
              property for the coherent-platform-function and the attaching of this
              process does not violate the
              <emphasis role="bold"><literal>&#8220;ibm,max-ints&#8221;</literal></emphasis>
              property for the coherent-platform-function, else return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>Verify that the pslVirtualIsn is not already in use by another coherent
              platform function under the coherent platform facility, if so return
              H_Resource.</para>
          </listitem>

          <listitem>
            <para>Validate that the application virtual ISN values are valid and not
              in use by another coherent platform function under the coherent platform
              facility, and do not collide with the specified pslVirtualIsn, if so
              return H_Resource.
              <itemizedlist>
                <listitem>
                  <para>Application virtual ISN values are calculated by adding the
                    base virtual ISN value found in the interrupt-ranges property of
                    the parent coherent platform facility node to the relative offset
                    (zero-based) of a bit in the bitmap that is set to 1. These
                    values are programmed into corresponding the CAIA process element
                    structure.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>Verify that all the virtual interrupts can be mapped into the CAIA
              process element, else return H_Resource. It may be possible to attempt
              to attach the process after detaching existing processes.</para>
          </listitem>

          <listitem>
            <para>Verify that the virtual interrupts provided will fit into the process
              element entry, if not return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>Disable the virtual interrupts provided in the process-element-struct.
              The partition must use <emphasis>ibm,set-xive</emphasis> (with priority less than 0xFF) to
              enable the virtual interrupt source after H_ATTACH_CA_PROCESS completes
              successfully.</para>
          </listitem>

          <listitem>
            <para>Select a process element to use for the coherent platform function
              and performs the procedure to attach a process as defined by the CAIA.
              During this procedure, H_Busy or H_LongBusy will be returned if hcall
              time limits are exceeded.</para>
          </listitem>

          <listitem>
            <para>Once the process element is attached as defined by the CAIA, return
              H_Success, R4 contains the process token and if
              <emphasis role="bold"><literal>&#8220;ibm,process-mmio&#8221;</literal></emphasis>
              is set to 1, R5 is the MMIO address, R6 is the MMIO length.</para>
          </listitem>
        </itemizedlist>
        <note>
          <para>Following a reset of the coherent platform facility or coherent platform
            function, platform firmware guarantees that the upper 4 byte portion of
            the returned process token will be different than it was for any process
            token returned since the previous reset.</para>
        </note>
      </simplesect>
    </section>

    <section xml:id="sec_detach_ca_process">
      <title>H_DETACH_CA_PROCESS</title>
      <para>The architectural intent of this hcall is to detach a process element
        from a coherent platform function. This hcall will remove the workload or p
        rocess element that was attached using H_ATTACH_CA_FUNCTION.</para>

      <simplesect>
        <title>Syntax:</title>
        <programlisting><![CDATA[int64                 /* H_Success:   The process was detached from the coherent */
                      /*              platform function. */
                      /* H_Parameter: An incorrect parameter was supplied. */
                      /* H_Hardware:  A hardware event prevented the detach */
                      /*              operation. */
                      /* H_Busy or H_LongBusy: If the hcall requires more */
                      /*              execution time, Busy will be returned and */
                      /*              the OS is required to call back until Busy */
                      /*              is no longer returned. */
                      /* H_State:     The coherent platform function is not in a */
                      /*              valid state to collect interrupt info. */
                      /* H_Resource:  The function has page table mappings for MMIO. */
                      /* H_Authority: The partition does not have authority to */
                      /*              perform this hcall; the coherent platform */
                      /*              facilities may need to be licensed. */
                      /* R4 contains the continue-token for the next call on Busy */
                      /*    return code. */
hcall ( const uint64 H_DETACH_CA_PROCESS,
        uint64 unit-address,
        uint64 process-token,
        uint64 continue-token);]]></programlisting>
      </simplesect>

      <simplesect>
        <title>Parameters:</title>
        <itemizedlist>
          <listitem>
            <para>uint64 unit-address: Unit Address per the device tree
              <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
              property of the coherent platform function</para>
          </listitem>

          <listitem>
            <para>uint64 process-token: process identifier token for the attached
              process returned in R4 on H_Success return from H_ATTACH_CA_PROCESS call.</para>
          </listitem>

          <listitem>
            <para>uint64 continue-token: Used to continue a process detach if H_Busy
              is returned. Set to zero on first call. If H_Busy is returned then
              call again but use the value returned in R4 from the previous call
              as the value of continue-token.</para>
          </listitem>
        </itemizedlist>
      </simplesect>

      <simplesect>
        <title>Semantics:</title>
        <itemizedlist>
          <listitem>
            <para>Verify that coherent platform facilities are licensed to be used,
              else return H_Authority.</para>
          </listitem>

          <listitem>
            <para>Verify that the unit-address parameter is valid else return
              H_Parameter.</para>
          </listitem>

          <listitem>
            <para>Verify that the process-token is currently an attached process to
              the coherent platform function, else return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>Verify that the coherent platform function is in an error state that
              allows detaching processes, else return H_State.</para>
          </listitem>

          <listitem>
            <para>If
              <emphasis role="bold"><literal>&#8220;ibm,process-mmio&#8221;</literal></emphasis>
              is set to 1, verify that there are no existing
              mappings in the page table for the process
            MMIO space, else return H_Resource.</para>
          </listitem>

          <listitem>
            <para>If the process is not completed or suspended, the process is
              terminated using the process terminate procedure in the CAIA. During
              this process the platform can return H_Busy or H_LongBusy and the OS
              is responsible for calling back until a non-busy return code is returned.</para>
          </listitem>

          <listitem>
            <para>Remove the process from the coherent platform function process
              element list according to the process remove procedure defined in the
              CAIA. During this process the platform can return H_Busy or H_LongBusy
              and the OS is responsible for calling back until a non-busy return code
              is returned.</para>
          </listitem>

          <listitem>
            <para>Invalidation of the SLB and TLB for the process being detached is
              performed. During this process the platform can return H_Busy or
              H_LongBusy and the OS is responsible for calling back until a non-busy
              return code is returned.</para>
          </listitem>

          <listitem>
            <para>If the hardware encounters an error while detaching the process,
              H_Hardware is returned.</para>
          </listitem>

          <listitem>
            <para>H_Success is returned.</para>
          </listitem>
        </itemizedlist>
      </simplesect>
    </section>

    <section xml:id="sec_control_ca_function">
      <title>H_CONTROL_CA_FUNCTION</title>
      <para>This H_CONTROL_CA_FUNCTION hypervisor call allows the partition to
        manipulate or query certain coherent platform function behaviors.</para>

      <simplesect>
        <title>Syntax:</title>
        <programlisting><![CDATA[int64                 /* H_Success:   The operation is completed for the coherent */
                      /*              platform facility */
                      /* H_Authority: The operating system does not have authority */
                      /*              to control the coherent platform facility or */
                      /*              the coherent platform facilities are not */
                      /*              licensed to be used. */
                      /* H_Parameter: An incorrect parameter was supplied. */
                      /* H_Hardware:  A hardware event prevented the control */
                      /*              operation. */
                      /* H_State:     The state was invalid for the operation. */
                      /* H_Busy or H_LongBusy: If the hcall requires more */
                      /*              execution time, Busy will be returned and */
                      /*              the OS is required to call back until Busy */
                      /*              is no longer returned. */
                      /* H_Not_Found: The operation supplied was not valid. */
                      /* H_Not_Available: The operation cannot be performed because */
                      /*              the AFU has not been downloaded. */
                      /* H_SG_LIST:   A scatter/gather list entry was invalid. */
                      /* H_Resource:  The function has page table mappings for MMIO. */
                      /* H_Function:  The function is not supported. */
                      /* R4 contains the continue-token for the next call on Busy */
                      /*    return code. */
                      /* R4 contains operation-specific data if applicable on */
                      /*    Success return code. */
hcall ( const uint64 H_CONTROL_CA_FUNCTION,
        uint64 unit-address,
        uint64 operation,
        uint64 parameter1,
        uint64 parameter2,
        uint64 parameter3,
        uint64 parameter4,
        uint64 continue-token);]]></programlisting>
      </simplesect>

      <simplesect>
        <title>Parameters:</title>
        <itemizedlist>
          <listitem>
            <para>uint64 unit-address: Unit Address per the device tree
              <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis>
              property
              of the coherent platform facility</para>
          </listitem>

          <listitem>
            <para>uint64 operation: operation to perform to the coherent platform
              facility. Valid values are:
              <itemizedlist>
                <listitem>
                  <para>Reset: operation = 1, perform a reset to the coherent platform
                    function, this is used when the partition needs to reset the coherent
                    platform function to a clean state. All attached processes and state
                    are cleared by firmware after this reset.</para>
                </listitem>

                <listitem>
                  <para>Suspend Process: operation = 2, suspend a process from being
                    executed</para>
                </listitem>

                <listitem>
                  <para>Resume Process: operation = 3, resume a process to be executed</para>
                </listitem>

                <listitem>
                  <para>Read Error State: operation = 4, read the error state of the
                    coherent platform function</para>
                </listitem>

                <listitem>
                  <para>Get Error Buffer: operation = 5, collect the AFU error buffer
                    for the coherent platform function.</para>
                </listitem>

                <listitem>
                  <para>Get Function Configuration Record: operation = 6, collect
                    configuration record for the coherent platform function</para>
                </listitem>

                <listitem>
                  <para>Get Function Download Status: operation = 7, query to return
                    download status of a programmable coherent platform function.</para>
                </listitem>

                <listitem>
                  <para>Terminate Process: operation = 8, terminate the process
                    before completion</para>
                </listitem>

                <listitem>
                  <para>Collect VPD: operation = 9, collect VPD for the coherent
                    platform function.</para>
                </listitem>

                <listitem>
                  <para>Get Function Error Interrupts: operation = 11, read the
                    function-wide error data based on an interrupt from
                    <emphasis role="bold"><literal>&#8220;ibm,function-error-interrupt&#8221;</literal></emphasis></para>
                </listitem>

                <listitem>
                  <para>Acknowledge Function Error Interrupts: operation = 12,
                    acknowledge function-wide error data based on an interrupt from
                    <emphasis role="bold"><literal>&#8220;ibm,function-error-interrupt&#8221;</literal></emphasis></para>
                </listitem>

                <listitem>
                  <para>Get Error Log: operation = 13, retrieve the Platform Log ID
                    (PLID) of an error log containing error data for the coherent
                    platform function. This is used after a Temporary Unavailable or
                    Permanently Unavailable Error State.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>uint64 parameter1: parameter 1 for operations, meaning changes based on the operation.</para>
          </listitem>

          <listitem>
            <para>uint64 parameter2: parameter 2 for operations, meaning changes based on the operation.</para>
          </listitem>

          <listitem>
            <para>uint64 parameter3: parameter 3 for operations, meaning changes based on the operation.</para>
          </listitem>

          <listitem>
            <para>uint64 parameter4: parameter 4 for operations, meaning changes based on the operation.</para>
          </listitem>

          <listitem>
            <para>uint64 continue-token: Used to continue an operation if H_Busy is returned.
              Set to zero on first call. If H_Busy is returned then call again but use the value
              returned in R4 from the previous call as the value of continue-token.

              <informaltable frame="all" pgwide="1">
                <tgroup cols="2">
                  <colspec colname="c1" colwidth="20*" align="center" />
                  <colspec colname="c2" colwidth="80*" />
                  <thead valign="middle">
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Operation</emphasis>
                        </para>
                      </entry>
                      <entry align="center">
                        <para>
                          <emphasis role="bold">Parameters</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody valign="middle">
                    <row>
                      <entry>
                        <para>Reset</para>
                      </entry>
                      <entry>
                        <para>None</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Suspect Process</para>
                      </entry>
                      <entry>
                        <para>
                          <itemizedlist spacing="compact">
                            <listitem>
                              <para>Parameter1 = process-token as returned from
                                H_ATTACH_CA_PROCESS when process was attached.</para>
                            </listitem>
                          </itemizedlist>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Resume Process</para>
                      </entry>
                      <entry>
                        <para>
                          <itemizedlist spacing="compact">
                            <listitem>
                              <para>Parameter1 = process-token as returned from
                                H_ATTACH_CA_PROCESS when process was attached.</para>
                            </listitem>
                          </itemizedlist>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Read Error State</para>
                      </entry>
                      <entry>
                        <para>None</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Get Error Buffer</para>
                      </entry>
                      <entry>
                        <para>
                          <itemizedlist spacing="compact">
                            <listitem>
                              <para>Parameter1 = byte offset into error buffer to retrieve,
                                valid values are between 0 and (ibm,error-buffer-size – 1)</para>
                            </listitem>
                            <listitem>
                              <para>Parameter2 = 4K aligned real address of error buffer,
                                to be filled in</para>
                            </listitem>
                            <listitem>
                              <para>Parameter3 = length of error buffer, valid values are
                                4K or less</para>
                            </listitem>
                          </itemizedlist>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Get Functional Configuration Record</para>
                      </entry>
                      <entry>
                        <para>
                          <itemizedlist spacing="compact">
                            <listitem>
                              <para>Parameter1 = # of configuration record to retrieve,
                                valid values are between 0 and (ibm,#config-records – 1)</para>
                            </listitem>
                            <listitem>
                              <para>Parameter2 = byte offset into configuration record
                                to retrieve, valid values are between 0 and
                                (ibm,config-record-size – 1)</para>
                            </listitem>
                            <listitem>
                              <para>Parameter3 = 4K aligned real address of configuration
                                record buffer, to be filled in</para>
                            </listitem>
                            <listitem>
                              <para>Parameter4 = length of configuration buffer, valid values are 4K or less</para>
                            </listitem>
                          </itemizedlist>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Get Function Download Status</para>
                      </entry>
                      <entry>
                        <para>None</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Terminate Process</para>
                      </entry>
                      <entry>
                        <para>
                          <itemizedlist spacing="compact">
                            <listitem>
                              <para>Parameter1 = process-token as returned from
                                H_ATTACH_CA_PROCESS when process was attached.</para>
                            </listitem>
                          </itemizedlist>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Collect VPD</para>
                      </entry>
                      <entry>
                        <para>
                          <itemizedlist spacing="compact">
                            <listitem>
                              <para>Parameter1 = # of VPD record to retrieve, valid
                                values are between 0 and (ibm,#config-records – 1)</para>
                            </listitem>
                            <listitem>
                              <para>Parameter2 = 4K naturally aligned real buffer
                                containing scatter/gather list entries. All fields in the scatter/gather list have big-endian byte ordering.</para>
                            </listitem>
                            <listitem>
                              <para>Parameter3 = number of entries in the scatter/gather
                                list, valid values are between 0 and 256</para>
                            </listitem>
                          </itemizedlist>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Get Function Error Interrupts</para>
                      </entry>
                      <entry>
                        <para>None</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Acknowledge Function Error Interrupts</para>
                      </entry>
                      <entry>
                        <para>
                          <itemizedlist spacing="compact">
                            <listitem>
                              <para>Parameter1 = value to write to the function-wide
                                error interrupt register</para>
                            </listitem>
                          </itemizedlist>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Get Error Log</para>
                      </entry>
                      <entry>
                        <para>None</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </informaltable>
            </para>
          </listitem>
        </itemizedlist>
      </simplesect>

      <simplesect>
        <title>Semantics:</title>
        <itemizedlist>
          <listitem>
            <para>Verify that coherent platform facilities are licensed to be used,
              else return H_Authority.</para>
          </listitem>

          <listitem>
            <para>Verify that the unit-address parameter is valid else return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>If operation is Reset:
              <itemizedlist>
                <listitem>
                  <para>If coherent platform function is in Temporarily Unavailable or
                    Permanently Unavailable error state or is already performing a reset,
                    return H_State.</para>
                </listitem>

                <listitem>
                  <para>If partition is not allowed to perform a Reset
                    (<emphasis role="bold"><literal>&#8220;ibm,privileged-function&#8221;</literal></emphasis>
                    property is 0 or not present), return H_Authority.</para>
                </listitem>

                <listitem>
                  <para>If coherent platform function has
                    <emphasis role="bold"><literal>&#8220;ibm,process-mmio&#8221;</literal></emphasis>
                    property set to 1 and partition has any page table mappings existing
                    for the function, return H_Resource.</para>
                </listitem>

                <listitem>
                  <para>If coherent platform function is in Normal error state, set to
                    Disabled error state.</para>
                </listitem>

                <listitem>
                  <para>Terminate and remove all process elements that were attached
                    via H_ATTACH_CA_PROCESS. If the termination takes longer than is
                    allowed for an hcall, R4 is set to the continue-token and H_Busy
                    or H_LongBusy are returned.</para>
                </listitem>

                <listitem>
                  <para>If allowed, perform a reset (disable AFU, PSL suspend, PSL
                    purge, TLB invalidate, SLB invalidate) of the coherent platform
                    function using CAIA procedures. If the reset takes longer than
                    is allowed for an hcall, R4 is set to the continue-token and H_Busy
                    or H_LongBusy are returned.</para>
                </listitem>

                <listitem>
                  <para>After the reset, if the coherent-platform-function has the
                    <emphasis role="bold"><literal>&#8220;ibm,programmable&#8221;</literal></emphasis>
                    property set to 1, a download is required via H_DOWNLOAD_CA_FUNCTION.
                    The Get Function Download Status operation can be used to query
                    the download state.</para>
                </listitem>

                <listitem>
                  <para>If the coherent-platform-function does not have the
                    <emphasis role="bold"><literal>&#8220;ibm,programmable&#8221;</literal></emphasis>
                    property or it is set to 0, the AFU is enabled.</para>
                </listitem>

                <listitem>
                  <para>If the reset fails while communicating with the hardware,
                    return H_Hardware.</para>
                </listitem>

                <listitem>
                  <para>Reset the error log data for the Get Error Log operation.</para>
                </listitem>

                <listitem>
                  <para>Set coherent platform function Error State to Normal and
                    return H_Success</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If operation is Suspend Process:
              <itemizedlist>
                <listitem>
                  <para>If the coherent platform function is not in a Normal Error State,
                    return H_State.</para>
                </listitem>

                <listitem>
                  <para>If the coherent platform function does not support suspending
                    processes, return H_Function.</para>
                </listitem>

                <listitem>
                  <para>If the process associated with the process token cannot be found,
                    return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If the process is not able to be suspended or is already suspended,
                    return H_State.</para>
                </listitem>

                <listitem>
                  <para>The process associated with the process-token is suspended via
                    the procedure defined in the CAIA. If the suspend takes longer
                    than is allowed for an hcall, R4 is set to the continue-token and
                    H_Busy or H_LongBusy are returned.</para>
                </listitem>

                <listitem>
                  <para>If the Suspend Process procedure encounters a hardware failure,
                    return H_Hardware.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If operation is Resume Process:
              <itemizedlist>
                <listitem>
                  <para>If the coherent platform function is not in a Normal Error State,
                    return H_State.</para>
                </listitem>

                <listitem>
                  <para>If the coherent platform function does not support resuming
                    processes, return H_Function.</para>
                </listitem>

                <listitem>
                  <para>If the process associated with the process token cannot be found,
                    return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If the process not suspended or resume isn't possible, return
                    H_State.</para>
                </listitem>

                <listitem>
                  <para>The process associated with the process-token is resumed via
                    the procedure defined in the CAIA. If the resume takes longer than
                    is allowed for an hcall, R4 is set to the continue-token and H_Busy
                    or H_LongBusy are returned.</para>
                </listitem>

                <listitem>
                  <para>If a hardware error occurs during the Resume Process operation,
                    return H_Hardware.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If operation is Read Error State:
              <itemizedlist>
                <listitem>
                  <para>Platform firmware checks the error state of the coherent platform
                    function. If already in an error state, H_Success is returned and
                    R4 contains the error state.</para>
                </listitem>

                <listitem>
                  <para>Platform firmware checks for errors on the coherent platform
                    function. If errors exist, error recovery is entered and H_Success
                    is returned and R4 contains the error state.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If operation is Get Error Buffer:
              <itemizedlist>
                <listitem>
                  <para>If parameter2 does not describe a valid 4K aligned real address,
                    return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If parameter3 is greater than 4K, return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If parameter1 plus parameter3 is greater than or equal to
                    <emphasis role="bold"><literal>&#8220;ibm,error-buffer-size&#8221;</literal></emphasis>,
                    return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If the coherent platform function is in a Temporarily Unavailable
                    or Permanently Unavailable state, return H_State.</para>
                </listitem>

                <listitem>
                  <para>Platform firmware collects the error data buffer from the AFU
                    descriptor associated with the coherent platform function and places
                    it in the partition buffer described by parameter2 and parameter3.</para>
                </listitem>

                <listitem>
                  <para>If the Get Error Buffer operation exceeds the time allowed for
                    an hcall, R4 is set to the continue-token and H_Busy or H_LongBusy
                    is returned.</para>
                </listitem>

                <listitem>
                  <para>If the error buffer cannot be read from the hardware due to a
                    hardware problem, return H_Hardware.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If operation is Get Function Configuration Record:
              <itemizedlist>
                <listitem>
                  <para>If parameter1 does not describe a valid configuration record number,
                    return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If parameter3 does not describe a valid 4K aligned real address,
                    return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If parameter4 is greater than 4K, return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If parameter2 plus parameter4 is greater than or equal to
                    “ibm,config-record-size”,
                    return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If the coherent platform function is not in a Normal Error State,
                    return H_State.</para>
                </listitem>

                <listitem>
                  <para>If platform firmware cannot retrieve the configuration record
                    from the coherent platform function, return H_Function.</para>
                </listitem>

                <listitem>
                  <para>If platform firmware cannot retrieve the configuration record
                    due to the coherent platform function not in a downloaded state, r
                    eturn H_NOT_AVAILABLE.</para>
                </listitem>

                <listitem>
                  <para>Platform firmware collects the configuration record from the
                    coherent platform function and places it in the partition buffer
                    described by parameter3 and parameter4. The data is stored as a
                    byte stream; the first byte in the buffer corresponds to byte 0 of
                    the configuration record.</para>
                </listitem>

                <listitem>
                  <para>If the Get Function Configuration Record operation exceeds the
                    time allowed for an hcall, R4 is set to the continue-token and
                    H_Busy or H_LongBusy is returned.</para>
                </listitem>

                <listitem>
                  <para>If the configuration record cannot be read from the hardware,
                    due to a hardware problem, return H_Hardware.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If operation is Get Function Download Status:
              <itemizedlist>
                <listitem>
                  <para>If coherent platform function does not support download,
                    return H_Function.</para>
                </listitem>

                <listitem>
                  <para>If the partition does not have the authority to get download status
                    (<emphasis role="bold"><literal>&#8220;ibm,privilegedfunction&#8221;</literal></emphasis>
                    property is 0 or not present), return H_Authority.</para>
                </listitem>

                <listitem>
                  <para>If the coherent platform function is not in a Normal or
                    Disabled Error State, return H_State.</para>
                </listitem>

                <listitem>
                  <para>Platform firmware returns the download status in R4, where
                    0 = no-download-found and 1 = download-found.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If operation is Terminate Process:
              <itemizedlist>
                <listitem>
                  <para>If the coherent platform function is not in a Normal Error State,
                    return H_State.</para>
                </listitem>

                <listitem>
                  <para>If the coherent platform function does not support terminating
                    processes, return H_Function.</para>
                </listitem>

                <listitem>
                  <para>If the process associated with the process token cannot be found,
                    return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If the process has already completed, return H_State.</para>
                </listitem>

                <listitem>
                  <para>The process associated with the process-token is terminated
                    via the procedure defined in the CAIA. If the attempt to terminate
                    the process takes longer than is allowed for an hcall, R4 is set
                    to the continue-token and H_Busy or H_LongBusy are returned.</para>
                </listitem>

                <listitem>
                  <para>If a hardware error occurs during the Terminate Process operation,
                    return H_Hardware.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If the operation is Collect VPD:
              <itemizedlist>
                <listitem>
                  <para>If parameter1 does not describe a valid VPD record number,
                    return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If parameter2 does not describe a valid 4K aligned real address,
                    return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If parameter3 is greater than 256, return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If a scatter/gather list entry specifies an invalid address, or
                    specifies a buffer that crosses a page boundary, return H_SG_LIST.</para>
                </listitem>

                <listitem>
                  <para>If the coherent platform function is not in a Normal Error State,
                    return H_State.</para>
                </listitem>

                <listitem>
                  <para>If platform firmware cannot retrieve the VPD from the coherent
                    platform function, return H_Function.</para>
                </listitem>

                <listitem>
                  <para>If platform firmware cannot retrieve the VPD due to the coherent
                    platform function not in a downloaded state, return H_NOT_AVAILABLE.</para>
                </listitem>

                <listitem>
                  <para>Platform firmware collects the VPD from the coherent platform
                    function and places it in the partition buffer described by parameter2
                    and parameter3. The data will be truncated as necessary to fit in the
                    provided buffer. The data is stored as a bytestream; the first byte
                    in the buffer corresponds to byte 0 of the VPD.</para>
                </listitem>

                <listitem>
                  <para>If the Collect VPD operation exceeds the time allowed for an hcall,
                    R4 is set to the continue-token and H_Busy or H_LongBusy is returned.</para>
                </listitem>

                <listitem>
                  <para>If a hardware error occurs during the Collect VPD operation, r
                    eturn H_Hardware.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success, and R4 is set to the length of the available
                    VPD, which may be different than the amount of data actually stored
                    in the partition buffer. It may also be different than the value
                    reported in the
                    <emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis>
                    property, though it will not be greater than that. A length of
                    0 means no VPD has been provided for the coherent platform function.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If the operation is Get Function Error Interrupts:
              <itemizedlist>
                <listitem>
                  <para>If the coherent platform function is not in a Normal Error or
                    Disabled State, return H_State.</para>
                </listitem>

                <listitem>
                  <para>If the coherent platform function does not support Get Function
                    Error Interrupts, return H_Function.</para>
                </listitem>

                <listitem>
                  <para>If the Function Error Interrupts cannot be retrieved from the
                    hardware, return H_Hardware.</para>
                </listitem>

                <listitem>
                  <para>Platform firmware returns the value of Function Error Interrupts
                    read from hardware in R4.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If the operation is Acknowledge Function Error Interrupts:
              <itemizedlist>
                <listitem>
                  <para>If the coherent platform function is not in a Normal or Disabled
                    Error State, return H_State.</para>
                </listitem>

                <listitem>
                  <para>If the coherent platform function does not support Acknowledge
                    Function Error Interrupts, return H_Function. </para>
                </listitem>

                <listitem>
                  <para>Acknowledge Function Error Interrupts using the value in
                    parameter1.</para>
                </listitem>

                <listitem>
                  <para>If the Acknowledge Function Error Interrupts cannot be sent
                    to the hardware, return H_Hardware.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If operation is Get Error Log:
              <itemizedlist>
                <listitem>
                  <para>If the coherent platform function is not in Disabled or
                    Permanently Unavailable Error State, return H_State.</para>
                </listitem>

                <listitem>
                  <para>If applicable, platform firmware writes the Platform Log ID
                    (PLID) in R4 for the error log that is associated with the cause
                    of the Temporarily Unavailable or Permanently Unavailable Error State.
                    This data is used to correlate errors between the platform owned
                    resource and the coherent platform function. If there is no
                    associated error log to reference, platform firmware writes zero to R4.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If operation is unknown, return H_Not_Found.</para>
          </listitem>
        </itemizedlist>
      </simplesect>
    </section>

    <section xml:id="sec_collect_ca_int_info">
      <title>H_COLLECT_CA_INT_INFO</title>
      <para>The architectural intent of this hcall is to collect interrupt info about
        a coherent platform function after an interrupt occurred.</para>

      <simplesect>
        <title>Syntax:</title>
        <programlisting><![CDATA[int64                 /* H_Success:   The interrupt info is returned in return */
                      /*              registers. */
                      /* H_Parameter: An incorrect parameter was supplied. */
                      /* H_Hardware:  A hardware event prevented the collection of */
                      /*              the interrupt info. */
                      /* H_State:     The coherent platform function is not in a */
                      /*              valid state to collect interrupt info. */
                      /* H_Authority: The partition does not have authority to */
                      /*              perform this hcall; the coherent platform */
                      /*              facilities may need to be licensed. */
hcall ( const uint64 H_COLLECT_CA_INT_INFO,
        uint64 unit-address,
        uint64 process-token);]]></programlisting>
      </simplesect>

      <simplesect>
        <title>Parameters:</title>
        <itemizedlist>
          <listitem>
            <para>uint64 unit-address: Unit Address per the device tree
              <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property
              of the coherent platform facility</para>
          </listitem>

          <listitem>
            <para>uint64 process-token: process identifier token for the attached
              process returned in R4 on H_Success return from H_ATTACH_CA_PROCESS call.</para>
          </listitem>
        </itemizedlist>
      </simplesect>

      <simplesect>
        <title>Return Values:</title>
        <itemizedlist>
          <listitem>
            <para>R4 contains the PSL_DSISR_An register value defined in the CAIA on
              H_Success.</para>
          </listitem>

          <listitem>
            <para>R5 contains the PSL_DAR_An register value defined in the CAIA on
              H_Success.</para>
          </listitem>

          <listitem>
            <para>R6 contains the PSL_DSR_An register value defined in the CAIA on
              H_Success.</para>
          </listitem>

          <listitem>
            <para>R7 contains the PSL_PID_An in the upper 32 bits and PSL_TID_An
              register in the lower 32 bits.</para>
          </listitem>

          <listitem>
            <para>R8 contains the AFU_ERR_An register value defined in the CAIA on
              H_Success.</para>
          </listitem>

          <listitem>
            <para>R9 contains the PSL_ErrStat_An register value defined in the
              CAIA on H_Success.</para>
          </listitem>

          <listitem>
            <para>R10 contains a handle for the process element that incurred
              the fault on H_Success.</para>
          </listitem>
        </itemizedlist>
      </simplesect>

      <simplesect>
        <title>Semantics:</title>
        <itemizedlist>
          <listitem>
            <para>Verify that coherent platform facilities are licensed to be used,
              else return H_Authority.</para>
          </listitem>

          <listitem>
            <para>Verify that the unit-address parameter is valid else return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>Verify that the process-token parameter is valid else return
              H_Parameter.</para>
          </listitem>

          <listitem>
            <para>Verify that the coherent platform function is in the proper state
              to read interrupt information else return H_State.</para>
          </listitem>

          <listitem>
            <para>Platform firmware reads the values of PSL_DSISR_An, PSL_DAR_An,
              PSL_DSR_An, PSL_DSR_An, PSL_PID_An, PSL_TID_An, AFU_ERR_An and
              PSL_ErrStat_An as defined by the CAIA and populates the return registers.
              AFU_ERR_An value is only valid if PSL_DSISR[AE] is 1 or PSL_SERR_An[AE]
              is 1. PSL_ErrStat_An value is only valid if PSL_DSISR[PE] is 1. If any
              of the reads fail from the hardware H_Hardware is returned and none of
              the return registers should be considered valid.</para>
          </listitem>

          <listitem>
            <para>H_Success is returned.</para>
          </listitem>
        </itemizedlist>
      </simplesect>
    </section>

    <section xml:id="sec_control_ca_faults">
      <title>H_CONTROL_CA_FAULTS</title>
      <para>The architectural intent of this hcall is to control the operation of a
        coherent platform function after a fault occurs.</para>

      <simplesect>
        <title>Syntax:</title>
        <programlisting><![CDATA[int64                 /* H_Success:   Faults were successfully controlled for the */
                      /*              function. */
                      /* H_Parameter: An incorrect parameter was supplied. */
                      /* H_Hardware:  A hardware event prevented the control of */
                      /*              faults. */
                      /* H_State:     The function was in an invalid state. */
                      /* H_Authority: The partition does not have authority to */
                      /*              perform this hcall; the coherent platform */
                      /*              facilities may need to be licensed. */
                      /* H_Function:  The function is not supported. */
                      /* H_Not_Found: The operation supplied was not valid. */
hcall ( const uint64 H_CONTROL_CA_FAULTS,
        uint64 unit-address,
        uint64 operation,
        uint64 operation,
        uint64 parameter1,
        uint64 parameter2,
        uint64 parameter3,
        uint64 parameter4);]]></programlisting>
      </simplesect>

      <simplesect>
        <title>Parameters:</title>
        <itemizedlist>
          <listitem>
            <para>uint64 unit-address: Unit Address per the device tree
              <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property
              of the coherent platform facility</para>
          </listitem>

          <listitem>
            <para>uint64 operation: operation to perform to the coherent platform
              facility. Valid values are:
              <itemizedlist>
                <listitem>
                  <para>Respond to page fault - PSL: operation = 1.</para>
                </listitem>

                <listitem>
                  <para>Respond to page fault - AFU: operation = 2.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>uint64 parameter1: parameter 1 for operations, meaning changes based on the operation.</para>
          </listitem>

          <listitem>
            <para>uint64 parameter2: parameter 2 for operations, meaning changes based on the operation.</para>
          </listitem>

          <listitem>
            <para>uint64 parameter3: parameter 3 for operations, meaning changes based on the operation.</para>
          </listitem>

          <listitem>
            <para>uint64 parameter4: parameter 4 for operations, meaning changes based on the operation.</para>
          </listitem>
        </itemizedlist>

        <informaltable frame="all" pgwide="1">
          <tgroup cols="2">
            <colspec colname="c1" colwidth="20*" align="center" />
            <colspec colname="c2" colwidth="80*" />
            <thead valign="middle">
              <row>
                <entry>
                  <para>
                    <emphasis role="bold">Operation</emphasis>
                  </para>
                </entry>
                <entry align="center">
                  <para>
                    <emphasis role="bold">Parameters</emphasis>
                  </para>
                </entry>
              </row>
            </thead>
            <tbody valign="middle">
              <row>
                <entry>
                  <para>Respond to page fault - PSL</para>
                </entry>
                <entry>
                  <para>
                    <itemizedlist spacing="compact">
                      <listitem>
                        <para>Parameter1 = process-token as returned from H_ATTACH_CA_PROCESS</para>
                      </listitem>
                      <listitem>
                        <para>Parameter2 = control-mask
                          <itemizedlist spacing="compact">
                            <listitem>
                              <para>bits 0-59: reserved</para>
                            </listitem>
                            <listitem>
                              <para>bit 60: acknowledge non-translation fault interrupt</para>
                            </listitem>
                            <listitem>
                              <para>bit 61: continue execution, current translation
                                fault is not resolved and must be retried at a later time</para>
                            </listitem>
                            <listitem>
                              <para>bit 62: restart function and indicate address error</para>
                            </listitem>
                            <listitem>
                              <para>bit 63: restart the transaction that caused the
                                translation fault</para>
                            </listitem>
                          </itemizedlist>
                        </para>
                      </listitem>
                      <listitem>
                        <para>Parameter3 = reset-mask
                          <itemizedlist spacing="compact">
                            <listitem>
                              <para>bit 0-62: reserved</para>
                            </listitem>
                            <listitem>
                              <para>bit 63: reset fault bits for a PSL level process
                                error (PSL_DSISR_An[PE] is set)</para>
                            </listitem>
                          </itemizedlist>
                        </para>
                      </listitem>
                    </itemizedlist>
                  </para>
                </entry>
              </row>
              <row>
                <entry>
                  <para>Respond to page fault - AFU</para>
                </entry>
                <entry>
                  <para>
                    <itemizedlist spacing="compact">
                      <listitem>
                        <para>Parameter1 = process-token</para>
                      </listitem>
                      <listitem>
                        <para>Parameter2 = process element handle returned from
                          H_COLLECT_CA_INT_INFO.</para>
                      </listitem>
                      <listitem>
                        <para>Parameter3 = effective address</para>
                      </listitem>
                      <listitem>
                        <para>Parameter4 = resolution, valid values are:
                          <itemizedlist spacing="compact">
                            <listitem>
                              <para>0x0 -- Page Fault Resolved</para>
                            </listitem>
                            <listitem>
                              <para>0x1 -- Addressing Error</para>
                            </listitem>
                            <listitem>
                              <para>0x2 -- Protection Fault on a Read operation</para>
                            </listitem>
                            <listitem>
                              <para>0x3 -- Protection Fault on a Write operation</para>
                            </listitem>
                          </itemizedlist>
                        </para>
                      </listitem>
                    </itemizedlist>
                  </para>
                </entry>
              </row>
            </tbody>
          </tgroup>
        </informaltable>

      </simplesect>
      <simplesect>
        <title>Semantics:</title>
        <itemizedlist>
          <listitem>
            <para>Verify that coherent platform facilities are licensed to be used,
              else return H_Authority.</para>
          </listitem>

          <listitem>
            <para>Verify that the unit-address parameter is valid else return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>If operation is Respond to page fault - PSL:
              <itemizedlist>
                <listitem>
                  <para>Verify that the process-token parameter is valid else return
                    H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>Verify that the coherent platform function is in a valid state
                    else return H_State.</para>
                </listitem>

                <listitem>
                  <para>Using the control-mask set the corresponding bits in
                    PSL_TFC_An as defined by CAIA. Only bits that are set are written.
                    If no bits are set, no changes are performed. If the setting of
                    the bits in the hardware encounters an error, return H_Hardware.</para>
                </listitem>

                <listitem>
                  <para>If bit 63 of the reset-mask is set, clear the PSL_ErrStat_An
                    bits by reading the register and writing back the value read. If
                    this operation encounters an error with the hardware, return
                    H_Hardware.</para>
                </listitem>

                <listitem>
                  <para>Perform a read from PSL_TFC_An and place corresponding values
                    in R4. If the read fails, return H_Hardware.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success with the following in R4:
                    <itemizedlist>
                      <listitem>
                        <para>bits 0-60: reserved</para>
                      </listitem>

                      <listitem>
                        <para>bit 61: function waiting to continue </para>
                      </listitem>

                      <listitem>
                        <para>bit 62: address error pending</para>
                      </listitem>

                      <listitem>
                        <para>bit 63: command reissue pending</para>
                      </listitem>
                    </itemizedlist>
                  </para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If operation is Respond to page fault - PSL:
              <itemizedlist>
                <listitem>
                  <para>Verify that the process-token parameter is valid else return
                    H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>Verify that the resolution parameter is valid else return
                    H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>Verify that the coherent platform function is in a valid state
                    else return H_State.</para>
                </listitem>

                <listitem>
                  <para>Verify that the coherent platform function supports paged
                    resolution response (via
                    <emphasis role="bold"><literal>&#8220;ibm,supports-prr&#8221;</literal></emphasis>
                     OF property), else return H_Function.</para>
                </listitem>

                <listitem>
                  <para>Write the effective address and resolution to the corresponding
                    fields in the PRR registers of the AFU. If this operation encounters
                    an error with the hardware, return H_Hardware.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>
          <listitem>
            <para>If operation is unknown, return H_Not_Found.</para>
          </listitem>
        </itemizedlist>
      </simplesect>
    </section>

    <section xml:id="sec_download_ca_function">
      <title>H_DOWNLOAD_CA_FUNCTION</title>
      <para>The architectural intent of this hcall is to provide platform support for
        downloading an application image to the coherent platform function. The
        partition provides download data to the platform via an image scatter/gather
        list. The scatter/gather list can architecturally describe up to 1 megabyte
        of data (256 entries of 4096 bytes each). The OS must subdivide the application
        image into chunks that are each 1 megabyte or less in size, and call H
        _DOWNLOAD_CA_FUNCTION for each of those chunks.</para>

      <simplesect>
        <title>Syntax:</title>
        <programlisting><![CDATA[int64                 /* H_Success:   This download operation completed */
                      /*              successfully, and the entire image has now */
                      /*              been downloaded and verified. */
                      /* H_Parameter: An incorrect parameter was supplied. */
                      /* H_Hardware:  A hardware event prevented the operation. */
                      /* H_Function:  The function is not supported. */
                      /* H_State:     The coherent platform facility is not in a */
                      /*              valid state. */
                      /* H_Resource:  The coherent platform facility cannot be */
                      /*              downloaded due to a resource restriction. */
                      /* H_Authority: The partition does not have authority to */
                      /*              download or the coherent platform facilities */
                      /*              are not licensed to be used. */
                      /* H_CONTINUE : Platform firmware has completed consuming the */
                      /*              current image scatter/gather list, partition */
                      /*              may now supply new scatter/gather list. */
                      /* H_SG_LIST:   An entry in the scatter/gather list was */
                      /*              invalid. */
                      /* H_BAD_DATA:  Image verification failed. */
                      /* H_Busy or H_LongBusy: Platform firmware requires more time */
                      /*              to complete operation. */
                      /* H_UNSUPPORTED: Downloaded function is not compatible. */
hcall ( const uint64 H_DOWNLOAD_CA_FUNCTION,
        uint64 unit-address,
        uint64 operation,
        uint64 scatter-gather-list-address,
        uint64 num-scatter-gather-list-entries,
        uint64 continue-token);]]></programlisting>
      </simplesect>

      <simplesect>
        <title>Parameters:</title>
        <itemizedlist>
          <listitem>
            <para>uint64 unit-address: Unit Address per the device tree
              <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property
              of the coherent platform facility</para>
          </listitem>

          <listitem>
            <para>uint64 scatter-gather-list-address: 4K naturally aligned real buffer
              containing scatter/gather list entries. All fields in
              the scatter/gather list and all fields in the image header have
              big-endian byte ordering.</para>
          </listitem>

          <listitem>
            <para>uint64 num-scatter-gather-list-entries: number of entries
              in the scatter/gather list</para>
          </listitem>

          <listitem>
            <para>uint64 continue-token: Used to continue an operation if H_Busy or
              H_CONTINUE is returned. Set to zero on first call. If H_Busy or
              H_CONTINUE is returned then call again but use the value returned in
              R4 from the previous call as the value of continue-token.

              <table frame="all" pgwide="1" xml:id="table_image_scatter_gather_list_entry_format">
                <?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
                <title>Image Scatter/Gather List Entry Format</title>
                <tgroup cols="2">
                  <colspec colname="c1" colwidth="50*" />
                  <colspec colname="c2" colwidth="50*" />
                  <tbody valign="middle">
                    <row>
                      <entry>
                        <para>8 byte logical real address of buffer</para>
                      </entry>
                      <entry>
                        <para>8 byte buffer length in bytes (max length is 4096 bytes)</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>

              <table frame="all" pgwide="1" xml:id="table_image_scatter_gather_list_format">
                <?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
                <title>Image Scatter/Gather List Format</title>
                <tgroup cols="2">
                  <colspec colname="c1" colwidth="50*" />
                  <colspec colname="c2" colwidth="50*" />
                  <tbody valign="middle">
                    <row>
                      <entry>
                        <para>Logical real address of buffer 0</para>
                      </entry>
                      <entry>
                        <para>Buffer 0 length in bytes)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Logical real address of buffer 1</para>
                      </entry>
                      <entry>
                        <para>Buffer 1 length in bytes)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>...</para>
                      </entry>
                      <entry>
                        <para>...</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Logical real address of buffer N-1</para>
                      </entry>
                      <entry>
                        <para>Buffer N-1 length in bytes)</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Logical real address of buffer N</para>
                      </entry>
                      <entry>
                        <para>Buffer N length in bytes)</para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>

              <table frame="all" pgwide="1" xml:id="table_application_image_header_version1">
                <?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
                <title>Application Image Header, Version 1</title>
                <tgroup cols="4">
                  <colspec colname="c1" colwidth="25*" />
                  <colspec colname="c2" colwidth="10*" align="center" />
                  <colspec colname="c3" colwidth="10*" align="center" />
                  <colspec colname="c4" colwidth="55*" />
                  <thead valign="middle">
                    <row>
                      <entry align="center">
                        <para>
                          <emphasis role="bold">Name</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Offset</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Length</emphasis>
                        </para>
                      </entry>
                      <entry align="center">
                        <para>
                          <emphasis role="bold">Description</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody valign="middle">
                    <row>
                      <entry>
                        <para>Version</para>
                      </entry>
                      <entry>
                        <para>0</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>Version of the AFU image header, value = 1</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Function Number</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>Physical function number that the application uses</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Application ID</para>
                      </entry>
                      <entry>
                        <para>4</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>Application identifier</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Reserved</para>
                      </entry>
                      <entry>
                        <para>6</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>Set to zero.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Vendor ID</para>
                      </entry>
                      <entry>
                        <para>8</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>PCI Vendor ID of the adapter owning the coherent
                          platform function</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Device ID</para>
                      </entry>
                      <entry>
                        <para>10</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>PCI Device ID of the adapter owning the coherent
                          platform function</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Subsystem Vendor ID</para>
                      </entry>
                      <entry>
                        <para>12</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>PCI Subsystem Vendor ID of the adapter owning the coherent
                          platform function</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Subsystem ID</para>
                      </entry>
                      <entry>
                        <para>14</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>PCI Subsystem ID of the adapter owning the coherent
                          platform function</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Image Offset</para>
                      </entry>
                      <entry>
                        <para>16</para>
                      </entry>
                      <entry>
                        <para>8</para>
                      </entry>
                      <entry>
                        <para>Offset to the application image bitstream</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Image Length</para>
                      </entry>
                      <entry>
                        <para>24</para>
                      </entry>
                      <entry>
                        <para>8</para>
                      </entry>
                      <entry>
                        <para>Length of the application image bitstream</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Verification Type</para>
                      </entry>
                      <entry>
                        <para>32</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>Type of verification required for image:
                          <itemizedlist spacing="compact">
                            <listitem>
                              <para>1 = Bounds Check</para>
                            </listitem>
                            <listitem>
                              <para>All other values reserved</para>
                            </listitem>
                          </itemizedlist>
                        </para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Reserved</para>
                      </entry>
                      <entry>
                        <para>34</para>
                      </entry>
                      <entry>
                        <para>6</para>
                      </entry>
                      <entry>
                        <para>Set to zero</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>CAIA Version</para>
                      </entry>
                      <entry>
                        <para>40</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>Minimum CAIA Version required by this application image</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>PSL Revision</para>
                      </entry>
                      <entry>
                        <para>42</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>Minimum PSL Revision required by this application image</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Reserved</para>
                      </entry>
                      <entry>
                        <para>44</para>
                      </entry>
                      <entry>
                        <para>84</para>
                      </entry>
                      <entry>
                        <para>Set to zero</para>
                      </entry>
                    </row>
                    <row>
                      <entry namest='c1' nameend='c4'>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para><emphasis>Image Bitstream</emphasis></para>
                      </entry>
                      <entry>
                        <para><emphasis>X</emphasis></para>
                      </entry>
                      <entry>
                        <para><emphasis>Y</emphasis></para>
                      </entry>
                      <entry>
                        <para><emphasis>Application image bitstream, where X = Image
                          Offset and Y = Image Length</emphasis></para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>

            </para>
          </listitem>
        </itemizedlist>
      </simplesect>

      <simplesect>
        <title>Return Values:</title>
        <itemizedlist>
          <listitem>
            <para>R4 on H_Busy or H_LongBusy or H_CONTINUE contains the continue-token
              to be used on the next call</para>
          </listitem>
        </itemizedlist>
      </simplesect>

      <simplesect>
        <title>Semantics:</title>
        <itemizedlist>
          <listitem>
            <para>Verify that coherent platform facilities are licensed to be used,
              else return H_Authority.</para>
          </listitem>

          <listitem>
            <para>Verify that the unit-address parameter is valid else return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>If the coherent-platform-facility cannot be downloaded at this
              time due to a resource constraint, H_Resource is returned.</para>
          </listitem>

          <listitem>
            <para>If the coherent platform facility does not support download,
              return H_Function.</para>
          </listitem>

          <listitem>
            <para>If the coherent platform function is already downloaded, or if a
              download is in progress, return H_State.</para>
          </listitem>

          <listitem>
            <para>If the partition does not have the authority to perform download
              (<emphasis role="bold"><literal>&#8220;ibm,privileged-function&#8221;</literal></emphasis>
              property is 0 or not present), return H_Authority.</para>
          </listitem>

          <listitem>
            <para>If the coherent platform facility is in a Temporary Unavailable
              Error State or has attached processes, return H_State.</para>
          </listitem>

          <listitem>
            <para>If the scatter-gather-list-address does not describe a 4K byte
              naturally aligned buffer, return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>If the Application Image Header version is not supported by platform
              firmware, return H_BAD_DATA.</para>
          </listitem>

          <listitem>
            <para>If necessary, platform firmware disables the coherent platform facility
              from operation.</para>
          </listitem>

          <listitem>
            <para>For each entry in the scatter/gather list described by
              scatter-gather-list-address:
              <itemizedlist>
                <listitem>
                  <para>Platform firmware validates address and length in the scatter/gather
                    list entry. The buffer described should not cross a 4K page boundary.
                    If invalid, returns H_SG_LIST.</para>
                </listitem>

                <listitem>
                  <para>Platform firmware copies data from the scatter/gather list entry
                    to the platform firmware buffer.</para>
                </listitem>

                <listitem>
                  <para>Platform firmware verifies the image bitstream data chunk in the
                    platform buffer. If platform firmware determines the image bitstream
                    data chunk is not valid, return H_BAD_DATA. During this operation,
                    H_Busy or H_LongBusy can be returned due to hcall maximum time
                    limits, the partition should call back, until a non-busy return
                    code is returned.</para>
                </listitem>

                <listitem>
                  <para>Platform firmware performs the download for the
                  coherent platform facility, using the image bitstream data chunk.
                  During this operation, H_Busy or H_LongBusy can be returned due to
                  hcall maximum time limits, the partition should call again, until a
                  non-busy return code is returned.</para>
                </listitem>

                <listitem>
                  <para>If the coherent platform facility does not accept the download
                    of the image bitstream data chunk or an error occurs while
                    communicating with the hardware, H_Hardware is returned.</para>
                </listitem>

                <listitem>
                  <para>If hcall time limit is exceeded, but more data is left to
                    copy in the current scatter/gather list, H_Busy or H_LongBusy is
                    returned. The partition should call back with the current
                    scatter/gather list.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>Once every entry in the current scatter/gather list is copied,
              platform firmware returns H_CONTINUE. The partition then calls back
              with a new scatter/gather list for the next chunk of image data and the
              previous steps are repeated for each new list. This is repeated as long
              as H_CONTINUE is returned.</para>
          </listitem>

          <listitem>
            <para>The CAIA AFU descriptor is read for the downloaded AFU, if any
              fields in the AFU descriptor are not compatible with the PSL,
              H_UNSUPPORTED is returned.</para>
          </listitem>

          <listitem>
            <para>If the Download operation completes successfully, if necessary,
              platform firmware re-enables coherent platform function for operation.</para>
          </listitem>

          <listitem>
            <para>H_Success is returned.</para>
          </listitem>
        </itemizedlist>

        <note>
          <para>Any error in the above steps will cause the download to be aborted.
            The partition must retry H_DOWNLOAD_CA_FUNCTION, starting with the
            Application Image header in order to complete the download.</para>
        </note>
        <note>
          <para>After H_DOWNLOAD_CA_FUNCTION is performed, the partition should call
            <emphasis>ibm,update-nodes</emphasis> and <emphasis>ibm,update-properties</emphasis>
            to receive the current configuration for the coherent platform facility.</para>
        </note>
        <note>
          <para>When H_DOWNLOAD_CA_FUNCTION is first called, some AFU or adapter resources
            may be reserved for use during the download sequence, which may span
            multiple H_DOWNLOAD_CA_FUNCTION calls, until the image download is
            complete as indicated by a return of H_SUCCESS. When H_CONTINUE is returned,
            indicating that more data is needed for the complete AFU image, the OS must call
            H_DOWNLOAD_CA_FUNCTION again within 1 milliseconds, or the download sequence will
            be abandoned and the OS may need to reset the AFU and restart the
            download sequence from the beginning.</para>
        </note>
      </simplesect>
    </section>

    <section xml:id="sec_download_ca_facility">
      <title>H_DOWNLOAD_CA_FACILITY</title>

      <para>The architectural intent of this hcall is to provide platform support for
        downloading a base adapter image to the coherent platform facility, and for
        validating the entire image after the download. The partition provides download
        data to the platform via an image scatter/gather list. The scatter/gather list
        can architecturally describe up to 1 megabyte of data (256 entries of 4096
        bytes each). The OS must subdivide the base adapter image into chunks that are
        each 1 megabyte or less in size, and call H_DOWNLOAD_CA_FACILITY for each of
        those chunks.</para>
      <para>Base adapter image download requires two separate operations. The first is
        the download operation, which processes the entire image, possibly returning
        H_CONTINUE a number of times, and completing when H_Success is returned. The
        second is the validate operation, which again processes the entire image with
        a number of H_CONTINUE returns until it completes with H_Success. The base
        adapter image is not usable until both operations have completed successfully.</para>

      <simplesect>
        <title>Syntax:</title>
        <programlisting><![CDATA[int64                 /* H_Success:   For the download operation, the entire image */
                      /*              has now been downloaded and is ready for the */
                      /*              validate operation. For the validate */
                      /*              operation, the entire image has been validated */
                      /*              and will take effect the next time the adapter */
                      /*              loads the image */
                      /* H_Parameter: An incorrect parameter was supplied. */
                      /* H_Hardware:  A hardware event prevented the operation. */
                      /* H_Function:  The function is not supported. */
                      /* H_State:     The coherent platform facility is not in a */
                      /*              valid state. */
                      /* H_Resource:  The coherent platform facility cannot be */
                      /*              downloaded due to a resource restriction. */
                      /* H_Authority: The partition does not have authority to */
                      /*              download or the coherent platform facilities */
                      /*              are not licensed to be used. */
                      /* H_CONTINUE : Platform firmware has completed consuming the */
                      /*              current image scatter/gather list, partition */
                      /*              may now supply new scatter/gather list. */
                      /* H_SG_LIST:   An entry in the scatter/gather list was */
                      /*              invalid. */
                      /* H_BAD_DATA:  Image verification failed. */
                      /* H_Busy or H_LongBusy: Platform firmware requires more time */
                      /*              to complete operation. */
                      /* H_UNSUPPORTED: Downloaded function is not compatible. */
hcall ( const uint64 H_DOWNLOAD_CA_FACILITY,
        uint64 unit-address,
        uint64 operation,
        uint64 scatter-gather-list-address,
        uint64 num-scatter-gather-list-entries,
        uint64 continue-token);]]></programlisting>
      </simplesect>

      <simplesect>
        <title>Parameters:</title>
        <itemizedlist>
          <listitem>
            <para>uint64 unit-address: Unit Address per the device tree
              <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property
              of the coherent platform facility</para>
          </listitem>

          <listitem>
            <para>uint64 operation: operation to perform to the coherent platform
              facility. Valid values are:
              <itemizedlist>
                <listitem>
                  <para>Download: operation = 1, the base image in the coherent platform
                    facility is first erased, and then programmed using the image supplied
                    in the scatter/gather list.</para>
                </listitem>

                <listitem>
                  <para>Validate: operation = 2, the base image in the coherent platform
                    facility is compared with the image supplied in the scatter/gather list.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>uint64 scatter-gather-list-address: 4K naturally aligned real buffer
              containing scatter/gather list entries. The format of the scatter/gather
              list is the same as for the H_DOWNLOAD_CA_FUNCTION hcall. All fields in
              the scatter/gather list and all fields in the image header have
              big-endian byte ordering.</para>
          </listitem>

          <listitem>
            <para>uint64 num-scatter-gather-list-entries: number of block list entries
              in the scatter/gather list</para>
          </listitem>

          <listitem>
            <para>uint64 continue-token: Used to continue an operation if H_Busy or
              H_CONTINUE is returned. Set to zero on first call. If H_Busy or
              H_CONTINUE is returned then call again but use the value returned in
              R4 from the previous call as the value of continue-token.
              <table frame="all" pgwide="1" xml:id="table_base_adapter_image_header_version1">
                <?dbhtml table-width="80%" ?><?dbfo table-width="80%" ?>
                <title>Base Adapter Image Header, Version 1</title>
                <tgroup cols="4">
                  <colspec colname="c1" colwidth="25*" />
                  <colspec colname="c2" colwidth="10*" align="center" />
                  <colspec colname="c3" colwidth="10*" align="center" />
                  <colspec colname="c4" colwidth="55*" />
                  <thead valign="middle">
                    <row>
                      <entry align="center">
                        <para>
                          <emphasis role="bold">Name</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Offset</emphasis>
                        </para>
                      </entry>
                      <entry>
                        <para>
                          <emphasis role="bold">Length</emphasis>
                        </para>
                      </entry>
                      <entry align="center">
                        <para>
                          <emphasis role="bold">Description</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody valign="middle">
                    <row>
                      <entry>
                        <para>Version</para>
                      </entry>
                      <entry>
                        <para>0</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>Version of the base adapter image header, value = 1</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Reserved</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>6</para>
                      </entry>
                      <entry>
                        <para>Set to zero.</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Vendor ID</para>
                      </entry>
                      <entry>
                        <para>8</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>PCI Vendor ID of the coherent platform facility</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Device ID</para>
                      </entry>
                      <entry>
                        <para>10</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>PCI Device ID of the coherent platform facility</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Subsystem Vendor ID</para>
                      </entry>
                      <entry>
                        <para>12</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>PCI Subsystem Vendor ID of the coherent platform facility</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Subsystem ID</para>
                      </entry>
                      <entry>
                        <para>14</para>
                      </entry>
                      <entry>
                        <para>2</para>
                      </entry>
                      <entry>
                        <para>PCI Subsystem ID of the coherent platform facility</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Image Offset</para>
                      </entry>
                      <entry>
                        <para>16</para>
                      </entry>
                      <entry>
                        <para>8</para>
                      </entry>
                      <entry>
                        <para>Offset to the base adapter image bitstream</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Image Length</para>
                      </entry>
                      <entry>
                        <para>24</para>
                      </entry>
                      <entry>
                        <para>8</para>
                      </entry>
                      <entry>
                        <para>Length of the base adapter image bitstream</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Reserved</para>
                      </entry>
                      <entry>
                        <para>32</para>
                      </entry>
                      <entry>
                        <para>96</para>
                      </entry>
                      <entry>
                        <para>Set to zero</para>
                      </entry>
                    </row>
                    <row>
                      <entry namest='c1' nameend='c4'>
                        <para>&#160;</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para><emphasis>Image Bitstream</emphasis></para>
                      </entry>
                      <entry>
                        <para><emphasis>X</emphasis></para>
                      </entry>
                      <entry>
                        <para><emphasis>Y</emphasis></para>
                      </entry>
                      <entry>
                        <para><emphasis>Base adapter image bitstream, where X = Image
                          Offset and Y = Image Length</emphasis></para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </table>
            </para>
          </listitem>
        </itemizedlist>
      </simplesect>

      <simplesect>
        <title>Return Values:</title>
        <itemizedlist>
          <listitem>
            <para>R4 on H_Busy or H_LongBusy or H_CONTINUE contains the continue-token
              to be used on the next call</para>
          </listitem>
        </itemizedlist>
      </simplesect>

      <simplesect>
        <title>Semantics:</title>
        <itemizedlist>
          <listitem>
            <para>Verify that coherent platform facilities are licensed to be used,
              else return H_Authority.</para>
          </listitem>

          <listitem>
            <para>Verify that the unit-address parameter is valid else return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>If the coherent-platform-facility cannot be downloaded at this
              time due to a resource constraint, H_Resource is returned.</para>
          </listitem>

          <listitem>
            <para>If the coherent platform facility does not support download,
              return H_Function.</para>
          </listitem>

          <listitem>
            <para>If a download is in progress for the coherent
            platform facility, return H_State.</para>
          </listitem>

          <listitem>
            <para>If the partition does not have the authority to perform download
              (<emphasis role="bold"><literal>&#8220;ibm,privileged-function&#8221;</literal></emphasis>
              property is 0 or not present), return H_Authority.</para>
          </listitem>

          <listitem>
            <para>If the coherent platform facility is in a Temporary Unavailable E
              rror State, return H_State.</para>
          </listitem>

          <listitem>
            <para>If the scatter-gather-list-address does not describe a 4K byte
              naturally aligned buffer, return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>If the Base Adapter Image Header version is not supported by platform
              firmware, return H_BAD_DATA.</para>
          </listitem>

          <listitem>
            <para>If necessary, platform firmware disables the coherent platform facility
              from operation.</para>
          </listitem>

          <listitem>
            <para>For each entry in the scatter/gather list described by
              scatter-gather-list-address:
              <itemizedlist>
                <listitem>
                  <para>Platform firmware validates address and length in the scatter/gather
                    list entry. The buffer described should not cross a 4K page boundary.
                    If invalid, returns H_SG_LIST.</para>
                </listitem>

                <listitem>
                  <para>Platform firmware copies data from the scatter/gather list entry
                    to the platform firmware buffer.</para>
                </listitem>

                <listitem>
                  <para>Platform firmware verifies the image bitstream data chunk in the
                    platform buffer. If platform firmware determines the image bitstream
                    data chunk is not valid, return H_BAD_DATA. During this operation,
                    H_Busy or H_LongBusy can be returned due to hcall maximum time
                    limits, the partition should call back, until a non-busy return
                    code is returned.</para>
                </listitem>

                <listitem>
                  <para>Platform firmware performs the download or validate operation for the
                  coherent platform facility, using the image bitstream data chunk.
                  During this operation, H_Busy or H_LongBusy can be returned due to
                  hcall maximum time limits, the partition should call again, until a
                  non-busy return code is returned.</para>
                </listitem>

                <listitem>
                  <para>If the coherent platform facility does not accept the download
                    of the image bitstream data chunk or an error occurs while
                    communicating with the hardware, H_Hardware is returned.</para>
                </listitem>

                <listitem>
                  <para>If hcall time limit is exceeded, but more data is left to
                    copy in the current scatter/gather list, H_Busy or H_LongBusy is
                    returned. The partition should call back with the current
                    scatter/gather list.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>Once every entry in the current scatter/gather list is copied,
              platform firmware returns H_CONTINUE. The partition then calls back
              with a new scatter/gather list for the next chunk of image data and the
              previous steps are repeated for each new list. This is repeated as long
              as H_CONTINUE is returned.</para>
          </listitem>

          <listitem>
            <para>If the validate operation completes successfully, platform
              firmware re-enables coherent platform facility for operation if necessary.</para>
          </listitem>
          <listitem>
            <para>H_Success is returned.</para>
          </listitem>
        </itemizedlist>

        <note>
          <para>Any error in the above steps will cause the download to be aborted.
            To complete the download, the partition must retry both H_DOWNLOAD_CA_FACILITY
            operations, including the Base Adapter Image header for each operation.</para>
        </note>
        <note>
          <para>After H_DOWNLOAD_CA_FACILITY is performed, the partition should call
            <emphasis>ibm,update-nodes</emphasis> and <emphasis>ibm,update-properties</emphasis>
            to receive the current configuration for the functions under this
            coherent platform facility.</para>
        </note>
        <note>
          <para>When H_DOWNLOAD_CA_FACILITY is first called, some adapter resources
            may be reserved for use during the download sequence, which may span
            multiple H_DOWNLOAD_CA_FACILITY calls, until the image download is
            complete as indicated by a return of H_SUCCESS. When H_CONTINUE is returned,
            indicating that more data is needed for the complete image, the OS must call
            H_DOWNLOAD_CA_FACILITY again within 3 seconds, or the download sequence may
            be abandoned and the OS may need to reset the facility and restart the
            download sequence from the beginning.</para>
        </note>
      </simplesect>
    </section>

    <section xml:id="sec_control_ca_facility">
      <title>H_CONTROL_CA_FACILITY</title>
      <para>This H_CONTROL_CA_FACILITY hypervisor call allows the partition to manipulate
        or query certain coherent platform facility behaviors.</para>

      <simplesect>
        <title>Syntax:</title>
        <programlisting><![CDATA[int64                 /* H_Success:   The operation is completed for the coherent */
                      /*              platform facility */
                      /* H_Authority: The operating system does not have authority */
                      /*              to control the coherent platform facility or */
                      /*              the coherent platform facilities are not */
                      /*              licensed to be used. */
                      /* H_Parameter: An incorrect parameter was supplied. */
                      /* H_Hardware:  A hardware event prevented the control */
                      /*              operation. */
                      /* H_State:     The state was invalid for the operation. */
                      /* H_Busy or H_LongBusy: If the hcall requires more */
                      /*              execution time, Busy will be returned and */
                      /*              the OS is required to call back until Busy */
                      /*              is no longer returned. */
                      /* H_Not_Found: The operation supplied was not valid. */
                      /* H_SG_LIST:   A scatter/gather list entry was invalid. */
                      /* H_Function:  The function is not supported. */
                      /* R4 contains the continue-token for the next call on Busy */
                      /*    return code. */
                      /* R4 contains operation-specific data if applicable on */
                      /*    Success return code. */
hcall ( const uint64 H_CONTROL_CA_FACILITY,
        uint64 unit-address,
        uint64 operation,
        uint64 parameter1,
        uint64 parameter2,
        uint64 parameter3,
        uint64 parameter4,
        uint64 continue-token);]]></programlisting>
      </simplesect>

      <simplesect>
        <title>Parameters:</title>
        <itemizedlist>
          <listitem>
            <para>uint64 unit-address: Unit Address per the device tree
              <emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> property
              of the coherent platform facility</para>
          </listitem>

          <listitem>
            <para>uint64 operation: operation to perform to the coherent platform
              facility. Valid values are:
              <itemizedlist>
                <listitem>
                  <para>Reset: operation = 1, initiate a reset to the coherent platform
                    facility, this is used when the partition needs to reset the
                    coherent platform facility and all of its child coherent platform
                    functions to a clean state. All attached processes and state are
                    cleared by firmware after this reset. If a new base adapter image
                    has been downloaded, that image will be activated.</para>
                </listitem>

                <listitem>
                  <para>Collect VPD: operation = 2, collect VPD for the coherent
                    platform facility.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>uint64 parameter1: parameter 1 for operations, meaning changes based on the operation.</para>
          </listitem>

          <listitem>
            <para>uint64 parameter2: parameter 2 for operations, meaning changes based on the operation.</para>
          </listitem>

          <listitem>
            <para>uint64 parameter3: parameter 3 for operations, meaning changes based on the operation.</para>
          </listitem>

          <listitem>
            <para>uint64 parameter4: parameter 4 for operations, meaning changes based on the operation.</para>
          </listitem>

          <listitem>
            <para>uint64 continue-token: Used to continue an operation if H_Busy is returned.
              Set to zero on first call. If H_Busy is returned then call again but use the value
              returned in R4 from the previous call as the value of continue-token.

              <informaltable frame="all" pgwide="1">
                <tgroup cols="2">
                  <colspec colname="c1" colwidth="20*" align="center" />
                  <colspec colname="c2" colwidth="80*" />
                  <thead valign="middle">
                    <row>
                      <entry>
                        <para>
                          <emphasis role="bold">Operation</emphasis>
                        </para>
                      </entry>
                      <entry align="center">
                        <para>
                          <emphasis role="bold">Parameters</emphasis>
                        </para>
                      </entry>
                    </row>
                  </thead>
                  <tbody valign="middle">
                    <row>
                      <entry>
                        <para>Reset</para>
                      </entry>
                      <entry>
                        <para>None</para>
                      </entry>
                    </row>
                    <row>
                      <entry>
                        <para>Collect VPD</para>
                      </entry>
                      <entry>
                        <para>
                          <itemizedlist spacing="compact">
                            <listitem>
                              <para>Parameter1 = 4K naturally aligned real buffer containing
                                scatter/gather list entries. All fields in the scatter/gather
                                list have big-endian byte ordering.</para>
                            </listitem>
                            <listitem>
                              <para>Parameter2 = number of entries in the scatter/gather
                                list, valid values are between 0 and 256</para>
                            </listitem>
                          </itemizedlist>
                        </para>
                      </entry>
                    </row>
                  </tbody>
                </tgroup>
              </informaltable>
            </para>
          </listitem>
        </itemizedlist>
      </simplesect>

      <simplesect>
        <title>Semantics:</title>
        <itemizedlist>
          <listitem>
            <para>Verify that coherent platform facilities are licensed to be used, else
              return H_Authority.</para>
          </listitem>

          <listitem>
            <para>Verify that the unit-address parameter is valid else return H_Parameter.</para>
          </listitem>

          <listitem>
            <para>If operation is Reset:
              <itemizedlist>
                <listitem>
                  <para>If coherent platform facility is in Temporarily Unavailable error
                    state or is already performing a reset, return H_State.</para>
                </listitem>

                <listitem>
                  <para>If partition is not allowed to perform a Reset
                    (<emphasis role="bold"><literal>&#8220;ibm,privileged-facility&#8221;</literal></emphasis>
                    property is 0 or not present), return H_Authority.</para>
                </listitem>

                <listitem>
                  <para>Set Temporarily Unavailable error state for the coherent
                    platform facility and all child coherent platform functions.</para>
                </listitem>

                <listitem>
                  <para>Initiate reset of the coherent platform facility.</para>
                </listitem>

                <listitem>
                  <para>If the Reset operation exceeds the time allowed for an hcall,
                    R4 is set to the continue-token and H_Busy or H_LongBusy is returned.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If operation is Collect VPD:
              <itemizedlist>
                <listitem>
                  <para>If parameter1 does not describe a valid 4K aligned real address, return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If parameter2 is greater than 256, return H_Parameter.</para>
                </listitem>

                <listitem>
                  <para>If a scatter/gather list entry specifies an invalid address,
                    or specifies a buffer that crosses a page boundary, return H_SG_LIST.</para>
                </listitem>

                <listitem>
                  <para>If the coherent platform facility is not in a Normal Error State,
                    return H_State.</para>
                </listitem>

                <listitem>
                  <para>If platform firmware cannot retrieve the VPD from the coherent
                    platform facility, return H_Function.</para>
                </listitem>

                <listitem>
                  <para>Platform firmware collects the VPD from the coherent platform
                    facility and places it in the partition buffer described by
                    parameter1 and parameter2. The data will be truncated as necessary
                    to fit in the provided buffer. The data is stored as a bytestream;
                    the first byte in the buffer corresponds to byte 0 of the VPD.</para>
                </listitem>

                <listitem>
                  <para>If the Collect VPD operation exceeds the time allowed for an hcall,
                    R4 is set to the continue-token and H_Busy or H_LongBusy is returned.</para>
                </listitem>

                <listitem>
                  <para>If a hardware error occurs during the Collect VPD operation,
                    return H_Hardware.</para>
                </listitem>

                <listitem>
                  <para>Return H_Success, and R4 is set to the length of the available VPD,
                    which may be different than the amount of data actually stored in the
                    partition buffer. It may also be different than the value reported in the
                    <emphasis role="bold"><literal>&#8220;ibm,vpd-size&#8221;</literal></emphasis>
                    property, though it will not be greater than that. A length of 0
                    means no VPD has been provided for the coherent platform facility.</para>
                </listitem>
              </itemizedlist>
            </para>
          </listitem>

          <listitem>
            <para>If operation is unknown, return H_Not_Found.</para>
          </listitem>
        </itemizedlist>
      </simplesect>
    </section>
  </section>
</chapter>