5. Lowered variables report

5.1. Generating the report

Poplar can be instructed to generate this report by setting the “debug.loweredVarDumpFile” option when creating the Engine object for the program. This can also be specified by setting an environment variable:

$ export POPLAR_ENGINE_OPTION='{"debug.loweredVarDumpFile":"vars.capnp"}'

This example will generate the report in Cap’n Proto format suitable for use with the PopVision Graph Analyser.

You can also generate the report in JSON format by specifying a .json file:

$ export POPLAR_ENGINE_OPTION='{"debug.loweredVarDumpFile":"vars.json"}'

5.2. Contents of the report

A short extract from the JSON output is shown below.

{
  "numTiles": 1216,
  "targetMemoryInfo": {
    "tileMemory": 262144,
    "interleavedMemoryStart": 131072,
    "memoryElementOffsets": [0, 16384, 32768, 49152, 65536, 81920, 98304, 114688, 131072, 163840, 196608, 229376],
    "supervisorInstrFetchDelay": 64
  },
  "vars": [
    { "var": 0,
      "info": {
        "allocated": true,
        "tile": 0,
        "name": "v1#0",
        "sizeBytes": 16,
        "alignment": 8,
        "offset": 352,
        "category": "variable",
        "isConstant": false,
        "alwaysLive": false,
        "executable": false,
        "vertexCode": false,
        "lowest256KB": false,
        "equivalenceClass": 21,
        "inInterleavedMem": false
      }
    }
  ],
  "equivalenceClassInterference": [
    [0, 16, 19, 20, 22, 25, 26, 28, 29, 30, 31, 32, 33, 34, 35],
    [13, 16, 19, 20, 22, 25, 26, 28, 29, 30, 32, 33, 34, 35]
  ],
  "allocationOrderByTile": [
    [2517, 9, 6, 1301, 1242, 6257, 6258],
    [2519, 11, 1270, 8, 1303, 1271, 1272, 6253, 6254]
  ]
}

The first part of the file summarises the system information: the number of tiles and the memory structure. For more information on the time memory architecture see the Vertex Assembly Programming Guide.

This is followed by information about every area of memory allocated in the graph program (see Variable information) and then some details of how they are allocated (see Allocation information).

5.2.1. Variable information

Each variable is identified by a number. This is used in the Allocation information to reference the variables.

For each variable, the following information is provided:

Table 5.1 Variable information

Field	Description
allocated	True if this variable has been allocated to a tile. If not, the rest of the information should be ignored.
tile	The tile number that the variable resides on.
name	The name of the variable (this may be automatically generated for data that does not correspond to variables created in the source code). The name may have a suffix of the form #n where n corresponds to the tile that the variable is on.
sizeBytes	The size of the variable, in bytes.
alignment	The alignment, in bytes. It is possible for variables to have smaller alignment constraints, but they will still be aligned to at least four bytes
offset	The offset of the variable within the .graph section.
category	The type of data (see Storage categories).
isConstant	True if this variable stores constant data that is never written to (for example, created by the Poplar graph.addConstant() function).
alwaysLive	True if the data is in memory during the whole program execution.
executable	True if this represents executable code.
vertexCode	True if code that is part of a vertex.
lowest256KB	Not used. Always false.
equivalenceClass	The equivalence class that this data belongs to (see Allocation information).
inInterleavedMem	True if this variable must be stored in interleaved memory.
elementConstraints	A list of variables that cannot be stored in the same memory element as this variable.
regionConstraints	A list of variables that cannot be stored in the same memory region as this variable.

5.2.2. Allocation information

Table 5.2 Allocation information

Constraint	Description
equivalenceClassInterference	Variables that have the same lifetime are grouped into sets called equivalence classes. This means that the compiler only needs to calculate the interference (overlap in memory use) between the classes rather than individual variables. This field contains a list of equivalence classes, with each entry being a list of other equivalence classes that conflict with this one. The list is indexed from zero.
equalAddressConstraints	This field is obsolete.
allocationOrderByTile	This field consists of a list for each tile. Each of these lists the variables on each tile, in the order that they are allocated.