First draft of Version 5, incorporating numerous approved changes
[dwarf-doc.git] / dwarf5 / latexdoc / typeentries.tex
index 4bd6c29..407d151 100644 (file)
@@ -105,7 +105,7 @@ is
 new 
 \addtoindexx{data bit offset attribute}
 in 
-\addtoindex{DWARF Version 4} and
+\addtoindex{DWARF Version 4}, unchanged in \addtoindex{DWARF Version 5}, and
 is also used for bit field members 
 (see Section \refersec{chap:datamemberentries}). 
 It
@@ -114,67 +114,11 @@ replaces the attribute
 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} 
 when used for base
 \addtoindexx{bit offset attribute (V3)}
-types as defined in DWARF V3 and earlier. The earlier attribute
-is defined in a manner suitable for bit field members on
-big\dash endian architectures but which is wasteful for use on
-little\dash endian architectures.}
-
-\textit{The attribute \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} is 
-deprecated in 
-\addtoindex{DWARF Version 4}
-for use in base types, but implementations may continue to
-support its use for compatibility.}
-
-\textit{The 
-\addtoindex{DWARF Version 3}
-definition of these attributes is as follows.}
-\begin{myindentpara}{1cm}
-\textit{A base type entry has a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}
-attribute, whose value
-(see Section \refersec{chap:staticanddynamicvaluesofattributes})
-is the size in bytes of the storage unit
-used to represent an object of the given type.}
-
-\textit{If the value of an object of the given type does not fully
-occupy the storage unit described by the byte size attribute,
-the base type entry may have a 
-\livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute 
-\addtoindexx{bit size attribute (V3)}
-and a
-\livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} attribute, both of whose values 
-(see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
-are integers. The bit size attribute describes the actual
-size in bits used to represent a value of the given type.
-The bit offset attribute describes the offset in bits of the
-high order bit of a value of the given type from the high
-order bit of the storage unit used to contain that value.}
-\end{myindentpara}
-
-\needlines{5}
-\textit{In comparing 
-DWARF Versions 3 
-\addtoindexx{DWARF Version 3}
-and 
-\addtoindexx{DWARF Version 4} and 4, note that DWARF V4
-defines the following combinations of attributes:}
-
-\begin{itemize}
-\item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}}
-\item \textit{\livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}}
-\item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size},
-\livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} 
-and optionally \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset}}
-\end{itemize}
-\textit{DWARF V3 defines the following combinations:}
-\addtoindexx{DWARF Version 3}
-% FIXME: the figure below interferes with the following
-% bullet list, which looks horrible as a result.
-\begin{itemize}
-\item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}}
-\item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}, 
-\livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and 
-\livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}}
-\end{itemize}
+types as defined in DWARF V3 and earlier.
+\livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}
+is deprecated for use in base types in DWARF Version 4 and later.
+See Section 5.1 in the DWARF Version 4
+specification for a discussion of compatibility considerations.}
 
 \begin{table}[!here]
 \caption{Encoding attribute values}
@@ -243,6 +187,7 @@ base types are used in combination with
 \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale}
 attributes.
 
+\needlines{5}
 A \livelink{chap:DWATdecimalsign}{DW\_AT\_decimal\_sign} attribute 
 \addtoindexx{decimal sign attribute}
 is an \livelink{chap:classconstant}{integer constant} that
@@ -343,6 +288,7 @@ a
 attribute with the same interpretation as described for the
 \livelink{chap:DWATEpackeddecimal}{DW\_ATE\_packed\_decimal} and \livelink{chap:DWATEnumericstring}{DW\_ATE\_numeric\_string} base types.
 
+\needlines{4}
 For a data type with a decimal scale factor, the fixed binary
 type entry has a 
 \livelink{chap:DWATdecimalscale}{DW\_AT\_decimal\_scale} attribute 
@@ -561,7 +507,7 @@ character. This is encoded in DWARF as:}
 \end{alltt}
 \end{dwflisting}
 
