DocsExtensionsV1

Runtime

These methods do not need a debugger session. Addresses are not involved. Offline VMs still appear in listVms.

JSON field names are camelCase. That is the serde rename the host uses.

listVms

host.v1.listVms takes no params. The result is an array of RunningVmInfo:

[
  {
    "id": "f1e6a94c-6ee2-4c9b-8a44-9be7b2ca6cf1",
    "name": "macOS Sonoma",
    "state": "running",
    "generation": 3
  },
  {
    "id": "offline-board",
    "name": "Windows 11 Arm",
    "state": "offline"
  }
]

generation is omitted when the VM is not live (skip_serializing_if on Option). state for a live session is the aggregate run-state string:

`state`	Meaning
`offline`	Registered, no session
`stopped`	Session has no machine (guest shutdown)
`resetting`	A vCPU requested reset
`running`	Any vCPU is running, or still in platform release-wait
`halted`	Every vCPU is halted, none wakeable
`paused`	Otherwise

getVmState

{ "vmId": "f1e6a94c-6ee2-4c9b-8a44-9be7b2ca6cf1" }

{ "state": "paused" }

A missing session returns { "state": "offline" }, not an error.

pauseVm and resumeVm

Same params as getVmState. The host calls Session::pause or Session::resume, emits the UI state event, and returns { "state": "<label>" } from the live session.

A VM that is not running returns -32000 with VM "<id>" is not running.

getVmUsage

Same { "vmId" }. The result is VmUsage from introspection, the object Overview already polls. First sample after launch reports 0 for rates because no prior interval exists.

One vCPU, software backend, no exec-profile dump:

{
  "runState": "running",
  "cpuCount": 1,
  "activeCpuCount": 1,
  "cpuPercent": 12.5,
  "averageIps": 1000000.0,
  "totalIps": 1000000.0,
  "minimumIps": 1000000.0,
  "maximumIps": 1000000.0,
  "averageCpuTimeIps": 2000000.0,
  "ipsSupported": true,
  "instructionsRetiredTotal": 4000000,
  "cpuTimeNsTotal": 2000000,
  "guestExecNsTotal": 0,
  "guestResidencyPercent": 0.0,
  "guestResidencyAvailable": false,
  "uptimeSeconds": 8,
  "memoryCapacityBytes": 4294967296,
  "memoryCommittedBytes": 4294967296,
  "perCpu": [
    {
      "vcpu": 0,
      "runState": "running",
      "cpuPercent": 12.5,
      "active": true,
      "ips": 1000000.0,
      "cpuTimeIps": 2000000.0,
      "ipsSupported": true,
      "instructionsRetired": 4000000,
      "cpuTimeNs": 2000000,
      "guestExecNs": 0,
      "guestExecNsSupported": false,
      "exitsTotal": 12,
      "exitsHalt": 4,
      "exitsShutdown": 0,
      "exitsReset": 0,
      "exitsIrqWindow": 0,
      "mmio": 8,
      "pio": 0,
      "irq": 0
    }
  ],
  "mmioTotal": 8,
  "pioTotal": 0,
  "irqTotal": 0,
  "exitsTotal": 12,
  "exitsHaltTotal": 4,
  "exitsShutdownTotal": 0,
  "exitsResetTotal": 0,
  "exitsIrqWindowTotal": 0,
  "networkInterfaces": [
    {
      "index": 0,
      "device": "virtio-net",
      "macAddress": "52:54:00:12:34:56",
      "linkUp": true,
      "rxBytes": 0,
      "txBytes": 0,
      "rxPackets": 0,
      "txPackets": 0
    }
  ],
  "x86ExecProfile": null,
  "aarch64ExecProfile": null,
  "acceleration": {
    "activeBackend": "software-interpreter",
    "requestedMode": "auto",
    "accelerated": false,
    "fellBack": false,
    "reason": ""
  },
  "processSchedulerTransitions": {
    "wfeIdleExpiries": 0,
    "wfeIdleWakes": 0,
    "wfiIdleExpiries": 0,
    "wfiIdleWakes": 0,
    "wfiDeadlineBounded": 0,
    "schedulerYields": 0,
    "schedulerReenters": 0,
    "schedulerBackstopYields": 0
  }
}

When the guest is generic AArch64, acceleration.aarch64Execution is present:

{
  "requestedHighestEl": "el3",
  "effectiveHighestEl": "el2",
  "guestOwnsEl2": true,
  "platformOwnsEl3": true,
  "executionMode": "platform_owned_el3",
  "el3NativeEligible": false,
  "el3NativeActive": false
}

That object is the unit-test encoding of Aarch64ExecutionStatus. executionMode is native, dormant_el3, software_only_el3, native_el3, or platform_owned_el3. Optional fallbackReason and readinessReason are omitted when null.

x86ExecProfile / aarch64ExecProfile are filled only when that executor profile is enabled. They serialize as null otherwise.