Overview

Beginning with version 17.7, PGI compilers have the ability to export information gathered from the internal representation (IR) of various compilation stages in an organized, machine readable text format. This Program Analysis Summary Output (PASO) feature is enabled using the -Msummary compiler option. The data provides a detailed summary of the program’s internal structure, spanning all the files that make up a project. PASO data contains detailed information about every function call site, every place where a variable is declared, read, or modified, OpenACC and OpenMP regions, and more.

Usage

PASO data export is enabled using the -Msummary option during compilation. PASO is supported on all PGI compilers for Linux x86-64 and Windows using the proprietary PGI back end.

By default the compilers embed the export data into the executable as a data section. This creates a section ".IPXPORT" which can be extracted using the pgextract command:

pgextract  (executable) -cz -name ".IPXPORT" (output filename)

JSON File Format

PASO uses JSON (JavaScript Object Notatation) format to export the internal data structures. The core syntax of JSON formatting is summarized below.

Structures: delimited by { }
Elements: "name":"data"(,)
Arrays: ["data","data","data"]

Correctly formatted JSON consists of a main structure encapsulating various pairs of named elements. A structure or array can take the place of any "data" element.

{
     "name":"example",
     "array":["one","two"],
     "structure":{
          "name":"substruct",
          "value":"10"
     }
}

Export File Structure

Within an PASO export file, there are a variety of structures. These include:

Data type definition:
Contains the internal name, size, and prototype of a structure, union, or derived type.
File:
Represents an object file, with its source if available. Contains data about the file and its contents, and any functions and modules.
Module:
A Fortran module, contains any module functions.
Function:
Represents a function, method, procedure, or a Fortran subroutine, program, or subprogram. Contains information about variables, calls, and assignments
Variable:
Contains metadata, type information, bindings to functions where it is used or modified, and default values
Binding records:
Contains information about an instance where a variable is used, modified, or assigned.
Call records:
Record of a function call, arguments passed, and additional binding information for variables passed as arguments.
Attributes:
Various properties of a function or variable covering a wide variety of additional information.

Structures Breakdown

Data Type Structures Breakdown

{
     "type":"derived D60",                   Type name
     "size":"16",                            Size in bytes
     "structure":"{int;int;int;int;}"        Layout
}

File Structures Breakdown

"file1":{                                    Generated unique file ID
     "name":"example.o",                     Object filename
     "source":"example.c",                   Source file
     "newobjectname":"_example.o",           Result of recompilation
     "library":"lib/xyz.ipl",                Library containing object
     "compiler":"PGI 16.10",                 Compiler version info
     "language":"c",                         Source compilation type
     "modules":{module structures},          Struct containing modules
     "functions":{function structures}       Struct of functions defined
}

Function Structures Breakdown

"testfunc":{                                  Name
     "name":"_testfunc",                      Mangled name
     "uname":"testfunc",                      Original name
     "module":"m1",                           Containing module
     "host program":{progref},                Parent program reference
     "lineno":"10",                           Source line number
     "size":"3",                              Size/weight of function
     "type":"(int)(*int,char)",               Function prototype
     "attributes":[…],                        Function attributes
     "loops":"2",                             Loops in function
     "max loop nest":"2",                     How many levels of nesting
     "direct calls":"1",                      Direct calls to this function
     "indirect calls":"1"                     Indirect/aliased calls
     "parameters":{…},                        Parameter variables
     "variables":{…},                         Local variables
     "common":[…],                            Common block vars used
     "globals":[…],                           Global variables used
     "nonlocal used":[…],                     Vars whose values are used
     "nonlocal modified":[…],                 Vars that are modified
     "callers":[…],                           Names of calling functions
     "calls":[…],                             Ordered list of call records
     "modules used":[…]                       List of modules used here
}

Modules Stuctures Breakdown

"testmodule":{                                Name of module
     "testfunc":{…},                          Function definition
     "testfunc2":{…}                          Etc.
}

Variables Structures Breakdown

{
     "name":"x",                              Name within current scope
     "type":"unsigned int",                   Full data type
     "bindings":[binding structures],         List of binding references
     "attributes":[…]                         List of attributes
}

Bindings Structures Breakdown

Binding references mean different things in different cases. A parameter is bound to any variables or constants that are passed to it, and any variables from which they are derived. A variable can also be bound to an assignment from another variable, a constant, or an expression. Bindings are a part of the variable that contains them.

{
     "type":"assignment/argument",            Type of binding
     "variable":{var}                         Variable derived from
     "constant":"100",                        Constant assigned
     "expr"                                   Runtime calculated value
}

Variable and Function References

All references within an PASO export file include a structure containing the file, function, module, host program, or variable name as needed. For example:

{"file":"file1","function":"main","variable":"var"}
{"file":"file3","module":"m","function":"func"}
{"file":"file2","program":"prog","function":"func2"}

General Attributes

addrtkn                 Address taken
alias                   Is an alias of another
assigned                Value will be changed
called                  Known path from main
canrecompile            Have source information
common                  Part of a common block
const                   Constant value
constvar                Is not changed
dummy                   Dummy argument definition
extern                  Can be called from another file
f90pointer              Fortran pointer
fileglobal              Global to current file
fromlib                 From a shared library
globalinit              Called before main
haveinfo                Info obtained from original source file
inline                  Declared as inline
inlineable              Can be inlined
inmodule                From a Fortran module
intrin                  Intrinsic function
main                    Main program or function
not-called              Never explicitly called
acc                     Function contains or call inside ACC region
omp                     Function contains or call inside OMP region

Export File Structure Schema

{
     "datatypes":[list of datatype structures],
     "files":{ 
          "file1":{
               (metadata)
               "functions":{
                    "func1":{
                         (metadata)
                         "variables":{
                              "var1":{
                                   "type":"xyz",     
                                   "bindings":[…],
                                   "attributes":[…]
                               },
                               …
                          },
                          "calls":[…]
                     },
                     …
                }
           },
           …
     }
}
Click me