esp32-s3-pie-simd-optimization

name	ESP32-S3 PIE SIMD Optimization
description	ESP32-S3 Processor Instruction Extensions (PIE) SIMD reference for accelerating C code. Use when converting scalar C loops into PIE SIMD assembly (EE.* instructions). Covers 128-bit QR registers, vector arithmetic, MAC, non-aligned data, FFT, and common patterns. Target chip: ESP32-S3 (Xtensa LX7 with TIE extensions).

ESP32-S3 PIE SIMD Quick Reference

REGISTERS

General Purpose

Register	Count	Width	Use
AR (a0-a15)	16	32-bit	Address/data, a1=sp, a2-a7=args, a8-a15=addr operands
QR (q0-q7)	8	128-bit	SIMD vectors: 16×8-bit, 8×16-bit, or 4×32-bit lanes
FR (f0-f15)	16	32-bit	IEEE754 float

Special Registers (PIE-specific)

Register	Width	Access via	Purpose
SAR	6-bit	RSR/WUR.SAR	Mul result right-shift amount (bits)
SAR_BYTE	4-bit	RUR/WUR.SAR_BYTE	Byte shift amount for SRC.Q
ACCX	40-bit	RUR/WUR ACCX_0,ACCX_1	Scalar accumulator (sum of all lane products)
QACC_H	160-bit	RUR/WUR QACC_H_0..4	Per-lane accumulator high (8×20-bit or 4×40-bit)
QACC_L	160-bit	RUR/WUR QACC_L_0..4	Per-lane accumulator low
FFT_BIT_WIDTH	4-bit	WUR.FFT_BIT_WIDTH	Bit-reversal width (0→3bit ... 7→10bit)
UA_STATE	128-bit	RUR/WUR UA_STATE	Unaligned load persistent state

Special Register Access

WSR.SAR aN          ; write SAR
RSR.SAR aN          ; read SAR
XSR.SAR aN          ; exchange AR and SAR
WUR.ACCX_0 aN       ; write ACCX[31:0]
WUR.ACCX_1 aN       ; write ACCX[39:32]  (lower 8 bits of aN used)
RUR.ACCX_0 aN       ; read ACCX[31:0]
RUR.ACCX_1 aN       ; read ACCX[39:32] → aN[7:0]
WUR.SAR_BYTE aN      ; write SAR_BYTE
RUR.SAR_BYTE aN      ; read SAR_BYTE
WUR.QACC_H_0 aN      ; write QACC_H segment 0 (bits 31:0)
RUR.QACC_H_0 aN      ; read QACC_H segment 0 (bits 31:0)
; QACC_H segments: _0(31:0) _1(63:32) _2(95:64) _3(127:96) _4(159:128)
; QACC_L same segment layout
EE.ZERO.ACCX         ; ACCX = 0
EE.ZERO.QACC         ; QACC_H = 0, QACC_L = 0
EE.ZERO.Q qN         ; qN = 0

---

ALIGNMENT RULES (CRITICAL)

PIE loads/stores force address low bits to 0:

• 128-bit access: low 4 bits forced to 0 (16-byte aligned)
• 64-bit access: low 3 bits forced to 0 (8-byte aligned)
• 32-bit access: low 2 bits forced to 0 (4-byte aligned)
• 16-bit access: low 1 bit forced to 0 (2-byte aligned)

Always declare buffers with __attribute__((aligned(16))) or use heap_caps_aligned_alloc(16, size, MALLOC_CAP_DEFAULT).

Unaligned Load Pattern (3 instructions)

EE.LD.128.USAR.IP  q0, aN, 16    ; load aligned chunk, save offset→SAR_BYTE, aN+=16
EE.VLD.128.IP      q1, aN, 16    ; load next aligned chunk, aN+=16
EE.SRC.Q           q2, q0, q1    ; {q1,q0} >> SAR_BYTE*8 → q2 (lower 128 bits)

---

INSTRUCTION CLASSIFICATION BY OPERATION

1. LOAD (Memory → QR / QACC)

