Nitpick Inline Assembly Specification

Nitpick provides direct, low-level access to the LLVM inline assembly backend via two powerful compiler built-ins: asm!! and asm!!!.

These built-ins act as ultimate escape hatches for performance-critical inner loops, SIMD optimizations, and direct hardware interaction.

1. Syntax and Structure

Both built-ins use a variadic generic signature that maps cleanly to LLVM’s inline assembly constructs.

asm!!<T>(string:arch, string:asm_code, string:constraints, args...);
asm!!!<T>(string:arch, string:asm_code, string:constraints, args...);

• T: The expected return type of the assembly block.
• arch: The target architecture string (e.g., "x86_64", "aarch64").
• asm_code: The raw assembly instructions.
• constraints: The standard LLVM register constraint string (e.g., "=r,r,r" or "=a,a,b").
• args...: The variadic Nitpick variables that feed into the assembly constraints.

2. Safety Tiers

Nitpick splits inline assembly into two tiers of safety regarding error handling.

2.1 The Supervised Tier: asm!!<T>

This variant enforces Nitpick’s standard error propagation by wrapping the return value in a Result<T>. By convention, if the assembly block leaves a negative integer in the primary output register, Nitpick interprets it as an error code, mapping it into the tbb error field of the Result<T>.

// Safe wrapping: Must unwrap with raw, drop, or check .is_error
Result<int32>:res = asm!!<int32>("x86_64", "add %eax, %ebx", "=r,r,r", x, y);
int32:val = raw res;

2.2 The Raw Tier: asm!!!<T>

This variant is completely unchecked. It returns a bare T, totally bypassing the Result<T> wrapper. It assumes the operation cannot fail or that the developer will manually check the output value.

// Raw return: no `raw` keyword or Result handling needed
int32:res = asm!!!<int32>("x86_64", "add %eax, %ebx", "=r,r,r", x, y);

3. Compiler Integration

The Nitpick compiler passes the assembly strings and constraints directly to the LLVM backend. Therefore, any constraint violations (e.g., couldn't allocate output register for constraint 'a') will be caught and reported natively during the LLVM code generation phase.

[!NOTE] By default, LLVM (and therefore Nitpick) uses AT&T syntax for x86/x86_64 inline assembly. Ensure your assembly strings follow AT&T register and instruction formatting (e.g., add %eax, %ebx instead of Intel’s add ebx, eax).

4. JIT SIMD Instruction Emission (v0.80.3)

The JIT engine provides direct SIMD instruction emission for runtime-generated vectorized code. These are not inline assembly — they are assembler API calls that emit machine code into a wildx code buffer.

4.1 CPUID Runtime Detection

JitCpuFeatures npk_jit_detect_cpu(void);   // Returns cached feature flags
bool npk_jit_has_avx2(void);                // AVX2 available?
bool npk_jit_has_sse42(void);               // SSE4.2 available?
bool npk_jit_has_neon(void);                // NEON available? (AArch64 only)

JitCpuFeatures fields: sse2, sse3, ssse3, sse41, sse42, avx, avx2, avx512f.

4.2 x86_64 SSE2 Instructions (128-bit, XMM)

4.3 x86_64 AVX2 Instructions (256-bit, YMM, VEX-encoded)

4.4 AArch64 NEON/AdvSIMD Instructions (128-bit, V registers)