XIVE Exploitation

Signed-off-by: Jeff Scheel <scheel@us.ibm.com>

DeviceTree/ch_devtree_system.xml

@@ -6824,8 +6824,19 @@
       <para>For LSIs, the platform shall adhere to the
       <xref linkend="dbdoclet.50569387_67880" /> interrupt structure OF
       representation.</para>
-
+      <para>PAPR may support one of two generations of interrupt controllers with
-      <section>
+        backward compatible firmware interfaces. The first generation interrupt
+        controller is represented per
+        <xref linkend="sec_powerpc_external_interrupt_controller_nodes" />
+        and its sub sections.
+        The second generation, External Interrupt Virtualization Engine is
+        represented either per
+        <xref linkend="sec_powerpc_external_interrupt_controller_nodes" />
+        when operated in Legacy Compatibility mode, or per
+        <xref linkend="sec_powerpc_external_interrupt_virtualization_engine_node" />
+        and its sub sections when operated in Exploitation mode.</para>
+
+      <section xml:id="sec_powerpc_external_interrupt_controller_nodes">
         <title>PowerPC External Interrupt Controller Nodes</title>
 
         <para>This section describes the properties for the PowerPC External
@@ -7177,6 +7188,130 @@
 
       </section>
 
+      <section xml:id="sec_powerpc_external_interrupt_virtualization_engine_node">
+        <title>PowerPC External Interrupt Virtualization Engine Nodes</title>
+
+        <para>This section describes the properties for the External Interrupt Virtualization
+          node. Interrupt controllers are normally packaged inside system chips, however,
+          they are logically represented in the device tree by the interrupt controller
+          node. This node reports the logical real addresses through which the client
+          program can manage the interrupt context for its physical processor thread.</para>
+
+        <para>Event source resources consist of either a single or pair of page addresses
+          associated with each individual event source that is allocated to the partition.
+          These addresses do not appear in the device tree; rather the platform provides
+          the hcall(), H_INT_GET_SOURCE_INFO.</para>
+
+        <para>At a dynamic reconfiguration event, such as adding or removing an IO adapter,
+          or processor, the associated
+          <emphasis role="bold"><literal>&#8220;int&#8221;</literal></emphasis>
+          property is added or removed from the partition
+          configuration and along with it the associated page addresses.</para>
+
+        <variablelist>
+          <varlistentry>
+            <term><emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> [S]</term>
+              <listitem>
+                <para>Standard
+                <emphasis>property name</emphasis> that denotes a PowerPC External
+                Interrupt Controller.</para>
+                <para><emphasis>prop-encoded-array</emphasis>: A string, encoded as with
+                <emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
+                <para>The value of this string shall be
+                <literal>&#8220;interrupt-controller&#8221;</literal>.</para>
+              </listitem>
+  			  </varlistentry>
+
+          <varlistentry>
+            <term><emphasis role="bold"><literal>&#8220;device_type&#8221;</literal></emphasis> [S]</term>
+              <listitem>
+                <para>Standard
+                <emphasis>property name</emphasis> that indicates an Interrupt
+                Controller.</para>
+                <para><emphasis>prop-encoded-array</emphasis>: A string, encoded as with
+                <emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
+                <para>The value of this property shall be
+                <literal>&#8220;power-ivpe&#8221;</literal>.</para>
+              </listitem>
+  			  </varlistentry>
+
+          <varlistentry>
+            <term><emphasis role="bold"><literal>&#8220;reg&#8221;</literal></emphasis> [S]</term>
+              <listitem>
+                <para>Standard
+                <emphasis>property name</emphasis> to define the base logical addresses
+                and sizes of the registers for managing the interrupt context of a
+                physical processor thread</para>
+                <para>
+                  <emphasis>prop-encoded-array</emphasis>: Two
+                  (<emphasis>encode-phys, endcode-int</emphasis>)
+                  pairs. The entries represent the user and OS level views of the
+                  XIVE physical processor thread interrupt management areas respectively
+                  (“TIMA” addresses). The first of the two entries is the base address and
+                  size of the user level view and the second of the two entries is the
+                  base address and size of the OS level view.</para>
+              </listitem>
+  			  </varlistentry>
+
+          <varlistentry>
+            <term><emphasis role="bold"><literal>&#8220;compatible&#8221;</literal></emphasis> [S]</term>
+              <listitem>
+                <para>Standard
+                <emphasis>property name</emphasis> to define alternate
+                <emphasis role="bold"><literal>&#8220;name&#8221;</literal></emphasis> property values.</para>
+                <para>
+                <emphasis>prop-encoded-array</emphasis>: The concatenation, with
+                <emphasis role="bold"><literal>encode+</literal></emphasis>, of an arbitrary number of text strings,
+                each encoded as with
+                <emphasis role="bold"><literal>encode-string</literal></emphasis>.</para>
+                <para>The property value shall include
+                <emphasis role="bold"><literal>&#8220;ibm,power-ivpe&#8221;</literal></emphasis>.</para>
+              </listitem>
+  			  </varlistentry>
+
+          <varlistentry>
+            <term><emphasis role="bold"><literal>&#8220;ibm,xive_eq-sizes&#8221;</literal></emphasis></term>
+              <listitem>
+                <para><emphasis>property name</emphasis>: Defines the sizes of event
+                queues that are supported by for the XIVE option.</para>
+                <para>
+                <emphasis>prop-encoded-value</emphasis>: One to N integers, encoded as with
+                <emphasis role="bold"><literal>encode-int</literal></emphasis>.</para>
+                <para>Each integer is expressed as the power of 2 of the event queue size.
+                  For example, a 4K event queue size is represented by the value of 12
+                  (4K = 2<superscript>12</superscript>). The integers are arranged in ascending order.</para>
+              </listitem>
+  			  </varlistentry>
+
+          <varlistentry>
+            <term><emphasis role="bold"><literal>&#8220;ibm,xive-lisn-ranges&#8221;</literal></emphasis></term>
+              <listitem>
+                <para><emphasis>property name:</emphasis> Defines the LISN ranges assigned
+                to the client program.</para>
+                <para><emphasis>prop-encoded-array</emphasis>: One or more
+                (<emphasis>LISN, number</emphasis>) pairs, where LISN is a single cell
+                hexadecimal value between 0x00000000 and 0x7FFFFFFF, and number is an
+                integer. Each pair represents a contiguous range of LISNs. These LISNs
+                can be used by the OS for any purpose (eg IPIs). The first range will
+                contain at least one per possible thread in the partition.</para>
+              </listitem>
+  			  </varlistentry>
+
+          <varlistentry>
+            <term><emphasis role="bold"><literal>&#8220;interrupt-controller&#8221;</literal></emphasis> [S]</term>
+              <listitem>
+                <para>Standard
+                <emphasis>property name</emphasis> to indicate an interrupt (sub-)tree
+                root.</para>
+                <para><emphasis>prop-encoded-array</emphasis>: &lt;none&gt; The presence of
+                this property indicates that this node represents an interrupt
+                controller.</para>
+              </listitem>
+  			  </varlistentry>
+        </variablelist>
+
+      </section>
+
     </section>
 
     <section>