EE.VLD.128.IP       qu, as, imm16    ; qu=load128(aligned(as)), as+=sext(imm16)*16
EE.VLD.128.XP       qu, as, ad       ; qu=load128(aligned(as)), as+=ad
EE.LD.128.USAR.IP   qu, as, imm16    ; SAR_BYTE=as[3:0], qu=load128(aligned(as)), as+=sext(imm16)*16
EE.LD.128.USAR.XP   qu, as, ad       ; SAR_BYTE=as[3:0], qu=load128(aligned(as)), as+=ad
EE.VLD.H.64.IP      qu, as, imm8     ; qu[127:64]=load64(aligned(as)), as+=sext(imm8)*8
EE.VLD.L.64.IP      qu, as, imm8     ; qu[63:0]=load64(aligned(as)), as+=sext(imm8)*8
EE.VLDBC.8          qu, as           ; qu = broadcast(load8(as)), as += 1
EE.VLDBC.8.IP       qu, as, imm1     ; qu = broadcast(load8(as)), as += imm1 (0..1)
EE.VLDBC.16         qu, as           ; qu = broadcast(load16(aligned(as))), as += 2
EE.VLDBC.32         qu, as           ; qu = broadcast(load32(aligned(as))), as += 4
EE.LDQA.S8.128.IP   as, imm16        ; sign-extend 16×8bit→16×20bit into QACC_H+L, as+=sext(imm16)*16
EE.LDQA.S16.128.IP  as, imm16        ; sign-extend 8×16bit→8×40bit into QACC_H+L, as+=sext(imm16)*16
EE.LDQA.U8.128.IP   as, imm16        ; zero-extend 16×8bit→16×20bit into QACC_H+L, as+=sext(imm16)*16
EE.LDQA.U16.128.IP  as, imm16        ; zero-extend 8×16bit→8×40bit into QACC_H+L, as+=sext(imm16)*16
; IP = Immediate Post-increment, XP = register post-increment
; VLD.128.IP: step = sext(imm16)*16, range -512..496  (6-bit immediate)
; VST.128.IP: step = sext(imm8)*16, range -2048..2032 (8-bit immediate)
; VLD.H/L.64.IP: step = sext(imm8)*8, range -1024..1016

2. STORE (QR → Memory)

EE.VST.128.IP       qv, as, imm16    ; store128(qv, aligned(as)), as+=sext(imm8)*16
EE.VST.128.XP       qv, as, ad       ; store128(qv, aligned(as)), as+=ad
EE.VST.H.64.IP      qv, as, imm8     ; store64(qv[127:64], aligned(as)), as+=sext(imm8)*8
EE.VST.L.64.IP      qv, as, imm8     ; store64(qv[63:0], aligned(as)), as+=sext(imm8)*8

3. VECTOR ARITHMETIC (lane-wise, saturated)

EE.VADDS.S8         qa, qx, qy       ; qa[i]=saturate_s8(qx[i]+qy[i])  for i in 0..15
EE.VADDS.S16        qa, qx, qy       ; qa[i]=saturate_s16(qx[i]+qy[i]) for i in 0..7
EE.VADDS.S32        qa, qx, qy       ; qa[i]=saturate_s32(qx[i]+qy[i]) for i in 0..3
EE.VSUBS.S8         qa, qx, qy       ; qa[i]=saturate_s8(qx[i]-qy[i])
EE.VSUBS.S16        qa, qx, qy       ; qa[i]=saturate_s16(qx[i]-qy[i])
EE.VSUBS.S32        qa, qx, qy       ; qa[i]=saturate_s32(qx[i]-qy[i])
; Combined Load+Arithmetic (qu=load result, qa=arithmetic result)
EE.VADDS.S8.LD.INCP  qu, as, qa, qx, qy  ; as+=16
EE.VADDS.S16.LD.INCP qu, as, qa, qx, qy  ; as+=16
EE.VADDS.S32.LD.INCP qu, as, qa, qx, qy  ; as+=16
; Combined Store+Arithmetic (store qv, compute qa)
EE.VADDS.S8.ST.INCP  qv, as, qa, qx, qy  ; store qv→aligned(as), as+=16

4. VECTOR MULTIPLY (lane-wise, SAR right-shift)

