Intel® ISPC User's Guide

The Intel® Implicit SPMD Program Compiler (Intel® ISPC) is a compiler for writing SPMD (single program multiple data) programs to run on the CPU and GPU. The SPMD programming approach is widely known to graphics and GPGPU programmers; it is used for GPU shaders and CUDA* and OpenCL* kernels, for example. The main idea behind SPMD is that one writes programs as if they were operating on a single data element (a pixel for a pixel shader, for example), but then the underlying hardware and runtime system executes multiple invocations of the program in parallel with different inputs (the values for different pixels, for example).

The main goals behind ispc are to:

  • Build a variant of the C programming language that delivers good performance to performance-oriented programmers who want to run SPMD programs on CPUs and GPUs.
  • Provide a thin abstraction layer between the programmer and the hardware--in particular, to follow the lesson from C for serial programs of having an execution and data model where the programmer can cleanly reason about the mapping of their source program to compiled assembly language and the underlying hardware.
  • Harness the computational power of Single Program, Multiple Data (SIMD) vector units without the extremely low-productivity task of directly writing intrinsics.
  • Explore opportunities enabled by tight coupling between C/C++ application code and SPMD ispc code running on the same processor—lightweight function calls between the two languages, direct data sharing via pointers without copying or reformatting, etc.

We are very interested in your feedback and comments about ispc and in hearing your experiences using the system. We are especially interested in hearing if you try using ispc but see results that are not as you were expecting or hoping for. We encourage you to send a note with your experiences or comments to the GitHub Discussions forum or to file bug or feature requests with the ispc bug tracker. (Thanks!)

Contents:

Recent Changes to ISPC

See the file ReleaseNotes.txt in the ispc distribution for a list of recent changes to the compiler.

Updating ISPC Programs For Changes In ISPC 1.32.0

Standard Library Changes:

  • Parallel bit deposit and extract functions pdep32(), pext32(), pdep64(), and pext64() have been added to the standard library, with uniform and varying overloads operating on uint32 and uint64 values. pdep deposits the low bits of a value into the set-bit positions of a mask, and pext gathers the bits selected by a mask into the low bits of the result; for example, pdep32(5u, 0x52u) == 0x42u. They are useful, for example, for computing Morton codes. Arguments are converted to the unsigned type of the function, so a negative int32 passed to pdep64() is sign-extended, and a uint64 passed to pdep32() is truncated.

New CPU Support:

  • --cpu=znver6 has been added for AMD Zen 6 processors (requires ISPC built with LLVM 23 or newer). It maps to the avx512icl-x16 target and enables native float16 arithmetic.

Compiler Switches:

  • Dependency files generated with -M/-MF now quote filenames containing spaces and other Make-special characters. A new -MQ <target> option specifies a dependency rule target that is quoted for Make, while -MT <target> uses the target verbatim.

New Architecture Support:

  • PowerPC 64-bit little-endian (ppc64le) support, which is experimental and enabled with the PPC64_ENABLED=ON CMake option, is now also available for the FreeBSD target OS. It is not included in official ISPC binaries; to use it, build ISPC from source.

Updating ISPC Programs For Changes In ISPC 1.31.0

ISPC Targets:

  • New avx10.2nvl-x4, avx10.2nvl-x8, avx10.2nvl-x16, avx10.2nvl-x32, and avx10.2nvl-x64 targets have been added for Intel Nova Lake processors. These targets implement AVX10.2 and APX (Advanced Performance Extensions) but, unlike the avx10.2dmr (Diamond Rapids) targets, they do not include AMX. The corresponding predefined macro is ISPC_TARGET_AVX10_2NVL.
  • The multi-target runtime dispatcher now selects an AMX-bearing server target variant (avx512spr, avx512gnr, avx10.2dmr) only when the system supports AMX, instead of relying solely on the ISA ordering.

