Fixes per internal review comments

Signed-off-by: Bill Schmidt <wschmidt@linux.ibm.com>

specification/bk_main.xml

@@ -94,7 +94,7 @@
     <revhistory>
       <!-- TODO: Set the initial version information and clear any old information out -->
       <revision>
-          <date>2020-05-21</date>
+          <date>2020-06-04</date>
           <revdescription>
             <itemizedlist spacing="compact">
               <listitem>

specification/ch_1.xml

@@ -69,9 +69,7 @@
         <emphasis><phrase revisionflag="added">IBM</phrase> Power
 	Instruction Set Architecture,</emphasis> Versions <phrase
 	revisionflag="deleted">2.7 and 3.0,</phrase> <phrase
-	revisionflag="added">2.07, 3.0, and 3.1,</phrase>
+	revisionflag="added">2.07, 3.0, and 3.1</phrase>, IBM, <phrase
-	<phrase revisionflag="deleted">IBM</phrase><phrase
-	revisionflag="added">OpenPOWER Foundation</phrase>, <phrase
 	revisionflag="deleted">2013-2016</phrase><phrase
 	revisionflag="added">2013-2020</phrase>.
         <emphasis>
@@ -214,7 +212,6 @@
 	  describe the implications of this new capability.  For specifics,
 	  see <xref linkend="dbdoclet.50655241_FnLinkage" />, <xref
 	  linkend="dbdoclet.50655240___codealign" />, <xref
-	  linkend="dbdoclet.50655240___tailcall" />, <xref
 	  linkend="dbdoclet.50655240___RefHeading___Toc377640591" />, <xref
 	  linkend="dbdoclet.50655241_18894" />, <xref
 	  linkend="dbdoclet.50655241_LinkerOpts" />, <xref
@@ -222,6 +219,17 @@
 	  linkend="dbdoclet.50655242_82622" />.
 	</para>
       </listitem>
+      <listitem>
+	<para>
+	  Appendix A, "Predefined Functions for Vector Programming,"
+	  and most of Chapter 6, "Vector Programming Interfaces," have
+	  been removed from this document.  This material is now
+	  incorporated into the <emphasis>POWER Vector Intrinsics
+	  Programming Reference</emphasis>.  See <xref
+	  linkend="dbdoclet.50655239___RefHeading___Toc377640569" />
+	  for a link to this document.
+	</para>
+      </listitem>
     </itemizedlist>
   </section>
 </chapter>

specification/ch_2.xml

@@ -2384,24 +2384,10 @@ xml:id="dbdoclet.50655240_pgfId-1156194">
                   <para>Function pointer</para>
                 </entry>
               </row>
-              <row revisionflag="changed">
+	      <row>
-                <entry morerows="3">
+                <entry morerows="2">
                   <para>Binary Floating-Point</para>
                 </entry>
-                <entry>
-                  <para>_Float16</para>
-                </entry>
-                <entry>
-                  <para>2</para>
-                </entry>
-                <entry>
-                  <para>Halfword</para>
-                </entry>
-                <entry>
-                  <para>Half-precision float</para>
-                </entry>
-              </row>
-	      <row>
                 <entry>
                   <para>float</para>
                 </entry>
@@ -2778,7 +2764,7 @@ xml:id="dbdoclet.50655240_pgfId-1156194">
                   <para>Vector of 1 signed quadword.</para>
                 </entry>
               </row>
-              <row>
+              <row revisionflag="deleted">
                 <entry>
                   <para></para>
                 </entry>
@@ -4091,9 +4077,9 @@ xml:id="dbdoclet.50655240_pgfId-1156194">
 	If a function contains any prefixed (8-byte) instructions,
 	functions should preferably be aligned on at least a 64-byte
 	boundary.  In ISA 3.1, executing a prefixed instruction that
-	crosses a 64-byte boundary will cause a SIGILL that must be
+	crosses a 64-byte boundary causes an alignment interrupt.
-	handled by the kernel.  Compilers and assemblers can avoid
+	Compilers and assemblers can avoid this if functions are
-	this if functions are aligned on a 64-byte boundary.
+	aligned on a 64-byte boundary.
       </para>
     </section>
   </section>
