9bfe96e44d
- Category pages linked each family as `<slug>.md`, relative to categories/, where no family page lives. They now link `../<category>/<slug>.md`. - Form pages linked a member into its *own* category directory, so every VMX128 sibling (`vsldoi128`) pointed at vmx128/ although its family page is under vmx/. They now link into the family's directory. - Hand-written "Related" and sibling mentions linked other categories' pages as if they were in the same directory. 109 are retargeted through the page index; 29 that pointed a family page at itself (`vrefp128` on vrefp.md) and 6 naming instructions the manual has no page for are plain text now. Regenerated at the existing Canary pin (f21ebd49e): upstream has moved on, and re-pinning belongs in its own change. The generator reports 0 family pages changed and is idempotent; the only dead links left are TEMPLATE.md's placeholders. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
116 lines
4.9 KiB
Markdown
116 lines
4.9 KiB
Markdown
# `dcbi` — Data Cache Block Invalidate
|
||
|
||
> **Category:** [Memory](../categories/memory.md) · **Form:** [X](../forms/X.md) · **Opcode:** `0x7c0003ac`
|
||
|
||
<!-- GENERATED: BEGIN -->
|
||
|
||
## Assembler Mnemonics
|
||
|
||
| Mnemonic | XML entry | Flags | Description |
|
||
| --- | --- | --- | --- |
|
||
| `dcbi` | `dcbi` | — | Data Cache Block Invalidate |
|
||
|
||
## Syntax
|
||
|
||
```asm
|
||
dcbi [RA0], [RB]
|
||
```
|
||
|
||
## Encoding
|
||
|
||
### `dcbi` — form `X`
|
||
|
||
- **Opcode word:** `0x7c0003ac`
|
||
- **Primary opcode (bits 0–5):** `31`
|
||
- **Extended opcode:** `470`
|
||
- **Synchronising:** no
|
||
|
||
| Bits | Field | Meaning |
|
||
| --- | --- | --- |
|
||
| 0–5 | `OPCD` | primary opcode |
|
||
| 6–10 | `RT/FRT/VRT` | destination |
|
||
| 11–15 | `RA/FRA/VRA` | source A |
|
||
| 16–20 | `RB/FRB/VRB` | source B |
|
||
| 21–30 | `XO` | extended opcode (10 bits) |
|
||
| 31 | `Rc` | record-form flag |
|
||
|
||
## Operands
|
||
|
||
| Field | Role | Description |
|
||
| --- | --- | --- |
|
||
| `RA0` | dcbi: read | Source GPR; when the encoded register number is 0 the operand is the literal 64-bit zero, **not** `r0`. |
|
||
| `RB` | dcbi: read | Source GPR. |
|
||
|
||
## Register Effects
|
||
|
||
### `dcbi`
|
||
|
||
- **Reads (always):** `RA0`, `RB`
|
||
- **Reads (conditional):** _none_
|
||
- **Writes (always):** _none_
|
||
- **Writes (conditional):** _none_
|
||
|
||
## Status-Register Effects
|
||
|
||
_No condition-register or status-register effects._
|
||
|
||
## Operation (pseudocode)
|
||
|
||
```
|
||
; No hand-written pseudocode for this instruction yet.
|
||
; The authoritative semantics are the Canary emitter snapshot under
|
||
; Implementation References; about half of Canary's emitters open
|
||
; with the PPC-style definition as a comment (`RD <- (RA) + (RB)`).
|
||
; Every side effect is also enumerated in the Register Effects and
|
||
; Status-Register Effects tables above.
|
||
```
|
||
|
||
## C Translation Example
|
||
|
||
```c
|
||
/* No hand-written C yet. Translate the Canary emitter snapshot */
|
||
/* under Implementation References; its HIR maps directly: */
|
||
/* f.LoadGPR(n) / f.StoreGPR(n, v) -> r[n] / r[n] = v */
|
||
/* f.LoadFPR / StoreFPR, f.LoadVR / StoreVR -> f[n], v[n] */
|
||
/* f.Load(ea, T), f.Store(ea, v) -> raw read / write; emitters */
|
||
/* wrap them in f.ByteSwap for the big-endian guest value */
|
||
/* f.UpdateCR(n, v) -> CR field n from v's LOW 32 BITS vs 0 */
|
||
/* f.LoadCA / f.StoreCA -> xer.CA; f.StoreSAT -> vscr.SAT */
|
||
/* i.XO.RA, i.D.DS, ... -> the bit-fields listed under Operands */
|
||
/* The Register Effects and Status-Register Effects tables above */
|
||
/* enumerate every side effect a faithful translation must emit. */
|
||
```
|
||
|
||
## Implementation References
|
||
|
||
**`dcbi`**
|
||
- Canary XML: [`tools/ppc-instructions.xml` — search for `mnem="dcbi"`](https://github.com/xenia-canary/xenia-canary/blob/f21ebd49e979e44f081f474df78c3fbfee9cb3f2/tools/ppc-instructions.xml)
|
||
- Sylpheed opcode: [`crates/sylpheed-ppc/src/opcode.rs:45`](../../../crates/sylpheed-ppc/src/opcode.rs#L45)
|
||
- Sylpheed decoder: [`crates/sylpheed-ppc/src/decoder.rs:926`](../../../crates/sylpheed-ppc/src/decoder.rs#L926)
|
||
|
||
<!-- GENERATED: END -->
|
||
|
||
## Special Cases & Edge Conditions
|
||
|
||
- **Privileged.** Unlike `dcbf` and `dcbst`, `dcbi` is supervisor-only. Executing in problem state raises a privileged-instruction (program) interrupt. Game code never issues `dcbi` directly; only the kernel.
|
||
- **Drops dirty data.** The line is removed from cache **without** writing back, so any modifications that have not already been pushed to memory are lost. Used only when the underlying memory is being repurposed (e.g. DMA window flip, page demap) and stale dirty data would be incorrect.
|
||
- **Cache line size.** Xenon lines are 128 bytes. The low seven bits of `EA` are ignored — the operation targets the cache line that contains `EA`.
|
||
- **`RA0` semantics.** When `RA = 0`, base is literal zero, so `dcbi 0, RB` invalidates the line containing address `RB`.
|
||
- **Canary does not implement it.** `dcbi` is in its opcode table but has no emitter, so translating one logs "Unimplemented instr" and, with the default `break_on_unimplemented_instructions`, breaks.
|
||
- **Sequencing.** Not synchronising. Pair with [`sync`](../alu/sync.md) when invalidation must precede a subsequent load on another thread.
|
||
- **Architecturally subsumed by `dcbf` for problem state.** Userspace that wants "this line is no longer valuable" must use [`dcbf`](dcbf.md), accepting the write-back cost.
|
||
|
||
## Related Instructions
|
||
|
||
- [`dcbf`](dcbf.md) — flush (write-back + invalidate); the unprivileged alternative.
|
||
- [`dcbst`](dcbst.md) — write-back without invalidate.
|
||
- [`dcbz`](dcbz.md), `dcbz128` — allocate-and-zero a line.
|
||
- [`dcbt`](dcbt.md), [`dcbtst`](dcbtst.md) — prefetch hints.
|
||
- [`icbi`](icbi.md) — instruction-cache analog (also problem-state, not privileged).
|
||
- [`sync`](../alu/sync.md), [`isync`](../alu/isync.md) — pair with cache-control ops for ordering.
|
||
|
||
## IBM Reference
|
||
|
||
- [AIX 7.3 — `dcbi` (Data Cache Block Invalidate)](https://www.ibm.com/docs/en/aix/7.3.0?topic=set-dcbi-data-cache-block-invalidate-instruction)
|
||
- `PowerISA v2.07B Book II` for the privilege model and cache-coherence rules.
|