Merge pull request #71 from adafruit/doc

Start documenting the PIO language subset supported by adafuit_pioasm

Author: tannewt

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
 =============
 

docs/index.rst

@@ -14,6 +14,12 @@ Table of Contents
 
     examples
 
+.. toctree::
+    :caption: Syntax
+    :maxdepth: 3
+
+    syntax
+
 .. toctree::
     :caption: API Reference
     :maxdepth: 3

docs/syntax.rst

@@ -0,0 +1,88 @@
+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.

docs/syntax.rst.license

@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2024 Jeff Epler, written for Adafruit Industries
+
+SPDX-License-Identifier: MIT