EE.VMUL.S8          qz, qx, qy       ; qz[i]=(s8*qx[i] * s8*qy[i]) >> SAR[5:0]  for i=0..15
EE.VMUL.S16         qz, qx, qy       ; qz[i]=(s16*qx[i] * s16*qy[i]) >> SAR[5:0] for i=0..7
EE.VMUL.U8          qz, qx, qy       ; unsigned variant
EE.VMUL.U16         qz, qx, qy       ; unsigned variant
; SET SAR BEFORE MULTIPLY:
;   movi aN, shift_amount
;   wsr.sar aN

5. COMPLEX MULTIPLY (16-bit, 4 complex pairs × selected qy half)

EE.CMUL.S16         qz, qx, qy, sel4
; sel4 selects one 32-bit complex number from qy:
;   temp[31:0] = qy[sel4*32+31:sel4*32]
;   For each of the 4 complex pairs in qx (i=0..3):
;     qz[64*i+15:64*i]   = qx[64*i+15:64*i] * temp[15:0] - qx[64*i+31:64*i+16] * temp[31:16]
;     qz[64*i+31:64*i+16] = qx[64*i+15:64*i] * temp[31:16] + qx[64*i+31:64*i+16] * temp[15:0]
;   All results right-shifted by SAR. All 4 complex pairs multiply with the
;   same selected temp value (not pairwise with corresponding qy elements).

6. MULTIPLY-ACCUMULATE

ACCX mode (scalar sum of all lane products):

EE.VMULAS.S8.ACCX    qx, qy    ; ACCX += Σ(qx[i] * qy[i]) for i=0..15, saturated to 40-bit
EE.VMULAS.S16.ACCX   qx, qy    ; ACCX += Σ(qx[i] * qy[i]) for i=0..7
EE.VMULAS.U8.ACCX    qx, qy    ; unsigned
EE.VMULAS.U16.ACCX   qx, qy    ; unsigned
; Read raw result: RUR.ACCX_0 aN (low 32), RUR.ACCX_1 aN (high 8)
EE.SRS.ACCX rd, rs, 0            ; arithmetic right shift ACCX by rs[5:0], write back to ACCX
                               ;   and write saturated 32-bit signed result to rd
                               ;   rd = min(max(ACCX>>rs[5:0], -2^31), 2^31-1)

QACC mode (per-lane accumulation, 20-bit or 40-bit per lane):

EE.VMULAS.S8.QACC    qx, qy    ; QACC[i] += qx[i]*qy[i], 20-bit signed saturated per lane
EE.VMULAS.S16.QACC   qx, qy    ; QACC[i] += qx[i]*qy[i], 40-bit signed saturated per lane
EE.VMULAS.U8.QACC    qx, qy    ; unsigned
EE.VMULAS.U16.QACC   qx, qy    ; unsigned
; Fused MAC + 128-bit load (same as P4 ESP.VMULAS.*.QACC.LD.XP):
;   QACC += qx * qy, then qu = load128(aligned(as)), as += ad
EE.VMULAS.S8.QACC.LD.XP  qu, as, ad, qx, qy
EE.VMULAS.S16.QACC.LD.XP qu, as, ad, qx, qy
EE.VMULAS.U8.QACC.LD.XP  qu, as, ad, qx, qy
EE.VMULAS.U16.QACC.LD.XP qu, as, ad, qx, qy
; Also .LD.IP with immediate post-increment (as += imm, typically 16)
EE.VMULAS.S8.QACC.LD.IP  qu, as, imm, qx, qy
EE.VMULAS.S16.QACC.LD.IP qu, as, imm, qx, qy
; Extract QACC→QR with right-shift+sat (shift amount from as register, NOT SAR):
EE.SRCMB.S8.QACC     qu, as, 0 ; 16×20-bit→16×8-bit, R-shift by as[4:0], saturate to s8→qu
EE.SRCMB.S16.QACC    qu, as, 0 ; 8×40-bit→8×16-bit, R-shift by as[5:0], saturate to s16→qu
; QACC values are also updated with the shifted results (read-modify-write)

7. COMPARISON (result = 0xFF on true, 0 on false)

