todo: per-process read unmet on Cambricon and Iluvatar and partial on Metax

What was left undone

The per-process read on Cambricon and Iluvatar, which this project has no card for, plus the
part of the Metax checklist a host without Kubernetes could not reach. Each has a full adapter
and a full binding wrapper in #92, and each is covered by unit tests over recorded vendor payloads.

Where each one stands

Metax has met a driver, and it showed three defects a recorded payload cannot. #319 ran the
adapter against a real MetaX C600-A with 16 cards and fixed all three: a zero-valued size passed to
an [in,out] MXSML query made the driver refuse to write, leaving driverVersion empty;
sgpu/destroy is a node the vendor documents and the driver never creates, so the missing file read
as an already-reclaimed slice and reclaim returned success while nothing was reclaimed; and
per-process memory matched MXSML's rows against the accelerator's physical id while the rows
themselves key off the device's sequence index, so every row was dropped and every card read back
idle with a successful return code. docs/reference/instance-metrics.md now marks Metax as read on
hardware for memory.

Two checklist steps stayed out of reach on that host, and neither is a formality. The
verification machine had no Kubernetes, so step 1 was exercised at the sysfs level the allocator
itself writes to rather than through a scheduled sliced Instance, and step 4 — the capability gauge
read through a running exporter, which needs device-manager serve against a real kubelet — was not
exercised at all. Those two are what remains for Metax, and access to that hardware is intermittent.

Hygon was the fourth manufacturer in this set and is done — adapter, observable path and docs.
Its evidence is in
this comment and
its follow-up, and the matrix marks it ✅.

Two traps the Hygon run found, which apply to the two untouched manufacturers and to what remains
on Metax

Neither is visible in a unit test over a recorded payload, because a recorded payload is a
successful answer by construction:

• An answering call is not a measuring one. RSMI's host-wide enumeration answers — with the pid,
  and both figures at zero. It is a list of processes, not a measurement, and only the per-device
  query measures. A present symbol is not a working one. The T-Head finding below is the same trap in
  different clothes.
• A fallback chain can have exactly one load-bearing link. On Hygon the product name and the
  compute-unit count both come from the HSA agent alone: the pci.ids link answers only on a host
  carrying the vendor's own copy (upstream has never carried that device id), and the amdgpu
  marketing-name link returns an empty string on a driver that otherwise works. A unit test mocks the
  first link as answering, so the chain looks healthy while its only working link is dead. The cost
  when it happened: an empty product name degenerated the node's feature label key, the Devices
  object never synced, and the node advertised nothing at all.

Where it came from

PR #92, commit feat(devicemanager): read per-process usage on the four untestable manufacturers, and
the bindings it builds on. The PR states the gap and the docs table encodes it per manufacturer.

What it needs in order to run

One card of each, on a node running the device manager. Any single card is enough — this is the
per-process read, not placement, so no multi-card shape is required.

How to verify it

Per manufacturer, on a node carrying one of its cards:

1. Create a logically sliced Instance with a workload that allocates device memory, and read the
   subresource, the exporter and /monitor/snapshot.
2. Assert memoryUsedMiB matches the vendor's own tool to the byte, exactly as the verified five were
   checked (nvidia-smi, rocm-smi, ppu-smi pmon, Ascend's own, hy-smi --showpids).
3. Assert coresUtilizationPercent is either present and plausible, or absent with a named reason —
   never zero. A zero here would be the failure mode this whole change exists to prevent: it reads as
   "measured and idle". The Hygon run showed how to separate the two: read the figure once while the
   workload only holds its allocation and once while the same process runs a kernel.
4. Read gpustack_accelerator_process_capability and confirm the reason it publishes matches what the
   driver actually answered, per entry point.
5. Update the "On hardware" column of docs/reference/instance-metrics.md with the result, and correct
   the memory/compute columns if the driver disagrees with the recorded payload. Say so explicitly
   where a figure has no independent second source — that is not the same evidence as agreement.

Step 1 needs the manufacturer's slice to be known to take effect first — see Related.

What is unproven until then

For Cambricon and Iluvatar: what the subresource, the exporter, /monitor/snapshot and the
capability gauge actually publish from the adapter, and whether the reason taxonomy classifies a
refusal correctly end to end. Neither has met a driver at all, so also unproven is whether the entry
point resolves — and, for Cambricon specifically, whether the compute figure exists.

For Metax: the same publication path, for the opposite reason. Its adapter has now met a driver
and is known to read correctly, but nothing has read it back through a scheduled sliced Instance or
through a running exporter. What those two surfaces publish from a working adapter is still unread,
and a correct adapter does not establish it.

A T-Head finding in #92 is why entry-point resolution deserves a driver rather than trust in symbol
presence: hgmlDeviceGetProcessesUtilizationInfo resolves on that driver and answers
NOT_SUPPORTED to every call, while the older symbol beside it serves the query. Only a driver can
tell the difference.

Related

• #138 — the slice must be known to take effect before a logically sliced Instance means anything.
  Cleared for Hygon by #140; still open for Iluvatar and MThreads.

Review PR #92 and the adapter and binding wrappers it introduced for Cambricon, Iluvatar, and Metax. Start with one manufacturer's hardware and the device-manager entry points, then exercise a sliced Instance, the exporter, /monitor/snapshot, and gpustack_accelerator_process_capability. Done means independent hardware verification, documented results in docs/reference/instance-metrics.md, and named reasons for unsupported measurements.