New Options:

  • A new --opt=disable-apx[=<list>] option allows disabling x86 APX (Advanced Performance Extensions) sub-features, which are enabled by default on APX-capable targets such as avx10.2dmr and avx10.2nvl. With no list it disables all APX sub-features; otherwise it accepts a comma-separated subset of egpr, ndd, push2pop2, ppx, ccmp, cf, nf, zu, and jmpabs.

Windows x64 Stack Unwinding For APX:

  • On Windows x64, code that uses the APX extended general purpose registers (egpr, R16-R31) cannot be described by the legacy v1/v2 SEH unwind encodings, which have no register-number field for registers beyond R15. When targeting Windows on an APX-capable target (the avx10.2dmr and avx10.2nvl families) with egpr enabled, ISPC now automatically requests Windows x64 unwind information version 3. If you need compatibility with an older unwinder, disable the extended registers with --opt=disable-apx=egpr, which also drops the unwind v3 request.

New Features:

  • Implementation of two new fast-math modes: balanced and aggressive. These modes bring more aggressive optimizations compared to the default legacy mode. The latter was the mode provided so far in previous ISPC versions. It is still available and left unchanged. The fast-math mode can be specified with the option --opt=fast-math:<mode>. See the optimization settings section for more information about the new modes.

Standard Library Changes:

  • Breaking change: reduce_add() now returns the same type as its input. Previously the signatures widened the result, but the implementation was inconsistent and partially incorrect. The new same-type convention also matches the prevailing convention in other SIMD/SPMD ecosystems and is consistent with reduce_min() / reduce_max() in ISPC. For overflow-safe accumulation, cast the input to a wider type explicitly, e.g. reduce_add((int32)x) for an int16 x. Any code that relied on the previous widened return type must be updated.
  • The Gauss error function erf and the complementary error function erfc have been added to the standard library.
  • The expm1 function (meant to compute exp(x)-1 accurately), and the log1p function (meant to compute log(1+x) accurately) have also been added to the standard library.
  • The hyperbolic functions sinh, cosh and tanh have also been added to the standard library.
  • The precision of several existing math functions has been improved, including asin (especially close to 0), acos, atan (which now also handles -0 correctly), and the default log. As a result, the values these functions return may differ slightly from previous ISPC versions. Code that relies on bit-exact results (for example, golden-output comparisons) may need to update its expected values.

New Architecture Support:

  • Initial support for the PowerPC 64-bit little-endian (ppc64le) architecture has been added using generic targets (e.g., generic-i32x4). The baseline is POWER ISA 2.7 (POWER8+) with VSX. This support is experimental and not included in official ISPC binaries. To use it, build ISPC from source with the PPC64_ENABLED=ON CMake option. Usage: ispc --arch=ppc64le --target=generic-i32x4 foo.ispc -o foo.o.

Updating ISPC Programs For Changes In ISPC 1.30.0

New Features:

  • Intel AMX (Advanced Matrix Extensions) support has been added to the standard library. AMX provides hardware acceleration for matrix operations, particularly useful for machine learning workloads. The new <amx.isph> header provides functions for tile configuration, data loading/storing, and matrix dot products for INT8, BF16, and FP16 data types. AMX is supported on avx512spr, avx512gnr, and avx10.2dmr targets. Please refer to Intel AMX (Advanced Matrix Extensions) for more details.

Language Changes:

  • Integral type aliases (size_t, ptrdiff_t, intptr_t, uintptr_t) can now be used as non-type template parameters.

Deprecated Targets:

  • The sse2-i32x4 and sse2-i32x8 targets are no longer deprecated. Based on customer feedback indicating active use, we have decided to retain these targets and removed the deprecation warning.

Updating ISPC Programs For Changes In ISPC 1.29.0

Language Changes:

The compiler now assumes that all loops with non-constant conditions will make forward progress and eventually terminate. This enables optimizations based on the assumption that loops will not execute indefinitely. Infinite loops with constant conditions like for (;;) or while (1) are treated specially and do not have this assumption applied.

