88 lines
4.2 KiB
ReStructuredText
88 lines
4.2 KiB
ReStructuredText
This chapter documents the language features accepted by the `adafruit_pioasm`
|
|
assembler. The dialect is intended to be a compatible subset of the one in the
|
|
pico-sdk's ``pioasm`` program (which does not produce CircuitPython-compatible
|
|
output).
|
|
|
|
For full details, refer to the relevant chapter in the RP2040 or RP2350 datasheet.
|
|
|
|
In this informal grammar, ``<angle brackets>`` represent some text, usually a single
|
|
word or number. ``{curly brackets}`` represent an element that is optional.
|
|
``|`` represents alternatives. ``...`` indicates further arguments that are
|
|
explained in the official datasheet.
|
|
|
|
Lines
|
|
~~~~~
|
|
|
|
First, any portion of the line starting with the comment character ``;`` is removed.
|
|
Then, extra whitespace is removed and the line is parsed.
|
|
|
|
Each line may be:
|
|
* blank
|
|
* a directive
|
|
* a label
|
|
* an instruction, possibly with side-set and delay information
|
|
|
|
Directives
|
|
----------
|
|
|
|
* ``.program <identifier>``: Accepts a program name, which should be a valid Python identifier
|
|
* ``.pio_version <number>``: The numeric version of the PIO peripheral to target. Version 0, the default, is in the RP2040. Version 1 is in RP2350
|
|
* ``.origin <number>``: The required load address of the program. If specified and not ``-1``, this will be stored in ``pio_kwargs["offset"]``
|
|
* ``.wrap``, ``.wrap_target``: This pair of directives set the range of instructions for implicit looping, by placing values in ``pio_kwargs``
|
|
* ``.side_set <number> {opt}``: Controls the side-set behavior and sets ``pio_kwargs["sideset_enable"]`` and ``pio_kwargs["sideset_pin_count"]``
|
|
* ``.fifo <identifier>``: Sets the FIFO mode. As a CircuitPython extension, ``auto`` (the default) automatically chooses among ``txrx``, ``tx``, and ``rx`` modes
|
|
* ``.mov_status ...``: Controls what information the ``mov status`` instruction accesses, by placing values in ``pio_kwargs``
|
|
* ``.out <count> {{left|right}} {{auto}}``: Settings that control how the ``out`` instruction works, including shift direction and whether auto pull is enabled, by placing values in ``pio_kwargs``
|
|
* ``.in <count> {{left|right}} {{auto}}``: Settings that control how the ``in`` instruction works, including shift direction and whether auto push is enabled, by placing values in ``pio_kwargs``
|
|
* ``.set <count>``: Settings that control how the ``set`` instruction works, including shift direction and whether auto push is enabled, by placing values in ``pio_kwargs``
|
|
|
|
Labels
|
|
------
|
|
|
|
* ``<identifier>:`` creates a label which may be referred to by a ``jmp`` instruction.
|
|
|
|
Instructions
|
|
------------
|
|
|
|
* ``nop``
|
|
* ``jmp <number|name>``
|
|
* ``wait ...``
|
|
* ``in ...``
|
|
* ``out ...``
|
|
* ``push ...``
|
|
* ``pull ...``
|
|
* ``mov ...``
|
|
* ``mov rxfifo[y|number], isr`` (requires PIO version 1 and compatible ``.fifo`` setting)
|
|
* ``mov osr, rxfifo[y|number]`` (requires PIO version 1 and compatible ``.fifo`` setting)
|
|
* ``irq <number> {rel}``
|
|
* ``irq next|prev <number>``. (requires PIO version 1) adafruit_pioasm follows sdk pioasm in placing ``next`` and ``prev`` before the IRQ number. The datasheet (version 05c4754) implies a different syntax.
|
|
* ``set ...``
|
|
|
|
Side-set and delay
|
|
------------------
|
|
The next part of each line can contain "side-set" and "delay" information, in order.
|
|
|
|
* ``side <number>``: Set the side-set pins to ``number``
|
|
* ``[<number>]``: Add ``number`` extra delay cycles to this instruction
|
|
|
|
The range of these numbers depends on the count of side-set pins and whether side-set is
|
|
optional. If side-set is not optional, a missing ``side <number>`` is treated the same as
|
|
``side 0``.
|
|
|
|
Unsupported Features
|
|
--------------------
|
|
|
|
In places where a numeric value is needed, only a valid Python numeric literal
|
|
is accepted. Arithmetic is not supported.
|
|
|
|
Whitespace is not accepted in certain places, for instance within an instruction delay.
|
|
It must be written ``[7]`` not ``[ 7 ]``.
|
|
|
|
Extra commas that would not be acceptable to sdk pioasm are not always diagnosed.
|
|
|
|
Extra words in some locations that would not be acceptable to sdk pioasm are not always diagnosed.
|
|
|
|
CircuitPython extensions
|
|
------------------------
|
|
|
|
* ``.fifo auto``: By default, CircuitPython joins the TX and RX fifos if a PIO program only receives or transmits. The ``.fifo auto`` directive makes this explicit.
|