ISPC Lit Tests

A concise guide for writing lit tests for the ISPC. These tests ensure compiler correctness, verify generated code, and prevent regressions.

---

When to Use Lit Tests

Use lit tests when validating:

• Compiler output — LLVM IR, assembly, or AST.
• Diagnostics — warnings, errors, or other emitted messages.
• Platform behavior — verifying cross-platform or target-specific differences.
• Regression coverage — reproducing and locking fixes for known compiler issues.

---

Core Guidelines

Always Use

--nowrap

Prevents line wrapping in compiler output for consistent FileCheck matching:

// RUN: %{ispc} %s --target=host --nowrap --emit-llvm-text -o - | FileCheck %s

Use

--nostdlib

When Not Testing Library Code

Simplifies test output and avoids unrelated symbols:

// RUN: %{ispc} %s --target=host --nostdlib --nowrap -o - | FileCheck %s

Avoid

export

Unless Testing It

export

functions generate both masked and unmasked IR — doubling the verification effort.

// Preferred
void foo() { ... }

// Avoid unless explicitly testing export behavior
export void foo() { ... }

Target Specification

Generic / Portable Tests

Use

--target=host

unless verifying target-specific codegen:

// RUN: %{ispc} %s --target=host --nowrap -o - | FileCheck %s

Writing Portable Checks

Avoid hardcoding vector widths or variable names.
Use named patterns like

[[WIDTH]]

and

[[TYPE]]

.

Example:

// CHECK-NEXT:  %test = sdiv <[[WIDTH:.*]] x i32> %a, %b
// CHECK-NEXT:  ret <[[WIDTH]] x i32> %test

When order is flexible:

// CHECK-DAG: {{%.*}} = shufflevector <[[WIDTH:.*]] x [[BASE_TYPE:i.*]]> {{%.*}}, <[[WIDTH]] x [[BASE_TYPE]]> {{poison|undef}}, <[[WIDTH]] x [[BASE_TYPE]]> zeroinitializer

Tip: Avoid relying on exact variable names — they differ between OS and LLVM versions.

Target-Specific Tests

When output differs by architecture or ISA:

• Specify the exact target and feature.
• Include a

  REQUIRES:

  directive for conditional execution.

Example:

// RUN: %{ispc} %s --target=avx512skx-x16 --emit-asm -o - | FileCheck %s
// REQUIRES: X86_ENABLED

Using

REQUIRES

for Feature Dependencies

Defined in

tests/lit-tests/lit.cfg

:

• Features:

  X86_ENABLED

  ,

  LLVM_*_0+

  , etc.
• Substitutions:

  %{ispc}

  ,

  %s

  ,

  %t

• Test configuration: format, suffixes, and substitutions

Testing Intermediate IR

Use

--debug-phase

to capture output of specific optimization passes:

// RUN: %{ispc} %s --target=avx2 --emit-llvm-text \
// RUN:   --debug-phase=325:325 --dump-file=%t -o /dev/null
// RUN: FileCheck --input-file %t/ir_325_LoadStoreVectorizerPass.ll %s

Comments and Documentation

Clearly describe what the test verifies and why it exists.

Example:

// Verifies that stmxcsr/ldmxcsr intrinsics correctly set/restore FTZ/DAZ flags
// when --opt=reset-ftz-daz is enabled.

Example Template

// Brief description of the test purpose
// RUN: %{ispc} %s --target=host --nostdlib --nowrap --emit-llvm-text -o - | FileCheck %s

// REQUIRES: <feature_if_needed>

// CHECK-LABEL: @function_name___
// CHECK: expected pattern
// CHECK-NOT: unexpected pattern

void function_name() {
    // Minimal reproducible test code here
}

Test commands

Run all lit tests:

cmake --build build --target check-all -j $(nproc)

To test the specific test, run:

TEST=/full/path/test.ispc cmake --build build --target check-one -j $(nproc)

Test names

• Regression tests: name them

  ####.ispc

  , where #### is the GitHub issue number.
• Other tests: use a short, descriptive name. For multiple tests of one feature, add numbers (e.g.,

  feature-name-1.ispc

  ,

  feature-name-2.ispc

  ).

Key Takeaways

• Keep tests minimal — validate one behavior per test.
• Use portable patterns for LLVM IR.
• Add REQUIRES for target-dependent tests.
• Prefer non-exported functions unless necessary.
• Document intent and expected outcome in comments.