RedBear-OS/local/docs/AMDGPU-DC-COMPILE-TRIAGE-PLAN.md

# AMDGPU DC Compile Triage Plan

**Date:** 2026-04-18
**Scope:** Triage of the current Red Bear amdgpu AMD Display Core compile path, specifically the
decision between growing the Linux compatibility surface and narrowing the imported display/DC
source set to the bounded path actually needed for first display bring-up.

> **Planning authority note (2026-04-18):** this file is a focused amdgpu/DC compile-triage and
> execution document. It does not replace `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md` as the
> canonical GPU/DRM plan. Use the DRM modernization plan for overall execution order, Intel/AMD
> parity criteria, and broader acceptance gates. Use this file for the specific question of how to
> triage the current amdgpu DC compile break without drifting into open-ended compatibility work.

> **Status update (2026-04-18):** Phase 1B has now been carried out in bounded form. The `amdgpu`
> recipe builds successfully on the retained Red Bear glue path (`amdgpu_redox_main.c` +
> `redox_stubs.c`), while the imported Linux AMD display, TTM, and amdgpu core trees remain
> explicitly outside the retained compile surface and still under compile triage.

## Title and intent

Red Bear currently compiles the imported AMD display tree too broadly for the evidence-backed goal
it actually has today.

The immediate goal is **not** to prove that the full imported AMD Display Core tree compiles on
Redox. The immediate goal is to unblock the bounded display path needed for first display-side
bring-up while preserving a maintainable route toward broader DC closure later.

This document exists to prevent two failure modes:

1. treating the first compile error as if it justifies unconstrained `linux-kpi` expansion, and
2. claiming progress from a narrowed compile path without documenting exactly what was excluded and
   why.

## Current grounded state

### Bottom line

The original broad-tree failure was **not** a `freesync.c`-specific logic bug. It exposed a broader
mismatch between the imported AMD DC / TTM / amdgpu trees and the current Red Bear compatibility
strategy.

After narrowing the recipe to the actual retained first-display path, the `amdgpu` recipe now
builds successfully from the Red Bear glue layer alone. That is the current truthful state: the
bounded retained path builds, while the imported Linux trees remain under compile triage rather than
being claimed as compile-complete.

### Confirmed evidence

| Area | Current evidence | Repo grounding |
|---|---|---|
| Historical broad-path rule | The old recipe compiled all `display/*.c` files and failed in optional AMD DC code before the retained path was proven | historical recipe state + `local/recipes/gpu/amdgpu/target/x86_64-unknown-redox/build/freesync.o.log` |
| Current retained build rule | The current recipe compiles only the bounded Red Bear glue path and links `libamdgpu_dc_redox.so` from that retained surface | `local/recipes/gpu/amdgpu/recipe.toml` |
| Historical first hard failure | `freesync.c -> dm_services.h -> dm_services_types.h -> os_types.h -> linux/kgdb.h` | `local/recipes/gpu/amdgpu/target/x86_64-unknown-redox/build/freesync.o.log` |
| Current shim posture | Compatibility surface is partial, not absent | `local/recipes/drivers/linux-kpi/source/src/c_headers/`, `local/recipes/gpu/amdgpu/source/redox_glue.h` |
| Small retained-path shim probes attempted | Added minimal `linux/export.h` and `linux/refcount.h` while testing whether imported TTM belonged on the retained path | `local/recipes/drivers/linux-kpi/source/src/c_headers/linux/export.h`, `.../linux/refcount.h` |
| Switch criterion outcome | Imported TTM immediately fanned into broader Linux-kernel surfaces (`__cond_acquires`, `iosys-map`, and related header fallout), so the retained path was narrowed again instead of growing shims further | retained build logs during TTM probe |
| Current Red Bear need | First display bring-up needs a bounded display path, not proof that all optional AMD DC subtrees compile | `local/docs/DRM-MODERNIZATION-EXECUTION-PLAN.md`, `local/docs/AMD-FIRST-INTEGRATION.md` |

### Why the current approach is unstable

The current amdgpu recipe uses a broad compile rule that effectively says:

> compile the imported display tree first, then see what breaks.

That is useful for discovery, but it is a poor default execution strategy for bounded bring-up.

It pulls optional and advanced display code into the same compile surface as the first modeset path,
which means a failure in a module such as FreeSync can block the entire experiment even when that
module is not yet proven necessary for the first Red Bear display target.

## Triage question

Red Bear needs an explicit answer to this question before continuing:

