Tungsten Debug Information Schema (debuginfo.json)

Overview

debuginfo.json describes instruction addresses, source locations, inline call stacks, tasks, and declarations for a compiled kernel. Use Portrait to browse source and execution together; you do not need to edit this file.

Keep the debug files from the same build as the image and simulation trace. listing.json provides Portrait's source listing, and bench.map supplies memory symbols for Portrait, miget, and meminsp.

The fields below are useful when inspecting debug information directly.

Paint writes one debuginfo.json for the whole layout (bench-debuginfo.json in a build). Its keys are compile ids, each holding one kernel's object in the shape below, plus .map, which lists the compile ids on each tile, indexed by x and then y. That file has no top-level version. The compiler also leaves each kernel's object in <kernel>_artefacts/<kernel><id>_debuginfo.json.

Schema (Version 1)

{
  // Schema version — consumers must check this before parsing.
  "version": 1,

  // Target architecture name.
  "arch": "sdr",

  // Source file that was compiled.
  "source_file": "kernel.w",

  // Unique compilation ID (from paint parameterization).
  "ucid": "0",

  // Compilation parameters (name→value from paint set= args).
  "parameters": {
    "N": "1024",
    "BLOCK_SIZE": "16"
  },

  // Task definitions with entry points.
  "tasks": [
    {
      "id": 0,
      "name": "main_task",
      "entry_addr": "0x0100",
      "status": "active"
    }
  ],

  // Handler definitions.
  "handlers": [
    {
      "name": "T0_main",
      "entry_addr": "0x0200"
    }
  ],

  // Variable/memory declarations for listing rendering.
  // This is NOT a replacement for bench.map — it provides type info for
  // display purposes only. bench.map remains authoritative for memory layout.
  "declarations": [
    {
      "name": "buf",
      "type": "xp",
      "address": "0x2000",
      "dims": [
        { "name": "r", "extent": 16 },
        { "name": "n", "extent": 128 }
      ],
      "section": "data",
      "is_register": false
    },
    {
      "name": "r0",
      "type": "xp",
      "address": null,
      "dims": [],
      "section": null,
      "is_register": true
    }
  ],

  // The core of debuginfo: every emitted instruction with full debug metadata.
  "instructions": [
    {
      // Word address (16-bit), always 4-digit hex.
      "addr": "0x0001",

      // Human-readable assembly text (YETI format).
      "asm": "fmace R0 = R1, R2;",

      // Source location for this instruction.
      // null if no source info available.
      "source": {
        "file": "kernel.w",
        "line": 10,
        "func": "compute"
      },

      // Inline call stack from innermost callee to outermost call site.
      // Empty array if not inlined.
      "inline_stack": [
        { "file": "math.w", "line": 25, "func": "add" }
      ],

      // Task or handler this instruction belongs to.
      "task_id": 0,

      // Basic block name (if available).
      "block": "entry"
    }
  ],

  // List of IR passes that ran during compilation.
  // Enables cross-referencing instructions to .wll dump files.
  "ir_passes": [
    {
      "id": 0,
      "name": "wmcir-assign-mem-addresses",
      "wll_file": "gs_sym-000-wmcir-assign-mem-addresses.wll"
    },
    {
      "id": 1,
      "name": "wmcir-encode",
      "wll_file": "gs_sym-001-wmcir-encode.wll"
    }
  ],

  // Source file lines for display (optional, included when source is available).
  "source_lines": {
    "kernel.w": [
      [1, "// kernel.w"],
      [2, "task main() {"],
      [3, "  xp buf[16];"],
      [10, "  buf[r] += a * b;"]
    ]
  }
}

---

Field Reference

Top-Level Fields

Field	Type	Required	Description
version	int	yes	Schema version of the kernel's object (currently 1)
arch	string	yes	Target architecture name, as given to the compiler's arch= ("sdr")
source_file	string	yes	Primary source file path
ucid	string	yes	The compile's ucid= value: the suffix of its <source>_artefacts file names. Paint gives each compile its own
parameters	object	no	Compilation parameters (name→string value)
tasks	array	yes	Task definitions
handlers	array	yes	Handler definitions
declarations	array	yes	Variable/register declarations
instructions	array	yes	Per-instruction debug entries
ir_passes	array	no	IR pass list for .wll cross-reference
source_lines	object	no	Source file contents for display

Instruction Entry

Field	Type	Description
addr	string	4-digit hex word address ("0x0001")
asm	string	YETI assembly text
source	object/null	{file, line, func} or null
inline_stack	array	Array of {file, line, func} frames
task_id	int/null	Task ID this instruction belongs to
block	string/null	Basic block name

Declaration Entry

Field	Type	Description
name	string	Variable/register name
type	string	Base type ("xp", "hp", "sp", "u32", etc.)
address	string/null	Hex address or null for registers
dims	array	Array of {name, extent} for array dimensions
section	string/null	Memory section: "data", "cache", "load" or "void"
is_register	bool	True if this is a register, not memory

Task Entry

Field	Type	Description
id	int	Task ID
name	string	Task name
entry_addr	string	Entry point hex address
status	string	Initial status: "idle", "active", "block" or "active_block"

Handler Entry

Field	Type	Description
name	string	Handler name
entry_addr	string	Entry point hex address

---

Using the files

Run a tutorial with GOAL=debugx, then launch portrait from its test-<id> directory. Select a tile and an instruction to inspect the corresponding source location and available operand values.

Use bench.map with meminsp to inspect memory symbols; debuginfo.json is not an input to meminsp.