Merge pull request #78 from FoamyGuy/update_frequency

Use higher frequency values

.gitattributes

@@ -0,0 +1,11 @@
+# SPDX-FileCopyrightText: 2024 Justin Myers for Adafruit Industries
+#
+# SPDX-License-Identifier: Unlicense
+
+.py text eol=lf
+.rst text eol=lf
+.txt text eol=lf
+.yaml text eol=lf
+.toml text eol=lf
+.license text eol=lf
+.md text eol=lf

.pre-commit-config.yaml

@@ -1,42 +1,21 @@
-# SPDX-FileCopyrightText: 2020 Diego Elio Pettenò
+# SPDX-FileCopyrightText: 2024 Justin Myers for Adafruit Industries
 #
 # SPDX-License-Identifier: Unlicense
 
 repos:
-  - repo: https://github.com/python/black
-    rev: 23.3.0
-    hooks:
-      - id: black
-  - repo: https://github.com/fsfe/reuse-tool
-    rev: v1.1.2
-    hooks:
-      - id: reuse
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
       - id: check-yaml
       - id: end-of-file-fixer
       - id: trailing-whitespace
-  - repo: https://github.com/pycqa/pylint
-    rev: v2.17.4
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.4
     hooks:
-      - id: pylint
-        name: pylint (library code)
-        types: [python]
-        args:
-          - --disable=consider-using-f-string
-        exclude: "^(docs/|examples/|tests/|setup.py$)"
-      - id: pylint
-        name: pylint (example code)
-        description: Run pylint rules on "examples/*.py" files
-        types: [python]
-        files: "^examples/"
-        args:
-          - --disable=missing-docstring,invalid-name,consider-using-f-string,duplicate-code
-      - id: pylint
-        name: pylint (test code)
-        description: Run pylint rules on "tests/*.py" files
-        types: [python]
-        files: "^tests/"
-        args:
-          - --disable=missing-docstring,consider-using-f-string,duplicate-code
+      - id: ruff-format
+      - id: ruff
+        args: ["--fix"]
+  - repo: https://github.com/fsfe/reuse-tool
+    rev: v3.0.1
+    hooks:
+      - id: reuse

.pylintrc