EE.VMAX.S8 / S16 / S32   qa, qx, qy    ; qa[i] = max(qx[i], qy[i])
EE.VMIN.S8 / S16 / S32   qa, qx, qy    ; qa[i] = min(qx[i], qy[i])
EE.VCMP.EQ.S8        qa, qx, qy       ; qa[i] = (qx[i]==qy[i]) ? 0xFF : 0
EE.VCMP.LT.S8        qa, qx, qy       ; qa[i] = (qx[i] < qy[i]) ? 0xFF : 0
EE.VCMP.GT.S8        qa, qx, qy       ; qa[i] = (qx[i] > qy[i]) ? 0xFF : 0
; Use ANDQ with mask to implement conditional selection (e.g. ReLU)

8. BITWISE

EE.ANDQ             qa, qx, qy    ; qa = qx & qy  (128-bit)
EE.ORQ              qa, qx, qy    ; qa = qx | qy
EE.XORQ             qa, qx, qy    ; qa = qx ^ qy
EE.NOTQ             qa, qx       ; qa = ~qx

9. SHIFT

EE.VSL.32           qa, qs        ; qa[i] = qs[i] << SAR[5:0]  (4×32-bit logical left)
EE.VSR.32           qa, qs        ; qa[i] = qs[i] >> SAR[5:0]  (4×32-bit arithmetic right)
EE.SRC.Q            qa, qs0, qs1  ; qa = ({qs1,qs0} >> SAR_BYTE*8)[127:0]
; SRC.Q used with LD.128.USAR for unaligned access

10. DATA MOVEMENT

MV.QR               qu, qs        ; qu = qs
EE.ZERO.Q           qa            ; qa = 0
EE.MOVI.32.A        qs, au, sel4  ; au = qs[sel4*32+31:sel4*32]  (extract 32-bit lane)
EE.MOVI.32.Q        qu, as, sel4  ; qu[sel4*32+31:sel4*32] = as  (insert 32-bit lane)
EE.MOV.S8.QACC      qs            ; sign-extend 16×8bit→16×20bit to QACC_H+L
EE.MOV.S16.QACC     qs            ; sign-extend 8×16bit→8×40bit to QACC_H+L
EE.MOV.U8.QACC      qs            ; zero-extend 16×8bit→16×20bit to QACC_H+L
EE.MOV.U16.QACC     qs            ; zero-extend 8×16bit→8×40bit to QACC_H+L

11. ACTIVATION

EE.VRELU.S8         qs, ax, ay    ; qs[i] = (qs[i]<=0) ? (qs[i]*ax[7:0])>>ay[4:0] : qs[i]
EE.VRELU.S16        qs, ax, ay    ; qs[i] = (qs[i]<=0) ? (qs[i]*ax[15:0])>>ay[5:0] : qs[i]
EE.VPRELU.S8        qz, qx, qy, ay  ; qz[i]=(qx[i]<=0) ? (qx[i]*qy[i])>>ay[4:0] : qx[i]
EE.VPRELU.S16       qz, qx, qy, ay  ; qz[i]=(qx[i]<=0) ? (qx[i]*qy[i])>>ay[5:0] : qx[i]

12. ZIP/UNZIP (interleave/deinterleave)

EE.VZIP.8 / 16 / 32   qs0, qs1    ; interleave qs0 and qs1 elements in-place
EE.VUNZIP.8 / 16 / 32  qs0, qs1   ; deinterleave qs0 and qs1 elements in-place

13. FFT-SPECIFIC

EE.FFT.R2BF.S16                qa0, qa1, qx, qy, sel2  ; radix-2 butterfly
EE.FFT.R2BF.S16.ST.INCP        qa0, qx, qy, as, sar4   ; butterfly + store sums
EE.FFT.CMUL.S16.LD.XP          qu, as, ad, qz, qx, qy, sel8  ; complex mul + load
EE.FFT.CMUL.S16.ST.XP          qx, qy, qv, as, ad, sel8, upd4, sar4  ; complex mul + store
EE.FFT.AMS.S16.LD.INCP         qu, as, qz, qz1, qx, qy, qm, sel2  ; FFT AMS + load
EE.FFT.AMS.S16.LD.INCP.UAUP    qu, as, qz, qz1, qx, qy, qm, sel2  ; AMS+unaligned load
EE.FFT.AMS.S16.LD.R32.DECP     qu, as, qz, qz1, qx, qy, qm, sel2  ; AMS+reversed32 load
EE.FFT.AMS.S16.ST.INCP         qv, qz1, at, as, qx, qy, qm, sel2  ; AMS + store
EE.FFT.VST.R32.DECP            qv, as, sar2           ; reversed32 store, as-=16
EE.BITREV                      qa, as                 ; bit-reverse (needs FFT_BIT_WIDTH)

