kernel — Standalone Kernel Runner

CLI Tool Standalone Execution Simulation File Format Testing & Development

Module Architecture

The kernel module consists of two key components: a Simulation class that manages the entire kernel execution lifecycle, and a CLI entry point that translates command-line flags into environment variables understood by the core engine.

flowchart TD
  CLI["oclgrind-kernel.cpp
CLI Entry Point"]
  PA["parseArguments()
Process 20+ flags"]
  SE["setEnvironment()
Map flags → OCLGRIND_* vars"]
  SIM["Simulation::load()
Parse sim file"]
  OP["Open program file
(source or bitcode)"]
  BUILD["Program::build()
Compile OpenCL C → LLVM IR"]
  BC["Program::createFromBitcodeFile()
Load precompiled bitcode"]
  KRN["Program::createKernel()
Extract named kernel"]
  ARGS["parseArgument() × N
Parse typed argument headers"]
  ALLOC["Memory::allocateBuffer()
Allocate global buffers"]
  RUN["Simulation::run()"]
  KI["KernelInvocation::run()
Execute NDRange"]
  DUMP["dumpArgument()
Print output buffers"]

  CLI --> PA
  PA --> SE
  PA -->|"simfile path"| SIM
  SIM --> OP
  OP -->|"magic 0x4243"| BC
  OP -->|"else source"| BUILD
  BC --> KRN
  BUILD --> KRN
  KRN --> ARGS
  ARGS --> ALLOC
  ALLOC --> RUN
  RUN --> KI
  KI --> DUMP

Simulation Lifecycle

sequenceDiagram
  participant User as User / Shell
  participant CLI as oclgrind-kernel
  participant SIM as Simulation
  participant CTX as Context
  participant PRG as Program
  participant KRN as Kernel
  participant MEM as Memory
  participant KI as KernelInvocation

  User->>CLI: oclgrind-kernel [flags] sim.file
  CLI->>CLI: parseArguments() → setEnvironment()
  CLI->>SIM: Simulation()
  SIM->>CTX: new Context()
  CLI->>SIM: load("sim.file")
  SIM->>SIM: Read program path, kernel name, NDRange, WGSize
  alt Source (.cl)
    SIM->>PRG: new Program(ctx, source)
    SIM->>PRG: build(BUILD, "")
  else Bitcode (.bc)
    SIM->>PRG: createFromBitcodeFile(ctx, path)
  end
  SIM->>KRN: program→createKernel(name)
  loop For each argument
    SIM->>SIM: parseArgument(index) — read header tokens
    SIM->>MEM: allocateBuffer(size, flags)
    SIM->>MEM: store(data, address, size)
    SIM->>KRN: setArgument(index, value)
  end
  CLI->>SIM: run(dumpGlobalMemory)
  SIM->>KI: KernelInvocation::run(ctx, kernel, 3, offset, ndrange, wgsize)
  KI-->>SIM: Execution complete
  SIM->>SIM: dumpArgument() for each dump-flagged arg
  SIM-->>CLI: return
  CLI-->>User: Output results

Key Classes & Functions

Interactions with Other Modules

CLI Flags & Configuration

Every CLI flag maps directly to an OCLGRIND_* environment variable via the setEnvironment() helper. The core engine reads these variables at Context construction time.

Simulation File Format

The sim file is a plain-text format parsed by Simulation::load(). Lines starting with # are comments. The format is:

// Sim file structure (parsed by Simulation::load):
// Line 1: program file path  (e.g., "vecadd.cl" or "vecadd.bc")
// Line 2: kernel name         (e.g., "vecadd")
// Line 3: NDRange x y z       (e.g., "1024 1 1")
// Line 4: work-group size x y z (e.g., "64 1 1")
// Lines 5+: argument headers + data, one per kernel argument
//
// Argument header format:  <token token ...>
// Tokens: size=N, type (int/float/...), fill=V, range=S:I:E,
//         dump, hex, noinit, null, ro, wo

Example Sim File

// vecadd.sim — add two vectors of 8 floats
vecadd.cl          # OpenCL source file
vecadd             # Kernel name
8 1 1              # NDRange: 8 work-items
8 1 1              # Work-group size: single group of 8

# Argument 0: input buffer A (read-only, 8 floats filled with 1.0)
<float size=32 ro fill=1.0>

# Argument 1: input buffer B (read-only, range 0..7)
<float size=32 ro range=0:1:7>

# Argument 2: output buffer C (write-only, dump results)
<float size=32 wo noinit dump>

Code Examples

Simulation Construction & Lifecycle

// From oclgrind-kernel.cpp — the complete main() flow
int main(int argc, char* argv[])
{
  // Step 1: Parse CLI flags and set environment variables
  if (!parseArguments(argc, argv))
    return 1;

  // Step 2: Create simulation (allocates Context)
  Simulation simulation;

  // Step 3: Load sim file (compile program, create kernel, parse args)
  if (!simulation.load(simfile))
    return 1;

  // Step 4: Execute the kernel and dump results
  simulation.run(outputGlobalMemory);
}

Argument Parsing — Header Token Processing

// Simplified from Simulation::parseArgument()
// Each argument has a header like: <float size=32 ro fill=1.0 dump>
void Simulation::parseArgument(size_t index)
{
  size_t size = SIZE_MAX;
  ArgDataType type = TYPE_NONE;
  bool dump = false, hex = false, noinit = false, null = false;
  string fill, range;

  // Read header tokens between < and >
  // Recognized tokens: char/uchar/.../double, size=N, fill=V,
  //   range=S:I:E, dump, hex, noinit, null, ro, wo

  // After parsing: allocate buffer, store initial data
  Memory* globalMemory = m_context->getGlobalMemory();
  size_t address = globalMemory->allocateBuffer(size, flags);
  globalMemory->store(data, address, size);

  // Bind argument to kernel
  m_kernel->setArgument(index, value);
}

Directory Map

src/kernel/
├── Simulation.h           ← Class declaration: Simulation, ArgDataType enum, DumpArg struct
├── Simulation.cpp         ← Implementation: load(), run(), parseArgument(), get<T>(), dumpArgument<T>()
│                             parseFill<T>(), parseRange<T>(), parseArgumentData<T>(), readValue<T>()
│                             ~780 lines — the core simulation engine
└── oclgrind-kernel.cpp    ← CLI entry point: main(), parseArguments(), setEnvironment(), printUsage()
                              ~317 lines — flag parsing and orchestration

Deep Dives