DWARF Standard


HOME
SPECIFICATIONS
FAQ
ISSUES



090824.1 Tommy Hoffner Coshape of Coarrays in Fortran 2008 Enhancement Accepted with modifications John Bishop



Background
----------
In Fortran, an array has a number of "dimensions", one per index. 
"INTEGER X(10)" declares a ten-element integer array; the elements 
of X are laid out sequentially in memory.

As of the 2008 standard, Fortran also defines "coarrays".  A coarray 
is an array or scalar which has at least one "codimension".  
Codimensions are indexed with square brackets rather than parentheses.  
A "*" must be used as the size of the last codimension and means "up to
a limit based on the number of processes".  The implication of a
codimension is that as the index values of the codimensions vary, 
the array elements are striped across multiple processes.  Note that
processes may be on different processors.  

For example, the coarray "INTEGER X(10)[*]" is a coarray of an array
of integers.  It has a dimension of 10 and a codimension of "*" (the 
current number of processes).  In each process there are ten elements 
laid out sequentially in memory.  In process 1 there are the ten 
elements "X(1)[1]" to "X(10)[1]"; in process 2 there are the ten 
elements "X(1)[2]" to "X(10)[2]" and so on through all the processes.  
Any process can refer to the elements in other processes using the 
square bracket notation.  References without square brackets (e.g. 
"X(3)") are references to the local coarray -- the one which would be 
coindexed with the current process' process number.  There is a 
semantic difference the 'bare' reference and one using the current 
process number but that doesn't matter for DWARF.

A scalar coarray is one where there is only a codimension.  Thus 
"INTEGER Y[*]" is a scalar in each process but the scalars in other 
process can be referred to with the square bracket notation.


Examples 
--------

---[ Scalar that is a coarray ]---

Source:

      INTEGER X[*]

Debug data:

<1><100> DW_TAG_coarray_type
         DW_AT_type <90>                 <-- points to "integer" base type

<2><110> DW_TAG_subrange_type
         DW_AT_lower_bound 1

<1><120> DW_TAG_variable
         DW_AT_name "X"
         DW_AT_type <100>                 <-- points to DW_TAG_coarray_type

The type of the variable "X" is not just the base type of integer, but a 
type which is a coarray of the base integer types.  That type has a child 
entry which is the codimension.

---[ Array that is also a coarray ]---

Source:

      INTEGER X(10)[*]

Debug data:

<1><200> DW_TAG_array_type
         DW_AT_ordering DW_ORD_col_major
         DW_AT_type <90>                 <-- points to "integer" base type

<2><210> DW_TAG_subrange_type
         DW_AT_lower_bound 1
         DW_AT_upper_bound 10

<1><220> DW_TAG_coarray_type
         DW_AT_type <200>                 <-- points to DW_TAG_array_type        

<2><230> DW_TAG_subrange_type
         DW_AT_lower_bound 1

<1><240> DW_TAG_variable
         DW_AT_name "X"
         DW_AT_type <220>                 <-- points to DW_TAG_coarray_type

---[ Multi-dimensioned array that is also a multi-dimensioned coarray ]---

Source:

      INTEGER X(10,11,12)[2,3,*]

Debug data:

<1><300> DW_TAG_array_type
         DW_AT_ordering DW_ORD_col_major
         DW_AT_type <90>                 <-- points to "integer" base type

<2><310> DW_TAG_subrange_type
         DW_AT_lower_bound 1
         DW_AT_upper_bound 10

<2><320> DW_TAG_subrange_type
         DW_AT_lower_bound 1
         DW_AT_upper_bound 11

<2><330> DW_TAG_subrange_type
         DW_AT_lower_bound 1
         DW_AT_upper_bound 12

<1><340> DW_TAG_coarray_type
         DW_AT_type <300>                 <-- points to DW_TAG_array_type        

<2><350> DW_TAG_subrange_type
         DW_AT_lower_bound 1
         DW_AT_upper_bound 2

<2><360> DW_TAG_subrange_type
         DW_AT_lower_bound 1
         DW_AT_upper_bound 13

<2><370> DW_TAG_subrange_type
         DW_AT_lower_bound 1

<1><380> DW_TAG_variable
         DW_AT_name "X"
         DW_AT_type <340>                 <-- points to DW_TAG_coarray_type

---[ end of examples ]---

Proposal:

Section 2.2, page 8:  
Figure 1, Tag names: Add DW_TAG_coarray_type after DW_TAG_base_type.

After section 5.4, page 84, add new section Section 5.5 (and renumber remaining sections):

In Fortran, a "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.

Coarrays are indexed by "codimensions" using a "coindex" or "coindices".

How coarray elements are located and how coindices are converted to
process specifications is processor-dependent.