RTAS/ch_rtas_call_defn.xml

@@ -5548,7 +5548,7 @@
                     <para>The index value for global interrupt
                     queue control indicator (9005) must be</para>
                     <para>(2
-                    <emphasis>ibm,interruptserver#-size</emphasis>) - 1 - the 
+                    <superscript>ibm,interrupt-server#-size</superscript>) - 1 - the
                     <emphasis role="bold"><literal>gserver#</literal></emphasis> of the global server to be controlled as
                     given in the
                     <emphasis role="bold"><literal>
@@ -6896,14 +6896,22 @@
                 <term><emphasis role="bold">R1-<xref linkend="sec_sensor_9005_giqc"
                 xrefstyle="select: labelnumber nopage"/>-2.</emphasis></term>
                   <listitem>
-                    <para>RThe index value for global interrupt
+                    <itemizedlist>
-                    queue control state sensor (9005) must be</para>
+                      <listitem>
-                    <para>(2
+                        <para>For legacy compatibility mode, the index value for global interrupt
-                    <emphasis>ibm,interrupt-server#-size</emphasis>) - 1- the gserver# of the
+                        queue control state sensor (9005) must be
+                        (2<superscript>ibm,interrupt-server#-size</superscript>) - 1- the gserver# of the
                         global queue to be sensed as given in the
                         <emphasis role="bold"><literal>
                         &#8220;ibm,ppc-interrupt-gserver#s&#8221;</literal></emphasis> property.</para>
                       </listitem>
+                      <listitem>
+                        <para>For exploitation compatibility mode, the index value must be 0,
+                          which is the only supported global server index in exploitation
+                          compatibility mode.</para>
+                      </listitem>
+                    </itemizedlist>
+                  </listitem>
              	</varlistentry>
             </variablelist>
 
@@ -10707,7 +10715,7 @@
                         </entry>
                         <entry>
                           <para>0x0 - 2
-                          <emphasis role="bold"><literal>&#8220;ibm,interrupt-server#-size&#8221;</literal></emphasis>
+                          <emphasis role="bold"><literal><superscript>&#8220;ibm,interrupt-server#-size&#8221;</superscript></literal></emphasis>
                           </para>
                         </entry>
                       </row>
@@ -10889,8 +10897,7 @@
                         </entry>
                         <entry>
                           <para>0x00 - 2
-                          <emphasis role="bold"><literal>
+                          <emphasis role="bold"><literal><superscript>&#8220;ibm,interrupt-server#-size&#8221;</superscript></literal></emphasis></para>
-                          &#8220;ibm,interrupt-server#-size&#8221;</literal></emphasis></para>
                         </entry>
                       </row>
                       <row>

RTAS/sec_rtas_get_indices.xml

@@ -5278,6 +5278,13 @@
                 <listitem>
                   <para>The OS completes/invalidates current dump status.</para>
                 </listitem>
+
+                <listitem>
+                  <para>The OS must use H_CLEAR_HPT to clear the page table if running
+                    in XIVE Exploitation Mode, H_REMOVE is not a sufficient mechanism
+                    to clear the HPT. Failure to use H_CLEAR_HPT may result in H_READ
+                    returning invalid entries as valid.</para>
+                </listitem>
               </orderedlist>
             </listitem>
        	</varlistentry>