> Should the repo first grow the Linux compatibility layer until the full imported AMD display tree
> compiles further, or should it first narrow the imported source set to the display path Red Bear
> actually needs today?

This document answers:

- **Start with Strategy B** — narrow the DC source set.
- Use **Strategy A** — minimal shim additions — only as a controlled fallback when the retained,
  bounded display path still proves a small required compatibility gap.

## Strategy comparison

| Strategy | What it does | Best when | Success criteria | Main failure mode |
|---|---|---|---|---|
| **A. Minimal shim additions** | Add the smallest Linux compatibility surface needed to expose the next blocker | The real retained display path is already known, and the missing API surface stays small and generic | Each shim advances the build by one blocker class without broadening scope dramatically | Header whack-a-mole grows into de facto kernel-environment emulation |
| **B. Narrow the DC source set** | Replace broad full-tree compile with an explicit bounded file list aligned to the actual first display goal | Optional or advanced modules are being pulled into the build before their necessity is proven | The reduced source set compiles further or reveals the next blocker on the true bring-up path | False confidence if the narrowed claim is not documented precisely |

## Recommendation

### Recommendation summary

Start with **B: narrow the compiled DC source set to the bounded display path Red Bear actually
uses today**.

That recommendation has now been implemented in bounded form. The retained path was narrowed far
enough to prove that the current Red Bear bring-up surface does not need the imported Linux AMD
display, TTM, or amdgpu core trees in order to build the shipped `amdgpu` recipe.

The current evidence supports that recommendation because:

1. the recipe compiles the entire imported display tree,
2. the first blocker sits in a dependency cone that likely contains several more Linux/DRM header
   and semantic assumptions, and
3. Red Bear's current need is bounded display bring-up, not immediate proof that every imported
   AMD DC subsystem compiles under Redox.

### Why A is not the first move

The first hard failure (`linux/kgdb.h`) is shallow enough to tempt a quick shim fix. That is useful
only if the retained path is already known. Right now it is not. Without narrowing the source set
first, each new shim risks paying compatibility cost for files Red Bear may not need for first
bring-up.

That is the main hidden cost of Strategy A at this stage: it can create real maintenance debt before
the repo has proven that the affected code is on the first bring-up path at all.

## ULW execution plan

## Phase 0 — Freeze the baseline

### Goal

Create one canonical failure snapshot that all later triage work can refer back to.

### Actions

- Record the current broad display compile rule in the amdgpu recipe.
- Record the first failing translation unit and full include chain.
- Record the current bounded Red Bear display objective and the currently targeted ASIC/runtime
  surface.

### Exit criteria

One written baseline exists showing:

- the current full-tree compile behavior,
- the current first hard failure at `linux/kgdb.h`, and
- the current bounded display objective.

### Current status

- complete enough to proceed

## Phase 1B — Narrow-source probe

### Goal

Identify the minimum imported display/DC source set required for current Red Bear display bring-up.

### Required mindset

The question in this phase is not “what can Linux build?”

The question is:

> what does Red Bear actually need compiled now to support its present display-side target?

### Actions

- Replace broad `find .../display -name '*.c'` behavior with an explicit bounded file list.
- Treat the first retained file list as a **probe hypothesis**, not as a proven final minimum.
- Keep only the C sources required for the current Red Bear bring-up surface hypothesis:
  - device initialization,
  - connector detection and mode enumeration,
  - bounded modeset path,
  - cleanup,
  - and the currently targeted ASIC families.
- Exclude obvious scope inflators first unless the call graph proves they are required:
  - `modules/freesync/*`,
  - untargeted DCN generations,
  - `amdgpu_dm/*`,
  - optional feature modules not on the first display path.

### Verification

- The reduced file list is explicit and reviewable.
- The reduced build is re-run.
- The next failure is checked to confirm that it occurs on the retained bounded path rather than in
  an excluded optional subtree.

### Exit criteria

One of the following becomes true:

1. the narrowed set compiles meaningfully further than the current build, or
2. the next blocker appears on the real retained path and is therefore a justified compatibility
   problem.

### Failure signal

If the narrowed set cannot be described cleanly because the retained path immediately drags in broad
optional subsystems, stop and move to the decision gate rather than continuing to guess.

### Current status

- complete — the retained path is now explicit and builds

## Phase 1A — Minimal-shim probe

### Goal

Expose the next blocker with the smallest justified compatibility addition.

### Entry condition

Only do this after Phase 1B has established a retained bounded path, or after the narrowed path
proves that a small missing Linux primitive is genuinely required.

