IR and SPIR-V Reference

Every exported symbol of the packages below the language: clsl/ir, clsl/spirv, clsl/spirv-back-end and clsl/generator. Programs need none of them; back ends, targets, tools and tests do. The docstrings say more, and The IR, SPIR-V, Targets and Grammar and Generator describe them. A structure's accessors are readers; those the tables mark setf-able have writers too, which the builder and front ends use.

clsl/ir

Types

Symbol	Kind	What it is
scalar-kind	type	:bool, :int, :uint, :float or :double.
address-space	type	:function, :input, :output, :uniform, :storage, :workgroup, :private or :handle.
stage	type	A stage a module is: :vertex, :tessellation-control, :tessellation-evaluation, :geometry, :fragment or :compute.
texture-dimension	type	:1d, :2d, :3d, :cube or :buffer.
image-format	type	The format of a storage image's texels, in cl-gfx's names.
layout	type	:std140 or :std430.
ir-type, ir-type-p	structure, predicate	A type of the IR, interned in its module: two types of a module are the same exactly when they are eq.
void-type, void-type-p	structure, predicate	:void, what a function returns when it returns nothing.
scalar-type, scalar-type-p, scalar-type-kind	structure, predicate, reader	A scalar of a scalar-kind.
vector-type, vector-type-p, vector-type-component, vector-type-count	structure, predicate, readers	A vector of 2 to 4 scalars.
matrix-type, matrix-type-p, matrix-type-column, matrix-type-count	structure, predicate, readers	A matrix of 2 to 4 columns, each a vector type.
array-type, array-type-p, array-type-element, array-type-length	structure, predicate, readers	An array, its length nil for one known only as the shader runs.
struct-type, struct-type-p, struct-type-name, struct-type-members	structure, predicate, readers	A struct, named by a symbol, of struct-members.
struct-member, struct-member-name, struct-member-type	structure, readers	A member of a struct type.
pointer-type, pointer-type-p, pointer-type-space, pointer-type-pointee	structure, predicate, readers	A pointer into an address space.
handle-type, handle-type-p, handle-type-dimension, handle-type-arrayed, handle-type-multisampled, handle-type-component	structure, predicate, readers	A texture or storage image, of the :handle space.
texture-type, texture-type-p, texture-type-dimension, texture-type-arrayed, texture-type-multisampled, texture-type-depth, texture-type-component	structure, predicate, readers	A texture with its sampler; texture-type-depth is true for a shadow texture.
image-type, image-type-p, image-type-dimension, image-type-arrayed, image-type-multisampled, image-type-component, image-type-format	structure, predicate, readers	A storage image, designated by its keyword and its format.
image-format-p object	function	True for a format of storage images.
image-formats	function	The formats of storage images, in a fixed order.
image-format-kind format	function	The scalar kind of its texels as shaders read them.
handle-keyword-description keyword	function	What a texture's or storage image's keyword is: (class dimension arrayed multisampled depth kind).
texture-keywords, image-keywords	functions	The keywords of the textures, and of the storage images.
intern-type module designator	function	A module's type for a designator, made the first time.
type-designator type	function	A type's designator, its external form.
pointer-to module space type	function	A module's type of pointers into a space to a type.
type-scalar-kind, type-component, type-component-count type	functions	The scalar kind, the scalar type, and the count of components of a scalar, vector or matrix, or nil.
boolean-type-p, integer-type-p, float-type-p, numeric-type-p type	functions	True for booleans, integers, floats, or numbers, scalars or vectors.
sized-type-p type	function	True for a type whose values have a size the IR knows, which may be stored, passed and returned.

Layout

Symbol	Kind	What it is
type-size, type-alignment type layout	functions	The size and alignment in bytes of a type laid out by std140 or std430.
array-stride type layout	function	The bytes from one element of an array type to the next.
matrix-stride type layout	function	The bytes from one column of a matrix type to the next.
member-offsets type layout	function	The offsets of a struct type's members.
aggregate-alignment alignment layout	function	The alignment of an array or struct whose most aligned member aligns to alignment.