14. GPIO

EE.WR_MASK_GPIO_OUT     as, ax          ; GPIO_OUT[7:0] = (GPIO_OUT & ~ax[7:0]) | (as[7:0] & ax[7:0])
EE.SET_BIT_GPIO_OUT     imm8            ; GPIO_OUT[imm8] = 1
EE.CLR_BIT_GPIO_OUT     imm8            ; GPIO_OUT[imm8] = 0
EE.GET_GPIO_IN          au              ; au[7:0] = GPIO_IN[7:0]

---

C → PIE SIMD CONVERSION PATTERNS

Pattern A: Element-wise Arithmetic (Add/Sub/Mul)

// C scalar: int16_t out[i] = in0[i] + in1[i] for i in 0..N-1

→

; a2=out, a3=in0, a4=in1, a5=N
    srai    a5, a5, 3            ; N/8 (8 elements per 128-bit load)
    loopgtz a5, 0f
    ee.vld.128.ip   q0, a3, 16   ; load 8×int16_t
    ee.vld.128.ip   q1, a4, 16
    ee.vadds.s16    q2, q0, q1   ; 8 lane adds with saturation
    ee.vst.128.ip   q2, a2, 16
0:

Pattern B: Dot Product (Reduce Sum)

// C scalar: sum += a[i] * b[i]  (int8_t)

→

; Use ACCX for scalar accumulation
    ee.zero.accx
    srai    a4, a4, 4            ; N/16 (16 elements per load)
    loopgtz a4, 0f
    ee.vld.128.ip   q0, a2, 16
    ee.vld.128.ip   q1, a3, 16
    ee.vmulas.s8.accx  q0, q1    ; ACCX += Σall_lanes(q0[i]*q1[i])
0:
    rur.accx_0  a2               ; result low 32
    rur.accx_1  a3               ; result high 8

Pattern C: Multiply with Scale (Weighted Sum)

// C: out[i] = (in[i] * weight[i]) >> shift

→

    movi    a6, shift_amount
    wsr.sar a6                   ; SAR controls right-shift
    srai    a5, a5, 3
    loopgtz a5, 0f
    ee.vld.128.ip   q0, a3, 16
    ee.vld.128.ip   q1, a4, 16
    ee.vmul.s16     q2, q0, q1   ; multiply, >>SAR
    ee.vst.128.ip   q2, a2, 16
0:

Pattern D: Multiply-Accumulate per Lane (e.g. Quantized Conv)

// C: accum[i] += input[i] * weight[i]  (per-lane accumulation)

→

; Use QACC for per-lane accumulation
    ee.zero.qacc
    movi    a6, shift_amount     ; shift for SRCMB (not SAR!)
    srai    a5, a5, 4            ; 16×int8 per load
    loopgtz a5, 0f
    ee.vld.128.ip     q0, a3, 16
    ee.vld.128.ip     q1, a4, 16
    ee.vmulas.s8.qacc q0, q1     ; QACC[i] += q0[i]*q1[i] for i=0..15
0:
    ee.srcmb.s8.qacc  q2, a6, 0  ; extract: 20-bit→8-bit with >>a6[4:0], saturate

Pattern E: ReLU Activation

// C: out[i] = in[i] > 0 ? in[i] : 0  (int16_t)

→

; Use VMAX with zero: max(x, 0) = ReLU (VCMP.GT only has S8, no S16 variant)
    ee.zero.q   q3               ; zeros vector
    srai    a5, a5, 3
    loopgtz a5, 0f
    ee.vld.128.ip    q0, a3, 16
    ee.vmax.s16      q2, q0, q3  ; q2[i] = max(q0[i], 0)
    ee.vst.128.ip    q2, a2, 16
0:

Alternative using VRELU (faster, fewer ops):

; EE.VRELU.S16 qs, ax, ay: if qs[i]<=0 then qs[i]=(qs[i]*ax)>>ay else qs[i]=qs[i]
; For standard ReLU: ax=0 (multiply by 0), ay=0 (shift 0)
    movi    a6, 0
    srai    a5, a5, 3
    loopgtz a5, 0f
    ee.vld.128.ip    q0, a3, 16
    ee.vrelu.s16     q0, a6, a6  ; in-place ReLU: negative→0
    ee.vst.128.ip    q0, a2, 16
