4 Source Code Instrumentation for Data Structures

By the following options, the source-to-source translation instruments the Fortran source program for data structures:

    fadapt -DINSTR <source_file>

The option -DINSTR itself is an abbreviation for a set of options:

    -DINSTR = -instr -dsp=array -pseudo=no -args=single -prof:DATA

• The option -instr makes a source-to-source translation that instruments the source program.

• The option -dsp=array guarantees that for all arrays of the source program a runtime descriptor will be generated (see Section 4.1).

• The option -args=single should be used to avoid that array descriptors are passed as additional arguments for subprogram calls (this feature is mainly necessary for HPF compilation and not considered here).

• The option -pseudo=no should be used to avoid that array descriptors are used for the features of ADAPTOR to make dynamic arrays to pseudo-dynamic arrays (feature used for HPF compilation).

• The option -prof:DATA is needed to generate runtime calls when array descriptors are available for the regions of the program and will also generate runtime calls when the values of array descriptors have changed (e.g. when they are allocated or deallocated, or when a pointer is assigned or nullified, see also Section 4.2).

4.1 Array Runtime Descriptors

The following example program is used to show how ADAPTOR introduces array descriptors.

       program TEST
       integer, parameter :: N = 10
       real, dimension (N) :: A
       real, dimension (N, N) :: B
       end program TEST

       fadapt -instr -dsp=array test.f

Every array defined in a subprogram unit gets a descriptor which is defined as an integer array of a certain size.

      program TEST
      integer, parameter :: N=10
      real, dimension (1:N) :: A
      real, dimension (1:N,1:N) :: B
      integer, dimension (1:256) :: A_DSP
      integer, dimension (1:256) :: B_DSP

Every array descriptor is defined and set when the subprogram starts:

      call DALIB_array_make_dsp (A_DSP,1,4,0,'A')
      call DALIB_array_define (A_DSP,1,N)
      call DALIB_array_setdata (A_DSP,A)
      call DALIB_array_make_dsp (B_DSP,2,4,0,'B')
      call DALIB_array_define (B_DSP,1,N,1,N)
      call DALIB_array_setdata (B_DSP,B)

• The routine dalib_array_make_dsp defines rank, size and name of the array in the descriptor.
• The routine dalib_array_define defines the extension of the array (lower and upper bounds in all dimensions).
• The routine dalib_array_setdata sets the memory address of the array in the descriptor.

Every array descriptor in a subprogram will be freed at the end of the subprogram.

      call DALIB_array_free (B_DSP,B)
      call DALIB_array_free (A_DSP,A)

For allocatable arrays the routines dalib_array_define and dalib_array_setdata are called when the array is allocated.

      real, dimension (:,:), allocatable :: C
      integer, dimension (1:256) :: C_DSP
      ...
      call DALIB_array_make_dsp (C_DSP,2,4,0,'C')
      call DALIB_array_define (C_DSP,1,N,1,N)
      allocate (C(1:N,1:N))
      call DALIB_array_setdata (C_DSP,C)
      ... 
      deallocate (C)
      call DALIB_array_deallocated (C_DSP)
      ...
      call DALIB_array_free (C_DSP,C)

4.2 Instrumentation for Data Profiling

Array descriptors on its own cannot be used for data profiling as they are not related to the regions of the program. For this purpose some additional instrumentation is needed that is enabled by the flag -prof:DATA.

• The routine dalib_region_dsp is called in every subprogram after the array descriptors have been defined.

    call DALIB_start_region (-1,'TEST',0,'test.f',0,1)
    ...
    call DALIB_array_make_dsp (C_DSP,2,4,0,'C')
    call DALIB_region_dsp (3,0,0,0,0,A_DSP,B_DSP,C_DSP)
  

  The routine passes all local, global, dummy, module and common array descriptors that are visible in the current subprogram.
• The routine dalib_mem_update is called for every descriptor where the memory layout has changed.

        allocate (C(1:N,1:N))
        call DALIB_array_setdata (C_DSP,C)
        call DALIB_mem_update (C_DSP)
        ...
        deallocate (C)
        call DALIB_array_deallocated (C_DSP)
        call DALIB_mem_update (C_DSP)
        ...
  

With this instrumentation, the runtime system knows for a region which data structures are valid during its lifetime and can map back virtual addresses to the data structures of the program.

4.3 Information about Data Layout

The instrumentation for data structures can give information about the memory layout at any place in the instrumented program. For test purposes or for getting some internal info about the layout, the following subroutine can be called in the user program:

      call DALIB_mem_info ()

At runtime, the information about the data structures in the region is written out.

  (region=25,dummy)  0x40580010:0x4058c00f IT (1:12288), size=4
   ...
  (region=25,dummy)  0x40619010:0x4067b00f WW (1:12544,1:4), size=8
  (region=25,local)  0x4067c020:0x40688023 INLD (0:12288), size=4
  (region=25,local)  0x40689020:0x40695023 INUD (0:12288), size=4
  (region=25,dummy)  0x40a47030:0x40d9280f AU (1:431868), size=8
  (region=25,dummy)  0x40d93030:0x410de80f AL (1:431868), size=8
  (region=25,dummy)  0x41d09030:0x41eaec1f IAU (1:431868), size=4
  (region=25,dummy)  0x4212f030:0x422d4c1f IAL (1:431868), size=4