-\needlines{3}
+\needlines{5}
 \textit{On the other hand}
 \begin{lstlisting}[numbers=none]                        
    volatile unsigned char * const restrict p;
@@ -723,6 +669,40 @@ which are described in
 Section \refersec{chap:dynamictypeproperties}. 
 For relevant examples, see also Appendix \refersec{app:fortran90example}.
 
+\section{Coarray Type Entries}
+\label{chap:coarraytypeentries}
+\addtoindexx{coarray}
+\textit{In Fortran, a \doublequote{coarray} is an array whose
+elements are located in different processes rather than in the
+memory of one process. The individual elements
+of a coarray can be scalars or arrays.
+Similar to arrays, coarrays have \doublequote{codimensions} that are 
+indexed using a \doublequote{coindex} or multiple \doublequote{coindices}.
+\addtoindexx{codimension|see{coarray}}
+\addtoindexx{coindex|see{coarray}}
+}
+
+A coarray type is represented by a debugging information entry 
+with the tag \livetarg{chap:DWTAGcoarraytype}{DW\_TAG\_coarray\_type}.
+If a name has been given to the 
+coarray type in the source, then the corresponding coarray type 
+entry has a \DWATname{} attribute whose value is a null-terminated 
+string containing the array type name as it appears in the source 
+program.
+
+A coarray entry has one or more \DWTAGsubrangetype{} child entries,
+one for each codimension. It also has a \DWATtype{} attribute 
+describing the type of each element of the coarray.
+
+\textit{In a coarray application, the run-time number of processes in the application
+is part of the coindex calculation.  It is represented in the Fortran source by
+a coindex which is declared with a \doublequote{*} as the upper bound.  To express this
+concept in DWARF, the \DWTAGsubrangetype{} child entry for that index has 
+only a lower bound and no upper bound.}
+
+\textit{How coarray elements are located and how coindices are 
+converted to process specifications is processor-dependent.}
+
 \section{Structure, Union, Class and Interface Type Entries}
 \label{chap:structureunionclassandinterfacetypeentries}
 
@@ -1308,7 +1288,7 @@ Appendix \refersec{app:pascalexample}.}
 
 \textit{Attribute \livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset} 
 is new in 
-\addtoindex{DWARF Version 4}
+\addtoindex{DWARF Version 4}, unchanged in \addtoindex{DWARF Version 5},
 and is also used for base types 
 (see Section 
 \refersec{chap:basetypeentries}). 
@@ -1317,108 +1297,12 @@ It replaces the
 attributes \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} and
 \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} when used to
 identify the beginning of bit field data members as defined
-in DWARF V3 and earlier. The earlier attributes are defined
-in a manner suitable for bit field members on big-endian
-architectures but which is either awkward or incomplete for
-use on little-endian architectures.  
-(\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} also
-has other uses that are not affected by this change.)}
-
-\textit{The \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}, 
+in DWARF V3 and earlier. The \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}, 
 \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and 
 \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}
 attribute combination is deprecated for data members in DWARF