Values

Symbol	Kind	What it is
value, value-p	structure, predicate	A value: a constant, a global, a parameter or an instruction's result.
value-type, value-name, value-source value	readers, setf-able	Its type, the name the source gave it, and the form it came from.
name-string name	function	The name a back end gives a symbol, for OpName or a GLSL identifier.
constant module type data	function, structure	A constant of a module of a type; a constant value.
constant-p, constant-datum	predicate, reader	A constant's value as Lisp data.
datum= a b	function	True if two constants' data are the same, 0.0 and -0.0 apart.
global, global-p	structure, predicate	A variable of a module.
global-space, global-location, global-built-in, global-interpolation, global-sampling, global-group, global-binding, global-access, global-patch global	readers	What add-global gave it.
global-store-type global	function	The type of what it holds.
per-vertex-global-p global stage	function	True if it holds a value for each vertex of a patch or primitive.
built-ins	function	The built-ins an :input or :output global may be.
parameter, parameter-p, parameter-function	structure, predicate, reader (setf-able)	A parameter of a function.
instruction, instruction-p	structure, predicate	An instruction, which is the value it gives.
instruction-operation, instruction-operands, instruction-indexes, instruction-callee instruction	readers	Its operation, its operands, its literal indexes, and a :call's function.
instruction-blocks, instruction-block, instruction-exact instruction	readers, setf-able	An :if's or :loop's blocks, the block it is in, and whether it is exact, which no compiler may contract or reassociate.
instruction-function instruction	function	The function it is in.
pointer-root pointer	function	The variable a pointer points into.

Blocks, functions and modules

Symbol	Kind	What it is
ir-block, block-statements, block-parent	structure, readers	A block: its statements, and its function or construct.
block-terminator block	function	The terminator it ends in, or nil.
terminator-target terminator	function	The construct an exit leaves or goes back to.
ir-function, ir-function-p, function-module, function-name, function-parameters, function-return-type	structure, predicate, readers	A function of a module.
function-body, function-source function	readers, setf-able	Its body, a block, and the form it came from.
module, module-p, module-stage	structure, predicate, reader	A module: one stage of a program.
module-structs, module-globals, module-functions, module-entry-point, module-execution module	readers, setf-able	Its structs, globals, functions, entry point, and its stage's options.
module-option module key	function	The value of one of its stage's options.
arrayed-stage-p stage	function	True for a tessellation or geometry stage, whose inputs are arrays of a value for each vertex.
primitive-vertex-count primitive	function	How many vertices a geometry shader's input primitive has.

Operations

Symbol	Kind	What it is
operations	function	The names of the IR's operations, in the table's order.
operation-kind name	function	:instruction, :terminator or :construct.
operation-arguments name	function	What it takes: its immediate, :type, :callee or nil; its least and most operands; its least and most literal indexes.
operation-effect name	function	nil, :read or :write.
operation-uniformity name	function	:collective for an operation that needs uniform control flow, or nil.
operation-stages name	function	The stages it may appear in, or nil for any.
operation-contractible-p name	function	True for floating-point arithmetic or a conversion a compiler may contract or reassociate.
construct-completes-p construct	function	True if an :if or :loop can complete.

Building

Symbol	Kind	What it is
make-module stage	function	A new, empty module of a stage.
add-struct module name members	function	Add a struct type.
add-global module name space type &key location built-in interpolation sampling group binding access patch	function	Add a global variable.
add-function module name parameters return-type	function	Add a function, whose body is empty.
set-entry-point module function &key ...	function	Make a function the module's entry point, with its stage's options.
builder, make-builder function	structure, function	A builder that adds instructions to the end of a block of a function.
builder-module builder	reader	Its module.
builder-block, builder-source, builder-exact builder	readers, setf-able	The block it adds to, the form the instructions come from, and whether they are exact.
build builder operation &rest arguments	function	Add an instruction, or the constant it folds to, and return its value.
build-if builder condition &optional type, build-loop builder &optional type	functions	Add an :if or a :loop.
if-then-block, if-else-block, loop-body-block, loop-continuing-block construct	functions	A construct's blocks.
with-block (builder block) &body body	macro	Build in another block for a time.
unreachable-block builder	function	A new block no control flow reaches, for code after a terminator.