0:

Pattern F: PReLU / LeakyReLU

// C: out[i] = in[i] > 0 ? in[i] : in[i] * slope  (int16_t, slope quantized)

→

; Load slope once, broadcast to all lanes
    ee.vldbc.16      q3, a5      ; broadcast slope to 8 lanes
    srai    a6, a6, 3
    loopgtz a6, 0f
    ee.vld.128.ip    q0, a3, 16
    ee.vprelu.s16    q2, q0, q3, a7  ; q2[i]=(q0[i]<=0)?(q0[i]*q3[i])>>a7:q0[i]
    ee.vst.128.ip    q2, a2, 16
0:

Pattern G: Loop with Unaligned Load

// C: process int16_t array at arbitrary (non-16-byte-aligned) address

→

    ee.ld.128.usar.ip  q0, a3, 16    ; first unaligned load, offset→SAR_BYTE
    ee.vld.128.ip      q1, a3, 16    ; second aligned load
    srai    a5, a5, 3
    addi    a5, a5, -1               ; one iteration already consumed
    loopgtz a5, 0f
    ee.src.q           q2, q0, q1    ; align: q2 = ({q1,q0}>>SAR_BYTE*8)[127:0]
    ee.vld.128.ip      q0, a3, 16    ; next aligned chunk
    ; ... process q2 ...
    ; swap q0↔q1 for next iteration:
    ee.src.q           q2, q1, q0    ; use the newly loaded data
    ee.vld.128.ip      q1, a3, 16
    ; ... process q2 ...
0:

Pattern H: Bias Addition (broadcast scalar to vector)

// C: out[i] = in[i] + bias  (same bias for all elements)

→

    ee.vldbc.16      q3, a4      ; broadcast bias to all 8 lanes
    srai    a5, a5, 3
    loopgtz a5, 0f
    ee.vld.128.ip    q0, a3, 16
    ee.vadds.s16     q2, q0, q3
    ee.vst.128.ip    q2, a2, 16
0:

Pattern I: Max Pooling (2x1)

// C: out[i] = max(in[i*2], in[i*2+1])

→

    srai    a5, a5, 4            ; output has N/8 elements, input has N/4
    loopgtz a5, 0f
    ee.vld.128.ip   q0, a3, 16   ; load 8 pairs = 16 elements
    ee.vld.128.ip   q1, a3, 16
    ; Use VUNZIP to separate evens and odds, then VMAX
    ee.vunzip.16    q0, q1       ; q0=evens, q1=odds
    ee.vmax.s16     q2, q0, q1
    ee.vst.128.ip   q2, a2, 16
0:

---

LOOP STRUCTURES

Label Naming Convention (REQUIRED)

For branch/loop targets, use local labels: either a plain number (0:, 1:, referenced as 0f/0b) or a .L-prefixed name (.Lloop, .Lremainder). Do not use full descriptive labels like loop_start: / end_label:.

• Numeric local labels keep tight inner loops compact and avoid name clashes.
• .L labels stay local to the file (not emitted into the symbol table) and clearly mark internal jump targets.

; GOOD — numeric local label
    loopgtz a6, 0f
        ee.vadds.s16.ld.incp q0, a3, q2, q0, q1
        ee.vld.128.ip       q1, a4, 16
        ee.vst.128.ip       q2, a2, 16
    0:

; GOOD — .L local label
    bgez  a9, .Lleft_shift
.Lright_shift_loop:
    ; ...
    bnez  a5, .Lright_shift_loop
.Lleft_shift:

; BAD — full descriptive global-style labels
right_shift_loop:
    ; ...
    bnez a5, right_shift_loop

Zero-Overhead Loop (preferred)

Xtensa hardware loop: no per-iteration addi/bnez. Used by Conv 11cn and native-KN MatMul (inner K). Special registers: LBEG, LEND, LCOUNT.

Instruction	When the body runs	When it is skipped
loop as, label	Always as times. as==0 runs 2^32 times — do not use if count can be 0	Never
loopgtz as, label	as > 0, body runs as times (LCOUNT ← as-1)	as <= 0, jump to label
loopnez as, label	as != 0	as == 0

