asm: roadmap for hand-written crypto kernels — in-asm control flow, SIMD-scale blocks, whole-function asm

[quaesitor-scientiam]

Context

asm … raw / asm … intel landed via #28358 (V1) and #28365 (v3), with AArch64
register names (#28375) and an Intel operand-width guard (#28369). A verbatim port
of OpenSSL's scalar poly1305_blocks inner sequence into asm amd64 raw {} now
assembles and produces the correct RFC 8439 tag under gcc / clang / tcc on Linux
(SysV) and Windows (Win64) — #28358 (comment)

That covers scalar bignum kernels (Poly1305, X25519 field arithmetic,
Montgomery multiply). Three gaps remain before inline asm can express the rest of
what a pure-V crypto acceleration layer needs. This issue tracks them as
separate deliverables.

---

1. Control flow inside a raw block (labels + loops)

Most real kernels loop internally over the message / limbs. Today the loop must
live in V, calling the asm block once per block — a function call + full operand
reload per iteration.

• Local labels usable within a raw template without colliding across multiple
  instantiations or inlined copies (GNU %=-style unique suffix, or a documented
  numeric 1: / 1b / 1f convention).
• A documented, tested bound-pointer + length operand pattern for a self-contained
  loop.
• Acceptance: a poly1305_blocks looping over an arbitrary-length buffer
  entirely inside one asm amd64 raw block, passing RFC 8439 vectors under
  gcc/clang/tcc on x86-64 SysV + Win64.

2. SIMD-scale blocks (XMM/YMM/ZMM pressure)

AES-NI, GHASH-CLMUL, ChaCha20 and SHA-NI use most of the vector register file plus
several GPRs.

• Confirm the register allocator + clobber model behaves when a raw block
  clobbers 10+ xmm/ymm registers and the surrounding V function also uses
  floats.
• Confirm %[name] operand binding for vector-typed inputs
  (pointer-to-[16]u8, [4]u32, …) and alignment expectations.
• Windows: XMM6–15 are callee-saved under Win64 — verify the compilers
  save/restore around the block, or document that the kernel must.
• Acceptance: a ChaCha20 block function and a GHASH (CLMUL) multiply as raw
  blocks passing RFC 8439 / GCM vectors on x86-64 SysV + Win64, plus the arm64
  equivalents (NEON / PMULL) on AArch64.

3. Whole-function / naked asm + call

OpenSSL kernels are whole functions that follow the platform C ABI and sometimes
call helper routines. V inline asm is a statement inside a V function, wrapped by
V's prologue/epilogue and the C compiler's frame.

• Decide the mechanism: a @[naked]-style attribute on a V fn whose body is a
  single asm block? A way to emit a bare .globl symbol + assembly from V?
  A first-class path for linking a .s V itself produces?
• Minimum viable: document that a kernel needing call or full frame control
  should ship as an external .s/.o (V already compiles .s/.S/.o inputs)
  and add a worked example under vlib/v/slow_tests/assembly/.
• Acceptance: one OpenSSL-scale kernel (e.g. aesni_ctr32_encrypt_blocks or
  sha256_block_data_order) callable from pure V via a documented, tested path.

---

Out of scope

• Rewriting vlib/crypto primitives themselves — downstream work once these land.
• A V-native (non-C-backend) assembler for these kernels.

/cc @medvednikov

Note

You can use the 👍 reaction to increase the issue's priority for developers.

Please note that only the 👍 reaction to the issue itself counts as a vote.
Other reactions and those to comments will not be taken into account.

[quaesitor-scientiam]

asm crypto roadmap-7e724c1a.plan.md

[quaesitor-scientiam]

Once the 3 PRs are merged this issue can be closed