-Version 4, but implementations may continue to support this
-use for compatibility.}
-
-\textit{The 
-\addtoindex{DWARF Version 3} 
-definitions of these attributes are
-as follows.}
-\begin{myindentpara}{1cm}
-\textit{If the data member entry describes a bit field, then that
-entry has the following attributes:}
-
-\begin{itemize}
-\item \textit{A \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} 
-attribute whose value 
-(see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
-is the number of bytes that contain an instance of the
-bit field and any padding bits.}
-
-\textit{The byte size attribute may be omitted if the size of the
-object containing the bit field can be inferred from the type
-attribute of the data member containing the bit field.}
-
-\item \textit{A \livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} 
-attribute 
-\addtoindexx{bit offset attribute (V3)}
-whose value 
-(see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
-is the number of bits to the left of the leftmost
-(most significant) bit of the bit field value.}
-
-\item \textit{A \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} 
-attribute 
-\addtoindexx{bit size attribute (V3)}
-whose value 
-(see Section \refersec{chap:staticanddynamicvaluesofattributes}) 
-is the number of bits occupied by the bit field value.}
-
-\end{itemize}
-
-\textit{The 
-\addtoindex{location description} for a bit field calculates the address
-of an anonymous object containing the bit field. The address
-is relative to the structure, union, or class that most closely
-encloses the bit field declaration. The number of bytes in this
-anonymous object is the value of the byte size attribute of
-the bit field. The offset (in bits) from the most significant
-bit of the anonymous object to the most significant bit of
-the bit field is the value of the bit offset attribute.}
-\end{myindentpara}
-
-
-\textit{Diagrams similar to the above that show the use of the
-\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}, 
-\livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and 
-\livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset} attribute
-combination may be found in the 
-\addtoindex{DWARF Version 3} Standard.}
-
-\textit{In comparing 
-DWARF Versions 3 and 4,
-\addtoindexx{DWARF Version 3}
-\addtoindexx{DWARF Version 4}
-note that DWARF V4
-defines the following combinations of attributes:}
-\begin{itemize}
-\item \textit{either \livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location} 
-or
-\livelink{chap:DWATdatabitoffset}{DW\_AT\_data\_bit\_offset} 
-(to specify the beginning of the data member)}
-\end{itemize}
-\textit{optionally together with}
-\begin{itemize}
-\item  \textit{either \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} or 
-\livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} (to
-specify the size of the data member)}
-\end{itemize}
-\textit{DWARF V3 defines the following combinations:}
-\begin{itemize}
-\item \textit{\livelink{chap:DWATdatamemberlocation}{DW\_AT\_data\_member\_location} 
-(to specify the beginning
-of the data member, except this specification is only partial
-in the case of a bit field) }
-\end{itemize}
-\textit{optionally together with}
-\begin{itemize}
-\item \textit{\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size}, 
-\livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} and 
-\livelink{chap:DWATbitoffset}{DW\_AT\_bit\_offset}
-(to further specify the beginning of a bit field data member
-as well as specify the size of the data member) }
-\end{itemize}
+Version 4 and later. See Section 5.6.6 in the DWARF Version 4
+specification for a discussion of compatibility considerations.}
 
 \subsection{Member Function Entries}
 \label{chap:memberfunctionentries}
@@ -1605,7 +1489,7 @@ the template definition, the name attribute for the debugging
 information entry representing the special compilation unit
 should be empty or omitted.
 
-\needlines{5}
+\needlines{4}
 \item If the class type entry representing the template
 instantiation or any of its child entries contains declaration
 coordinate attributes, those attributes should refer to
@@ -1937,11 +1821,11 @@ tag \livelink{chap:DWTAGunspecifiedparameters}{DW\_TAG\_unspecified\_parameters}
 
 
 \section{String Type Entries}
-\label{chap:classstringtypeentries}
+\label{chap:stringtypeentries}
 
 \textit{A \doublequote{string} is a sequence of characters that have specific
 \addtoindexx{string type entry}
-semantics and operations that separate them from arrays of
+semantics and operations that distinguish them from arrays of
 characters. 
 \addtoindex{Fortran} is one of the languages that has a string
 type. Note that \doublequote{string} in this context refers to a target
@@ -1952,39 +1836,63 @@ A string type is represented by a debugging information entry
 with the tag \livetarg{chap:DWTAGstringtype}{DW\_TAG\_string\_type}. 
 If a name has been given to
 the string type in the source program, then the corresponding
-string type entry has a \livelink{chap:DWATname}{DW\_AT\_name} attribute
+string type entry has a 
+\livelink{chap:DWATname}{DW\_AT\_name} attribute
 \addtoindexx{name attribute}
 whose value is
 a null\dash terminated string containing the string type name as
 it appears in the source program.
 
+\needlines{4}
+The string type entry may have a 
+\livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute or 
+\livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}
+attribute, whose value 
+(see Section \refersec{chap:byteandbitsizes}) 
+is the amount of
+storage needed to hold a value of the string type.
+
+
 The 
 \hypertarget{chap:DWATstringlengthstringlengthofstringtype}
