Skip to content
Lorenzi edited this page Apr 12, 2026 · 15 revisions

Integer literals

  • Decimal literals: 123
  • Binary literals: 0b111010 or %111010
  • Octal literals: 0o137
  • Hexadecimal literals: 0x4bf86 or $4bf86

Sizes are derived automatically from the given radix and digits (except for decimal literals), and leading zeroes matter in this regard. You can use an underscore _ to visually separate digits. If you need to explicitly indicate a value's size, you can use the slice operator, like 255`8, as seen below.

Struct literals

From v0.13.12 onwards: struct { x = 123, y = 456 }

Structs are useful to pass multiple values around. A struct is always copied and passed by value. You currently can't mutate its contents after creation. You can read its fields by using dot notation:

#const my_struct = struct {
    x = 123
    y = 456
}

#d16 my_struct.x
#d16 my_struct.y

Operators

The following operators are listed in the order of the lowest precedence to the highest.

  • ?, ? : Binary and Ternary Conditional
  • = Assignment
  • @ Concatenation
  • || Lazy Or
  • && Lazy And
  • ==, !=, <, <=, >, >= Relational
  • | Binary Or
  • ^ Binary Xor
  • & Binary And
  • <<, >> Binary Shifts
  • +, - Addition and Subtraction
  • *, /, % Multiplication, Division, and Modulo
  • x[hi:lo] Slice (Verilog-style)
  • x`size Slice shorthand
  • !, - Unary Not and Unary Negation

You can also use code blocks.

Built-in Variables

  • $
    The address of the current instruction or the current expression in a data directive.

Built-in Functions

  • $sizeof(value)
    Returns the definite size of the value in bits. Values have definite sizes when created from a sized literal (binary, octal, and hexadecimal literals, and string literals), or when sliced. For example: $sizeof(0x012) == 12 or $sizeof((1 + 1)`8) == 8.

  • $bankof(label)
    Returns a reference to the bank the given label belongs to. See the page on banks for more information.

  • $le(value)
    Reverses the bytes of an integer, essentially performing little-endian encoding. The integer must have a size that is a multiple of 8 bits. For example: $le(0x1234) or $le(65000`16).

  • $assert(condition)
    Generates an error when condition is false. Useful to check for the validity of instruction arguments, and also for multiple-match resolution.

  • $utf8(str), $ascii(str), $utf16be(str), $utf16le(str), $utf32be(str), $utf32le(str)
    Reencodes the given string. For example, $utf16be("abc") will give you 0x0061_0062_0063. The default string encoding is already utf8, so that function is usually redundant. For the ascii encoding, invalid codepoints are converted to 0x00.

  • $incbin(relative_filename)
    Reads the given binary file and returns its contents as a sized integer. Useful with the unsized data directive for including existing binary files into your output, for example as #d $incbin("graphics.bin")

  • $incbinstr(relative_filename)
    Reads the given text file, which should only contain the ASCII digits 0 and 1 (ignoring whitespace and underscores), and returns the interpreted binary value as a sized integer. Useful for including files generated from customasm with the binstr format.

  • $inchexstr(relative_filename)
    Reads the given text file, which should only contain the valid hexadecimal ASCII digits (ignoring whitespace and underscores), and returns the interpreted hexadecimal value as a sized integer. Useful for including files generated from customasm with the hexstr format.

Clone this wiki locally