OS Awareness

Software-aware debug contexts are created with ContextManager.add-software-context.

ContextManager.new name=cm0
cm0.attach board=board0
cm0.add-software-context board=board0 name=boot config=./os-awareness/linux.yaml

The config argument points at a YAML file describing the OS-awareness plugin to use and the debug artifacts associated with that software context.

YAML structure

The YAML document is a mapping with the following top-level keys:

version

Optional schema version. Current examples use 1.

plugin

Required root plugin name such as bare-metal, sparc-rtems, riscv-linux, or sparc-xng.

kind

Optional semantic discriminator for the node.

main

Common debug artifact bindings for the current node.

plugin-config

Plugin-specific configuration values.

images

Optional mapping of child image identifiers to nested image nodes.

Relative paths in the YAML file are resolved relative to the YAML file itself, not relative to the current working directory.

main

The main mapping holds common debug artifact references. Supported keys currently include:

  • debug-info: Main ELF, symbol-map, or other object file used to create the software context.

  • symbols: Optional alternate symbol file.

  • source-root: Optional source root used for source lookup/path mapping.

Additional keys may be added later.

plugin-config

The plugin-config mapping contains plugin-specific values. Examples:

  • Linux: runqueue-symbol, hypervisor-root, second-level-root

  • XNG: partition-file

Key names may use - or _. The OS-awareness configuration layer treats runqueue-symbol and runqueue_symbol as equivalent.

images

images is a recursive mapping from a plugin-defined target identifier to a child node with the same structure as the root node.

The meaning of the key depends on the parent plugin:

  • For Linux it is typically an absolute executable path in the target file system such as /sbin/init.

  • For XNG it can be a partition name such as Partition0.

  • For future hypervisor-style plugins it can be a guest, VM, or partition name.

Each child node may define:

  • kind: Semantic type such as executable, partition, or guest

  • plugin: Optional child plugin override

  • main

  • plugin-config

  • nested images

This allows a hierarchical debug description, for example a hypervisor with guest partitions where one partition runs Linux and itself contains executable mappings.

Example: bare metal

version: 1
plugin: bare-metal

main:
  debug-info: ../bare-metal/bare-metal.elf
  source-root: ../bare-metal

Example: Linux kernel with executable mapping

version: 1
plugin: riscv-linux

main:
  debug-info: ../RISC-V/Linux/hello-world/build/build/linux-6.13.12/vmlinux
  source-root: ../RISC-V/Linux/hello-world

plugin-config:
  runqueue-symbol: runqueues

images:
  /sbin/init:
    kind: executable
    main:
      debug-info: ../RISC-V/Linux/hello-world/build/images/fw_payload.elf
      source-root: ../RISC-V/Linux/hello-world

Example: XNG hypervisor with partition mapping

version: 1
plugin: sparc-xng

main:
  debug-info: ../sparcv8-xng-hello-world/hello-world.elf
  source-root: ../sparcv8-xng-hello-world

plugin-config:
  partition-file: ../sparcv8-xng-hello-world/xml/module.xml

images:
  Partition0:
    kind: partition
    main:
      debug-info: ../sparcv8-xng-hello-world/Partition0.elf
      source-root: ../sparcv8-xng-hello-world

Example: nested hierarchy

version: 1
plugin: hypervisor

main:
  debug-info: ./hypervisor.elf

images:
  linux-guest:
    kind: guest
    plugin: riscv-linux
    main:
      debug-info: ./linux/vmlinux
    plugin-config:
      runqueue-symbol: runqueues
    images:
      /sbin/init:
        kind: executable
        main:
          debug-info: ./linux/init.elf