Add the errata-1.4 document.
Signed-off-by: Bill Schmidt <wschmidt@linux.vnet.ibm.com>pull/92/head
parent
e65ae8781b
commit
cfb017fdc7
@ -0,0 +1,110 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!--
|
||||
Copyright (c) 2016 OpenPOWER Foundation
|
||||
|
||||
Licensed under the GNU Free Documentation License, Version 1.3;
|
||||
with no Invariants Sections, with no Front-Cover Texts,
|
||||
and with no Back-Cover Texts (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.gnu.org/licenses/fdl-1.3.txt
|
||||
|
||||
-->
|
||||
|
||||
<!-- The following entity variable is used to reflect the version of the
|
||||
template document master used for building a document. This value
|
||||
should be set by copy of the of template used to create a new
|
||||
document and should not be changed. Use of this value is in
|
||||
in the Abstract section in this file. -->
|
||||
<!DOCTYPE book [
|
||||
<!ENTITY template_version "1.1.0">
|
||||
]>
|
||||
|
||||
<book xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xi="http://www.w3.org/2001/XInclude"
|
||||
xmlns:xlink="http://www.w3.org/1999/xlink"
|
||||
version="5.0"
|
||||
xml:id="bk_main">
|
||||
|
||||
<title>OpenPOWER ELFv2 Errata</title>
|
||||
<subtitle>For ELFv2 ABI Version 1.4</subtitle>
|
||||
|
||||
<info>
|
||||
<author>
|
||||
<personname>
|
||||
System Software Work Group
|
||||
</personname>
|
||||
<email>syssw-chair@openpowerfoundation.org</email>
|
||||
<affiliation>
|
||||
<orgname>OpenPower Foundation</orgname>
|
||||
</affiliation>
|
||||
</author>
|
||||
<copyright>
|
||||
<year>2018</year>
|
||||
<holder>OpenPOWER Foundation</holder>
|
||||
</copyright>
|
||||
<releaseinfo>Revision 1.0</releaseinfo>
|
||||
<productname>OpenPOWER</productname>
|
||||
<pubdate/>
|
||||
|
||||
<!-- TODO: Select one of the two following legalnotice role= values:
|
||||
"apache2" for an Apache V2 license or
|
||||
"opfExternal" for an official OpenPOWER Foundation external license text.
|
||||
If you don't know which one to select, change to "opfExternal" and ask your TSC representative. -->
|
||||
<!-- legalnotice role="apache2" -->
|
||||
<!-- legalnotice role="opfExternal" -->
|
||||
<!-- Following matches the ABI itself -->
|
||||
<legalnotice role="gnuFreeDoc">
|
||||
|
||||
<annotation>
|
||||
<remark>Copyright details are filled in by the template.</remark>
|
||||
</annotation>
|
||||
</legalnotice>
|
||||
|
||||
<!-- TODO: Update the following text with the correct document description (first paragraph),
|
||||
Work Group name, and Work Product track (both in second paragraph). -->
|
||||
<abstract>
|
||||
<para>This document provides errata against version 1.4 of the
|
||||
OpenPOWER ELF v2 Application Binary Interface Specification. These
|
||||
errata should be considered part of said specification until such
|
||||
time as a newer version of the full specification is published.</para>
|
||||
<para>This document is a Non-standard Track, Work Group Note work
|
||||
product owned by the System Software Workgroup and handled in compliance
|
||||
with the requirements outlined in the <citetitle>OpenPOWER Foundation
|
||||
Work Group (WG) Process</citetitle> document. It was created using the
|
||||
<citetitle>Document Development Guide</citetitle> version
|
||||
&template_version;. Comments, questions, etc. can be submitted to the
|
||||
public mailing list for the parent specification at
|
||||
<email>syssw-elfv2abi@mailinglist.openpowerfoundation.org</email>.</para>
|
||||
</abstract>
|
||||
|
||||
<revhistory>
|
||||
<!-- TODO: Set the initial version information and clear any old information out -->
|
||||
<revision>
|
||||
<date>2018-02-05</date>
|
||||
<revdescription>
|
||||
<itemizedlist spacing="compact">
|
||||
<listitem>
|
||||
<para>Initial document creation</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</revdescription>
|
||||
</revision>
|
||||
</revhistory>
|
||||
</info>
|
||||
|
||||
<!-- The ch_preface.xml file is required by all documents -->
|
||||
<xi:include href="../../Docs-Master/common/ch_preface.xml"/>
|
||||
|
||||
<!-- TODO: Add your chapter heading files here. Remove both files and insert your own. -->
|
||||
<!-- See the template document for naming conventions and location of files. -->
|
||||
<xi:include href="ch_errata.xml"/>
|
||||
|
||||
<!-- The app_foundation.xml appendix file is required by all documents. -->
|
||||
<xi:include href="../../Docs-Master/common/app_foundation.xml"/>
|
||||
|
||||
<!-- TODO: The following template document may be modified to create additional appendices as needed. -->
|
||||
<!-- xi:include href="app_template.xml"/ -->
|
||||
|
||||
</book>
|
@ -0,0 +1,224 @@
|
||||
<!--
|
||||
Copyright (c) 2016 OpenPOWER Foundation
|
||||
|
||||
Licensed under the GNU Free Documentation License, Version 1.3;
|
||||
with no Invariants Sections, with no Front-Cover Texts,
|
||||
and with no Back-Cover Texts (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.gnu.org/licenses/fdl-1.3.txt
|
||||
|
||||
-->
|
||||
<chapter xmlns="http://docbook.org/ns/docbook"
|
||||
xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"
|
||||
xml:id="dbdoclet.50655240_pgfId-1156194">
|
||||
|
||||
<title>Errata</title>
|
||||
<para>The following statements in version 1.4 of the 64-Bit ELF V2 ABI
|
||||
Specification for the Power Architecture are incorrect, and should be
|
||||
considered corrected as specified.</para>
|
||||
<section>
|
||||
<title>Section 2.1.2.2, Fundamental Types</title>
|
||||
<para>
|
||||
<emphasis role="underline">Problem</emphasis>: Paragraph 2 contains a
|
||||
statement that makes use of undefined behavior according to the C standard.
|
||||
</para>
|
||||
<para>
|
||||
<blockquote>
|
||||
<para>
|
||||
Regardless of the alignment rules for the allocation of data types,
|
||||
pointers to both aligned and unaligned data of each data type shall
|
||||
return the value corresponding to a data type starting at the specified
|
||||
address when accessed with either the pointer dereference operator * or
|
||||
the array reference operator [ ].
|
||||
</para>
|
||||
</blockquote>
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="underline">Resolution</emphasis>: Paragraph 2 is stricken
|
||||
from the ABI.
|
||||
</para>
|
||||
</section>
|
||||
<section>
|
||||
<title>Section 6.1, Vector Data Types</title>
|
||||
<para>
|
||||
<emphasis role="underline">Problem 1</emphasis>: The following sentence
|
||||
likewise makes use of undefined behavior according to the C standard.
|
||||
</para>
|
||||
<para>
|
||||
<blockquote>
|
||||
<para>
|
||||
While the preferred alignment for vector data types is a multiple of 16
|
||||
bytes, pointers may point to vector objects at an arbitrary alignment.
|
||||
</para>
|
||||
</blockquote>
|
||||
</para>
|
||||
<para>
|
||||
As stated in Table 2.12, Vector Types, <emphasis>all</emphasis> vector
|
||||
types have quadword alignment; there is no "preferred" alignment.
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="underline">Resolution 1</emphasis>: The offending sentence
|
||||
is stricken from the ABI.
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="underline">Problem 2</emphasis>: This section contains
|
||||
another sentence and an example that likewise make use of undefined
|
||||
behavior according to the C standard. The offending sentence reads:
|
||||
</para>
|
||||
<para>
|
||||
<blockquote>
|
||||
<para>
|
||||
The use of vector built-in functions such as vec_xl and vec_xst is
|
||||
discouraged except for languages where no dereference operators are
|
||||
available.
|
||||
</para>
|
||||
</blockquote>
|
||||
</para>
|
||||
<para>
|
||||
The offending example appears directly afterwards.
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="underline">Resolution 2</emphasis>: The offending sentence
|
||||
is replaced as follows:
|
||||
</para>
|
||||
<para>
|
||||
<blockquote>
|
||||
<para>
|
||||
The dereference operator * may <emphasis>not</emphasis> be used to
|
||||
access data that is not aligned at least to a quadword boundary.
|
||||
Built-in functions such as vec_xl and vec_xst are provided for
|
||||
unaligned data access.
|
||||
</para>
|
||||
</blockquote>
|
||||
</para>
|
||||
<para>
|
||||
The offending example is stricken from the ABI.
|
||||
</para>
|
||||
</section>
|
||||
<section>
|
||||
<title>Section 6.4, Vector Built-In Functions</title>
|
||||
<para>
|
||||
<emphasis role="underline">Problem 1</emphasis>: The Note following
|
||||
Table 6.1 likewise encourages undefined behavior (in this context):
|
||||
</para>
|
||||
<para>
|
||||
<blockquote>
|
||||
<para>
|
||||
Reminder: The assignment operator = is the preferred way to assign
|
||||
values from one vector data type to another vector data type in
|
||||
accordance with the C and C++ programming languages.
|
||||
</para>
|
||||
</blockquote>
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="underline">Resolution 1</emphasis>: The Note is
|
||||
stricken from the ABI.
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="underline">Problem 2</emphasis>: The paragraph following
|
||||
Table 6.2 ends with the following sentence that likewise encourages
|
||||
undefined behavior:
|
||||
</para>
|
||||
<para>
|
||||
<blockquote>
|
||||
<para>
|
||||
It is recommended that programmers use the assignment operator =
|
||||
or the vector vec_xl and vec_xst vector built-in functions to access
|
||||
unaligned data streams.
|
||||
</para>
|
||||
</blockquote>
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="underline">Resolution 2</emphasis>: This sentence is
|
||||
replaced as follows:
|
||||
</para>
|
||||
<para>
|
||||
<blockquote>
|
||||
<para>
|
||||
It is recommended that programmers use the vec_xl and vec_xst
|
||||
vector built-in functions to access unaligned data streams.
|
||||
</para>
|
||||
</blockquote>
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="underline">Problem 3</emphasis>: The first sentence of
|
||||
the second paragraph following Table 6.2 wrongly identifies vec_xl and
|
||||
vec_xst as optional built-ins:
|
||||
</para>
|
||||
<para>
|
||||
<blockquote>
|
||||
<para>
|
||||
The set of extended mnemonics in Table 6.3, "Optional Built-In Memory
|
||||
Access Functions" [127] may be provided by some compilers and are not
|
||||
required by the Power SIMD programming interfaces.
|
||||
</para>
|
||||
</blockquote>
|
||||
</para>
|
||||
<para>
|
||||
The title of Table 6.3 likewise calls these optional.
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="underline">Resolution 3</emphasis>: The title of Table
|
||||
6.3 is changed to "VSX Memory Access Built-In Functions", and this
|
||||
sentence is replaced as follows:
|
||||
</para>
|
||||
<para>
|
||||
<blockquote>
|
||||
<para>
|
||||
The built-in functions in Table 6.3, "VSX Memory Access Built-In
|
||||
Functions" [127] provide unaligned access to data in memory that
|
||||
is to be copied to or from a variable having vector data type.
|
||||
</para>
|
||||
</blockquote>
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="underline">Problem 4</emphasis>: The second paragraph
|
||||
following Table 6.2 contains one sentence that likewise encourages
|
||||
undefined behavior, and another sentence that is simply incorrect:
|
||||
</para>
|
||||
<para>
|
||||
<blockquote>
|
||||
<para>
|
||||
In particular, the assignment operator = will have the same effect
|
||||
of copying values between vector data types and provides a preferable
|
||||
method to assign values while giving the compiler more freedom to
|
||||
optimize data allocation. The only use for these functions is to
|
||||
support some coding patterns enabling big-endian vector layout code
|
||||
sequences in both big-endian and little-endian environments.
|
||||
</para>
|
||||
</blockquote>
|
||||
</para>
|
||||
<para>
|
||||
The second sentence applies to functions in table 6.4, not 6.3.
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="underline">Resolution 4</emphasis>: The offending
|
||||
sentences are stricken from the ABI.
|
||||
</para>
|
||||
</section>
|
||||
<section>
|
||||
<title>
|
||||
Section 6.4.1, Big-Endian Vector Layout in Little-Endian Environments
|
||||
</title>
|
||||
<para>
|
||||
<emphasis role="underline">Problem</emphasis>: Table 6.8, and the
|
||||
sentence preceding it, wrongly identify the vec_xl and vec_xst
|
||||
built-in functions as optional.
|
||||
</para>
|
||||
<para>
|
||||
<blockquote>
|
||||
<para>
|
||||
See Table 6.8, "Optional Built-In Memory Access Functions (BE Layout
|
||||
in LE Mode)" [129].
|
||||
</para>
|
||||
</blockquote>
|
||||
</para>
|
||||
<para>
|
||||
<emphasis role="underline">Resolution</emphasis>: Table 6.8 is renamed
|
||||
"VSX Built-In Memory Access Functions (BE Layout in LE Mode)" and
|
||||
referenced thus in the preceding sentence.
|
||||
</para>
|
||||
</section>
|
||||
</chapter>
|
@ -0,0 +1,156 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!--
|
||||
Copyright (c) 2016 OpenPOWER Foundation
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
|
||||
-->
|
||||
<project xmlns="http://maven.apache.org/POM/4.0.0"
|
||||
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
|
||||
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
|
||||
<parent>
|
||||
|
||||
<groupId>org.openpowerfoundation.docs</groupId>
|
||||
<artifactId>workgroup-pom</artifactId>
|
||||
<version>1.0.0-SNAPSHOT</version>
|
||||
<relativePath>../pom.xml</relativePath>
|
||||
</parent>
|
||||
<modelVersion>4.0.0</modelVersion>
|
||||
|
||||
<artifactId>elfv2-1_4-errata</artifactId>
|
||||
|
||||
<packaging>jar</packaging>
|
||||
|
||||
<name>OpenPOWER ELFv2 ABI 1.4 Errata</name>
|
||||
|
||||
<properties>
|
||||
<!-- This is set by Jenkins according to the branch. -->
|
||||
<release.path.name></release.path.name>
|
||||
<comments.enabled>0</comments.enabled>
|
||||
</properties>
|
||||
<!-- ################################################ -->
|
||||
<!-- USE "mvn clean generate-sources" to run this POM -->
|
||||
<!-- ################################################ -->
|
||||
<build>
|
||||
<plugins>
|
||||
<plugin>
|
||||
|
||||
<groupId>org.openpowerfoundation.docs</groupId>
|
||||
|
||||
<artifactId>openpowerdocs-maven-plugin</artifactId>
|
||||
<!-- version set in ../pom.xml -->
|
||||
<executions>
|
||||
<execution>
|
||||
<id>generate-webhelp</id>
|
||||
<goals>
|
||||
<goal>generate-webhelp</goal>
|
||||
</goals>
|
||||
<phase>generate-sources</phase>
|
||||
<configuration>
|
||||
<!-- These parameters only apply to webhelp -->
|
||||
<enableDisqus>${comments.enabled}</enableDisqus>
|
||||
<disqusShortname>openpower-template-guide</disqusShortname>
|
||||
<enableGoogleAnalytics>1</enableGoogleAnalytics>
|
||||
<googleAnalyticsId>UA-17511903-1</googleAnalyticsId>
|
||||
<generateToc>
|
||||
appendix toc,title
|
||||
article/appendix nop
|
||||
article toc,title
|
||||
book toc,title,figure,table,example,equation
|
||||
book/appendix nop
|
||||
book/chapter nop
|
||||
chapter toc,title
|
||||
chapter/section nop
|
||||
section toc
|
||||
part toc,title
|
||||
reference toc,title
|
||||
set toc,title
|
||||
</generateToc>
|
||||
<!-- The following elements sets the autonumbering of sections in output for chapter numbers but no numbered sections-->
|
||||
<sectionAutolabel>1</sectionAutolabel>
|
||||
<tocSectionDepth>3</tocSectionDepth>
|
||||
<sectionLabelIncludesComponentLabel>1</sectionLabelIncludesComponentLabel>
|
||||
|
||||
<webhelpDirname>elfv2-1_4-errata</webhelpDirname>
|
||||
|
||||
<pdfFilenameBase>elfv2-1_4-errata</pdfFilenameBase>
|
||||
|
||||
<!-- TODO: Define the appropriate work product type. These values are defined by the IPR Policy.
|
||||
Consult with the Work Group Chair or a Technical Steering Committee member if you have
|
||||
questions about which value to select.
|
||||
|
||||
If no value is provided below, the document will default to "Work Group Notes".-->
|
||||
<workProduct>workgroupNotes</workProduct>
|
||||
<!-- workProduct>workgroupSpecification</workProduct -->
|
||||
<!-- workProduct>candidateStandard</workProduct -->
|
||||
<!-- workProduct>openpowerStandard</workProduct -->
|
||||
|
||||
<!-- TODO: Set the appropriate security policy for the document. For documents
|
||||
which are not "public" this will affect the document title page and
|
||||
create a vertical running ribbon on the internal margin of the
|
||||
security status in all CAPS. Values and definitions are formally
|
||||
defined by the IPR policy. A layman's definition follows:
|
||||
|
||||
public = this document may be shared outside the
|
||||
foundation and thus this setting must be
|
||||
used only when completely sure it allowed
|
||||
foundationConfidential = this document may be shared freely with
|
||||
OpenPOWER Foundation members but may not be
|
||||
shared publicly
|
||||
workgroupConfidential = this document may only be shared within the
|
||||
work group and should not be shared with
|
||||
other Foundation members or the public
|
||||
|
||||
The appropriate starting security for a new document is "workgroupConfidential". -->
|
||||
<security>workgroupConfidential</security>
|
||||
<!-- security>foundationConfidential</security -->
|
||||
<!-- security>public</security -->
|
||||
|
||||
<!-- TODO: Set the appropriate work flow status for the document. For documents
|
||||
which are not "published" this will affect the document title page
|
||||
and create a vertical running ribbon on the internal margin of the
|
||||
security status in all CAPS. Values and definitions are formally
|
||||
defined by the IPR policy. A layman's definition follows:
|
||||
|
||||
published = this document has completed all reviews and has
|
||||
been published
|
||||
draft = this document is actively being updated and has
|
||||
not yet been reviewed
|
||||
review = this document is presently being reviewed
|
||||
|
||||
The appropriate starting security for a new document is "draft". -->
|
||||
<documentStatus>draft</documentStatus>
|
||||
<!-- documentStatus>review</documentStatus -->
|
||||
<!--documentStatus>published</documentStatus -->
|
||||
|
||||
</configuration>
|
||||
</execution>
|
||||
</executions>
|
||||
<configuration>
|
||||
<!-- These parameters apply to pdf and webhelp -->
|
||||
<xincludeSupported>true</xincludeSupported>
|
||||
<sourceDirectory>.</sourceDirectory>
|
||||
<includes>
|
||||
bk_main.xml
|
||||
</includes>
|
||||
|
||||
<!-- **TODO: Set to the correct project URL. This likely needs input from the TSC. -->
|
||||
<!-- canonicalUrlBase>http://openpowerfoundation.org/docs/template-guide/content</canonicalUrlBase -->
|
||||
<glossaryCollection>${basedir}/../glossary/glossary-terms.xml</glossaryCollection>
|
||||
<includeCoverLogo>1</includeCoverLogo>
|
||||
<coverUrl>www.openpowerfoundation.org</coverUrl>
|
||||
</configuration>
|
||||
</plugin>
|
||||
</plugins>
|
||||
</build>
|
||||
</project>
|
Loading…
Reference in New Issue