Skip to content
Skills Library
Programming · Analysis

attribute-to-layer

/attribute-to-layer

Decide which layer of the VirtIO GPU stack owns a bug before fixing it — the guest driver (UMD/KMD), the virtio transport and virglrenderer, the d3dmetal-native or DXMT backend shim, Apple's D3DMetal itself, Wine/CrossOver behavior, or UTM's display path — by swapping backends, pinning D3DMetal versions, comparing against CrossOver correctly, and running one probe through every layer. Use when a bug might not be ours, when a result differs between backends or from CrossOver, or before investing in a fix.

Repository
utmapp-bot ↗
Licence
Apache-2.0
Last repository change
12.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

Decide which layer of the VirtIO GPU stack owns a bug before fixing it — the guest driver (UMD/KMD), the virtio transport and virglrenderer, the d3dmetal-native or DXMT backend shim, Apple's D3DMetal itself, Wine/CrossOver behavior, or UTM's display path — by swapping backends, pinning D3DMetal versions, comparing against CrossOver correctly, and running one probe through every layer. Use when a bug might not be ours, when a result differs between backends or from CrossOver, or before investing in a fix.

Triggers from the description

s D3DMetal itself, Wine/CrossOver behavior, or UTM

Arguments

/attribute-to-layer <bug or failing test>
Original author description

Decide which layer of the VirtIO GPU stack owns a bug before fixing it — the guest driver (UMD/KMD), the virtio transport and virglrenderer, the d3dmetal-native or DXMT backend shim, Apple's D3DMetal itself, Wine/CrossOver behavior, or UTM's display path — by swapping backends, pinning D3DMetal versions, comparing against CrossOver correctly, and running one probe through every layer. Use when a bug might not be ours, when a result differs between backends or from CrossOver, or before investing in a fix.

How it works

  1. Steps
  2. Decide
  3. Conformance-scale parity (optional)
Original SKILL.md headings · 102 lines, 836 words
SKILL.md preview
---
name: attribute-to-layer
description: Decide which layer of the VirtIO GPU stack owns a bug before fixing it — the guest driver (UMD/KMD), the virtio transport and virglrenderer, the d3dmetal-native or DXMT backend shim, Apple's D3DMetal itself, Wine/CrossOver behavior, or UTM's display path — by swapping backends, pinning D3DMetal versions, comparing against CrossOver correctly, and running one probe through every layer. Use when a bug might not be ours, when a result differs between backends or from CrossOver, or before investing in a fix.
argument-hint: "<bug or failing test>"
---

# Attribute a bug to a layer

Bug: `$ARGUMENTS`

The same symptom can come from six layers. A fix in the wrong one either
does nothing or masks the real bug. Attribute first.

```
guest app -> D3D runtime -> UMD/KMD (guest) -> virtio-gpu (QEMU) -> virglrenderer
          -> backend shim (d3dmetal-native | DXMT) -> D3DMetal (Apple) -> Metal
display:  guest present -> scanout -> QEMU SPICE GL -> UTM window
```

## Steps

1. **Swap the backend.** Run the repro under both backends:
   `utmbot vm up --backend d3dmetal` and `--backend dxmt`, and prove each
   with `utmbot backend`.
   - Fails on one backend only: that backend's shim or D3DMetal/DXMT itself,
     or a translation our layer applies only for it.
   - Fails on both: our guest driver, the transport or virglrenderer, the
     display path, or the app.
   - Compare at equal frame rates: anything rate-dependent (tearing,
     flashes) looks backend-specific when it is not.
2. **Pin the D3DMetal version.** Record the version that ran next to every
   result (`utmbot backend` prints it). Different D3DMetal releases fix and
   break different things.
   - Point `D3DMETAL_FRAMEWORK_PATH` at another D3DMetal build
     (`vm up --env …`) to test a version theory.
   - Before calling something a regression, check which D3DMetal the
     "passing" run used. A known-good result once came from a different
     D3DMetal that had drifted in.
