systemsoftware
/
ELFv2-ABI
35
1
Fork 0
Code Issues 10 Pull Requests Projects Releases Wiki Activity

Add the errata-1.4 document.

Browse Source 
Signed-off-by:  Bill Schmidt  <wschmidt@linux.vnet.ibm.com>
pull/92/head
Bill Schmidt 7 years ago
parent e65ae8781b
commit cfb017fdc7
4 changed files with 491 additions and 0 deletions
Show Stats Download Patch File Download Diff File

110
errata-1.4/bk_main.xml
Unescape Escape View File

@ -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>

224
errata-1.4/ch_errata.xml
Unescape Escape View File

@ -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>

156
errata-1.4/pom.xml
Unescape Escape View File

@ -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>

1
pom.xml
Unescape Escape View File

@ -18,5 +18,6 @@
<!-- Add new documents are build in the project, add their directories to this list to <!-- Add new documents are build in the project, add their directories to this list to
enable all document builds from the top level --> enable all document builds from the top level -->
<module>specification</module> <module>specification</module>
<module>errata-1.4</module>
</modules> </modules>
</project> </project>

Write Preview
Loading…
Cancel
Save