Merge pull request #96 from rjmccall/intro-write-portability

[Editorial] Rewrite the introduction, standardize on "base C ABI", prepare for portability

Author: rjmccall

abi.html

@@ -61,40 +61,64 @@ <h2> Contents </h2>
 <h2><a href="#acknowledgements"> Acknowledgements</a></h2>
 <p> <hr> <p>
 
-<p>This document was developed jointly by an informal industry
-coalition consisting of (in alphabetical order) CodeSourcery, Compaq,
-EDG, HP, IBM, Intel, Red Hat, and SGI.  Additional contributions were
-provided by a variety of individuals.</p>
+<p>This document was originally developed jointly by an informal
+industry coalition consisting of (in alphabetical order) CodeSourcery,
+Compaq, EDG, HP, IBM, Intel, Red Hat, and SGI.  Additional contributions
+were provided by a variety of individuals.  It is now developed as an
+open-source project with contributions from a variety of individuals
+and companies.</p>
 
 <p> <hr> <p>
 <a name="intro">
 <h2><a href="#intro"> Chapter 1: Introduction </a></h2>
 <p> <hr> <p>
 
-In this document, we specify the Application Binary Interface for
-C++ programs,
-that is, the object code interfaces between user C++ code and the
-implementation-provided system and libraries.
-This includes the memory layout for C++ data objects,
-including both predefined and user-defined data types,
-as well as internal compiler generated objects such as virtual tables.
-It also includes function calling interfaces,
-exception handling interfaces,
-global naming,
-and various object code conventions.
-
-<p>
-In general, this document is written as a generic specification,
-to be usable by C++ implementations on a variety of architectures.
-However, it does contain processor-specific material for the Itanium
-64-bit ABI, identified as such.
-Where structured data layout is described,
-we generally assume Itanium psABI member sizes.
-An implementation for a 32-bit ABI would typically just change the
-sizes of members as appropriate
-(i.e. pointers and long ints would become 32 bits),
-but sometimes an order change would be required for compactness,
-and we note more substantive changes.
+In this document, we specify the Application Binary Interface (ABI)
+for C++ programs: that is, the object code interfaces between different
+user-provided C++ program fragments and between those fragments and
+the implementation-provided runtime and libraries.  This includes the
+memory layout for C++ data objects, including both predefined and
+user-defined data types, as well as internal compiler generated
+objects such as virtual tables.  It also includes function calling
+interfaces, exception handling interfaces, global naming, and various
+object code conventions.
+
+<p>
+In general, this document is meant to serve as a generic specification
+which can be used by C++ implementations on a variety of platforms.
+It does this by layering on top of a platform's base C ABI.  However,
+it was originally written for the Itanium architecture, and some parts
+still directly make Itanium-specific or 64-bit-specific assumptions.
+There is an ongoing project to restate the entire C++ ABI specification
+in terms of portable C concepts that are defined in the C ABI.  In
+the meantime, it is usually straightforward to recognize these
+unportable assumptions and translate them appropriately, e.g. by
+replacing a 64-bit pointer with a 32-bit pointer.
+
+<p>
+This document is not an authoritative definition of the C++ ABI for
+any particular platform.  Platform vendors retain the ultimate power
+to define the C++ ABI for their platform.  Platforms using this ABI
+for C++ should declare that they do so, either unmodified or with a
+certain set of changes.
+
+<p>
+While this ABI has generally stood up well, there are some parts of it
+that are now seen as mistakes.  This document includes several
+recommendations for platforms adopting this ABI with no need to
+interoperate with existing C++ object code.  These recommendations
+appear as follows:
+
+<blockquote>
+  <span class="future-abi">Recommendation for new platforms: consider
+  forbidding the use of function templates on your platform so that
+  the ABI can remove these expression-mangling rules.</span>
+</blockquote>
+
+<p>
+Platforms adopting any of these recommendations should describe the
+exact changes they've made in their platform ABI documentation,
+as the set of recommendations in this document may change over time.
 
 <p> <hr> <p>
 <a name="definitions">
@@ -262,7 +286,7 @@ <h3><a href="#definitions"> 1.1 Definitions </a></h3>
 complement of the definition in [class.temporary]p3 of types for which
 an extra temporary is allowed when passing or returning a type.  A type
 which is trivial for the purposes of the ABI will be passed and returned
-according to the rules of the underlying C ABI, e.g. in registers; often
+according to the rules of the base C ABI, e.g. in registers; often
 this has the effect of performing a trivial copy of the type.
 </p>
 </dd>
@@ -630,7 +654,7 @@ <h3><a href="#pod"> 2.2 POD Data Types </a></h3>
 
 <p>
 The size and alignment of a type which is a <a href="#POD">POD for the
-purpose of layout<a> is as specified by the base (C) ABI, with the
+purpose of layout<a> is as specified by the base C ABI, with the
 following provisos:
 </p>
 
@@ -811,7 +835,7 @@ <h3><a href="#class-types"> 2.4 Non-POD Class Types </a></h3>
        <p>
        <li>
        If <code>sizeof(T)*8 >= n</code>,
-       the bit-field is allocated as required by the underlying C psABI,
+       the bit-field is allocated as required by the base C ABI,
        subject to the constraint that a bit-field is never placed in the
        tail padding of a base class of C.
 

code.css

@@ -13,6 +13,8 @@ H4 { font-size: 1.34em; }
 H5 { font-size: 1.05em; font-weight: bold }
 H6 { font-size: 1em; font-weight: bold }
 
+SPAN.future-abi { color:green; }
+
 SPAN.change { color:red; }
 DIV.change { color:red; }