Expressions

Integer literals

• Decimal literals: 123
• Binary literals: 0b111_010 (From v0.13.0 onwards: you can also use %111_010)
• Octal literals: 0o137
• Hexadecimal literals: 0x4bf86 (From v0.13.0 onwards: you can also use $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, 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

• $ or pc
  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. It's important that the value have a size which 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.