The external form, the verifier and the uniformity analysis

Symbol	Kind	What it is
module-form module &key package	function	A module's external form, an s-expression.
read-module-form form	function	The module an external form describes, built but not verified.
verify-module module	function	Check a module against the IR's rules, and return it, or signal an ir-error.
uniformity-failures module &key severity	function	The operations that need uniform control flow and may not have it, as uniformity-failures.
uniformity-failure, uniformity-failure-p	structure, predicate	One such operation.
uniformity-failure-severity, uniformity-failure-origin, uniformity-failure-kind, uniformity-failure-parameter, uniformity-failure-path, uniformity-failure-need failure	readers	:error or :warning; the instructions at fault; what must be uniform; an argument's position; the steps by which it may not be; and what the operation needs.
ir-error	condition	IR that breaks the IR's rules, a clsl-error.

Targets

Symbol	Kind	What it is
target	class	One API's rules for the code a program becomes.
target-name target	generic function	The target's name, such as :vulkan.
find-target name	generic function	The target of a name, or a no-target-error.
define-target name class	macro	Make find-target return an instance of a class for a name.
target-compile target module	generic function	The target's code of a module.
target-features target module code	generic function	The optional device features the code needs.
target-disassemble target code stream	generic function	Print the code for people to read.

clsl/spirv

Types and the condition

Symbol	Kind	What it is
word	type	A 32-bit word of a SPIR-V module.
words	type	The words of a module, as cl-gfx's create-shader-module takes them.
id	type	An id of a module: a positive integer below its bound.
version	type	A SPIR-V version, (major minor).
spirv-error	condition	SPIR-V its grammar does not allow, a clsl-error.

The grammar's tables

Symbol	Kind	What it is
grammar-version	function	The newest version the tables describe, and the grammar's revision.
instruction-opcode name, opcode-instruction opcode	functions	An instruction's opcode, and an opcode's instruction.
instruction-spirv-name name	function	The name SPIR-V gives an instruction.
instruction-capabilities, instruction-extensions name	functions	What a module needs one of to use an instruction.
instruction-version, instruction-last-version name	functions	The versions from which, and up to which, it is core SPIR-V.
enumerant-names kind	function	The enumerants of an operand kind.
enumerant-value, enumerant-spirv-name kind name	functions	An enumerant's value, and its name in SPIR-V.
enumerant-capabilities, enumerant-extensions, enumerant-version, enumerant-last-version kind name	functions	What an enumerant needs, and its versions.
extended-instruction-number, extended-instruction-capabilities set name	functions	An instruction of an extended set's number, and what it needs.

The module builder

Symbol	Kind	What it is
module	structure	A SPIR-V module being built. One thread at a time.
make-module &key version generator	function	A new, empty module, of SPIR-V 1.6 by default.
module-version, module-generator module	readers	The version and the generator word its header gives.
new-id module	function	A new id.
emit module name &rest operands	function	Add an instruction, and return the id it defines, or nil.
void-type, bool-type module	functions	The id of the void and boolean types, declared once.
int-type module width signedp, float-type module width	functions	The id of an integer or float type.
vector-type module component-type count, matrix-type module column-type count	functions	The id of a vector or matrix type.
pointer-type module storage-class type	function	The id of a pointer type.
function-type module return-type &rest parameter-types	function	The id of a function type.
image-type module sampled-type dim &key ..., sampler-type module, sampled-image-type module image-type	functions	The ids of image, sampler and sampled image types.
new-array-type, new-runtime-array-type, new-struct-type	functions	A new array, runtime array or struct type, each call another.
constant module type value, constant-composite module type &rest constituents, null-constant module type	functions	The id of a constant, declared once.
import-instruction-set module name	function	The id of an import of an extended instruction set.
module-words module	function	The module's words, header first.
module-requirements module	function	What the module holds needs, as requirements.
requirement, requirement-capabilities, requirement-extensions, requirement-what	structure, readers	What a module must declare one of to use something, and what that is.