Assembler syntax: loopgtz as, label — label is the first instruction after the body (not the last instruction of the body). Encoding is BRI8: body must fit in 256 bytes (~56–80 instructions).

; Prefer LOOPGTZ: count 0 skips the body (safe for K=1 remainder)
    srai    a5, a5, 3            ; convert element count to iteration count
    loopgtz a5, 0f
        ee.vld.128.ip   q0, a3, 16
        ee.vst.128.ip   q0, a2, 16
0:                               ; first insn AFTER the loop

Restrictions (hard):

• No nesting. One LBEG/LEND/LCOUNT. Put ZOL on the hottest inner loop (usually K). Outer M / N-block stay addi/bnez.
• Sequential ZOLs are OK: the next loopgtz overwrites LCOUNT.
• No branches / jumps / calls inside the body. Last insn must be a regular op (ee.vldbc, ee.vmulas, ee.vst, …), not bnez/j/callx.
• Do not jump into the middle of a ZOL body.
• as is sampled at setup; after loopgtz the AR can be reused.
• When as <= 0, loopgtz still writes LBEG/LEND/LCOUNT but does not execute the body.

When to fall back to a software loop: body > 256 bytes, need a taken branch inside, or the loop is the outer nest.

Manual Loop (when zero-overhead loop constraints violated)

    srai    a5, a5, 3
    beqz    a5, 1f
.Lloop:
    ; ... loop body ...
    addi    a5, a5, -1
    bnez    a5, .Lloop
1:

---

PIPELINE & SCHEDULING

Data Dependencies (insert NOPs or reorder to avoid stalls)

• QR load → use: 2 cycle latency (result ready in W stage, used in R stage)
• QR multiply → use: result ready in E stage (same as arithmetic), 0-1 cycle
• SAR write → use: requires ISYNC or at least 1 instruction gap

Prefer LD+OP fused instructions when available

Instead of separate load + compute:

; Sub-optimal: 3 instructions
ee.vld.128.ip  q0, a3, 16
ee.vld.128.ip  q1, a4, 16
ee.vadds.s16   q2, q0, q1

; Optimal when loading new data for next iteration:
ee.vadds.s16.ld.incp  q0, a3, q2, q4, q5  ; computes q2 while loading q0 for next iter

; Outer-product / reduction: MAC current vectors, prefetch next B row
ee.vmulas.s16.qacc.ld.xp q2, a2, a11, q0, q1  ; QACC += q0*q1, q2 = *a2, a2 += a11

---

KEY CONSTRAINTS & GOTCHAS

1. SAR must be set before VMUL/VMULAS/CMUL — forgotten SAR causes wrong scaling.
2. Only 8 QR registers (q0-q7) — register pressure is real. Plan allocation carefully.
3. VLD/VST force address alignment — unaligned addresses silently read/write wrong data.
4. No 32-bit multiply — only 8-bit and 16-bit vector multiply. Use multiple 16-bit ops for 32-bit.
5. Zero-overhead loop — use loopgtz (not loop if count can be 0). Body ≤ 256 bytes, no nested ZOL, no branches/calls inside. Label is the insn after the body. See Zero-Overhead Loop above.
6. ACCX is 40-bit — saturated to [-2^39, 2^39-1]. Read with RUR ACCX_0 + ACCX_1.
7. QACC is per-lane — 16 lanes of 20-bit for S8/U8, 8 lanes of 40-bit for S16/U16.
8. VADDS/VSUBS saturate — use when overflow is a concern; VMUL shifts and truncates (no sat).
9. EE.VRELU modifies input register in-place — qs is both source and destination.
10. Don't mix EE. and Xtensa native load/store on same address* without MEMW/DSYNC if caching matters.
11. Assembly functions are declared with .balign 4 alignment.

---

QUICK DECISION TABLE: Which Instruction to Use

