# Issue 090824.1: Coshape of Coarrays in Fortran 2008

Author: Tommy Hoffner John Bishop 2009-08-24 Enhancement Accepted with modifications 5
```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:

Appendix A
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/issues/090824.1-1.html
Revised 4/22/2013.
Revised 5/23/2013:  Added non-normative text to Section 5.5.