@@ -4142,12 +4128,12 @@ xml:id="dbdoclet.50655240_pgfId-1156194">
 	tables is further described in the referenced section.  A program may
 	contain any combination of the function call protocols in these
 	tables.
-	<note><para>Note that
+	<note><para>This ABI does not define protocols where the
-	this ABI does not define protocols where the caller does not use
+	caller does not use a TOC pointer, but does preserve r2.  It
-	a TOC pointer, but does preserve r2.  It is most efficient when
+	is most efficient when such functions are always leaf
-	such functions are always leaf procedures.  It is not forbidden for
+	procedures.  It is not forbidden for such a function to call
-	such a function to call another function, but in this case it is
+	another function, but in this case it is up to the caller to
-	up to the caller to save and restore r2 around each call.
+	save and restore r2 around each call.
 	</para></note>
       </para>
       <table frame="all" pgwide="1"
@@ -4471,10 +4457,9 @@ xml:id="dbdoclet.50655240_pgfId-1156194">
 	  linkage table (PLT) stub that saves r2 and replaces the nop
 	  instruction with a restore of r2.  (The save of r2 may be omitted
 	  from the PLT stub if the R_PPC64_TOCSAVE relocation is used; see
-	  <xref linkend="dbdoclet.50655241_90220" />.)  If the callee requires
+	  <xref linkend="dbdoclet.50655241_90220" />.)  See <xref
-	  a TOC, the PLT stub also includes code to place the callee's global
+	  linkend="dbdoclet.50655242_82622" /> for a full description
-	  entry point into r12.  See <xref linkend="dbdoclet.50655242_82622"
+	  of PLT stubs.
-	  /> for a full description of PLT stubs.
 	</para>
       </section>
       <section xml:id="dbdoclet.50655241_Ext1">
@@ -4487,8 +4472,7 @@ xml:id="dbdoclet.50655240_pgfId-1156194">
 	  after the bl instruction for the call.  Instead, the compiler
 	  annotates the bl instruction with an R_PPC64_REL24_NOTOC
 	  relocation.  The linker generates a PLT stub that does not include
-	  a save of r2.  If the callee requires a TOC, the PLT stub also
+	  a save of r2.
-	  includes code to place the callee's global entry point into r12.
 	</para>
       </section>
       <section xml:id="dbdoclet.50655241_Local20">
@@ -4685,19 +4669,23 @@ xml:id="dbdoclet.50655240_pgfId-1156194">
                 <entry>
                   <para>Nonvolatile<footnote>
                   <para>Register r2 is nonvolatile with respect to calls
-		  between <phrase revisionflag="added">most</phrase> functions
+		  between functions in the same compilation
-		  in the same compilation unit. It is saved and restored by
+		  unit<phrase revisionflag="deleted">. It is saved and
-		  code inserted
+		  restored by code inserted by the linker resolving a
-		  by the linker resolving a call to an external function. For
+		  call to an external function.</phrase><phrase
-		  more information, see <xref linkend="dbdoclet.50655240_51083"
+		  revisionflag="added">, except under the conditions
-		  /> <phrase revisionflag="added"> and <xref
+		  in footnote (b).</phrase> For more information, see
-		  linkend="dbdoclet.50655241_FnLinkage" /></phrase>.</para>
+		  <xref linkend="dbdoclet.50655240_51083" /> <phrase
+		  revisionflag="added"> and <xref
+		  linkend="dbdoclet.50655241_FnLinkage"
+		  /></phrase>.</para>
                   </footnote><phrase revisionflag="added"> or
 		  Volatile<footnote>
 		  <para>Register r2 is volatile and available for use in a
 		  function that does not use a TOC pointer and that does
-		  not preserve r2.  See
+		  not guarantee that it preserves r2.  See
-		  <xref linkend="dbdoclet.50655241_FnLinkage" />.</para>
+		  <xref linkend="dbdoclet.50655241_FnLinkage" /> and
+		  <xref linkend="dbdoclet.50655241_95185" />.</para>
 		  </footnote></phrase></para>
                 </entry>
                 <entry>
