[Editorial] Rewrite the section on member pointers

- Break it up into subsections for data and function member pointers
- Be much more precise
- Use portable concepts
- Include the ARM representation for virtual member functions pointers
- Add a future-platform recommendation about null data member pointers

Author: rjmccall

abi.html

@@ -151,6 +151,13 @@ <h3><a href="#definitions"> 1.1 Definitions </a></h3>
 A function that runs the destructors for non-static data members of T and
 non-virtual direct base classes of T.
 
+<p>
+<dt> <i>basic ABI properties</i> of a type T</dt>
+<dd>
+The basic representational properties of a type decided by the base C ABI,
+including its size, its alignment, its treatment by calling conventions,
+and the representation of pointers to it.
+
 <p>
 <dt> <i>complete object destructor</i> of a class T</dt>
 <dd>
@@ -686,40 +693,110 @@ <h3><a href="#pod"> 2.2 POD Data Types </a></h3>
 <a name="member-pointers"></a>
 <h3><a href="#member-pointers"> 2.3 Member Pointers </a></h3>
 
+<a name="data-member-pointers"></a>
+<h4><a href="#data-member-pointers"> 2.3.1 Data Member Pointers </a></h4>
+
 <p>
-A pointer to data member is an offset from the base
-address of the class object containing it,
-represented as a <code>ptrdiff_t</code>.
-It has the size and alignment attributes of a <code>ptrdiff_t</code>.
-A NULL pointer is represented as -1.
+The basic ABI properties of data member pointer types are those
+of <code>ptrdiff_t</code>.
 
 <p>
-A pointer to member function is a pair <ptr, adj> as follows:
+A data member pointer is represented as the data member's offset in bytes
+from the address point of an object of the base type, as a
+<code>ptrdiff_t</code>.
 
-<dl>
 <p>
-<dt> <code>ptr</code>:
-<dd> For a non-virtual function, this field is a simple function pointer.
-     (Under current base Itanium psABI conventions,
-     that is a pointer to a GP/function address pair.)
-     For a virtual function,
-     it is 1 plus the virtual table offset (in bytes) of the function,
-     represented as a <code>ptrdiff_t</code>.
-     The value zero represents a NULL pointer,
-     independent of the adjustment field value below.
+A null data member pointer is represented as an offset of <code>-1</code>.
+Unfortunately, it is possible to generate an data member pointer with an
+offset of <code>-1</code> using explicit derived-to-base conversions.
+If this is done, implementations following this ABI may misbehave.
+<span class="future-abi">Recommendation for new platforms: consider using
+<code>PTRDIFF_MIN</code> as the null data member pointer instead.</span>
 
 <p>
-<dt> <code>adj</code>:
-<dd> The required adjustment to <i>this</i>,
-     represented as a <code>ptrdiff_t</code>.
-</dl>
+Note that by <code>[dcl.init]</code>, "zero initialization" of a data
+member pointer object stores a null pointer value into it.  Under this
+representation, that value has a non-zero bit representation.  On most
+modern platforms, data member pointers are the only type with this
+property.
 
 <p>
-It has the size, data size, and alignment
-of a class containing those two members, in that order.
-(For 64-bit Itanium, that will be 16, 16, and 8 bytes respectively.)
+Base-to-derived and derived-to-base conversions of a non-null data member
+pointer can be performed by adding or subtracting (respectively) the static
+offset of the base within the derived class.  The C++ standard does not
+permit base-to-derived and derived-to-base conversions of member pointers
+to cross a <code>virtual</code> base relationship, and so a static offset
+is always known.
 
+<a name="member-function-pointers"></a>
+<h4><a href="#member-function-pointers"> 2.3.2 Member Function Pointers </a></h4>
+
+<p>
+The basic ABI properties of member function pointer types are those of
+the following class:
+
+<pre>
+  struct {
+    fnptr_t ptr;
+    ptrdiff_t adj;
+  };
+</pre>
 
+where <code>fnptr_t</code> is the appropriate function-pointer type
+for the member type.
+
+<p>
+A member function pointer for a non-virtual function is represented
+with <code>ptr</code> set to a function pointer to the function,
+using the base ABI's representation of function pointers.
+
+<p>
+A member function pointer for a virtual function is represented
+with <code>ptr</code> set to 1 plus the virtual table offset of
+the function (in bytes), converted to a function pointer as if by <code>reinterpret_cast&lt;fnptr_t&gt;(uintfnptr_t(1 + offset))</code>,
+where <code>uintfnptr_t</code> is an unsigned integer of the same
+size as <code>fnptr_t</code>.
+
+<p>
+In both cases, <code>adj</code> stores the offset (in bytes) which
+must be added to a pointer to the base type before the call can be
+made.  For a virtual member function pointer, the v-table is loaded
+from the adjusted address.
+
+<p>
+The representation of virtual member function pointers requires the
+representation of a function pointer to a non-static member function
+to never have its lowest bit set.  On most platforms, this is either
+always true, or it can be made true at little cost.  (For example,
+on most platforms a function pointer is just the address of the
+first instruction in the function.  Many architectures align all
+instructions to at least 2 bytes; even on architectures where that's
+not true, or where functions aren't byte-addressed, the compiler can
+just increase the alignment of non-static member functions until the
+low bit of the address is always reliably zero.)  However, some platforms
+use the low bit of a function pointer for special purposes, such as to
+distinguish THUMB functions on ARM.  Such platforms must use a slightly
+different representation: the virtual/non-virtual bit is instead stored
+as the lowest bit of <code>adj</code>, and the adjustment value is
+stored left-shifted by 1.
+
+<p>
+A null member function pointer is represented by a null value for
+<code>ptr</code>.  (This assumes that the low bit of a null pointer
+is not 1; platforms with non-zero bit representations for null function
+pointers may need an adjusted rule.)  The value of <code>adj</code>
+is not specified unless the alternative virtual-bit representation
+is being used, in which case the lowest bit of <code>adj</code> must
+also be zero but the remaining bits are still unspecified.
+
+<p>
+Base-to-derived and derived-to-base conversions of a member function
+pointer can be performed by adding or subtracting (respectively) the
+static offset of the base within the derived class to the value of
+<code>adj</code>.  In the alternative virtual-bit representation,
+the addend must be shifted by one.  Because the adjustment does not
+factor into whether a member function pointer is null, this can be
+done unconditionally when performing a conversion.
 
 <p> <hr> <p>
 <a name="class-types">