Language reference

CLK syntax

A CLK file defines a small register-based program and the 32-bit output patterns emitted by that program. This page documents the syntax accepted by CLK Workbench.

File structure

A file contains three ordered parts.

Definitions and instructions Numeric symbols, command labels, and executable instructions.
START_BIT_DATA The required marker that separates instructions from pattern data. It must occur exactly once.
Bit patterns Named sequences of positive durations and 32-bit output words.

$NAME VALUE

@LABEL instruction operands
       instruction operands

START_BIT_DATA
&PATTERN bit DURATION BIT_WORD
         bit DURATION BIT_WORD
         endb

Lexical rules

Form	Meaning
`# comment`	A comment begins with `#` and continues to the end of the line.
`$NAME`	Numeric symbol. A definition uses `$NAME VALUE`. It is an alias for an unsigned 32-bit integer and can be used where an instruction expects a register address or value.
`@LABEL`	Command label. A label and its instruction must be on the same line.
`&PATTERN`	Named output pattern referenced by `outp`.
`VALUE`	Unsigned 32-bit decimal or hexadecimal integer. Hexadecimal values use the `0x` prefix.
`BIT_WORD`	Exactly 32 binary digits. The Workbench displays the leftmost digit as bit 31 and the rightmost as bit 0.

Case and encoding. Source text must be ASCII. Keywords, mnemonics, and symbol names are case-sensitive; instruction mnemonics are lowercase. The Workbench recognizes a symbol by its prefix and does not otherwise restrict the characters in its name. Letters, digits, and underscores are recommended.

Numeric ranges. Numeric definitions, register addresses, and register contents are unsigned 32-bit integers in the range 0–0xFFFFFFFF. Normal reads of an unwritten register return zero; retn handles an unwritten return register as described below. Pattern durations follow the separate rules described under Pattern directives.

Compatibility. This implementation uses unsigned 32-bit integers for numeric definitions, register addresses, and register contents.

Minimal example

This program emits one four-tick pattern and then terminates. The first two ticks have a zero word; the final two ticks set bit 0.

# Minimal CLK program
outp &PULSE
halt

START_BIT_DATA
&PULSE bit 2 00000000000000000000000000000000
       bit 2 00000000000000000000000000000001
       endb

Instruction reference

R[$REG] denotes the register whose address is defined by $REG. In load and copy, an address or value may be written as either a numeric symbol or a decimal/hexadecimal literal. PC is the instruction address that will execute next.

Syntax	Definition
`nop`	Performs no operation, then advances to the next instruction.
`outp &PATTERN`	Appends every row of the named pattern to the output in declaration order, then advances.
`jump @LABEL`	Sets `PC` to the named command label.
`ajmp $REG @LABEL`	Jumps when `R[$REG] > 0`. The register is not modified. Otherwise advances.
`bjmp $REG @LABEL`	When `R[$REG] > 0`, clears that register to zero and jumps. Otherwise advances.
`cjmp $REG @LABEL`	When `R[$REG] > 0`, decrements it by one and jumps. Otherwise advances.
`cmpz $LEFT $RIGHT`	If the two register values are equal, sets `R[$LEFT]` to zero. Then advances.
`load ADDRESS VALUE`	Stores `VALUE` in the register at `ADDRESS`, then advances. Both operands accept a numeric symbol or an integer literal.
`copy DESTINATION SOURCE`	Copies the register at `SOURCE` to the register at `DESTINATION`, then advances. Both operands accept a numeric symbol or an integer literal; `SOURCE` is an address, not an immediate value.
`subj $RETURN @LABEL`	Stores the address of the next instruction in `R[$RETURN]`, then jumps to the label. There is no call stack; reusing the register overwrites its return address.
`retn $RETURN`	Sets `PC` to the address stored in `R[$RETURN]`. If that register has never been written, execution moves to the end of the instruction list.
`halt`	Terminates execution immediately.

Command-label address. The toolbar's Label address setting determines whether a label resolves to its same-line instruction or the following instruction. The default is same-line instruction.

Waveform events. An event accepts exactly one non-output instruction and runs it once immediately after the selected outp. Events cannot contain outp or define labels. Event and Source load/copy commands use the same numeric symbol and literal operand rules.

Pattern directives

Syntax	Definition
`&NAME bit DURATION BIT_WORD`	Starts a named pattern and defines its first output row.
`bit DURATION BIT_WORD`	Adds a row to the active pattern. Duration must be a positive decimal or hexadecimal integer.
`endb`	Terminates the active pattern. It takes no operands, and an empty pattern is invalid.

Durations are expressed in ticks. Conversion from ticks to physical time, and the mapping from bit positions to hardware signals, are device-specific and are not defined by the CLK file.