@@ -5042,11 +5030,7 @@ xml:id="dbdoclet.50655240_pgfId-1156194">
 	revisionflag="changed">least-significant halves of those VSX
 	registers corresponding</phrase> to the classic floating-point
 	registers (that is, vsr0&#8211;vsr31), <phrase
-	revisionflag="changed">are</phrase> volatile.  <phrase
+	revisionflag="changed">are</phrase> volatile.</para>
-	revisionflag="added">If the most-significant half of such a
-	VSX register is a non-volatile floating-point register that is
-	not used for a function call, the entire VSX register is
-	volatile.</phrase></para>
 
         <table frame="all" pgwide="1" xml:id="dbdoclet.50655240_83567">
           <title>Floating-Point Register Roles for Binary Floating-Point
@@ -6009,8 +5993,15 @@ xml:id="dbdoclet.50655240_pgfId-1156194">
           <para>Any future type requiring 16-byte alignment (see
           <xref linkend="dbdoclet.50655240_15141" />) or processed in vector
           registers</para>
-          <para>For the purpose of determining a qualified floating-point argument,
+          <para>For the purpose of determining a qualified
-          _Float128 shall be considered a vector data type. In addition, _Float128
+	  floating-point argument, <phrase
+	  revisionflag="deleted">_Float128</phrase><phrase
+	  revisionflag="added">IEEE BINARY 128 QUADRUPLE
+	  PRECISION</phrase> shall be considered a vector data type. In
+	  addition, <phrase
+	  revisionflag="deleted">_Float128</phrase><phrase
+	  revisionflag="added">IEEE BINARY 128 QUADRUPLE
+	  PRECISION</phrase>
           is like a vector data type for determining if multiple aggregate members
           are like.</para>
           <para>A homogeneous aggregate can consist of a variety of nested
@@ -6594,7 +6585,7 @@ s6            -           72 (stored)</programlisting>
       Area must be large enough to accommodate all parameters, including
       parameters passed in registers.</para>
       <para revisionflag="added">
-	The caller of any function with an ellipsis in its prototype
+	The caller of any function with a variable argument list
 	must allocate a Parameter Save Area, as described in <xref
 	linkend="dbdoclet.50655240_78421" />.
       </para>
@@ -6652,44 +6643,6 @@ s6            -           72 (stored)</programlisting>
         </listitem>
       </itemizedlist>
     </section>
-    <section xml:id="dbdoclet.50655240___tailcall"
-	     revisionflag="added">
-      <title>Tail-Call Optimization</title>
-      <para>
-	When the last action of a function <emphasis>F</emphasis> is
-	to perform a function call to a function
-	<emphasis>G</emphasis>, and optionally return the value
-	returned from <emphasis>G</emphasis>, a compiler may perform a
-	<emphasis>tail-call optimization</emphasis> so long as the
-	optimization is undetectable by the caller of
-	<emphasis>G</emphasis>.  The full details of and requirements
-	for tail-call optimization will not be described here, but in
-	essence <emphasis>F</emphasis> removes its stack frame and
-	issues a direct branch to <emphasis>G</emphasis>, which reuses
-	the stack space and the saved link register so that
-	<emphasis>G</emphasis> eventually returns to the caller of
-	<emphasis>F</emphasis>.
-      </para>
-      <para>
-	When the call from <emphasis>F</emphasis> to
-	<emphasis>G</emphasis> is not local, and
-	<emphasis>F</emphasis> is a TOC-preserving function, tail-call
-	optimization is disallowed because <emphasis>F</emphasis> and
-	<emphasis>G</emphasis> may have different TOC pointers.
-	Tail-call optimization cannot guarantee that the correct TOC
-	will be restored when <emphasis>G</emphasis> returns.
-      </para>
-      <para>
-	When the call from <emphasis>F</emphasis> to
-	<emphasis>G</emphasis> is local, and <emphasis>F</emphasis> is
-	a TOC-preserving function, but <emphasis>G</emphasis> is
-	<emphasis>not</emphasis> a TOC-preserving function, then
-	tail-call optimization is again disallowed.  In this case,
-	<emphasis>G</emphasis> may have placed any value into register
-	r2, and the correct TOC will not be restored when
-	<emphasis>G</emphasis> returns.
-      </para>
-    </section>
   </section>
   <section xml:id="dbdoclet.50655240___RefHeading___Toc377640591">
     <title>Coding Examples</title>
@@ -8255,19 +8208,30 @@ bctrl</programlisting>
           </tbody>
         </tgroup>
       </table>
-      <para>Function calls <phrase revisionflag="added">often</phrase>
+      <para revisionflag="deleted">Function calls 
       need to be performed in conjunction with
       establishing, maintaining, and restoring addressability through the TOC
       pointer register, r2. When a function is called, the TOC pointer register
-      may be modified. <phrase revisionflag="added">In many cases,</phrase>
+      may be modified. The caller must provide a nop
-      <phrase revisionflag="changed">the</phrase> caller must provide a nop
       after the bl instruction performing a call, if r2 is not known to have
       the same value in the callee. This is generally true for external calls.
       The linker will replace the nop with an r2 restoring instruction if the
-      caller and callee use different r2 values<phrase
+      caller and callee use different r2 values, The linker leaves it
-      revisionflag="changed">.</phrase> The linker leaves it unchanged if they
+      unchanged if they 
       use the same r2 value. This scheme avoids having a compiler generate an
-      overconservative r2 save and restore around every external call.</para>
+      overconservative r2 save and restore around every external
+      call.</para>
+      <para revisionflag="added">
+	When a function requires addressability through the TOC
+	pointer register, r2, and that function calls another function
+	that may not preserve the value of r2, the caller must provide
+	a nop after the bl instruction performing the call.  The
+	linker will replace the nop with an r2-restoring instruction
+	if it determines that r2 may be changed as a result of the
+	call; otherwise the linker will leave the nop unchanged.  See
+	<xref linkend="dbdoclet.50655241_FnLinkage" /> for a full
+	description of when a nop must be inserted.
+      </para>
       <para revisionflag="added">
 	There are two cases where the caller need not provide a nop after
 	the bl instruction performing a call:

specification/ch_3.xml

@@ -5606,7 +5606,7 @@ addi      r4, r4, lower</programlisting>
       <programlisting>typedef struct {
     /* Reservation for HWCAP data. */
         <phrase revisionflag="deleted">unsigned int hwcap2;</phrase>
-        unsigned int hwcap; /* not used in LE ABI */
+        <phrase revisionflag="changed">uint64_t</phrase> hwcap; <phrase revisionflag="deleted">/* not used in LE ABI */</phrase>
  
     <phrase revisionflag="deleted">/* Indicate if HTM capable (ISA 2.07). */
         int tm_capable;
@@ -9083,7 +9083,8 @@ nop</programlisting>
     <section xml:id="dbdoclet.ie-le-pcrel" revisionflag="added">
       <title>Initial Exec to Local Exec (PC-Relative)</title>
       <table frame="all" pgwide="1">
-        <title>Initial-Exec-to-Local-Exec Initial Relocations</title>
+        <title>Initial-Exec-to-Local-Exec Initial Relocations
+	(PC-Relative)</title>
         <tgroup cols="3">
           <colspec colname="c1" colwidth="33*" />
           <colspec colname="c2" colwidth="33*" />

specification/ch_4.xml

@@ -718,7 +718,7 @@ PPC_FEATURE2_DARN           0x00200000 /* darn instruction */
 PPC_FEATURE2_SCV            0x00100000 /* scv syscall */
 PPC_FEATURE2_HTM_NO_SUSPEND 0x00080000 /* TM without suspended state */
 PPC_FEATURE2_ARCH_3_1       0x00040000 /* ISA 3.1 */
-PPC_FEATURE2_MMA            0x00020000 /* Matrix Multiply Accumulate */</programlisting>
+PPC_FEATURE2_MMA            0x00020000 /* Matrix Multiply Assist */</programlisting>
         <para>When a process starts to execute, its stack holds the arguments,
         environment, and auxiliary vector received from the exec call. The system
         makes no guarantees about the relative arrangement of argument strings,

specification/ch_5.xml

@@ -320,7 +320,7 @@ xml:id="dbdoclet.50655243_pgfId-1099317">
             <row>
               <entry morerows="1">
                 <para>__VEC_ELEMENT_REG_ORDER__</para>
-                <para>For more information, see 
+                <para revisionflag="deleted">For more information, see 
                 <xref linkend="dbdoclet.50655244_25365" />.</para>
               </entry>
               <entry>