### Allowed shim order

Add one shim family at a time, in this rough priority order:

1. `linux/kgdb.h`
2. `asm/byteorder.h`
3. `linux/vmalloc.h`
4. `ktime_get_raw_ns` / timekeeping support
5. `div64_u64` / `div64_u64_rem`
6. `linux/refcount.h`

### Rules

- One shim family per change.
- No speculative shim batches.
- No ad hoc amdgpu-only workaround when the gap clearly belongs in `linux-kpi`.
- If a shim exposes a large new Linux subsystem expectation rather than a narrow primitive, stop and
  reconsider the strategy.

### Verification

- Re-run the build after each shim family.
- Confirm that the build advances by one blocker class.
- Confirm that the next failure remains on the retained bounded path.

### Exit criteria

- The build advances by exactly one blocker class, and
- the next failure still belongs to the retained bounded path.

### Failure signal

If one shim immediately reveals several unrelated Linux subsystem requirements, stop and return to
Strategy B.

## Phase 2 — Decision gate

### Stay on Strategy B if

- the blocker sits in optional or advanced code such as FreeSync,
- narrowing quickly reduces the blocker surface,
- failures outside the retained path disappear,
- or the retained path becomes understandable and controllable.

### Switch from B to A if

- **all** of the following are true:
  - an explicit retained file list has been written down,
  - the failure reproduces on that retained path after the narrowing pass,
  - the missing piece is a small generic primitive or header family rather than a broad subsystem
    expectation,
  - and the same compatibility gap is visible across multiple retained core files or one retained
    shared include chain.

### Abort A and return to B if

- more than one or two unrelated shim families are required before reaching a meaningful compile
  milestone,
- missing APIs are dominated by files outside the retained runtime path,
- or the work starts resembling unconstrained kernel-environment emulation.

## Phase 3 — Continue on the chosen path

### If B wins

- Keep the bounded file list explicit.
- Document exactly what the bounded claim covers.
- Do not quietly re-expand the tree.
- Add excluded modules back only behind explicit proof of need.
- Treat success here as **compile-triage progress only**. It does not imply full DC feature closure,
  optional-module completeness, or runtime readiness.

### If A wins

- Expand `linux-kpi` deliberately rather than scattering shims through amdgpu-local code.
- Keep each new shim family generic and reusable where possible.
- Track each new compatibility family as maintenance debt that must justify itself.

## Commit slicing

Recommended commit order:

1. narrow source set only,
2. first shim family only,
3. one blocker family per follow-up change.

Never mix broad source pruning and broad compatibility growth in the same commit.

## Red / Green / Refactor loop

### Red

The historical full-tree display build failed at `linux/kgdb.h` while compiling `freesync.c`.

### Green

Either:

- the narrowed source set compiles further, or
- one small shim advances the retained path to the next blocker.

Current green state:

- the bounded retained path now builds successfully,
- and the imported Linux AMD display / TTM / amdgpu trees remain explicitly excluded pending proven
  need.

### Refactor

Codify the smallest proven source set and execution path before adding more compatibility surface.

## Hidden failure modes

### Strategy B hidden failure mode

Strategy B can produce false confidence if the repo narrows the file list but does not write down
what functionality is now intentionally out of scope.

That is why every narrowing step must be paired with an explicit bounded claim.

### Strategy A hidden failure mode

Strategy A can feel productive because each header addition removes one hard stop. But that can hide
the fact that the repo is drifting into long-term Linux-environment emulation for code that the
current Red Bear target may not even need.

That is why A must stay subordinate to a retained, justified source set.

## Definition of done

This triage plan is complete when:

- the repo has an explicit choice between bounded source narrowing and compatibility expansion,
- the choice is backed by compile evidence,
- optional AMD DC modules are not silently treated as required for first bring-up,
- and compatibility growth, if needed, is happening in the right long-term layer.

For clarity, done here means the compile-triage path is explicit and justified. It does **not** mean
that the full AMD DC tree is complete, that excluded optional modules are unnecessary in all future
phases, or that runtime display validation is closed.

## Immediate next action

Do this next:

1. keep the retained `amdgpu` build path explicit and bounded,
2. do not quietly re-introduce imported Linux AMD display / TTM / core sources,
3. re-introduce imported subsystems only behind concrete runtime or feature evidence,
4. if a future re-introduction attempt fans into broad Linux-kernel compatibility work again,
   treat that as a new triage pass rather than as proof that the broader tree belongs in the
   default retained build.