-string type entry may have a 
+string type entry may also have a 
 \livelink{chap:DWATstringlength}{DW\_AT\_string\_length} attribute
 whose 
 \addtoindexx{string length attribute}
 value is a 
 \addtoindex{location description} yielding the location
-where the length of the string is stored in the program. The
-string type entry may also have a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute
-or \livelink{chap:DWATbitsize}{DW\_AT\_bit\_size} attribute, whose value 
-(see Section \refersec{chap:byteandbitsizes}) 
+where the length of the string is stored in the program.
+If the \DWATstringlength{} attribute is not present, the size
+of the string is assumed to be the amount of storage that is
+allocated for the string (as specified by the \DWATbytesize{}
+or \DWATbitsize{} attribute).
+
+The string type entry may also have a 
+\livetarg{chap:DWATstringlengthbytesize}{DW\_AT\_string\_length\_byte\_size}
+attribute or
+\livetarg{chap:DWATstringlengthbitsize}{DW\_AT\_string\_length\_bit\_size} attribute,
+\addtoindexx{string length attribute!size of length data}
+whose value (see Section \refersec{chap:byteandbitsizes}) 
 is the size of the data to be retrieved from the location
 referenced by the string length attribute. If no (byte or bit)
 size attribute is present, the size of the data to be retrieved
 is the same as the 
-\addtoindex{size of an address} on the target machine.Fif the amount
-
-\needlines{4}
-If no string length attribute is present, the string type
-entry may have a \livelink{chap:DWATbytesize}{DW\_AT\_byte\_size} attribute or 
-\livelink{chap:DWATbitsize}{DW\_AT\_bit\_size}
-attribute, whose value 
-(see Section \refersec{chap:byteandbitsizes}) 
-is the amount of
-storage needed to hold a value of the string type.
+\addtoindex{size of an address} on the target machine.
 
+\addtoindexx{DWARF Version 5}  % Avoid italics
+\textit{Prior to DWARF Version 5, the meaning of a 
+\DWATbytesize{} attribute depends on the presence of the
+\DWATstringlength{} attribute:
+\begin{itemize}
+\item If \DWATstringlength{} is present, \DWATbytesize{} 
+       specifies the size of the length data to be retrieved 
+       from the location specified by the \DWATstringlength{} attribute.
+\item If \DWATstringlength{} is not present, \DWATbytesize{}
+       specifies the amount of storage allocated for objects
+       of the string type.
+\end{itemize}
+In DWARF Version 5, \DWATbytesize{} always specifies the amount of storage 
+allocated for objects of the string type.}
 
 \section{Set Type Entries}
 \label{chap:settypeentries}
@@ -2107,16 +2015,21 @@ be a language\dash dependent default constant.
 \addtoindexx{lower bound attribute!default}
 The default lower bound is 0 for 
 \addtoindex{C}, \addtoindex{C++}, 
-\addtoindex{D}, 
+\addtoindex{D},
+\addtoindex{Go},
+\addtoindex{Haskell}, 
 \addtoindex{Java}, 
 \addtoindex{Objective C}, 
 \addtoindex{Objective C++},
+\addtoindex{OpenCL},
 \addtoindex{Python}, and 
 \addtoindex{UPC}. 
 The default lower bound is 1 for 
-\addtoindex{Ada}, \addtoindex{COBOL},
+\addtoindex{Ada}, 
+\addtoindex{COBOL},
 \addtoindex{Fortran}, 
 \addtoindex{Modula-2},
+\addtoindex{Modula-3},
 \addtoindex{Pascal} and 
 \addtoindex{PL/I}.