Datasheet

3.3. PIO Assembler (pioasm)
The PIO Assembler parses a PIO source file and outputs the assembled version ready for inclusion in an RP2040
application. This includes C and C++ applications built against the SDK, and Python programs running on the RP2040
MicroPython port.
This section briefly introduces the directives and instructions that can be used in pioasm input. A deeper discussion of
how to use pioasm, how it is integrated into the SDK build system, extended features such as code pass through, and the
various output formats it can produce, is given in the Raspberry Pi Pico C/C++ SDK book.
3.3.1. Directives
The following directives control the assembly of PIO programs:
Table 373. pioasm
directives
.define ( PUBLIC ) <symbol> <value> Define an integer symbol named <symbol> with the value <value> (see Section
3.3.2). If this .define appears before the first program in the input file, then the
define is global to all programs, otherwise it is local to the program in which it
occurs. If PUBLIC is specified the symbol will be emitted into the assembled
output for use by user code. For the SDK this takes the form of:
#define <program_name>_<symbol> value for program symbols or #define <symbol>
value for global symbols
.program <name> Start a new program with the name <name>. Note that that name is used in
code so should be alphanumeric/underscore not starting with a digit. The
program lasts until another .program directive or the end of the source file. PIO
instructions are only allowed within a program
.origin <offset> Optional directive to specify the PIO instruction memory offset at which the
program must load. Most commonly this is used for programs that must load
at offset 0, because they use data based JMPs with the (absolute) jmp target
being stored in only a few bits. This directive is invalid outside of a program
.side_set <count> (opt) (pindirs) If this directive is present, <count> indicates the number of side-set bits to be
used. Additionally opt may be specified to indicate that a side <value> is
optional for instructions (note this requires stealing an extra bit — in addition
to the <count> bits — from those available for the instruction delay). Finally,
pindirs may be specified to indicate that the side set values should be applied
to the PINDIRs and not the PINs. This directive is only valid within a program
before the first instruction
.wrap_target Place prior to an instruction, this directive specifies the instruction where
execution continues due to program wrapping. This directive is invalid outside
of a program, may only be used once within a program, and if not specified
defaults to the start of the program
.wrap Placed after an instruction, this directive specifies the instruction after which,
in normal control flow (i.e. jmp with false condition, or no jmp), the program
wraps (to .wrap_target instruction). This directive is invalid outside of a
program, may only be used once within a program, and if not specified
defaults to after the last program instruction.
.lang_opt <lang> <name> <option> Specifies an option for the program related to a particular language generator.
(See Language generators). This directive is invalid outside of a program
.word <value> Stores a raw 16-bit value as an instruction in the program. This directive is
invalid outside of a program.
RP2040 Datasheet
3.3. PIO Assembler (pioasm) 338