A coarray is described by a debugging information entry with the tag 
DW_TAG_coarray_type.   Like DW_TAG_array_type, these entries have 
DW_TAG_subrange_type child entries which describe the codimensions and
DW_AT_type attributes pointing to the element type.

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 "*" as the upper bound.  To express this
concept in DWARF, the DW_TAG_subrange_type child entry for that index would have
only a lower bound and no upper bound.

Figure 18, pg 154, Tag Encodings:
Add DW_TAG_coarray_type 0x44

Appendix A
Add entry for TAG DW_TAG_coarray_type
With applicable attributes:
   DECL
   DW_AT_data_location
   DW_AT_name
   DW_AT_sibling
   DW_AT_type


Appendix D.

The Fortran source in figure D.<A> is used to illustrate the use of
DW_TAG_coarray_type to support a variable which is a coarray of a scalar.

-----------------------------------------
      INTEGER X[*]

Figure D.<A> 
-----------------------------------------


Coarray Scalar Example"
The DWARF representation for this is in table D.<B>

-----------------------------------------
10$: DW_TAG_coarray_type
         DW_AT_type( reference to INTEGER )
         DW_TAG_subrange_type
             DW_AT_lower_bound( constant 1 )

11$: DW_TAG_variable
         DW_AT_name( "X" )
         DW_AT_type( reference to coarray type at 10$ )

Figure D.<B> "Coarray Scalar Example" 
-----------------------------------------


Example 2, array that is also a coarray

The Fortran source in figure D.<C> is used to illustrate the use of 
DW_TAG_coarray_type to support a variable which is a coarray of an array.

-----------------------------------------
      INTEGER X(10)[*]

Figure D.<C>
-----------------------------------------

Coarray Array Example
The DWARF representation for this is in table D.<D>

-----------------------------------------
10$: DW_TAG_array_type
         DW_AT_ordering( DW_ORD_col_major )
         DW_AT_type( reference to INTEGER )

11$:     DW_TAG_subrange_type
             DW_AT_lower_bound( constant 1 )
             DW_AT_upper_bound( constant 10 )

12$: DW_TAG_coarray_type
         DW_AT_type( reference to array type at 10$ )

13$:     DW_TAG_subrange_type
             DW_AT_lower_bound( constant 1 )

14$: DW_TAG_variable
         DW_AT_name( "X" )
         DW_AT_type( reference to coarray type at $12 )

Figure D.<D>, Coarray Array Example
-----------------------------------------


Example 3, multi-dimensioned array that is also a multi-dimensioned coarray

The Fortran source in figure D.<E> is used to illustrate the use of
DW_TAG_coarray_type to support a variable which is a multi-dimensioned
coarray of a multi-dimensioned array.

-----------------------------------------
      INTEGER X(10,11,12)[2,3,*]

Figure D.<E> 
-----------------------------------------

Multi-dimensioned Coarray Array Example
The DWARF representation for this is in table D.<F>

-----------------------------------------
10$: DW_TAG_array_type
         DW_AT_ordering( DW_ORD_col_major )
         DW_AT_type( reference to INTEGER )

11$:     DW_TAG_subrange_type
             DW_AT_lower_bound( constant 1 )
             DW_AT_upper_bound( constant 10 )

12$:     DW_TAG_subrange_type
             DW_AT_lower_bound( constant  1 )
             DW_AT_upper_bound( constant 11 )

13$:     DW_TAG_subrange_type
             DW_AT_lower_bound( constant  1 )
             DW_AT_upper_bound( constant 12 )

14$: DW_TAG_coarray_type
         DW_AT_type( reference to array_type at 10$ )

15$:     DW_TAG_subrange_type
             DW_AT_lower_bound( constant 1 )
             DW_AT_upper_bound( constant 2 )

16$:     DW_TAG_subrange_type
             DW_AT_lower_bound( constant 1 )
             DW_AT_upper_bound( constant 3 )

17$:     DW_TAG_subrange_type
             DW_AT_lower_bound( constant 1 )

18$: DW_TAG_variable
         DW_AT_name( "X" )
         DW_AT_type( reference to coarray type at 14$ )

Figure D.<F>, Multi-dimensioned Coarray Array Example
-----------------------------------------

---

Revised 12/6/2012.
Revised 2/14/2013.  Previous version: http://dwarfstd.org/ShowIssue.php?issue=090824.1-1
Revised 4/22/2013.
Revised 5/23/2013:  Added non-normative text to Section 5.5.
		    Added Appendix D examples.
Accepted 4/23/2013 as modified.  


All logos and trademarks in this site are property of their respective owner.
The comments are property of their posters, all the rest © 2007-2017 by DWARF Standards Committee.