@@ -1,399 +0,0 @@
-# SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
-#
-# SPDX-License-Identifier: Unlicense
-
-[MASTER]
-
-# A comma-separated list of package or module names from where C extensions may
-# be loaded. Extensions are loading into the active Python interpreter and may
-# run arbitrary code
-extension-pkg-whitelist=
-
-# Add files or directories to the ignore-list. They should be base names, not
-# paths.
-ignore=CVS
-
-# Add files or directories matching the regex patterns to the ignore-list. The
-# regex matches against base names, not paths.
-ignore-patterns=
-
-# Python code to execute, usually for sys.path manipulation such as
-# pygtk.require().
-#init-hook=
-
-# Use multiple processes to speed up Pylint.
-jobs=1
-
-# List of plugins (as comma separated values of python modules names) to load,
-# usually to register additional checkers.
-load-plugins=pylint.extensions.no_self_use
-
-# Pickle collected data for later comparisons.
-persistent=yes
-
-# Specify a configuration file.
-#rcfile=
-
-# Allow loading of arbitrary C extensions. Extensions are imported into the
-# active Python interpreter and may run arbitrary code.
-unsafe-load-any-extension=no
-
-
-[MESSAGES CONTROL]
-
-# Only show warnings with the listed confidence levels. Leave empty to show
-# all. Valid levels: HIGH, INFERENCE, INFERENCE_FAILURE, UNDEFINED
-confidence=
-
-# Disable the message, report, category or checker with the given id(s). You
-# can either give multiple identifiers separated by comma (,) or put this
-# option multiple times (only on the command line, not in the configuration
-# file where it should appear only once).You can also use "--disable=all" to
-# disable everything first and then reenable specific checks. For example, if
-# you want to run only the similarities checker, you can use "--disable=all
-# --enable=similarities". If you want to run only the classes checker, but have
-# no Warning level messages displayed, use"--disable=all --enable=classes
-# --disable=W"
-# disable=import-error,raw-checker-failed,bad-inline-option,locally-disabled,file-ignored,suppressed-message,useless-suppression,deprecated-pragma,deprecated-str-translate-call
-disable=raw-checker-failed,bad-inline-option,locally-disabled,file-ignored,suppressed-message,useless-suppression,deprecated-pragma,import-error,pointless-string-statement,unspecified-encoding
-
-# Enable the message, report, category or checker with the given id(s). You can
-# either give multiple identifier separated by comma (,) or put this option
-# multiple time (only on the command line, not in the configuration file where
-# it should appear only once). See also the "--disable" option for examples.
-enable=
-
-
-[REPORTS]
-
-# Python expression which should return a note less than 10 (10 is the highest
-# note). You have access to the variables errors warning, statement which
-# respectively contain the number of errors / warnings messages and the total
-# number of statements analyzed. This is used by the global evaluation report
-# (RP0004).
-evaluation=10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)
-
-# Template used to display messages. This is a python new-style format string
-# used to format the message information. See doc for all details
-#msg-template=
-
-# Set the output format. Available formats are text, parseable, colorized, json
-# and msvs (visual studio).You can also give a reporter class, eg
-# mypackage.mymodule.MyReporterClass.
-output-format=text
-
-# Tells whether to display a full report or only the messages
-reports=no
-
-# Activate the evaluation score.
-score=yes
-
-
-[REFACTORING]
-
-# Maximum number of nested blocks for function / method body
-max-nested-blocks=5
-
-
-[LOGGING]
-
-# Logging modules to check that the string format arguments are in logging
-# function parameter format
-logging-modules=logging
-
-
-[SPELLING]
-
-# Spelling dictionary name. Available dictionaries: none. To make it working
-# install python-enchant package.
-spelling-dict=
-
-# List of comma separated words that should not be checked.
-spelling-ignore-words=
-
-# A path to a file that contains private dictionary; one word per line.
-spelling-private-dict-file=
-
-# Tells whether to store unknown words to indicated private dictionary in
-# --spelling-private-dict-file option instead of raising a message.
-spelling-store-unknown-words=no
-
-
-[MISCELLANEOUS]
-
-# List of note tags to take in consideration, separated by a comma.
-# notes=FIXME,XXX,TODO
-notes=FIXME,XXX
-
-
-[TYPECHECK]
-
-# List of decorators that produce context managers, such as
-# contextlib.contextmanager. Add to this list to register other decorators that
-# produce valid context managers.
-contextmanager-decorators=contextlib.contextmanager
-
-# List of members which are set dynamically and missed by pylint inference
-# system, and so shouldn't trigger E1101 when accessed. Python regular
-# expressions are accepted.
-generated-members=
-
-# Tells whether missing members accessed in mixin class should be ignored. A
-# mixin class is detected if its name ends with "mixin" (case insensitive).
-ignore-mixin-members=yes
-
-# This flag controls whether pylint should warn about no-member and similar
-# checks whenever an opaque object is returned when inferring. The inference
-# can return multiple potential results while evaluating a Python object, but
-# some branches might not be evaluated, which results in partial inference. In
-# that case, it might be useful to still emit no-member and other checks for
-# the rest of the inferred objects.
-ignore-on-opaque-inference=yes
-
-# List of class names for which member attributes should not be checked (useful
-# for classes with dynamically set attributes). This supports the use of
-# qualified names.
-ignored-classes=optparse.Values,thread._local,_thread._local
-
-# List of module names for which member attributes should not be checked
-# (useful for modules/projects where namespaces are manipulated during runtime
-# and thus existing member attributes cannot be deduced by static analysis. It
-# supports qualified module names, as well as Unix pattern matching.
-ignored-modules=board
-
-# Show a hint with possible names when a member name was not found. The aspect
-# of finding the hint is based on edit distance.
-missing-member-hint=yes
-
-# The minimum edit distance a name should have in order to be considered a
-# similar match for a missing member name.
-missing-member-hint-distance=1
-
-# The total number of similar names that should be taken in consideration when
-# showing a hint for a missing member.
-missing-member-max-choices=1
-
-
-[VARIABLES]
-
-# List of additional names supposed to be defined in builtins. Remember that
-# you should avoid to define new builtins when possible.
-additional-builtins=
-
-# Tells whether unused global variables should be treated as a violation.
-allow-global-unused-variables=yes
-
-# List of strings which can identify a callback function by name. A callback
-# name must start or end with one of those strings.
-callbacks=cb_,_cb
-
-# A regular expression matching the name of dummy variables (i.e. expectedly
-# not used).
-dummy-variables-rgx=_+$|(_[a-zA-Z0-9_]*[a-zA-Z0-9]+?$)|dummy|^ignored_|^unused_
-
-# Argument names that match this expression will be ignored. Default to name
-# with leading underscore
-ignored-argument-names=_.*|^ignored_|^unused_
-
-# Tells whether we should check for unused import in __init__ files.
-init-import=no
-
-# List of qualified module names which can have objects that can redefine
-# builtins.
-redefining-builtins-modules=six.moves,future.builtins
-
-
-[FORMAT]
-
-# Expected format of line ending, e.g. empty (any line ending), LF or CRLF.
-# expected-line-ending-format=
-expected-line-ending-format=LF
-
-# Regexp for a line that is allowed to be longer than the limit.
-ignore-long-lines=^\s*(# )?<?https?://\S+>?$
-
-# Number of spaces of indent required inside a hanging  or continued line.
-indent-after-paren=4
-
-# String used as indentation unit. This is usually "    " (4 spaces) or "\t" (1
-# tab).
-indent-string='    '
-
-# Maximum number of characters on a single line.
-max-line-length=100
-
-# Maximum number of lines in a module
-max-module-lines=1000
-
-# Allow the body of a class to be on the same line as the declaration if body
-# contains single statement.
-single-line-class-stmt=no
-
-# Allow the body of an if to be on the same line as the test if there is no
-# else.
-single-line-if-stmt=no
-
-
-[SIMILARITIES]
-
-# Ignore comments when computing similarities.
-ignore-comments=yes
-
-# Ignore docstrings when computing similarities.
-ignore-docstrings=yes
-
-# Ignore imports when computing similarities.
-ignore-imports=yes
-
-# Minimum lines number of a similarity.
-min-similarity-lines=12
-
-
-[BASIC]
-
-# Regular expression matching correct argument names
-argument-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
-
-# Regular expression matching correct attribute names
-attr-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
-
-# Bad variable names which should always be refused, separated by a comma
-bad-names=foo,bar,baz,toto,tutu,tata
-
-# Regular expression matching correct class attribute names
-class-attribute-rgx=([A-Za-z_][A-Za-z0-9_]{2,30}|(__.*__))$
-
-# Regular expression matching correct class names
-# class-rgx=[A-Z_][a-zA-Z0-9]+$
-class-rgx=[A-Z_][a-zA-Z0-9_]+$
-
-# Regular expression matching correct constant names
-const-rgx=(([A-Z_][A-Z0-9_]*)|(__.*__))$
-
-# Minimum line length for functions/classes that require docstrings, shorter
-# ones are exempt.
-docstring-min-length=-1
-
-# Regular expression matching correct function names
-function-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
-
-# Good variable names which should always be accepted, separated by a comma
-# good-names=i,j,k,ex,Run,_
-good-names=r,g,b,w,i,j,k,n,x,y,z,ex,ok,Run,_
-
-# Include a hint for the correct naming format with invalid-name
-include-naming-hint=no
-
-# Regular expression matching correct inline iteration names
-inlinevar-rgx=[A-Za-z_][A-Za-z0-9_]*$
-
-# Regular expression matching correct method names
-method-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
-
-# Regular expression matching correct module names
-module-rgx=(([a-z_][a-z0-9_]*)|([A-Z][a-zA-Z0-9]+))$
-
-# Colon-delimited sets of names that determine each other's naming style when
-# the name regexes allow several styles.
-name-group=
-
-# Regular expression which should only match function or class names that do
-# not require a docstring.
-no-docstring-rgx=^_
-
-# List of decorators that produce properties, such as abc.abstractproperty. Add
-# to this list to register other decorators that produce valid properties.
-property-classes=abc.abstractproperty
-
-# Regular expression matching correct variable names
-variable-rgx=(([a-z][a-z0-9_]{2,30})|(_[a-z0-9_]*))$
-
-
-[IMPORTS]
-
-# Allow wildcard imports from modules that define __all__.
-allow-wildcard-with-all=no
-
-# Analyse import fallback blocks. This can be used to support both Python 2 and
-# 3 compatible code, which means that the block might have code that exists
-# only in one or another interpreter, leading to false positives when analysed.
-analyse-fallback-blocks=no
-
-# Deprecated modules which should not be used, separated by a comma
-deprecated-modules=optparse,tkinter.tix
-
-# Create a graph of external dependencies in the given file (report RP0402 must
-# not be disabled)
-ext-import-graph=
-
-# Create a graph of every (i.e. internal and external) dependencies in the
-# given file (report RP0402 must not be disabled)
-import-graph=
-
-# Create a graph of internal dependencies in the given file (report RP0402 must
-# not be disabled)
-int-import-graph=
-
-# Force import order to recognize a module as part of the standard
-# compatibility libraries.
-known-standard-library=
-
-# Force import order to recognize a module as part of a third party library.
-known-third-party=enchant
-
-
-[CLASSES]
-
-# List of method names used to declare (i.e. assign) instance attributes.
-defining-attr-methods=__init__,__new__,setUp
-
-# List of member names, which should be excluded from the protected access
-# warning.
-exclude-protected=_asdict,_fields,_replace,_source,_make
-
-# List of valid names for the first argument in a class method.
-valid-classmethod-first-arg=cls
-
-# List of valid names for the first argument in a metaclass class method.
-valid-metaclass-classmethod-first-arg=mcs
-
-
-[DESIGN]
-
-# Maximum number of arguments for function / method
-max-args=5
-
-# Maximum number of attributes for a class (see R0902).
-# max-attributes=7
-max-attributes=11
-
-# Maximum number of boolean expressions in a if statement
-max-bool-expr=5
-
-# Maximum number of branch for function / method body
-max-branches=12
-
-# Maximum number of locals for function / method body
-max-locals=15
-
-# Maximum number of parents for a class (see R0901).
-max-parents=7
-
-# Maximum number of public methods for a class (see R0904).
-max-public-methods=20
-
-# Maximum number of return / yield for function / method body
-max-returns=6
-
-# Maximum number of statements in function / method body
-max-statements=50
-
-# Minimum number of public methods for a class (see R0903).
-min-public-methods=1
-
-
-[EXCEPTIONS]
-
-# Exceptions that will emit a warning when being caught. Defaults to
-# "Exception"
-overgeneral-exceptions=builtins.Exception

.readthedocs.yaml

@@ -8,8 +8,11 @@
 # Required
 version: 2
 
+sphinx:
+  configuration: docs/conf.py
+
 build:
-  os: ubuntu-20.04
+  os: ubuntu-lts-latest
   tools:
     python: "3"
 

README.rst

@@ -13,9 +13,9 @@ Introduction
     :target: https://github.com/adafruit/Adafruit_CircuitPython_PIOASM/actions
     :alt: Build Status
 
-.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-    :target: https://github.com/psf/black
-    :alt: Code Style: Black
+.. image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json
+    :target: https://github.com/astral-sh/ruff
+    :alt: Code Style: Ruff
 
 Simple assembler to convert pioasm to bytes
 
@@ -75,7 +75,7 @@ Usage Example
 
     sm = rp2pio.StateMachine(
         assembled,
-        frequency=2000,
+        frequency=4000,
         init=adafruit_pioasm.assemble("set pindirs 1"),
         first_set_pin=board.LED,
     )

adafruit_pioasm.py

@@ -12,7 +12,7 @@ Simple assembler to convert pioasm to bytes
 """
 
 try:
-    from typing import List, MutableSequence
+    from typing import Any, List, Sequence
 except ImportError:
     pass
 
@@ -29,13 +29,23 @@ CONDITIONS = ["", "!x", "x--", "!y", "y--", "x!=y", "pin", "!osre"]
 IN_SOURCES = ["pins", "x", "y", "null", None, None, "isr", "osr"]
 OUT_DESTINATIONS = ["pins", "x", "y", "null", "pindirs", "pc", "isr", "exec"]
 WAIT_SOURCES = ["gpio", "pin", "irq", None]
-MOV_DESTINATIONS = ["pins", "x", "y", None, "exec", "pc", "isr", "osr"]
+MOV_DESTINATIONS_V0 = ["pins", "x", "y", None, "exec", "pc", "isr", "osr"]
+MOV_DESTINATIONS_V1 = ["pins", "x", "y", "pindirs", "exec", "pc", "isr", "osr"]
 MOV_SOURCES = ["pins", "x", "y", "null", None, "status", "isr", "osr"]
 MOV_OPS = [None, "~", "::", None]
 SET_DESTINATIONS = ["pins", "x", "y", None, "pindirs", None, None, None]
+FIFO_TYPES = {
+    "auto": 0,
+    "txrx": 0,
+    "tx": 0,
+    "rx": 0,
+    "txput": 1,
+    "txget": 1,
+    "putget": 1,
+}
 
 
-class Program:  # pylint: disable=too-few-public-methods
+class Program:
     """Encapsulates a program's instruction stream and configuration flags
 
     Example::
@@ -45,31 +55,80 @@ class Program:  # pylint: disable=too-few-public-methods
 
     """
 
+    assembled: array.array
+    """The assembled PIO program instructions"""
+    public_labels: dict[str, int]
+    """The offset of any labels declared public"""
+    pio_kwargs: dict[str, Any]
+    """Settings from assembler directives to pass to the StateMachine constructor"""
+
     def __init__(self, text_program: str, *, build_debuginfo: bool = False) -> None:
         """Converts pioasm text to encoded instruction bytes"""
-        # pylint: disable=too-many-branches,too-many-statements,too-many-locals
         assembled: List[int] = []
         program_name = None
         labels = {}
+        public_labels = {}
         linemap = []
         instructions: List[str] = []
         sideset_count = 0
         sideset_enable = 0
+        sideset_pindirs = False
         wrap = None
         wrap_target = None
         offset = -1
+        pio_version = 0
+        fifo_type = "auto"
+        mov_status_type = None
+        mov_status_n = None
+        in_count = None
+        in_shift_right = None
+        auto_push = None
+        push_threshold = None
+        out_count = None
+        out_shift_right = None
+        auto_pull = None
+        pull_threshold = None
+        set_count = None
+
+        def require_before_instruction():
+            if len(instructions) != 0:
+                raise RuntimeError(f"{words[0]} must be before first instruction")
+
+        def require_version(required_version, instruction):
+            if pio_version < required_version:
+                raise RuntimeError(f"{instruction} requires .pio_version {required_version}")
+
+        def int_in_range(arg, low, high, what, radix=0):
+            result = int(arg, radix)
+            if low <= result < high:
+                return result
+            raise RuntimeError(f"{what} must be at least {low} and less than {high}, got {result}")
+
+        def parse_rxfifo_brackets(arg, fifo_dir):
+            require_version(1, line)
+            if fifo_type != "putget" and fifo_type != fifo_dir:
+                raise RuntimeError(
+                    f"FIFO must be configured for '{fifo_dir}' or 'putget' for {line}"
+                )
+            if arg.endswith("[y]"):
+                return 0b1000
+            return int_in_range(arg[7:-1], 0, 8, "rxfifo index")
+
         for i, line in enumerate(text_program.split("\n")):
-            line = line.strip()
+            line = line.split(";")[0].strip()
             if not line:
                 continue
-            if ";" in line:
-                line = line.split(";")[0].strip()
+            words = line.split()
             if line.startswith(".program"):
                 if program_name:
                     raise RuntimeError("Multiple programs not supported")
                 program_name = line.split()[1]
+            elif line.startswith(".pio_version"):
+                require_before_instruction()
+                pio_version = int_in_range(words[1], 0, 2, ".pio_version")
             elif line.startswith(".origin"):
-                offset = int(line.split()[1], 0)
+                require_before_instruction()
+                offset = int_in_range(words[1], 0, 32, ".origin")
             elif line.startswith(".wrap_target"):
                 wrap_target = len(instructions)
             elif line.startswith(".wrap"):
@@ -79,8 +138,89 @@ class Program:  # pylint: disable=too-few-public-methods
             elif line.startswith(".side_set"):
                 sideset_count = int(line.split()[1], 0)
                 sideset_enable = "opt" in line
+                sideset_pindirs = "pindirs" in line
+            elif line.startswith(".fifo"):
+                require_before_instruction()
+                fifo_type = line.split()[1]
+                required_version = FIFO_TYPES.get(fifo_type)
+                if required_version is None:
+                    raise RuntimeError(f"Invalid fifo type {fifo_type}")
+                require_version(required_version, line)
+            elif line.startswith(".mov_status"):
+                require_before_instruction()
+                required_version = 0
+                mov_status_n = 0
+                mov_status_type = words[1]
+                if words[1] in {"txfifo", "rxfifo"}:
+                    if words[2] != "<":
+                        raise RuntimeError(f"Invalid {line}")
+                    mov_status_n = int_in_range(words[3], 0, 32, words[1])
+                elif words[1] == "irq":
+                    required_version = 1
+                    idx = 2
+                    if words[idx] == "next":
+                        mov_status_n = 0x10
+                        idx += 1
+                    elif words[idx] == "prev":
+                        mov_status_n = 0x8
+                        idx += 1
+                    else:
+                        mov_status_n = 0
+                    if words[idx] != "set":
+                        raise RuntimeError(f"Invalid {line})")
+                    mov_status_n |= int_in_range(words[idx + 1], 0, 8, "mov_status irq")
+                require_version(required_version, line)
+            elif words[0] == ".out":
+                require_before_instruction()
+                out_count = int_in_range(words[1], 1, 33, ".out count")
+                auto_pull = False
+
+                idx = 2
+                if idx < len(words) and words[idx] == "left":
+                    out_shift_right = False
+                    idx += 1
+                elif idx < len(words) and words[idx] == "right":
+                    out_shift_right = True
+                    idx += 1
+
+                if idx < len(words) and words[idx] == "auto":
+                    auto_pull = True
+                    idx += 1
+
+                if idx < len(words):
+                    pull_threshold = int_in_range(words[idx], 1, 33, ".out threshold")
+                    idx += 1
+
+            elif words[0] == ".in":
+                require_before_instruction()
+                in_count = int_in_range(words[1], 32 if pio_version == 0 else 1, 33, ".in count")
+                auto_push = False
+
+                idx = 2
+                if idx < len(words) and words[idx] == "left":
+                    in_shift_right = False
+                    idx += 1
+                elif idx < len(words) and words[idx] == "right":
+                    in_shift_right = True
+                    idx += 1
+
+                if idx < len(words) and words[idx] == "auto":
+                    auto_push = True
+                    idx += 1
+
+                if idx < len(words):
+                    push_threshold = int_in_range(words[idx], 1, 33, ".in threshold")
+                    idx += 1
+
+            elif words[0] == ".set":
+                require_before_instruction()
+                set_count = int_in_range(words[1], 5 if pio_version == 0 else 1, 6, ".set count")
+
             elif line.endswith(":"):
                 label = line[:-1]
+                if line.startswith("public "):
+                    label = label[7:]
+                    public_labels[label] = len(instructions)
                 if label in labels:
                     raise SyntaxError(f"Duplicate label {repr(label)}")
                 labels[label] = len(instructions)
@@ -89,12 +229,22 @@ class Program:  # pylint: disable=too-few-public-methods
                 instructions.append(line)
                 linemap.append(i)
 
+        mov_destinations: Sequence[str | None]
+        if pio_version >= 1:
+            mov_destinations = MOV_DESTINATIONS_V1
+        else:
+            mov_destinations = MOV_DESTINATIONS_V0
+
         max_delay = 2 ** (5 - sideset_count - sideset_enable) - 1
         assembled = []
         for line in instructions:
             instruction = splitter(line.strip())
             delay = 0
-            if len(instruction) > 1 and instruction[-1].endswith("]"):  # Delay
+            if (
+                len(instruction) > 1
+                and instruction[-1].startswith("[")
+                and instruction[-1].endswith("]")
+            ):  # Delay
                 delay = int(instruction[-1].strip("[]"), 0)
                 if delay < 0:
                     raise RuntimeError("Delay negative:", delay)
@@ -130,24 +280,50 @@ class Program:  # pylint: disable=too-few-public-methods
                     try:
                         assembled[-1] |= CONDITIONS.index(instruction[1]) << 5
                     except ValueError as exc:
-                        raise ValueError(
-                            f"Invalid jmp condition '{instruction[1]}'"
-                        ) from exc
+                        raise ValueError(f"Invalid jmp condition '{instruction[1]}'") from exc
 
             elif instruction[0] == "wait":
                 #                instr delay p sr index
                 assembled.append(0b001_00000_0_00_00000)
                 polarity = int(instruction[1], 0)
+                source = instruction[2]
                 if not 0 <= polarity <= 1:
                     raise RuntimeError("Invalid polarity")
                 assembled[-1] |= polarity << 7
-                assembled[-1] |= WAIT_SOURCES.index(instruction[2]) << 5
-                num = int(instruction[3], 0)
-                if not 0 <= num <= 31:
-                    raise RuntimeError("Wait num out of range")
-                assembled[-1] |= num
-                if instruction[-1] == "rel":
-                    assembled[-1] |= 0x10  # Set the high bit of the irq value
+                if instruction[2] == "jmppin":
+                    require_version(1, "wait jmppin")
+                    num = 0
+                    if len(instruction) > 3:
+                        if len(instruction) < 5 or instruction[3] != "+":
+                            raise RuntimeError("invalid wait jmppin")
+                        num = int_in_range(instruction[4], 0, 4, "wait jmppin offset")
+                    assembled[-1] |= num
+                    assembled[-1] |= 0b11 << 5  # JMPPIN wait source
+                else:
+                    idx = 3
+                    assembled[-1] |= WAIT_SOURCES.index(instruction[2]) << 5
+                    if source == "irq":
+                        if instruction[idx] == "next":
+                            require_version(1, "wait irq next")
+                            assembled[-1] |= 0b11000
+                            idx += 1
+                        elif instruction[idx] == "prev":
+                            require_version(1, "wait irq prev")
+                            assembled[-1] |= 0b01000
+                            idx += 1
+
+                        limit = 8
+                        # The flag index is decoded in the same way as the IRQ
+                        # index field, decoding down from the two MSBs
+                        if instruction[-1] == "rel":
+                            if assembled[-1] & 0b11000:
+                                raise RuntimeError("cannot use next/prev with rel")
+                            assembled[-1] |= 0b10000
+                    else:
+                        limit = 32
+                    num = int_in_range(instruction[idx], 0, limit, "wait {instruction[2]}")
+                    assembled[-1] |= num
+
             elif instruction[0] == "in":
                 #                instr delay src count
                 assembled.append(0b010_00000_000_00000)
@@ -167,9 +343,7 @@ class Program:  # pylint: disable=too-few-public-methods
                 try:
                     assembled[-1] |= OUT_DESTINATIONS.index(destination) << 5
                 except ValueError as exc:
-                    raise ValueError(
-                        f"Invalid out destination '{destination}'"
-                    ) from exc
+                    raise ValueError(f"Invalid out destination '{destination}'") from exc
                 count = int(instruction[-1], 0)
                 if not 1 <= count <= 32:
                     raise RuntimeError("Count out of range")
@@ -181,56 +355,83 @@ class Program:  # pylint: disable=too-few-public-methods
                     assembled[-1] |= 0x80
                 if instruction[-1] == "block" or not instruction[-1].endswith("block"):
                     assembled[-1] |= 0x20
-                if len(instruction) > 1 and instruction[1] in ("ifempty", "iffull"):
+                if len(instruction) > 1 and instruction[1] in {"ifempty", "iffull"}:
                     assembled[-1] |= 0x40
             elif instruction[0] == "mov":
                 #                instr delay dst op src
-                assembled.append(0b101_00000_000_00_000)
-                assembled[-1] |= MOV_DESTINATIONS.index(instruction[1]) << 5
-                source = instruction[-1]
-                source_split = mov_splitter(source)
-                if len(source_split) == 1:
-                    try:
-                        assembled[-1] |= MOV_SOURCES.index(source)
-                    except ValueError as exc:
-                        raise ValueError(f"Invalid mov source '{source}'") from exc
+                if instruction[1].startswith("rxfifo["):  # mov rxfifo[], isr
+                    assembled.append(0b100_00000_0001_1_000)
+                    if instruction[2] != "isr":
+                        raise ValueError("mov rxfifo[] source must be isr")
+                    assembled[-1] ^= parse_rxfifo_brackets(instruction[1], "txput")
+                elif instruction[2].startswith("rxfifo["):  # mov osr, rxfifo[]
+                    assembled.append(0b100_00000_1001_1_000)
+                    if instruction[1] != "osr":
+                        raise ValueError("mov ,rxfifo[] target must be osr")
+                    assembled[-1] ^= parse_rxfifo_brackets(instruction[2], "txget")
                 else:
-                    assembled[-1] |= MOV_SOURCES.index(source_split[1])
-                    if source[:1] == "!":
-                        assembled[-1] |= 0x08
-                    elif source[:1] == "~":
-                        assembled[-1] |= 0x08
-                    elif source[:2] == "::":
-                        assembled[-1] |= 0x10
+                    assembled.append(0b101_00000_000_00_000)
+                    assembled[-1] |= mov_destinations.index(instruction[1]) << 5
+                    source = instruction[-1]
+                    source_split = mov_splitter(source)
+                    if len(source_split) == 1:
+                        try:
+                            assembled[-1] |= MOV_SOURCES.index(source)
+                        except ValueError as exc:
+                            raise ValueError(f"Invalid mov source '{source}'") from exc
                     else:
-                        raise RuntimeError("Invalid mov operator:", source[:1])
-                if len(instruction) > 3:
-                    assembled[-1] |= MOV_OPS.index(instruction[-2]) << 3
+                        assembled[-1] |= MOV_SOURCES.index(source_split[1])
+                        if source[:1] == "!":
+                            assembled[-1] |= 0x08
+                        elif source[:1] == "~":
+                            assembled[-1] |= 0x08
+                        elif source[:2] == "::":
+                            assembled[-1] |= 0x10
+                        else:
+                            raise RuntimeError("Invalid mov operator:", source[:1])
+                    if len(instruction) > 3:
+                        assembled[-1] |= MOV_OPS.index(instruction[-2]) << 3
             elif instruction[0] == "irq":
-                #                instr delay z c w index
+                #                instr delay z c w tp/idx
                 assembled.append(0b110_00000_0_0_0_00000)
+
+                irq_type = 0
+                idx = 1
+                if instruction[idx] == "wait":
+                    assembled[-1] |= 0x20
+                    idx += 1
+                elif instruction[idx] == "clear":
+                    assembled[-1] |= 0x40
+                    idx += 1
+
+                if instruction[idx] == "prev":
+                    irq_type = 1
+                    require_version(1, "irq prev")
+                    idx += 1
+                elif instruction[idx] == "next":
+                    irq_type = 3
+                    require_version(1, "irq next")
+                    idx += 1
+
                 if instruction[-1] == "rel":
-                    assembled[-1] |= 0x10  # Set the high bit of the irq value
+                    if irq_type != 0:
+                        raise RuntimeError("cannot use next/prev with rel")
+                    irq_type = 2
                     instruction.pop()
-                num = int(instruction[-1], 0)
-                if not 0 <= num <= 7:
-                    raise RuntimeError("Interrupt index out of range")
+
+                assembled[-1] |= irq_type << 3
+
+                num = int_in_range(instruction[idx], 0, 8, "irq index")
                 assembled[-1] |= num
-                if len(instruction) == 3:  # after rel has been removed
-                    if instruction[1] == "wait":
-                        assembled[-1] |= 0x20
-                    elif instruction[1] == "clear":
-                        assembled[-1] |= 0x40
-                    # All other values are the default of set without waiting
+                instruction.pop()
+
             elif instruction[0] == "set":
                 #                instr delay dst data
                 assembled.append(0b111_00000_000_00000)
                 try:
                     assembled[-1] |= SET_DESTINATIONS.index(instruction[1]) << 5
                 except ValueError as exc:
-                    raise ValueError(
-                        f"Invalid set destination '{instruction[1]}'"
-                    ) from exc
+                    raise ValueError(f"Invalid set destination '{instruction[1]}'") from exc
                 value = int(instruction[-1], 0)
                 if not 0 <= value <= 31:
                     raise RuntimeError("Set value out of range")
@@ -247,18 +448,66 @@ class Program:  # pylint: disable=too-few-public-methods
         if offset != -1:
             self.pio_kwargs["offset"] = offset
 
+        if pio_version != 0:
+            self.pio_kwargs["pio_version"] = pio_version
+
         if sideset_count != 0:
             self.pio_kwargs["sideset_pin_count"] = sideset_count
+        if sideset_pindirs:
+            self.pio_kwargs["sideset_pindirs"] = sideset_pindirs
 
         if wrap is not None:
             self.pio_kwargs["wrap"] = wrap
         if wrap_target is not None:
             self.pio_kwargs["wrap_target"] = wrap_target
 
+        if fifo_type != "auto":
+            self.pio_kwargs["fifo_type"] = fifo_type
+
+        if mov_status_type is not None:
+            self.pio_kwargs["mov_status_type"] = mov_status_type
+            self.pio_kwargs["mov_status_n"] = mov_status_n
+
+        if set_count is not None:
+            self.pio_kwargs["set_pin_count"] = set_count
+
+        if out_count not in {None, 32}:
+            self.pio_kwargs["out_pin_count"] = out_count
+
+        if out_shift_right is not None:
+            self.pio_kwargs["out_shift_right"] = out_shift_right
+
+        if auto_pull is not None:
+            self.pio_kwargs["auto_pull"] = auto_pull
+
+        if pull_threshold is not None:
+            self.pio_kwargs["pull_threshold"] = pull_threshold
+
+        if in_count not in {None, 32}:
+            self.pio_kwargs["in_pin_count"] = in_count
+
+        if in_shift_right is not None:
+            self.pio_kwargs["in_shift_right"] = in_shift_right
+
+        if auto_push is not None:
+            self.pio_kwargs["auto_push"] = auto_push
+
+        if push_threshold is not None:
+            self.pio_kwargs["push_threshold"] = push_threshold
+
         self.assembled = array.array("H", assembled)
 
         self.debuginfo = (linemap, text_program) if build_debuginfo else None
 
+        self.public_labels = public_labels
+
+    @classmethod
+    def from_file(cls, filename: str, **kwargs) -> "Program":
+        """Assemble a PIO program in a file"""
+        with open(filename, encoding="utf-8") as i:
+            program = i.read()
+        return cls(program, **kwargs)
+
     def print_c_program(self, name: str, qualifier: str = "const") -> None:
         """Print the program into a C program snippet"""
         if self.debuginfo is None:
@@ -271,14 +520,10 @@ class Program:  # pylint: disable=too-few-public-methods
         print(
             f"{qualifier} int {name}_wrap = {self.pio_kwargs.get('wrap', len(self.assembled)-1)};"
         )
-        print(
-            f"{qualifier} int {name}_wrap_target = {self.pio_kwargs.get('wrap_target', 0)};"
-        )
+        print(f"{qualifier} int {name}_wrap_target = {self.pio_kwargs.get('wrap_target', 0)};")
         sideset_pin_count = self.pio_kwargs.get("sideset_pin_count", 0)
         print(f"{qualifier} int {name}_sideset_pin_count = {sideset_pin_count};")
-        print(
-            f"{qualifier} bool {name}_sideset_enable = {self.pio_kwargs['sideset_enable']};"
-        )
+        print(f"{qualifier} bool {name}_sideset_enable = {+self.pio_kwargs['sideset_enable']};")
         print(f"{qualifier} uint16_t {name}[] = " + "{")
         last_line = 0
         if linemap:
@@ -300,14 +545,12 @@ class Program:  # pylint: disable=too-few-public-methods
                 last_line += 1
         else:
             for i in range(0, len(self.assembled), 8):
-                print(
-                    "    " + ", ".join("0x%04x" % i for i in self.assembled[i : i + 8])
-                )
+                print("    " + ", ".join("0x%04x" % i for i in self.assembled[i : i + 8]))
         print("};")
         print()
 
 
-def assemble(program_text: str) -> MutableSequence[int]:
+def assemble(program_text: str) -> array.array:
     """Converts pioasm text to encoded instruction bytes
 
     In new code, prefer to use the `Program` class so that the extra arguments

docs/api.rst

@@ -4,5 +4,8 @@
 .. If your library file(s) are nested in a directory (e.g. /adafruit_foo/foo.py)
 .. use this format as the module name: "adafruit_foo.foo"
 
+API Reference
+#############
+
 .. automodule:: adafruit_pioasm
    :members:

docs/conf.py

@@ -1,12 +1,10 @@
-# -*- coding: utf-8 -*-
-
 # SPDX-FileCopyrightText: 2017 Scott Shawcroft, written for Adafruit Industries
 #
 # SPDX-License-Identifier: MIT
 
+import datetime
 import os
 import sys
-import datetime
 
 sys.path.insert(0, os.path.abspath(".."))
 
@@ -51,9 +49,7 @@ project = "Adafruit PIOASM Library"
 creation_year = "2021"
 current_year = str(datetime.datetime.now().year)
 year_duration = (
-    current_year
-    if current_year == creation_year
-    else creation_year + " - " + current_year
+    current_year if current_year == creation_year else creation_year + " - " + current_year
 )
 copyright = year_duration + " Scott Shawcroft"
 author = "Scott Shawcroft"
@@ -113,7 +109,6 @@ napoleon_numpy_docstring = False
 import sphinx_rtd_theme
 
 html_theme = "sphinx_rtd_theme"
-html_theme_path = [sphinx_rtd_theme.get_html_theme_path(), "."]
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

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

examples/pioasm_7seg.py

@@ -39,8 +39,10 @@ Wiring:
 
 import array
 import time
+
 import board
 import rp2pio
+
 import adafruit_pioasm
 
 _program = adafruit_pioasm.Program(
@@ -114,7 +116,7 @@ class SMSevenSegment:
         self._buf = array.array("H", (DIGITS_WT[0] & ~COM_WT[i] for i in range(4)))
         self._sm = rp2pio.StateMachine(
             _program.assembled,
-            frequency=2000,
+            frequency=4000,
             first_out_pin=first_pin,
             out_pin_count=14,
             auto_pull=True,

examples/pioasm_7seg_fader.py

@@ -36,12 +36,14 @@ Wiring:
  * Pico GP16 to LED matrix 14 (COM1)
 """
 
+import array
 import asyncio
 import random
-import array
+
 import board
 import rp2pio
 from ulab import numpy as np
+
 import adafruit_pioasm
 
 _pio_source = """
@@ -130,20 +132,16 @@ def make_digit_wt(v):
 
 
 class LedFader:
-    def __init__(
-        self, first_pin, pin_count, cathode_weights, anode_weights, levels=64
-    ):  # pylint: disable=too-many-arguments
+    def __init__(self, first_pin, pin_count, cathode_weights, anode_weights, levels=64):
         self._cathode_weights = cathode_weights
         self._anode_weights = anode_weights
-        self._stream = array.array("L", [0, 0, 1]) * (
-            1 + len(cathode_weights) * len(anode_weights)
-        )
+        self._stream = array.array("L", [0, 0, 1]) * (1 + len(cathode_weights) * len(anode_weights))
         self._levels = levels
         self._max_count = levels * len(self)
         self._total = len(self)
 
         program = adafruit_pioasm.Program(_pio_source.format(n=pin_count))
-        self._sm = rp2pio.StateMachine(  # pylint: disable=too-many-arguments
+        self._sm = rp2pio.StateMachine(
             program.assembled,
             frequency=125_000_000,
             first_out_pin=first_pin,
@@ -152,9 +150,7 @@ class LedFader:
             pull_threshold=14,
             **program.pio_kwargs,
         )
-        print(
-            f"Note: approximate refresh rate {self._sm.frequency / self._max_count:.0f}Hz"
-        )
+        print(f"Note: approximate refresh rate {self._sm.frequency / self._max_count:.0f}Hz")
         self._sm.background_write(loop=self._stream)
 
     def __enter__(self):

examples/pioasm_background_morse.py

@@ -19,8 +19,10 @@ https://en.wikipedia.org/wiki/Morse_code
 
 import array
 import time
+
 from board import LED
 from rp2pio import StateMachine
+
 from adafruit_pioasm import Program
 
 # This program turns the LED on or off depending on the first bit of the value,
@@ -73,7 +75,7 @@ sm = StateMachine(
 )
 
 # To simply repeat 'TEST' forever, change to 'if True':
-if False:  # pylint: disable=using-constant-test
+if False:
     print("Sending out TEST forever", end="")
     sm.background_write(loop=TEST)
     while True:

examples/pioasm_blink.py

@@ -6,8 +6,10 @@
 
 import array
 import time
+
 import board
 import rp2pio
+
 import adafruit_pioasm
 
 blink = adafruit_pioasm.assemble(

examples/pioasm_hello.py

@@ -5,8 +5,10 @@
 # Adapted from the example https://github.com/raspberrypi/pico-examples/tree/master/pio/hello_pio
 
 import time
+
 import board
 import rp2pio
+
 import adafruit_pioasm
 
 hello = """
@@ -25,7 +27,7 @@ assembled = adafruit_pioasm.assemble(hello)
 
 sm = rp2pio.StateMachine(
     assembled,
-    frequency=2000,
+    frequency=4000,
     first_out_pin=board.LED,
 )
 print("real frequency", sm.frequency)

examples/pioasm_i2s_codec.py

@@ -0,0 +1,211 @@
+# SPDX-FileCopyrightText: 2024 Tim Chinowsky
+# SPDX-License-Identifier: MIT
+
+import array
+
+import board
+import rp2pio
+
+import adafruit_pioasm
+
+# Implement extended multichannel I2S interface like that used by audio codecs
+# such as the TAC5212.  In extended I2S, "Left" and "Right" can each contain
+# multiple channels, so for instance 8 channels of audio can be sent as a "left"
+# containing 4 channels and a "right" containing 4 channels.
+
+# In this implementation the number of bits per sample, sample rate, and
+# number of channels can be independently specified.  The number of channels must
+# be even, to divide evenly between left and right.
+
+# Ramped test data containing the requested number of sample sets (one set = one
+# sample for each channel) and spanning the specified number of bits will be generated
+# and sent out over I2S on the specified pins.
+
+# Data will be preceded and followed by a set of zeros for convenience.
+# (Some protocol analyzers have trouble analyzing serial data at the the beginning
+# and end of a data set)
+
+# At the same time that I2S data is sent out the out_pin, I2S data will be received
+# on the in_pin.  If the output is looped back (connected) to the input, the data
+# received should be the same as the data sent.
+
+# Some samples run in loopback configuration:
+
+# bits per sample: 16
+#     sample rate: 48000
+#        channels: 4
+#     sample sets: 4
+
+# actual sample frequency   47984.6 Hz
+#               bit clock 3071017.0 Hz
+
+# write: 00000000  00000000  00000000  00000000
+#  read: 00000000  00000000  00000000  00000000
+
+# write: 00000000  00001111  00002222  00003333
+#  read: 00000000  00001111  00002222  00003333
+
+# write: 00004444  00005555  00006666  00007777
+#  read: 00004444  00005555  00006666  00007777
+
+# write: 00008888  00009999  0000aaaa  0000bbbb
+#  read: 00008888  00009999  0000aaaa  0000bbbb
+
+# write: 0000cccc  0000dddd  0000eeee  0000ffff
+#  read: 0000cccc  0000dddd  0000eeee  0000ffff
+
+# write: 00000000  00000000  00000000  00000000
+#  read: 00000000  00000000  00000000  00000000
+
+# bits per sample: 24
+#     sample rate: 24000
+#        channels: 8
+#     sample sets: 5
+
+# actual sample frequency   23987.7 Hz
+#               bit clock 4605642.0 Hz
+
+# write: 00000000  00000000  00000000  00000000  00000000  00000000  00000000  00000000
+#  read: 00000000  00000000  00000000  00000000  00000000  00000000  00000000  00000000
+
+# write: 00000000  00069069  000d20d2  0013b13b  001a41a4  0020d20d  00276276  002df2df
+#  read: 00000000  00069069  000d20d2  0013b13b  001a41a4  0020d20d  00276276  002df2df
+
+# write: 00348348  003b13b1  0041a41a  00483482  004ec4ec  00555554  005be5be  00627626
+#  read: 00348348  003b13b1  0041a41a  00483482  004ec4ec  00555554  005be5be  00627626
+
+# write: 00690690  006f96f8  00762762  007cb7ca  00834834  0089d89c  00906904  0096f96c
+#  read: 00690690  006f96f8  00762762  007cb7ca  00834834  0089d89c  00906904  0096f96c
+
+# write: 009d89d8  00a41a40  00aaaaa8  00b13b10  00b7cb7c  00be5be4  00c4ec4c  00cb7cb4
+#  read: 009d89d8  00a41a40  00aaaaa8  00b13b10  00b7cb7c  00be5be4  00c4ec4c  00cb7cb4
+
+# write: 00d20d20  00d89d88  00df2df0  00e5be58  00ec4ec4  00f2df2c  00f96f94  00ffffff
+#  read: 00d20d20  00d89d88  00df2df0  00e5be58  00ec4ec4  00f2df2c  00f96f94  00ffffff
+
+# write: 00000000  00000000  00000000  00000000  00000000  00000000  00000000  00000000
+#  read: 00000000  00000000  00000000  00000000  00000000  00000000  00000000  00000000
+
+
+def i2s_codec(
+    channels=2,
+    sample_rate=48000,
+    bits=16,
+    bclk_pin=None,
+    out_pin=None,
+    in_pin=None,
+):
+    i2s_clock = sample_rate * channels * bits
+    pio_clock = 4 * i2s_clock
+    pio_code = """
+        .program i2s_codec
+        .side_set 2
+                            ; at program start we initialize the bit count top
+                            ; (which may be >32) with data
+                            ; pulled from the input fifo
+            pull noblock    ; first empty the input fifo
+            pull noblock
+            pull noblock
+            pull noblock
+            out null, 32    ; then clear OSR so we can get a new value
+            pull block      ; then get the bit count top value from the fifo
+                            ;        /--- LRCLK
+                            ;        |/-- BCLK
+                            ;        ||
+            mov x, osr;       side 0b01 [1] ; save it in x
+            out null, 32      side 0b00 [1]
+            mov y, x          side 0b01 [1] ; start of main loop (wrap target=8)
+        bitloop1:
+            out pins 1        side 0b00
+            in pins 1         side 0b00
+            jmp y-- bitloop1  side 0b01 [1]
+            out pins 1        side 0b10
+            in pins 1         side 0b10
+            mov y, x          side 0b11 [1]
+        bitloop0:
+            out pins 1        side 0b10
+            in pins 1         side 0b10
+            jmp y-- bitloop0  side 0b11 [1]
+            out pins 1        side 0b00
+            in pins 1         side 0b00
+    """
+    pio_params = {
+        "frequency": pio_clock,
+        "first_out_pin": out_pin,
+        "first_in_pin": in_pin,
+        "first_sideset_pin": bclk_pin,
+        "sideset_pin_count": 2,
+        "auto_pull": True,
+        "auto_push": True,
+        "out_shift_right": False,
+        "in_shift_right": False,
+        "pull_threshold": bits,
+        "push_threshold": bits,
+        "wait_for_txstall": False,
+        "wrap_target": 8,
+    }
+    pio_instructions = adafruit_pioasm.assemble(pio_code)
+    i2s_clock = sample_rate * channels * bits
+    pio_clock = 4 * i2s_clock
+    pio = rp2pio.StateMachine(pio_instructions, **pio_params)
+    return pio
+
+
+def spaced_samples(length, bits):
+    max_int = (1 << bits) - 1
+    if length == 1:
+        return [0]
+    step = max_int / (length - 1)
+    result = [round(i * step) for i in range(length)]
+    result[0] = 0
+    result[-1] = max_int
+    return result
+
+
+while True:
+    print()
+    BITS = int(input("# bits per sample: "))
+    SAMPLE_RATE = int(input("#     sample rate: "))
+    CHANNELS = int(input("#        channels: "))
+    SAMPLE_SETS = int(input("#     sample sets: "))
+
+    n_samples = CHANNELS * SAMPLE_SETS
+    buffer_type = "L"
+    buffer_width = 32
+    data = [0] * CHANNELS + spaced_samples(n_samples, BITS) + [0] * CHANNELS
+    # initialize pio bit count top value by sending it at the start of output data
+    bit_count_top = BITS * (CHANNELS // 2) - 2
+    buffer_out = array.array(
+        buffer_type, [bit_count_top] + [d << (buffer_width - BITS) for d in data]
+    )
+    buffer_in = array.array(buffer_type, [0] * len(data))
+
+    PIO = i2s_codec(
+        channels=CHANNELS,
+        bits=BITS,
+        sample_rate=SAMPLE_RATE,
+        out_pin=board.D9,
+        in_pin=board.D10,
+        bclk_pin=board.D5,  # L/R signal will be one pin higher, i.e. D6
+    )
+    print()
+    print(f"# actual sample frequency {PIO.frequency/4/CHANNELS/BITS:9.1f} Hz")
+    print(f"#               bit clock {PIO.frequency/4:9.1f} Hz")
+    print()
+    PIO.write_readinto(buffer_out, buffer_in)
+    start = 0
+    line_length = CHANNELS
+
+    while start < len(buffer_in):
+        print("# write: ", end="")
+        for i in range(start, min(len(data), start + line_length)):
+            print(f"{data[i]:0{buffer_width/4}x} ", end=" ")
+        print()
+        print("#  read: ", end="")
+        for i in range(start, min(len(buffer_in), start + line_length)):
+            print(f"{buffer_in[i]:0{buffer_width/4}x} ", end=" ")
+        print()
+        print()
+        start += line_length
+    PIO.deinit()
+    del PIO

examples/pioasm_i2sout.py

@@ -5,9 +5,11 @@
 import array
 import math
 import time
+
 import board
 import digitalio
 import rp2pio
+
 import adafruit_pioasm
 
 trigger = digitalio.DigitalInOut(board.D4)

examples/pioasm_led_brightness.py

@@ -5,8 +5,10 @@
 # Adapted from the an example in Appendix C of RPi_PiPico_Digital_v10.pdf
 
 import time
+
 import board
 import rp2pio
+
 import adafruit_pioasm
 
 led_quarter_brightness = adafruit_pioasm.assemble(
@@ -30,20 +32,14 @@ led_full_brightness = adafruit_pioasm.assemble(
 )
 
 while True:
-    sm = rp2pio.StateMachine(
-        led_quarter_brightness, frequency=10000, first_set_pin=board.LED
-    )
+    sm = rp2pio.StateMachine(led_quarter_brightness, frequency=10000, first_set_pin=board.LED)
     time.sleep(1)
     sm.deinit()
 
-    sm = rp2pio.StateMachine(
-        led_half_brightness, frequency=10000, first_set_pin=board.LED
-    )
+    sm = rp2pio.StateMachine(led_half_brightness, frequency=10000, first_set_pin=board.LED)
     time.sleep(1)
     sm.deinit()
 
-    sm = rp2pio.StateMachine(
-        led_full_brightness, frequency=10000, first_set_pin=board.LED
-    )
+    sm = rp2pio.StateMachine(led_full_brightness, frequency=10000, first_set_pin=board.LED)
     time.sleep(1)
     sm.deinit()

examples/pioasm_neopixel.py

@@ -3,9 +3,11 @@
 # SPDX-License-Identifier: MIT
 
 import time
-import rp2pio
+
 import board
 import microcontroller
+import rp2pio
+
 import adafruit_pioasm
 
 # NeoPixels are 800khz bit streams. We are choosing zeros as <312ns hi, 936 lo>

examples/pioasm_neopixel_bg.py

@@ -23,8 +23,10 @@ pattern across all the LEDs.
 """
 
 import struct
+
 import adafruit_pixelbuf
 from rp2pio import StateMachine
+
 from adafruit_pioasm import Program
 
 # Pixel color order constants
@@ -66,12 +68,8 @@ wait_reset:
 )
 
 
-class NeoPixelBackground(  # pylint: disable=too-few-public-methods
-    adafruit_pixelbuf.PixelBuf
-):
-    def __init__(
-        self, pin, n, *, bpp=3, brightness=1.0, auto_write=True, pixel_order=None
-    ):
+class NeoPixelBackground(adafruit_pixelbuf.PixelBuf):
+    def __init__(self, pin, n, *, bpp=3, brightness=1.0, auto_write=True, pixel_order=None):
         if not pixel_order:
             pixel_order = GRB if bpp == 3 else GRBW
         elif isinstance(pixel_order, tuple):

examples/pioasm_pdm.py

@@ -4,9 +4,11 @@
 
 import array
 import time
+
 import board
 import digitalio
 import rp2pio
+
 import adafruit_pioasm
 
 trigger = digitalio.DigitalInOut(board.D4)

examples/pioasm_pulsegroup.py

@@ -8,13 +8,12 @@
 
 import array
 
+import adafruit_ticks
 import board
 import rp2pio
-import adafruit_ticks
 import ulab.numpy as np
 from adafruit_motor import servo
 
-
 import adafruit_pioasm
 
 _cycle_count = 3
@@ -73,7 +72,7 @@ class PulseItem:
     def _recalculate(self):
         self._turn_on = self._get_turn_on()
         self._turn_off = self._get_turn_off()
-        self._group._maybe_update()  # pylint: disable=protected-access
+        self._group._maybe_update()
 
     def _get_turn_on(self):
         maxval = self._maxval
@@ -104,7 +103,7 @@ class PulseGroup:
         maxval=65535,
         stagger=False,
         auto_update=True,
-    ):  # pylint: disable=too-many-arguments
+    ):
         """Create a pulse group with the given characteristics"""
         self._frequency = round(1 / period)
         pio_frequency = round((1 + maxval) * _cycle_count / period)
@@ -149,9 +148,9 @@ class PulseGroup:
         changes = {0: [0, 0]}
 
         for i in self._items:
-            turn_on = i._turn_on  # pylint: disable=protected-access
-            turn_off = i._turn_off  # pylint: disable=protected-access
-            mask = i._mask  # pylint: disable=protected-access
+            turn_on = i._turn_on
+            turn_off = i._turn_off
+            mask = i._mask
 
             if turn_on is not None:
                 this_change = changes.get(turn_on)

examples/pioasm_rotaryencoder.py

@@ -6,8 +6,10 @@
 # https://github.com/micropython/micropython/pull/6894/files
 
 import array
-import rp2pio
+
 import board
+import rp2pio
+
 import adafruit_pioasm
 
 
@@ -110,8 +112,6 @@ encoder = IncrementalEncoder(board.GP2, board.GP3)
 
 old_value = None
 while True:
-    gen()  # pylint: disable=undefined-variable
-
     value = encoder.value
     if old_value != value:
         print("Encoder:", value)

examples/pioasm_rp2350_fifo.py

@@ -0,0 +1,86 @@
+# SPDX-FileCopyrightText: 2024 Jeff Epler, written for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""A PIO demo that uses the FIFO in random access mode
+
+Random access mode is a new feature of the PIO peripheral of the RP2350.
+This demo is not compatible with the original RP2040 or Raspberry Pi
+Pico.
+
+Wiring:
+ * LED with current limiting resistor on GP25 (Pico 2 standard location)
+
+The LED will blink in several patterns depending on the values loaded in the 'rxfifo' registers
+"""
+
+import array
+import time
+
+import board
+import rp2pio
+
+import adafruit_pioasm
+
+program = adafruit_pioasm.Program(
+    """
+    .pio_version 1
+    .set 1
+    .fifo txget
+
+    ; LED on time taken from rxfifo[0]
+    mov osr, rxfifo[0]
+    mov x, osr
+
+    set pins, 1
+xloop1:
+    jmp x--, xloop1
+
+    ; LED off time taken from rxfifo[1]
+    mov osr, rxfifo[1]
+    mov x, osr
+
+    set pins, 0
+xloop2:
+    jmp x--, xloop2
+    """
+)
+
+
+def assign_uint32s(ar, off, *args):
+    """Assign multiple 32-bit registers within an AddressRange"""
+    vv = b"".join(v.to_bytes(4, "little") for v in args)
+    ar[off : off + 4 * len(args)] = vv
+
+
+print(program.pio_kwargs)
+sm = rp2pio.StateMachine(
+    program.assembled,
+    first_set_pin=board.GP25,
+    frequency=10_000_000,
+    **program.pio_kwargs,
+)
+fifo = sm.rxfifo
+
+# Set non-zero register entries & re-start the state machine at its offset.
+# this is needed because the default register value could represent a very long delay
+fifo[0:4] = b"\1\0\0\0"
+fifo[4:8] = b"\1\0\0\0"
+sm.run(array.array("H", [sm.offset]))
+
+while True:
+    # equal blinks
+    assign_uint32s(fifo, 0, 2000000, 2000000)
+    time.sleep(1)
+
+    # small on time
+    assign_uint32s(fifo, 0, 1000000, 3000000)
+    time.sleep(1)
+
+    # small off time
+    assign_uint32s(fifo, 0, 3000000, 1000000)
+    time.sleep(1)
+
+    # slower blinks
+    assign_uint32s(fifo, 0, 3000000, 3000000)
+    time.sleep(1)

examples/pioasm_rxuart.py

@@ -3,6 +3,7 @@
 # SPDX-License-Identifier: MIT
 
 import rp2pio
+
 import adafruit_pioasm
 
 code = adafruit_pioasm.assemble(
@@ -43,8 +44,8 @@ class RXUART:
         return self.pio.frequency // 8
 
     @baudrate.setter
-    def baudrate(self, frequency):  # pylint: disable=unused-argument
-        self.pio.frequency = freqency * 8  # pylint: disable=undefined-variable
+    def baudrate(self, frequency):
+        self.pio.frequency = freqency * 8
 
     @property
     def in_waiting(self):
@@ -55,5 +56,5 @@ class RXUART:
         n = self.pio.readinto(b)
         return b[:n]
 
-    def readinto(self, buf):  # pylint: disable=unused-argument
-        return self.pio.readinto(n)  # pylint: disable=undefined-variable
+    def readinto(self, buf):
+        return self.pio.readinto(n)

examples/pioasm_simpletest.py

@@ -3,8 +3,10 @@
 # SPDX-License-Identifier: MIT
 
 import time
-import rp2pio
+
 import board
+import rp2pio
+
 import adafruit_pioasm
 
 squarewave = """

examples/pioasm_txuart.py

@@ -3,6 +3,7 @@
 # SPDX-License-Identifier: MIT
 
 import rp2pio
+
 import adafruit_pioasm
 
 code = adafruit_pioasm.Program(

ruff.toml

@@ -0,0 +1,112 @@
+# SPDX-FileCopyrightText: 2024 Tim Cocks for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+target-version = "py38"
+line-length = 100
+
+[lint]
+preview = true
+select = ["I", "PL", "UP"]
+
+extend-select = [
+  "D419",  # empty-docstring
+  "E501",  # line-too-long
+  "W291",  # trailing-whitespace
+  "PLC0414",  # useless-import-alias
+  "PLC2401",  # non-ascii-name
+  "PLC2801",  # unnecessary-dunder-call
+  "PLC3002",  # unnecessary-direct-lambda-call
+  "E999",  # syntax-error
+  "PLE0101",  # return-in-init
+  "F706",  # return-outside-function
+  "F704",  # yield-outside-function
+  "PLE0116",  # continue-in-finally
+  "PLE0117",  # nonlocal-without-binding
+  "PLE0241",  # duplicate-bases
+  "PLE0302",  # unexpected-special-method-signature
+  "PLE0604",  # invalid-all-object
+  "PLE0605",  # invalid-all-format
+  "PLE0643",  # potential-index-error
+  "PLE0704",  # misplaced-bare-raise
+  "PLE1141",  # dict-iter-missing-items
+  "PLE1142",  # await-outside-async
+  "PLE1205",  # logging-too-many-args
+  "PLE1206",  # logging-too-few-args
+  "PLE1307",  # bad-string-format-type
+  "PLE1310",  # bad-str-strip-call
+  "PLE1507",  # invalid-envvar-value
+  "PLE2502",  # bidirectional-unicode
+  "PLE2510",  # invalid-character-backspace
+  "PLE2512",  # invalid-character-sub
+  "PLE2513",  # invalid-character-esc
+  "PLE2514",  # invalid-character-nul
+  "PLE2515",  # invalid-character-zero-width-space
+  "PLR0124",  # comparison-with-itself
+  "PLR0202",  # no-classmethod-decorator
+  "PLR0203",  # no-staticmethod-decorator
+  "UP004",  # useless-object-inheritance
+  "PLR0206",  # property-with-parameters
+  "PLR0904",  # too-many-public-methods
+  "PLR0911",  # too-many-return-statements
+  "PLR0912",  # too-many-branches
+  "PLR0913",  # too-many-arguments
+  "PLR0914",  # too-many-locals
+  "PLR0915",  # too-many-statements
+  "PLR0916",  # too-many-boolean-expressions
+  "PLR1702",  # too-many-nested-blocks
+  "PLR1704",  # redefined-argument-from-local
+  "PLR1711",  # useless-return
+  "C416",  # unnecessary-comprehension
+  "PLR1733",  # unnecessary-dict-index-lookup
+  "PLR1736",  # unnecessary-list-index-lookup
+
+  # ruff reports this rule is unstable
+  #"PLR6301",  # no-self-use
+
+  "PLW0108",  # unnecessary-lambda
+  "PLW0120",  # useless-else-on-loop
+  "PLW0127",  # self-assigning-variable
+  "PLW0129",  # assert-on-string-literal
+  "B033",  # duplicate-value
+  "PLW0131",  # named-expr-without-context
+  "PLW0245",  # super-without-brackets
+  "PLW0406",  # import-self
+  "PLW0602",  # global-variable-not-assigned
+  "PLW0603",  # global-statement
+  "PLW0604",  # global-at-module-level
+
+  # fails on the try: import typing used by libraries
+  #"F401",  # unused-import
+
+  "F841",  # unused-variable
+  "E722",  # bare-except
+  "PLW0711",  # binary-op-exception
+  "PLW1501",  # bad-open-mode
+  "PLW1508",  # invalid-envvar-default
+  "PLW1509",  # subprocess-popen-preexec-fn
+  "PLW2101",  # useless-with-lock
+  "PLW3301",  # nested-min-max
+]
+
+ignore = [
+    "PLR2004", # magic-value-comparison
+    "UP030", # format literals
+    "PLW1514",  # unspecified-encoding
+    "PLR0913", # too-many-arguments
+    "PLR0915", # too-many-statements
+    "PLR0917", # too-many-positional-arguments
+    "PLR0904", # too-many-public-methods
+    "PLR0912", # too-many-branches
+    "PLR0916", # too-many-boolean-expressions
+    "PLR6301", # could-be-static no-self-use
+    "PLC0415", # import outside toplevel
+    "PLC2701", # private import
+    "PLW2901", # loop var overwrite
+    "PLR1702", # too many nested blocks
+    "PLR1714", # multiple comparisons
+    "PLR0914", # too many local vars
+]
+
+[format]
+line-ending = "lf"

tests/pytest_helpers.py

@@ -45,4 +45,6 @@ def assert_assembly_fails(
 
 def assert_pio_kwargs(source: str, **kw: Any) -> None:
     program = adafruit_pioasm.Program(source)
-    assert kw == program.pio_kwargs
+    assert (
+        kw == program.pio_kwargs
+    ), f"Assembling {source!r}: Expected {kw}, got {program.pio_kwargs}"

tests/test_all.py

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2024 Jeff Epler, written for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+import all_pio_instructions
+import pytest
+from pytest_helpers import assert_assembles_to
+
+
+def _assert_one(expected, instruction_in, fifo="putget"):
+    program = f"""
+        .program all_pio
+        .pio_version 1
+        .fifo {fifo}
+        {instruction_in}
+        """
+    assert_assembles_to(program, [expected])
+
+
+def assert_one(expected, instruction_in):
+    if isinstance(instruction_in, str):
+        return _assert_one(expected, instruction_in)
+    return _assert_one(expected, instruction_in[0], **instruction_in[1])
+
+
+@pytest.mark.parametrize("arg", all_pio_instructions.all_instruction.items())
+def test_all(arg):
+    expected = arg[0]
+    instruction = arg[1]
+    assert_one(expected, instruction)

tests/test_in.py

@@ -58,12 +58,8 @@ def test_in_delay_with_sideset() -> None:
 
 
 def test_in_bad_source() -> None:
-    assert_assembly_fails(
-        "in bad, 17", match="Invalid in source 'bad'", errtype=ValueError
-    )
+    assert_assembly_fails("in bad, 17", match="Invalid in source 'bad'", errtype=ValueError)
 
 
 def test_in_bad_bitcount() -> None:
-    assert_assembly_fails(
-        "in pins, 0", match="Count out of range", errtype=RuntimeError
-    )
+    assert_assembly_fails("in pins, 0", match="Count out of range", errtype=RuntimeError)

tests/test_label.py

@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: 2024 Jeff Epler for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Tests out
+"""
+
+from pytest_helpers import assert_assembly_fails
+
+import adafruit_pioasm
+
+
+def test_label() -> None:
+    source = [
+        "    jmp label1",
+        "label1:",
+        "    jmp label2",
+        "public label2:",
+        "    nop",
+    ]
+    program = adafruit_pioasm.Program("\n".join(source))
+    assert program.public_labels == {"label2": 2}
+
+    # Test each combination of public/privagte label duplication
+    source = [
+        "label1:\n",
+        "nop\n",
+        "public label1:\n",
+        "nop\n",
+    ]
+    assert_assembly_fails("\n".join(source), match="Duplicate label", errtype=SyntaxError)
+
+    source = [
+        "label1:\n",
+        "    nop\n",
+        "label1:\n",
+        "    nop\n",
+    ]
+    assert_assembly_fails("\n".join(source), match="Duplicate label", errtype=SyntaxError)
+
+    source = [
+        "public label1:\n",
+        "    nop\n",
+        "label1:\n",
+        "    nop\n",
+    ]
+    assert_assembly_fails("\n".join(source), match="Duplicate label", errtype=SyntaxError)
+
+    source = [
+        "public label1:\n",
+        "    nop\n",
+        "public label1:\n",
+        "    nop\n",
+    ]
+    assert_assembly_fails("\n".join(source), match="Duplicate label", errtype=SyntaxError)

tests/test_misc.py

@@ -28,12 +28,8 @@ def test_invalid_sideset() -> None:
 
 
 def test_invalid_delay() -> None:
-    assert_assembly_fails(
-        "[5]", match=r"Unknown instruction: \[5\]", errtype=RuntimeError
-    )
+    assert_assembly_fails("[5]", match=r"Unknown instruction: \[5\]", errtype=RuntimeError)
 
 
 def test_invalid_instruction() -> None:
-    assert_assembly_fails(
-        "bad", match=r"Unknown instruction: bad", errtype=RuntimeError
-    )
+    assert_assembly_fails("bad", match=r"Unknown instruction: bad", errtype=RuntimeError)

tests/test_mov.py

@@ -11,9 +11,7 @@ from pytest_helpers import assert_assembles_to, assert_assembly_fails
 
 def test_mov_non_happy() -> None:
     # non happy path
-    assert_assembly_fails(
-        "mov x, blah", match="Invalid mov source 'blah'", errtype=ValueError
-    )
+    assert_assembly_fails("mov x, blah", match="Invalid mov source 'blah'", errtype=ValueError)
 
 
 def test_mov_invert() -> None:

tests/test_nop.py

@@ -34,9 +34,7 @@ def test_sideset_opt() -> None:
 
 def test_set() -> None:
     # non happy path
-    assert_assembly_fails(
-        "set isr, 1", match="Invalid set destination 'isr'", errtype=ValueError
-    )
+    assert_assembly_fails("set isr, 1", match="Invalid set destination 'isr'", errtype=ValueError)
 
 
 def test_jmp() -> None:

tests/test_out.py

@@ -60,12 +60,8 @@ def test_out_delay_with_sideset() -> None:
 
 
 def test_out_bad_destination() -> None:
-    assert_assembly_fails(
-        "out bad, 17", match="Invalid out destination 'bad'", errtype=ValueError
-    )
+    assert_assembly_fails("out bad, 17", match="Invalid out destination 'bad'", errtype=ValueError)
 
 
 def test_out_bad_bitcount() -> None:
-    assert_assembly_fails(
-        "out pins, 0", match="Count out of range", errtype=RuntimeError
-    )
+    assert_assembly_fails("out pins, 0", match="Count out of range", errtype=RuntimeError)

tests/test_print_c_program.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: 2025 Jeff Epler, written for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+import contextlib
+import io
+
+import adafruit_pioasm
+
+
+def test_print_c_program():
+    output = io.StringIO()
+    with contextlib.redirect_stdout(output):
+        adafruit_pioasm.Program(".side_set 1 opt").print_c_program("mood")
+    c_program = output.getvalue()
+    assert "True" not in c_program
+    assert "sideset_enable = 1" in c_program

tests/test_pseudo.py

@@ -6,8 +6,26 @@
 Tests pseudo-ops
 """
 
-from pytest_helpers import assert_pio_kwargs
+from pytest_helpers import assert_assembly_fails, assert_pio_kwargs
 
 
 def test_offset() -> None:
     assert_pio_kwargs(".origin 7", offset=7, sideset_enable=False)
+    assert_assembly_fails("nop\n.origin 7")
+
+
+def test_sideset_pindirs() -> None:
+    assert_pio_kwargs(
+        ".side_set 2 opt pindirs",
+        sideset_pin_count=2,
+        sideset_enable=True,
+        sideset_pindirs=True,
+    )
+    assert_pio_kwargs(
+        ".side_set 2 pindirs",
+        sideset_pin_count=2,
+        sideset_enable=False,
+        sideset_pindirs=True,
+    )
+    # Setting not emitted (as =False) for backwards compat
+    assert_pio_kwargs(".side_set 2", sideset_pin_count=2, sideset_enable=False)

tests/test_version.py

@@ -0,0 +1,146 @@
+# SPDX-FileCopyrightText: 2024 Jeff Epler, written for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Tests version dependent instructions
+"""
+
+from pytest_helpers import assert_assembles_to, assert_assembly_fails, assert_pio_kwargs
+
+
+def test_version() -> None:
+    assert_pio_kwargs(".pio_version 0", sideset_enable=0)
+    assert_pio_kwargs(".pio_version 1", pio_version=1, sideset_enable=0)
+    assert_assembly_fails(".pio_version muffin", errtype=ValueError)
+    assert_assembly_fails(".pio_version -1")
+
+
+def test_fifo() -> None:
+    assert_pio_kwargs(".fifo txrx", sideset_enable=0, fifo_type="txrx")
+    assert_pio_kwargs(".fifo auto", sideset_enable=0)
+    assert_assembly_fails(".fifo txput")
+    assert_pio_kwargs(
+        ".pio_version 1\n.fifo txput",
+        pio_version=1,
+        sideset_enable=0,
+        fifo_type="txput",
+    )
+
+
+def test_mov_status() -> None:
+    assert_pio_kwargs(
+        ".mov_status txfifo < 5",
+        sideset_enable=0,
+        mov_status_type="txfifo",
+        mov_status_n=5,
+    )
+    assert_pio_kwargs(
+        ".mov_status rxfifo < 8",
+        sideset_enable=0,
+        mov_status_type="rxfifo",
+        mov_status_n=8,
+    )
+    assert_assembly_fails(".mov_status rxfifo < -1")
+    assert_assembly_fails(".mov_status rxfifo < 33")
+    assert_assembly_fails(".mov_status irq next set 3")
+    assert_pio_kwargs(
+        ".pio_version 1\n.mov_status irq prev set 3",
+        pio_version=1,
+        sideset_enable=0,
+        mov_status_type="irq",
+        mov_status_n=3 | 0x8,
+    )
+    assert_pio_kwargs(
+        ".pio_version 1\n.mov_status irq next set 3",
+        pio_version=1,
+        sideset_enable=0,
+        mov_status_type="irq",
+        mov_status_n=3 | 0x10,
+    )
+    assert_pio_kwargs(
+        ".pio_version 1\n.mov_status irq set 3",
+        pio_version=1,
+        sideset_enable=0,
+        mov_status_type="irq",
+        mov_status_n=3,
+    )
+    assert_assembly_fails(".pio_version 1\n.mov_status irq prev set 9")
+
+
+def test_dot_in() -> None:
+    assert_pio_kwargs(
+        ".in 32 left auto 11",
+        sideset_enable=0,
+        auto_push=True,
+        push_threshold=11,
+        in_shift_right=False,
+    )
+    assert_assembly_fails(".in 16")
+    assert_pio_kwargs(
+        ".pio_version 1\n.in 16 right",
+        pio_version=1,
+        sideset_enable=0,
+        in_pin_count=16,
+        auto_push=False,
+        in_shift_right=True,
+    )
+
+
+def test_dot_out() -> None:
+    assert_pio_kwargs(
+        ".out 32 left auto 11",
+        sideset_enable=0,
+        auto_pull=True,
+        pull_threshold=11,
+        out_shift_right=False,
+    )
+    assert_pio_kwargs(
+        ".out 16 right",
+        sideset_enable=0,
+        out_pin_count=16,
+        auto_pull=False,
+        out_shift_right=True,
+    )
+
+
+def test_dot_set() -> None:
+    assert_pio_kwargs(".set 5", sideset_enable=0, set_pin_count=5)
+    assert_assembly_fails(".set 16")
+    assert_assembly_fails(".pio_version 1\n.set 16")
+    assert_assembly_fails(".set 3")
+    assert_pio_kwargs(
+        ".pio_version 1\n.set 3 right", pio_version=1, sideset_enable=0, set_pin_count=3
+    )
+
+
+def test_irq_v1() -> None:
+    assert_assembly_fails("irq next 7")
+    assert_assembly_fails(".pio_version 1\nirq next 7 rel")
+    assert_assembles_to(".pio_version 1\nirq next 5", [0b110_00000_0_0_0_11_101])
+    assert_assembles_to(".pio_version 1\nirq wait prev 1", [0b110_00000_0_0_1_01_001])
+
+
+def test_mov_v1() -> None:
+    assert_assembly_fails("mov osr, rxfifo[y]")
+    assert_assembly_fails(".pio_version 1\nmov osr, rxfifo[y]")
+    prefix = ".pio_version 1\n.fifo putget\n"
+    assert_assembly_fails(prefix + "mov osr, rxfifo[8]")
+    assert_assembles_to(prefix + "mov rxfifo[y], isr", [0b100_00000_0001_0_000])
+    assert_assembles_to(prefix + "mov osr, rxfifo[1]", [0b100_00000_1001_1_001])
+
+    assert_assembly_fails("mov pindirs, null", errtype=ValueError)
+    assert_assembles_to(prefix + "mov pindirs, null", [0b101_00000_01100011])
+
+
+def test_wait_v1() -> None:
+    assert_assembly_fails("wait 0 jmppin")
+    assert_assembly_fails("wait 0 irq next 5")
+    prefix = ".pio_version 1\n"
+    assert_assembly_fails(prefix + "wait 0 jmppin +")
+    assert_assembly_fails(prefix + "wait 0 jmppin + 7")
+    assert_assembles_to(prefix + "wait 0 jmppin + 3", [0b001_00000_0_11_00011])
+    assert_assembles_to(prefix + "wait 1 jmppin", [0b001_00000_1_11_00000])
+
+    assert_assembles_to(prefix + "wait 0 irq next 5", [0b001_00000_0_10_11_101])
+    assert_assembles_to(prefix + "wait 1 irq prev 4", [0b001_00000_1_10_01_100])

tools/make_all.py

@@ -0,0 +1,128 @@
+# SPDX-FileCopyrightText: 2024 Jeff Epler, written for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+
+"""
+Generate test cases for adafruit_pioasm, with expected results from sdk pioasm
+"""
+
+import re
+from subprocess import check_output
+
+PIOASM = "/home/jepler/src/circuitpython/ports/raspberrypi/sdk/tools/pioasm/build/pioasm"
+
+
+def assemble_one_instruction(instruction_in):
+    if isinstance(instruction_in, str):
+        return _assemble_one_instruction(instruction_in)
+    return _assemble_one_instruction(instruction_in[0], **instruction_in[1])
+
+
+def _assemble_one_instruction(instruction_in, fifo="putget"):
+    nops = "\n".join("nop" for _ in range(31))
+    program = f"""
+        .program all_pio
+        .pio_version 1
+        .fifo {fifo}
+        {instruction_in}
+        {nops}
+        """
+    output = check_output([PIOASM, "/dev/stdin", "/dev/stdout"], input=program, encoding="utf-8")
+    return int(re.search("0x[0-9a-f]{4}", output).group(0), 16)
+
+
+def all_jmp():
+    for i in range(32):
+        yield f"jmp {i}"
+        for cond in "!x", "x--", "!y", "y--", "x!=y", "pin", "!osre":
+            yield f"jmp {cond} {i}"
+
+
+def all_wait():
+    for polarity in range(2):
+        yield f"wait {polarity} jmppin"
+        for source in "gpio", "pin":
+            for i in range(32):
+                yield f"wait {polarity} {source} {i}"
+        for i in range(8):
+            yield f"wait {polarity} irq {i} rel"
+            for what in "prev", "next":
+                yield f"wait {polarity} irq {what} {i}"
+        for i in range(1, 4):
+            yield f"wait {polarity} jmppin + {i}"
+
+
+def all_in():
+    for source in "pins", "x", "y", "null", "isr", "osr":
+        for bit_count in range(1, 33):
+            yield f"in {source} {bit_count}"
+
+
+def all_out():
+    for dest in "pins", "x", "y", "null", "pindirs", "pc", "isr", "exec":
+        for bit_count in range(1, 33):
+            yield f"out {dest} {bit_count}"
+
+
+def all_push():
+    yield "push", {"fifo": "txrx"}
+    yield "push iffull block", {"fifo": "txrx"}
+    yield "push iffull noblock", {"fifo": "txrx"}
+
+
+def all_pull():
+    yield "pull", {"fifo": "txrx"}
+    yield "pull ifempty block", {"fifo": "txrx"}
+    yield "pull ifempty noblock", {"fifo": "txrx"}
+
+
+def all_mov():
+    for dest in ("pins", "x", "y", "pindirs", "exec", "pc", "isr", "osr"):
+        for source in ("pins", "x", "y", "null", "status", "isr", "osr"):
+            for operator in "", "~", "::":
+                yield f"mov {dest} {operator}{source}"
+    for where in 0, 1, 2, 3, "y":
+        yield f"mov rxfifo[{where}], isr"
+        yield f"mov osr, rxfifo[{where}]"
+
+
+def all_irq():
+    for i in range(8):
+        yield f"irq {i}"
+        yield f"irq {i} rel"
+        for what in "prev", "next":
+            yield f"irq {what} {i}"
+
+
+def all_set():
+    for dest in ("pins", "x", "y", "pindirs"):
+        for i in range(32):
+            yield f"set {dest} {i}"
+
+
+def all_instructions():
+    yield from all_jmp()
+    yield from all_wait()
+    yield from all_in()
+    yield from all_out()
+    yield from all_push()
+    yield from all_pull()
+    yield from all_mov()
+    yield from all_irq()
+    yield from all_set()
+
+
+if __name__ == "__main__":
+    print(
+        """\
+# SPDX-FileCopyrightText: 2024 Jeff Epler, written for Adafruit Industries
+#
+# SPDX-License-Identifier: MIT
+# fmt: off
+"""
+    )
+    print("all_instruction = {")
+    for instr in all_instructions():
+        assembled = assemble_one_instruction(instr)
+        print(f"    {assembled}: {instr!r},")
+    print("}")