From 4d17d310df4d32c8b8a62bacc8b15738b04176a7 Mon Sep 17 00:00:00 2001 From: Jeff Epler Date: Thu, 19 Sep 2024 11:53:46 -0500 Subject: [PATCH] Start documenting the PIO language subset supported by adafuit_pioasm this documentation could be more complete, but it's better than nothing. --- README.rst | 5 --- docs/index.rst | 6 +++ docs/syntax.rst | 82 +++++++++++++++++++++++++++++++++++++++++ docs/syntax.rst.license | 3 ++ 4 files changed, 91 insertions(+), 5 deletions(-) create mode 100644 docs/syntax.rst create mode 100644 docs/syntax.rst.license diff --git a/README.rst b/README.rst index 67e7577..b7ae53a 100644 --- a/README.rst +++ b/README.rst @@ -55,11 +55,6 @@ To install in a virtual environment in your current project: source .venv/bin/activate pip3 install adafruit-circuitpython-pioasm -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. - Usage Example ============= diff --git a/docs/index.rst b/docs/index.rst index da492bc..4e8cc91 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,12 @@ Table of Contents examples +.. toctree:: + :caption: Syntax + :maxdepth: 3 + + syntax + .. toctree:: :caption: API Reference :maxdepth: 3 diff --git a/docs/syntax.rst b/docs/syntax.rst new file mode 100644 index 0000000..129162c --- /dev/null +++ b/docs/syntax.rst @@ -0,0 +1,82 @@ +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, ```` 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 ``: Accepts a program name, which should be a valid Python identifier + * ``.pio_version ``: The numeric version of the PIO peripheral to target. Version 0, the default, is in the RP2040. Version 1 is in RP2350 + * ``.origin ``: 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 {opt}``: Controls the side-set behavior and sets ``pio_kwargs["sideset_enable"]`` and ``pio_kwargs["sideset_pin_count"]`` + * ``.fifo ``: 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 {{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 {{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 ``: Settings that control how the ``set`` instruction works, including shift direction and whether auto push is enabled, by placing values in ``pio_kwargs`` + +Labels +------ + + * ``:`` creates a label which may be referred to by a ``jmp`` instruction. + +Instructions +------------ + + * ``nop`` + * ``jmp `` + * ``wait ...`` + * ``in ...`` + * ``out ...`` + * ``push ...`` + * ``pull ...`` + * ``mov ...`` + * ``irq ...`` + * ``set ...`` + +Side-set and delay +------------------ +The next part of each line can contain "side-set" and "delay" information, in order. + + * ``side ``: Set the side-set pins to ``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 `` 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 +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. diff --git a/docs/syntax.rst.license b/docs/syntax.rst.license new file mode 100644 index 0000000..6fd4abf --- /dev/null +++ b/docs/syntax.rst.license @@ -0,0 +1,3 @@ +SPDX-FileCopyrightText: 2024 Jeff Epler, written for Adafruit Industries + +SPDX-License-Identifier: MIT