ispc-builtins

name: ispc-builtins description: Best practices for creating and modifying ISPC builtin files. Use when adding target-specific optimizations, implementing new builtin functions, or working with the hierarchical target system.

ISPC Builtins Guide

Understanding the hierarchical target system is critical for correctly implementing and maintaining builtins.

Architecture Overview

ISPC's standard library consist of two layers:

1. Standard Library (stdlib/stdlib.ispc) — User-visible functions written in ISPC language
2. Builtins (builtins/) — Target-specific implementations in LLVM IR that support the stdlib

Hierarchical Target System

Key Concept: Targets are organized hierarchically. A child target inherits all functions from its parent that it doesn't explicitly override.

Target Parent Map (src/builtins.cpp)

The hierarchy is defined in targetParentMap:

std::unordered_map<ISPCTarget, ISPCTarget> targetParentMap = {
    // ARM NEON -> generic
    {ISPCTarget::neon_i8x16, ISPCTarget::generic_i8x16},

    // AVX512 hierarchy: dmr -> gnr -> spr -> icl -> skx -> generic
    {ISPCTarget::avx10_2dmr_x16, ISPCTarget::avx512gnr_x16},
    {ISPCTarget::avx512gnr_x16, ISPCTarget::avx512spr_x16},
    {ISPCTarget::avx512spr_x16, ISPCTarget::avx512icl_x16},
    {ISPCTarget::avx512icl_x16, ISPCTarget::avx512skx_x16},
    {ISPCTarget::avx512skx_x16, ISPCTarget::generic_i1x16},

    // AVX/SSE hierarchy: avx2vnni -> avx2 -> avx1 -> sse4 -> sse2 -> generic
    {ISPCTarget::avx2vnni_i32x8, ISPCTarget::avx2_i32x8},
    {ISPCTarget::avx2_i32x8, ISPCTarget::avx1_i32x8},
    // ...
};

How Linking Works

When compiling user code:

1. Link the target-specific builtins (e.g., avx512skx-x16)
2. Check for unresolved symbols
3. If unresolved, link parent target's builtins (e.g., generic-i1x16)
4. Repeat until all symbols are resolved or error

Implication: You only need to implement functions that differ from the parent.

File Structure (builtins/)

Function signatures are declared in stdlib/include/builtins.isph.

Creating/Modifying Builtins

Step 1: Define the Function Signature

Add declaration to stdlib/include/builtins.isph:

EXT inline READNONE varying float __my_builtin_float(varying float);

Step 2: Implement Generic Fallback and Optimized Versions

New builtins must always have a generic implementation in generic.ispc. This ensures all targets work correctly via hierarchy fallback.

Then add optimized LLVM IR versions at the appropriate level — they will be inherited by all children:

• avx512skx — inherited by icl, spr, gnr, dmr
• avx512icl — inherited by spr, gnr, dmr (overrides skx)

Example optimized implementation in target-avx512skx-x16.ll:

define <16 x float> @__my_builtin_float(<16 x float> %input) nounwind readnone alwaysinline {
    %result = call <16 x float> @llvm.x86.avx512.something(<16 x float> %input)
    ret <16 x float> %result
}

Best Practices

1. Leverage hierarchy — Only implement what differs from parent; don't copy-paste
2. Use generic as fallback — Implement in generic.ispc first, optimize later
3. Use include() — Share code via target-*-utils.ll files
4. Mark functions correctly — Use nounwind readnone alwaysinline attributes

Testing Builtins

See CLAUDE.md for build, lit test, and IR/assembly inspection commands.

Verify Correct Builtin Was Linked

Dump IR before optimizations to see builtins as they were linked:

build/bin/ispc test.ispc --target=avx512skx-x16 --debug-phase=pre:first --dump-file=dbg -o /dev/null
# Check dbg/ir_*.ll files for the builtin implementation