OpenParable
Skip to content
← Back to skills

Ispc Builtins

Development
ispc-builtins

Ispc Builtins is an Agent Skill for development published in the ispc/ispc repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

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.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/ispc/ispc/blob/HEAD/.claude/skills/ispc-builtins/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/ispc-builtins, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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/)

File PatternDescription
target-<isa>-<variant>.llTarget-specific LLVM IR (e.g., target-avx512skx-x16.ll)
target-<isa>-common.llShared code for ISA family (e.g., target-sse4-common.ll)
target-<isa>-utils.llUtility macros/functions for ISA (e.g., target-avx512-utils.ll)
generic.ispcTarget-independent implementations in ISPC
util.m4M4 macros for generating LLVM IR

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