Compiler Switches:

  • Added --profile-sample-use=<file> to enable profile-guided optimization using sample profile data. When provided, the ISPC compiler loads the specified sample profile data file and uses it to guide optimization decisions during compilation. Use with --sample-profiling-debug-info to generate debug information optimized for sample-based profiling.
  • Added --[no-]internal-export-functions to control generation of internal (ISPC-callable) versions of exported functions. The flag is enabled by default. When disabled (--no-internal-export-functions), only external versions are generated and calling exported functions from ISPC code will result in a compilation error.
  • Added --stack-protector[=<level>] flag to enable Stack Smash Protection (SSP) for ISPC functions, providing runtime detection of stack buffer overflows. --stack-protector (equivalent to --stack-protector=on) enables stack protectors for functions vulnerable to stack smashing. --stack-protector=strong enables stack protectors for functions that contain arrays of any size or take addresses of local variables. --stack-protector=all enables stack protectors for all functions. --stack-protector=none disables stack protectors (default).
  • The default DWARF version has been updated to DWARF 5, matching the LLVM default. If your debugging tools do not support DWARF 5, you can use the --dwarf-version=<N> flag to specify an earlier version.

Warning for Exported Function Calls:

A new warning has been introduced to prepare for an upcoming behavior change in exported functions. Currently, export functions generate both internal (ISPC-callable) and external (C/C++-callable) versions. Starting in ISPC 1.30, the default behavior will change to generate only external versions, matching the behavior of the external_only attribute.

In ISPC 1.29, the compiler issues a warning when an exported function without the external_only attribute is called from ISPC code. This warning helps identify code that may be affected by the upcoming change. To address this warning, you can:

  • Use a non-exported function for ISPC-to-ISPC calls
  • Add the external_only attribute (see external_only) to the function (note: this will generate an error instead of a warning)
  • Use the --no-internal-export-functions command-line flag to suppress internal version generation (note: this will generate errors instead of warnings for all exported function calls)

Note: The compiler can only detect calls to exported functions within the same compilation unit. Cross-module calls to exported functions cannot be detected.

ISPC Targets:

  • New avx512gnr-x4, avx512gnr-x8, avx512gnr-x16, avx512gnr-x32, and avx512gnr-x64 targets have been added for Intel Granite Rapids processors. These targets support AVX-512 with AMX-FP16 capabilities.
  • avx10.2 family of targets has been renamed to avx10.2dmr. The macro ISPC_TARGET_AVX10_2 has been replaced with ISPC_TARGET_AVX10_2DMR.
  • sse2-i32x4 and sse2-i32x8 targets are deprecated and will be removed in future releases.
  • gen9-x8, and gen9-x16 targets have been removed.

Predefined Macros:

  • New predefined macros ISPC_TARGET_HAS_FP16_SUPPORT and ISPC_TARGET_HAS_FP64_SUPPORT have been added following the consistent naming convention used by other target capability macros. The old macro names ISPC_FP16_SUPPORTED and ISPC_FP64_SUPPORTED remain available for backward compatibility but are now deprecated.
  • The ISPC_TARGET_AVX512GNR macro has been added.
  • The ISPC_TARGET_AVX10_2 macro has been replaced with ISPC_TARGET_AVX10_2DMR to match the target renaming.

Updating ISPC Programs For Changes In ISPC 1.28.0

