To: J3                                                     10-205r4
From: Bill Long
Subject: Interop TR: Version numbers
Date: 2010 October 13
Reference: 10-165r2.pdf, 10-203

Discussion:

A Version number scheme was suggested as a means for implementations
to detect possible incompatible changes to the header file and
descriptor contents. A Version Number would be included in the header
file as a macro that expands to an integer constant.  Similarly, a
Version member is added to the C descriptor.  If a user-written
function, or one of the supplied intrinsic functions, determines that
the version number in a C descriptor does not match the corresponding
Version in the header file included when the function was compiled, an
error can be issued.  This facility allows for possible future changes
to the C descriptor definition by providing a means of detecting when
incompatible descriptor definitions are being used.

As an example, a function is compiled with an 'old' header file
included, but gets linked into a code that is compiled with a 'new'
header file included.  If the new C descriptor version is not an
upward compatible extension of the old one, the memory reference
offsets into the descriptor in the old function might be wrong for the
format of the descriptor being passed to the function.  This is not an
issue for a set of user files that are all re-compiled
together. However, it could be an issue for a collection of library
routines that are archived and later linked into new codes.

This feature is useful only if the location and format of the version
field is fixed in the descriptor. Otherwise a program compiled with a
new header file would not be able to find the version in an old
descriptor. This requires that the layout of the members of the cdesc
struct be more constrained.

Edits to 10-165r2:


[9:19-20] In the second sentence of 5.2.2 CFI_cdesc_t, para 1, replace
"in any order:" with ".". Then add two new sentences: "The first three
members of the struct shall be base_addr, elem_len, and version in
that order. The final member shall be dim, with the other members
after version and before dim in any order."

[9:26+] Add a new member to the C descriptor struct:

"int version; shall be set equal to the value of CFI_VERSION in the
ISO_Fortran_binding.h header file that defined the format and meaning
of this descriptor."


[10:23+] Add a new paragraph and Note after p2 of 5.2.5 Macros:

"CFI_VERSION - an integer constant that encodes the version of the
ISO_Fortran_binding.h header file containing this macro."

   "NOTE 5.0+
   The intent is that the version should be increased every time that
   the header is incompatibly changed, and that the version in a descriptor may
   be used to provide a level of upwards compatibility, by using
   means not defined by this Technical Report."


[12:33+] Add a new paragraph after para 1 of 5.2.7 Restrictions on the
use of C descriptors.

"The elem_len, version, rank, type, and attribute members of a C
descriptor shall be defined with valid values before the descriptor is
used to represent an object, and once defined the values of these
members shall not be redefined or become undefined while the members
of the descriptor are capable of being referenced."