fabi/Sylpheed
1
0
Fork 0
Code Issues 9 Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
Sylpheed/tools/ppc-manual/vmx/vpkshss.md
sim 9bfe96e44d fix(ppc-manual): 543 dead links, from two generator bugs and wrong relative paths 
- 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>
2026-09-16 22:37:12 +02:00

204 lines
8.6 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# `vpkshss` — Vector Pack Signed Half Word Signed Saturate
> **Category:** [VMX (Altivec)](../categories/vmx.md) · **Form:** [VX](../forms/VX.md) · **Opcode:** `0x1000018e`
<!-- GENERATED: BEGIN -->
## Assembler Mnemonics
| Mnemonic | XML entry | Flags | Description |
| --- | --- | --- | --- |
| `vpkshss` | `vpkshss` | — | Vector Pack Signed Half Word Signed Saturate |
| `vpkshss128` | `vpkshss128` | — | Vector128 Pack Signed Half Word Signed Saturate |
## Syntax
```asm
vpkshss [VD], [VA], [VB]
vpkshss128 [VD], [VA], [VB]
```
## Encoding
### `vpkshss` — form `VX`
- **Opcode word:** `0x1000018e`
- **Primary opcode (bits 0–5):** `4`
- **Extended opcode:** `398`
- **Synchronising:** no
| Bits | Field | Meaning |
| --- | --- | --- |
| 0–5 | `OPCD` | primary opcode (4) |
| 6–10 | `VRT/VD` | destination vector register |
| 11–15 | `VRA/VA` | source A vector register |
| 16–20 | `VRB/VB` | source B vector register |
| 21–31 | `XO` | extended opcode (11 bits) |
### `vpkshss128` — form `VX128`
- **Opcode word:** `0x14000200`
- **Primary opcode (bits 0–5):** `5`
- **Extended opcode:** `512`
- **Synchronising:** no
| Bits | Field | Meaning |
| --- | --- | --- |
| 0–5 | `OPCD` | primary opcode (4 or 5) |
| 6–10 | `VD128l` | destination low 5 bits |
| 11–15 | `VA128l` | source A low 5 bits |
| 16–20 | `VB128l` | source B low 5 bits |
| 21 | `VA128H` | source A high bit |
| 22 | `—` | reserved |
| 23–25 | `VC` | optional VC / XO sub-field |
| 26 | `VA128h` | source A middle bit |
| 27 | `—` | reserved |
| 28–29 | `VD128h` | destination high 2 bits |
| 30–31 | `VB128h` | source B high 2 bits |
## Operands
| Field | Role | Description |
| --- | --- | --- |
| `VA` | vpkshss: read; vpkshss128: read | Source A vector register. |
| `VB` | vpkshss: read; vpkshss128: read | Source B vector register. |
| `VD` | vpkshss: write; vpkshss128: write | Destination vector register. |
| `VSCR` | vpkshss: write; vpkshss128: write | Vector Status and Control Register (NJ/SAT bits). |
## Register Effects
### `vpkshss`
- **Reads (always):** `VA`, `VB`
- **Reads (conditional):** _none_
- **Writes (always):** `VD`, `VSCR`
- **Writes (conditional):** _none_
### `vpkshss128`
- **Reads (always):** `VA`, `VB`
- **Reads (conditional):** _none_
- **Writes (always):** `VD`, `VSCR`
- **Writes (conditional):** _none_
## Status-Register Effects
- `vpkshss`: **VSCR[SAT]** may be stickied on saturating vector operations.
- `vpkshss128`: **VSCR[SAT]** may be stickied on saturating vector operations.
## 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
**`vpkshss`**
- Canary XML: [`tools/ppc-instructions.xml` — search for `mnem="vpkshss"`](https://github.com/xenia-canary/xenia-canary/blob/f21ebd49e979e44f081f474df78c3fbfee9cb3f2/tools/ppc-instructions.xml)
- Canary emitter: [`src/xenia/cpu/ppc/ppc_emit_altivec.cc:1831`](https://github.com/xenia-canary/xenia-canary/blob/f21ebd49e979e44f081f474df78c3fbfee9cb3f2/src/xenia/cpu/ppc/ppc_emit_altivec.cc#L1831)
- Sylpheed opcode: [`crates/sylpheed-ppc/src/opcode.rs:405`](../../../crates/sylpheed-ppc/src/opcode.rs#L405)
- Sylpheed decoder: [`crates/sylpheed-ppc/src/decoder.rs:586`](../../../crates/sylpheed-ppc/src/decoder.rs#L586)
<details><summary>Canary emitter (frozen snapshot @ <code>f21ebd49e9</code>)</summary>
```cpp
int InstrEmit_vpkshss(PPCHIRBuilder& f, const InstrData& i) {
return InstrEmit_vpkshss_(f, i.VX.VD, i.VX.VA, i.VX.VB);
}
// ── delegates to (src/xenia/cpu/ppc/ppc_emit_altivec.cc:1816) ──
int InstrEmit_vpkshss_(PPCHIRBuilder& f, uint32_t vd, uint32_t va,
uint32_t vb) {
// Vector Pack Signed Halfword Signed Saturate
// Convert VA and VB from signed words to signed saturated bytes then
// concat:
// for each i in VA + VB:
// i = int8_t(Clamp(EXTS(int16_t(t)), -128, 127))
// dest = VA | VB (lower 8bit values)
Value* v = f.Pack(f.LoadVR(va), f.LoadVR(vb),
PACK_TYPE_8_IN_16 | PACK_TYPE_IN_SIGNED |
PACK_TYPE_OUT_SIGNED | PACK_TYPE_OUT_SATURATE);
f.StoreSAT(f.DidSaturate(v));
f.StoreVR(vd, v);
return 0;
}
```
</details>
**`vpkshss128`**
- Canary XML: [`tools/ppc-instructions.xml` — search for `mnem="vpkshss128"`](https://github.com/xenia-canary/xenia-canary/blob/f21ebd49e979e44f081f474df78c3fbfee9cb3f2/tools/ppc-instructions.xml)
- Canary emitter: [`src/xenia/cpu/ppc/ppc_emit_altivec.cc:1834`](https://github.com/xenia-canary/xenia-canary/blob/f21ebd49e979e44f081f474df78c3fbfee9cb3f2/src/xenia/cpu/ppc/ppc_emit_altivec.cc#L1834)
- Sylpheed opcode: [`crates/sylpheed-ppc/src/opcode.rs:406`](../../../crates/sylpheed-ppc/src/opcode.rs#L406)
- Sylpheed decoder: [`crates/sylpheed-ppc/src/decoder.rs:733`](../../../crates/sylpheed-ppc/src/decoder.rs#L733)
<details><summary>Canary emitter (frozen snapshot @ <code>f21ebd49e9</code>)</summary>
```cpp
int InstrEmit_vpkshss128(PPCHIRBuilder& f, const InstrData& i) {
return InstrEmit_vpkshss_(f, VX128_VD128, VX128_VA128, VX128_VB128);
}
// ── delegates to (src/xenia/cpu/ppc/ppc_emit_altivec.cc:1816) ──
int InstrEmit_vpkshss_(PPCHIRBuilder& f, uint32_t vd, uint32_t va,
uint32_t vb) {
// Vector Pack Signed Halfword Signed Saturate
// Convert VA and VB from signed words to signed saturated bytes then
// concat:
// for each i in VA + VB:
// i = int8_t(Clamp(EXTS(int16_t(t)), -128, 127))
// dest = VA | VB (lower 8bit values)
Value* v = f.Pack(f.LoadVR(va), f.LoadVR(vb),
PACK_TYPE_8_IN_16 | PACK_TYPE_IN_SIGNED |
PACK_TYPE_OUT_SIGNED | PACK_TYPE_OUT_SATURATE);
f.StoreSAT(f.DidSaturate(v));
f.StoreVR(vd, v);
return 0;
}
```
</details>
<!-- GENERATED: END -->
## Special Cases & Edge Conditions
- **Signed half-word → signed byte saturating pack.** Each of the 16 input half-word lanes (8 from `VA`, 8 from `VB`) is clamped to the `int8` range `[−128, +127]`. Values outside that range produce the nearest extreme and **set the sticky `VSCR[SAT]`** bit.
- **Lane-count doubling.** 8+8 = 16 half-word lanes → 16 byte lanes in `VD`.
- **Big-endian ordering.** `VA`'s 8 half-words fill `VD.b[0..7]`; `VB`'s 8 fill `VD.b[8..15]`.
- **Signed vs. unsigned output.** `vpkshss` has signed input and signed output. Compare with [`vpkshus`](vpkshus.md), which keeps signed input but clamps to `uint8` (`[0, 255]`).
- **`VSCR[SAT]` is sticky.** Once set it remains set until an `mtvscr` clears it. Software that needs a per-block saturation signal must clear before the kernel and test after.
- **No `Rc`, no XER / FPSCR.**
- **VMX128 sibling `vpkshss128`.** Same semantics, wider register file.
## Related Instructions
- [`vpkshus`](vpkshus.md) — signed → unsigned saturating (same half-word input).
- [`vpkuhus`](vpkuhus.md), [`vpkuhum`](vpkuhum.md) — unsigned half-word input, unsigned byte output (saturating / modulo).
- [`vpkswss`](vpkswss.md), [`vpkswus`](vpkswus.md) — the word → half-word analogues.
- [`vupkhsb`](vupkhsb.md), [`vupklsb`](vupklsb.md) — the inverse unpacks that sign-extend bytes back to half-words.
- [`vaddsbs`](vaddsbs.md), [`vsubsbs`](vsubsbs.md) — other sources of byte-saturating arithmetic.
## IBM Reference
- [AIX 7.3 — `vpkshss` (Vector Pack Signed Half Word Signed Saturate)](https://www.ibm.com/docs/en/aix/7.3.0?topic=set-vpkshss-vector-pack-signed-half-word-signed-saturate-instruction)
- [IBM AltiVec Technology Programmer's Interface Manual, Chapter 6 — Permute and Formatting](https://www.nxp.com/docs/en/reference-manual/ALTIVECPIM.pdf)
Reference in New Issue View Git Blame Copy Permalink