The reader and the disassembler

Symbol	Kind	What it is
read-words pathname	function	A SPIR-V file's words, in either byte order.
read-header source	function	The header's version, generator, bound and schema.
read-instructions source	function	A module's instructions, in the form emit takes.
read-capabilities source	function	The capabilities a module declares.
disassemble-spirv source &key stream raw-ids	function	Print a module as SPIR-V assembly, as spirv-dis does.

clsl/spirv-back-end

Symbol	Kind	What it is
translate-module module target	function	Verify an IR module, and translate it into the words of a SPIR-V module by a target's rules.
spirv-target	class	A target whose code is SPIR-V.
target-spirv-version, target-capabilities, target-extensions target	readers	The SPIR-V version of its modules, and the capabilities and extensions its API allows.
target-execution-modes target stage	generic function	The execution modes it gives every module of a stage.
target-built-in target built-in	generic function	The SPIR-V BuiltIn of an IR built-in.
target-descriptor-binding target group binding	generic function	The descriptor set and binding of a bind group's binding.
target-discard-instruction target	generic function	The instruction that discards a fragment.

clsl/generator

Symbol	Kind	What it is
regenerate-grammar	function	Write spirv/grammar.lisp from the grammar files, and return its pathname.
grammar-text	function	The text of spirv/grammar.lisp, as the generator writes it.
write-grammar grammar extended-grammars stream	function	Write the tables of a grammar and its extended grammars.
read-json source	function	A JSON document as plain Lisp data.
read-grammar pathname, parse-grammar json	functions	The core grammar of a file, or of what read-json returned.
read-extended-grammar pathname name, parse-extended-grammar json name	functions	An extended instruction set's grammar.
lisp-name name	function	The name of the keyword clsl uses for a name of the grammar.
version	type	A SPIR-V version, (major minor).
quantifier	type	How often an operand may occur: nil, :optional or :variadic.
category	type	What sort of operand kind a kind is: :id, :literal, :value-enum, :bit-enum or :composite.
grammar, make-grammar, grammar-p	structure, constructor, predicate	The core grammar.
grammar-copyright, grammar-magic-number, grammar-major-version, grammar-minor-version, grammar-revision, grammar-instructions, grammar-operand-kinds	readers	Its parts.
extended-grammar, make-extended-grammar, extended-grammar-p	structure, constructor, predicate	An extended instruction set's grammar.
extended-grammar-name, extended-grammar-copyright, extended-grammar-version, extended-grammar-revision, extended-grammar-instructions	readers	Its parts.
instruction, make-instruction, instruction-p	structure, constructor, predicate	An instruction of a grammar.
instruction-name, instruction-opcode, instruction-class, instruction-operands, instruction-capabilities, instruction-extensions, instruction-version, instruction-last-version, instruction-aliases, instruction-provisional-p	readers	Its parts.
operand, make-operand, operand-p, operand-kind, operand-name, operand-quantifier	structure, constructor, predicate, readers	An operand of an instruction, or a parameter of an enumerant.
kind, make-kind, kind-p, kind-name, kind-category, kind-enumerants, kind-bases, kind-documentation	structure, constructor, predicate, readers	An operand kind.
enumerant, make-enumerant, enumerant-p	structure, constructor, predicate	A value of an enumerating operand kind.
enumerant-name, enumerant-value, enumerant-parameters, enumerant-capabilities, enumerant-extensions, enumerant-version, enumerant-last-version, enumerant-aliases, enumerant-provisional-p	readers	Its parts.
grammar-error	condition	A grammar file that is not well-formed JSON, or not of the grammar's format.
grammar-error-source, grammar-error-context, grammar-error-message condition	functions	The file read, or nil; where in the grammar; what is wrong.