C Operation	Data Type	Best PIE Instruction(s)
c = a + b (element-wise)	int8/int16/int32	EE.VADDS.S8/S16/S32
c = a - b (element-wise)	int8/int16/int32	EE.VSUBS.S8/S16/S32
c = a * b >> shift	int8/int16	EE.VMUL.S8/S16 (set SAR first)
sum += a[i] * b[i] (scalar result)	int8/int16	EE.VMULAS.S8/S16.ACCX
accum[i] += a[i] * b[i] (per-lane)	int8/int16	EE.VMULAS.S8/S16.QACC → EE.SRCMB
accum[i] += a[i] * b[i] + prefetch next 16B	int8/int16	EE.VMULAS.S8/S16.QACC.LD.XP / .LD.IP
c = max(a, b)	int8/int16/int32	EE.VMAX.S8/S16/S32
c = min(a, b)	int8/int16/int32	EE.VMIN.S8/S16/S32
c = a > 0 ? a : 0 (ReLU)	int16	EE.VRELU.S16 qs, zero, zero
c = a > 0 ? a : a*slope (PReLU)	int8/int16	EE.VPRELU.S8/S16
c = a > b ? 0xFF : 0 (mask)	int8	EE.VCMP.GT.S8
c = a & b	any	EE.ANDQ
`c = a	b`	any
c = broadcast(scalar)	int8/int16/int32	EE.VLDBC.8/16/32
unaligned load	any	EE.LD.128.USAR.IP + EE.SRC.Q
c = a << n (per 32-bit lane)	int32	EE.VSL.32 (set SAR first)
c = a >> n (per 32-bit lane)	int32	EE.VSR.32 (set SAR first)
clear accumulator	-	EE.ZERO.ACCX / EE.ZERO.QACC
complex multiply	int16	EE.CMUL.S16
Radix-2 FFT butterfly	int16

---

FUNCTION TEMPLATE

    .align  4
    .text
    .global my_kernel_name
    .type   my_kernel_name, @function
my_kernel_name:
    # a2: output pointer (int16_t*, 16-byte aligned)
    # a3: input0 pointer  (int16_t*, 16-byte aligned)
    # a4: input1 pointer  (int16_t*, 16-byte aligned)
    # a5: element count

    entry   sp, 64              # allocate stack frame

    # Pre-loop setup
    ; set SAR if multiplying
    ; zero accumulators if accumulating
    ; broadcast scalars if needed

    srai    a5, a5, 3           # count → iterations (8 × int16 per 128-bit)
    loopgtz a5, 0f

    ee.vld.128.ip   q0, a3, 16  # load input0
    ee.vld.128.ip   q1, a4, 16  # load input1
    ee.vadds.s16    q2, q0, q1  # compute
    ee.vst.128.ip   q2, a2, 16  # store output
0:
    retw

---

SUMMARY: Conversion Workflow

1. Identify the C loop operation and data type (int8/int16/int32).
2. Check alignment — ensure buffers are 16-byte aligned; use unaligned load pattern if not.
3. Select the right PIE instruction from the decision table above.
4. Set SAR if the instruction uses it (multiply, shift).
5. Zero accumulators if using ACCX or QACC.
6. Compute iteration count: N / (128/bits_per_element). E.g., int16 → N/8.
7. Write the zero-overhead loop body using loopgtz.
8. Extract accumulator results (RUR.*) after the loop if needed.
9. Watch register pressure — you only have q0-q7, plan which hold constants, which are temporaries.

---

REFERENCE DOCUMENTS

When you need to query complete instruction encodings, all instruction variants, detailed bit fields of special registers, exceptions/interrupts, or Xtensa native instructions, refer to the following reference files:

Document	Path	Content
PIE Instruction Set Complete Reference	references/pie_instruction_set.md	All EE.* instructions with encoding, pseudocode, SAR/QACC/ACCX special register access, unaligned data handling, pipeline hazards
Xtensa ISA Reference	references/xtensa_isa.md	AR/FR/BR registers, all Xtensa native instructions (load/store/branch/call/loop/float/cache/TLB), exception vectors, special register map

Reading Strategy: This skill file provides quick lookup tables and conversion templates. Please read the corresponding reference files when you need the following information:

• Exact bit encoding of instructions (instruction word encoding)
• Complete operation pseudocode (e.g., detailed formulas for all 16 lanes)
• Full segment access list for special registers (e.g., QACC_H_04, QACC_L_04)
• Xtensa native instructions (instructions without EE.* prefix)
• Exception handling, TLB, cache management