New Features:

  • Added a new command-line option --include-float16-conversions. This option makes the compiler include float16 conversion functions in the compiled module. This is useful for targets that do not have native instructions for float16 conversions, such as x86 targets prior to AVX2. This option is disabled by default.
  • ISPC can now generate nanobind wrappers for ISPC modules, allowing easy and lightweight integration of ISPC code with Python. The generated wrappers can be built into native Python modules and imported into Python code. The --nanobind-wrapper=<filename> command-line option enables this feature.
  • Struct operator overloading has been extended. Extended support for overloading unary (++, --, -, !, ~), binary (*, /, %, +, -, >>, <<, ==, !=, <, >, <=, >=, &, |, ^, &&, ||), and assignment (=, +=, -= , *=, /=, %=, <<=, >>=, &=, |=, ^=) operators for struct types.
  • ISPC can now be used as a C++ library (libispc) for embedding ISPC compilation directly into applications. It now also provides CMake configuration files for easy integration into other CMake projects. The library includes experimental Just-In-Time (JIT) compilation capabilities for runtime code generation and execution. See the section Using ISPC as a Library for more details.
  • Added a new include/intrinsics directory containing header files that implement selected SSE intrinsics in ISPC. If you're porting existing code from intrinsics to ISPC, you can use these headers as a reference.

Language and Syntax Changes:

  • Integer literals are now stricter:
    • Limits the number of occurrences of [uUlL] symbols (e.g., ulll, uul, and lulu are not valid anymore).
    • The value modification suffix (i.e., [kMG]) must precede the type modification suffix (i.e., [uUlL] symbols).
    • Like C/C++, lL and Ll suffixes are no longer allowed (i.e., mixing lower- and upper-case L to form a LL suffix).

Standard Library Changes:

  • select functions now support unsigned integer types uint8, uint16, uint32, and uint64 as well as uniform short vectors.

  • Added new functions: isinf, isfinite, and srgb8_to_float.

  • Standard library functions for short vectors have been moved to a separate header file short_vec.isph. They are no longer defined implicitly for every file compiled with ISPC. Code using such functions should now include this file with:

    #include "short_vec.isph"
    
  • Support for short vector types has been added to the following element-wise functions: fmod, isnan, rsqrt_fast, and clamp.

Debugging:

The default DWARF version was updated to DWARF 5. You can still specify any supported DWARF version with the --dwarf-version= switch.

Updating ISPC Programs For Changes In ISPC 1.27.0

New targets:

New targets have been added for platforms supporting Intel® Advanced Vector Extensions 10.2: avx10.2-x4, avx10.2-x8, avx10.2-x16, avx10.2-x32, and avx10.2-x64. Additionally, a new macro ISPC_TARGET_AVX10_2 has been introduced.

Standard library:

  • Cross-lane operations - broadcast, rotate, shift, and shuffle - are now supported for unsigned types.
  • ISPC's data handling capabilities have been extended to include signed and unsigned int8 and int16 types in the reduction functions.
  • Support for packed_load and packed_store operations has also been expanded to include: int8, int16 (signed/unsigned), float16, float, and double.
  • The cube root function cbrt has been added to the standard library for float and double types.
  • Dot product functionality has been enhanced with mixed signedness support for 16-bit integers. The following input combinations are now supported: u16 x u16 (unsigned x unsigned), i16 x i16 (signed x signed), u16 x i16 (mixed signedness). For consistency with other naming conventions, the function dot2add_i16_packed has been renamed to dot2add_i16i16_packed.

New standard library functions for short vectors:

The max, min and abs functions for short vectors of basic types have been added to the standard library. They support both uniform and varying short vector types for all basic types supported by the corresponding standard functions, i.e., signed and unsigned integer types and floating-point types.

It makes it possible, for example, to find the maximum value between two short vectors:

uniform int<3> a = {1, 2, 3};
uniform int<3> b = {3, -2, 1};
uniform int<3> c = max(a, b); // c = {3, 2, 3}

varying float<4> x, y;
varying float<4> z = max(x, y);

Support for short vector types has also been added for the following floating-point element-wise functions: round, floor, ceil, trunc, rcp, rcp_fast, sqrt, rsqrt, sin, asin, cos, acos, tan, atan, exp, log, atan2, pow and cbrt.

Language changes:

  • The aligned(N) attribute is now available to specify the alignment of variables and struct types.