API Specification System

Unified specification format for declaring pointer, mod/ref, and related function effects across analysis boundaries.

Headers: include/Annotation/APISpec.h

Overview

The API Specification system provides a unified format for declaring the semantic effects of library and external functions. It consolidates multiple spec-file formats (pointer specs, mod/ref specs, etc.) into a single structured representation that can be consumed by alias analyses, checkers, and optimisers.

The specification system is designed to be lightweight (no LLVM header dependencies in the public interface) and extensible.

Components

SpecOpKind

Describes the kind of operation a function performs on a particular value:

Ignore — No effect (no-op).
Alloc — Allocates new memory.
Dealloc — Deallocates memory.
Copy — Copies data between locations.
Exit — Terminates the program.
Mod — Modifies (writes to) the memory location.
Ref — References (reads from) the memory location.

QualifierKind

Classifies how a value is qualified in the spec:

Value — The value/pointer itself.
Region — The pointee region.
Data — The data object.
Unknown — Unrecognised qualifier.

SelectorKind

Identifies which program value the spec refers to:

Ret — The function return value.
Arg — The N-th argument (Arg<N>).
AfterArg — Memory after the N-th argument (AfterArg<N>).
Static — An external static address.
Null — The null pointer literal.

Value Selectors

struct ValueSelector {
  SelectorKind kind;
  int index;     // Used for Arg/AfterArg
  bool isValid;
};

CopyEffect, AllocEffect, ModRefEffect

Each spec entry records:

The target value (ValueSelector)
The operation kind (SpecOpKind)
Optional qualifiers and context information

FunctionSpec

Aggregates all effects for a single function, keyed by function name.

APISpec

Top-level loader that parses spec files (config/ptr.spec, config/modref.spec, etc.) and provides query access:

#include "Annotation/APISpec.h"

lotus::APISpec spec;
spec.loadFromDirectory("./config/");
spec.loadFromFile("./extra.spec");

auto effects = spec.queryAllEffects("malloc");
auto modRef   = spec.queryModRef("memcpy");
auto pointers = spec.queryPointerEffects("fopen");

Usage

Spec files use a text format with entries like:

function: malloc
  effect: alloc Ret

function: memcpy
  effect: mod Arg1
  effect: ref Arg2

The loader parses these into the structured APISpec representation for use by alias analyses and checkers.