3. **Compare with CrossOver,** which runs the same D3DMetal/DXMT on the host
   without our guest layers. If it works under CrossOver and fails in the
   VM, the difference is ours: guest driver, transport, shim usage or caps.
   `/utmapp-bot:crossover-compare` runs a game or an x64 probe in a bottle
   on a chosen backend and proves the backend (`utmbot cx run`, `cx verify`,
   `cx exec`). Rules:
   - **Verify the backend CrossOver really used from inside the app**, e.g.
     the adapter name or vendor ID it reports. A bottle setting or
     environment override is not proof: CrossOver's compatibility database
     can pick another backend per app, and a D3D9 or OpenGL game never
     reaches D3DMetal or DXMT at all. `cx run` and `cx proof` print the
     proven `BACKEND` and exit 2 when the run did not respect the
     backend asked for.
   - **Make CrossOver look like the VM, never the reverse.** Use the same
     executable name, the same reported vendor and device IDs, the same
     feature level and memory size (`D3DM_VENDOR_ID`, `D3DM_DEVICE_ID`,
     `D3DM_EXE_OVERRIDE` for D3DMetal; crossover-compare has the adapters
     each backend reports by default). D3DMetal and some engines switch
     behavior on the executable name or GPU vendor. *Example: an engine
     enabled shared video surfaces only for some GPU vendor IDs: video was
     black in the VM, fine in CrossOver, and nothing was wrong in the
     driver.*
   - **CrossOver's capability answers are not ground truth.** Its backends
     answer some queries with placeholders. Parity means the same behavior,
     not the same numbers.
   - **A CrossOver "timeout" is often a crash** waiting on a debugger
     dialog. Run CrossOver only while the VM is down: they share the GPU.
4. **One probe through every layer** (`/utmapp-bot:write-gpu-probe`). Run the
   same minimal repro:
   1. against the backend directly on the host (a small program that loads
      D3DMetal or DXMT the way the shim does);
   2. through the shim (d3dmetal-native/DXMT native API);
   3. under CrossOver/Wine as a Windows exe;
   4. in the Neptune guest.

   The first layer where the verdict flips owns the bug.
5. **The display path is its own suspect.** If offscreen readback in the
   guest is right but the window is wrong, it is scanout, SPICE GL or UTM.
   Frames going backwards can only be the display path (triage skill,
   black-screen-and-pacing.md).

## Decide

- **Ours:** fix it in our layer, generically, and land it with
  `/utmapp-bot:land-stack-change` (its review step comes first).
- **A backend defect** (fails raw on the host, or under CrossOver with
  identical failure text): record it with the probe that shows it, and work
  around it in the shim only when the workaround is correct for every legal
  input. Fix our own bugs first. A test counts as a backend defect only when
  CrossOver fails it with the *same* failure; a different failure text is
  two bugs.
- **App behavior** (vendor checks, executable-name profiles): document it.
  Change the driver only if the API contract says we are wrong.
- **More than one layer:** one symptom can need two fixes. An odd answer in
  one layer (a mode list, a capability, a format query) can make the app
  take a path that then breaks another layer. Attribute each cause
  separately, starting from the earliest difference from a working run,
  and expect fixes in more than one repository.

## Conformance-scale parity (optional)

When a whole test suite differs between CrossOver and the VM, compare per
test case, not by totals. The directx-cts harness
(`https://github.com/osy/directx-cts`) runs Microsoft's HLK D3D conformance
content under both and diffs the results per case. A sampled run hides
crashes, so run the full plan of the area you changed. Every test that
passes on CrossOver must pass in the VM; anything only the VM fails is
ours until shown otherwise.

Versions

The database has no other skills named attribute-to-layer.

Database snapshot: 13.11.2026 · package version fc473c6e4655 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100land-stack-change
    Turn an investigation's working tree into clean, reviewable commits across the repos of the VirtIO GPU stack (guest driver, KMD, virglrenderer, backend shims, QEMU, UTM) — separate diagnostics from the fix, check it against the API documentation (MSDN for DirectX APIs and DDIs,…
  • 100crossover-compare
    Run the same Windows D3D11 or D3D12 game (or probe) in CrossOver on this Mac as the A/B partner of a UTM VM — on the D3DMetal or DXMT backend the caller chose (D3D11 on the VM's backend, D3D12 on D3DMetal), on the host without any of our guest layers — in a per-game bottle…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.