docs/library: Add initial API reference for rp2 module and its classes.

All the method signatures from rp2_pio.c and friends have been taken and converted to RST format, then explanatory notes added for each signature. Signed-off-by: Tim Radvan <tim@tjvr.org>
4 years ago · fd24e649fd
6 changed files with 359 additions and 2 deletions
--- a/docs/library/index.rst
+++ b/docs/library/index.rst
@ -165,3 +165,14 @@ The following libraries are specific to the ESP8266 and ESP32.

  esp.rst
  esp32.rst
+
+
+Libraries specific to the RP2040
+--------------------------------
+
+The following libraries are specific to the RP2040, as used in the Raspberry Pi Pico.
+
+.. toctree::
+  :maxdepth: 2
+
+  rp2.rst
--- a/docs/library/machine.rst
+++ b/docs/library/machine.rst
@ -64,9 +64,11 @@ Interrupt related functions
 Power related functions
 -----------------------

-.. function:: freq()
+.. function:: freq([hz])

-    Returns CPU frequency in hertz.
+    Returns the CPU frequency in hertz.
+
+    On some ports this can also be used to set the CPU frequency by passing in *hz*.

 .. function:: idle()

--- a/docs/library/rp2.Flash.rst
+++ b/docs/library/rp2.Flash.rst
@ -0,0 +1,36 @@
+.. currentmodule:: rp2
+.. _rp2.Flash:
+
+class Flash -- access to built-in flash storage
+===============================================
+
+This class gives access to the SPI flash memory.
+
+In most cases, to store persistent data on the device, you'll want to use a
+higher-level abstraction, for example the filesystem via Python's standard file
+API, but this interface is useful to :ref:`customise the filesystem
+configuration <filesystem>` or implement a low-level storage system for your
+application.
+
+
+Constructors
+------------
+
+.. class:: Flash()
+
+   Gets the singleton object for accessing the SPI flash memory.
+
+
+Methods
+-------
+
+.. method:: Flash.readblocks(block_num, buf)
+            Flash.readblocks(block_num, buf, offset)
+.. method:: Flash.writeblocks(block_num, buf)
+            Flash.writeblocks(block_num, buf, offset)
+.. method:: Flash.ioctl(cmd, arg)
+
+    These methods implement the simple and extended
+    :ref:`block protocol <block-device-interface>` defined by
+    :class:`uos.AbstractBlockDev`.
+
--- a/docs/library/rp2.PIO.rst
+++ b/docs/library/rp2.PIO.rst
@ -0,0 +1,94 @@
+.. currentmodule:: rp2
+.. _rp2.PIO:
+
+class PIO -- advanced PIO usage
+===============================
+
+The :class:`PIO` class gives access to an instance of the RP2040's PIO
+(programmable I/O) interface.
+
+The preferred way to interact with PIO is using :class:`rp2.StateMachine`, the
+PIO class is for advanced use.
+
+For assembling PIO programs, see :func:`rp2.asm_pio`.
+
+
+Constructors
+------------
+
+.. class:: PIO(id)
+
+    Gets the PIO instance numbered *id*. The RP2040 has two PIO instances,
+    numbered 0 and 1.
+
+    Raises a ``ValueError`` if any other argument is provided.
+
+
+Methods
+-------
+
+.. method:: PIO.add_program(program)
+
+    Add the *program* to the instruction memory of this PIO instance.
+
+    The amount of memory available for programs on each PIO instance is
+    limited. If there isn't enough space left in the PIO's program memory
+    this method will raise ``OSError(ENOMEM)``.
+
+.. method:: PIO.remove_program([program])
+
+    Remove *program* from the instruction memory of this PIO instance.
+
+    If no program is provided, it removes all programs.
+
+    It is not an error to remove a program which has already been removed.
+
+.. method:: PIO.state_machine(id, [program, ...])
+
+    Gets the state machine numbered *id*. On the RP2040, each PIO instance has
+    four state machines, numbered 0 to 3.
+
+    Optionally initialize it with a *program*: see `StateMachine.init`.
+
+    >>> rp2.PIO(1).state_machine(3)
+    StateMachine(7)
+
+.. method:: PIO.irq(handler=None, trigger=IRQ_SM0|IRQ_SM1|IRQ_SM2|IRQ_SM3, hard=False)
+
+    Returns the IRQ object for this PIO instance.
+
+    MicroPython only uses IRQ 0 on each PIO instance. IRQ 1 is not available.
+
+    Optionally configure it.
+
+
+Constants
+---------
+
+.. data:: PIO.IN_LOW
+          PIO.IN_HIGH
+          PIO.OUT_LOW
+          PIO.OUT_HIGH
+
+    These constants are used for the *out_init*, *set_init*, and *sideset_init*
+    arguments to `asm_pio`.
+
+.. data:: PIO.SHIFT_LEFT
+          PIO.SHIFT_RIGHT
+
+    These constants are used for the *in_shiftdir* and *out_shiftdir* arguments
+    to `asm_pio` or `StateMachine.init`.
+
+.. data:: PIO.JOIN_NONE
+          PIO.JOIN_TX
+          PIO.JOIN_RX
+
+    These constants are used for the *fifo_join* argument to `asm_pio`.
+
+.. data:: PIO.IRQ_SM0
+          PIO.IRQ_SM1
+          PIO.IRQ_SM2
+          PIO.IRQ_SM3
+
+    These constants are used for the *trigger* argument to `PIO.irq`.
+
--- a/docs/library/rp2.StateMachine.rst
+++ b/docs/library/rp2.StateMachine.rst
@ -0,0 +1,131 @@
+.. currentmodule:: rp2
+.. _rp2.StateMachine:
+
+class StateMachine -- access to the RP2040's programmable I/O interface
+=======================================================================
+
+The :class:`StateMachine` class gives access to the RP2040's PIO (programmable
+I/O) interface.
+
+For assembling PIO programs, see :func:`rp2.asm_pio`.
+
+
+Constructors
+------------
+
+.. class:: StateMachine(id, [program, ...])
+
+    Get the state machine numbered *id*. The RP2040 has two identical PIO
+    instances, each with 4 state machines: so there are 8 state machines in
+    total, numbered 0 to 7.
+
+    Optionally initialize it with the given program *program*: see
+    `StateMachine.init`.
+
+
+Methods
+-------
+
+.. method:: StateMachine.init(program, freq=-1, *, in_base=None, out_base=None, set_base=None, jmp_pin=None, sideset_base=None, in_shiftdir=None, out_shiftdir=None, push_thresh=None, pull_thresh=None)
+
+    Configure the state machine instance to run the given *program*.
+
+    The program is added to the instruction memory of this PIO instance. If the
+    instruction memory already contains this program, then its offset is
+    re-used so as to save on instruction memory.
+
+    - *freq* is the frequency in Hz to run the state machine at. Defaults to
+      the system clock frequency.
+
+      The clock divider is computed as ``system clock frequency / freq``, so
+      there can be slight rounding errors.
+
+      The minimum possible clock divider is one 65536th of the system clock: so
+      at the default system clock frequency of 125MHz, the minimum value of
+      *freq* is ``1908``. To run state machines at slower frequencies, you'll
+      need to reduce the system clock speed with `machine.freq()`.
+    - *in_base* is the first pin to use for ``in()`` instructions.
+    - *out_base* is the first pin to use for ``out()`` instructions.
+    - *set_base* is the first pin to use for ``set()`` instructions.
+    - *jmp_pin* is the first pin to use for ``jmp(pin, ...)`` instructions.
+    - *sideset_base* is the first pin to use for side-setting.
+    - *in_shiftdir* is the direction the ISR will shift, either
+      `PIO.SHIFT_LEFT` or `PIO.SHIFT_RIGHT`.
+    - *out_shiftdir* is the direction the OSR will shift, either
+      `PIO.SHIFT_LEFT` or `PIO.SHIFT_RIGHT`.
+    - *push_thresh* is the threshold in bits before auto-push or conditional
+      re-pushing is triggered.
+    - *pull_thresh* is the threshold in bits before auto-push or conditional
+      re-pushing is triggered.
+
+.. method:: StateMachine.active([value])
+
+    Gets or sets whether the state machine is currently running.
+
+    >>> sm.active()
+    True
+    >>> sm.active(0)
+    False
+
+.. method:: StateMachine.restart()
+
+    Restarts the state machine and jumps to the beginning of the program.
+
+    This method clears the state machine's internal state using the RP2040's
+    ``SM_RESTART`` register. This includes:
+
+     - input and output shift counters
+     - the contents of the input shift register
+     - the delay counter
+     - the waiting-on-IRQ state
+     - a stalled instruction run using `StateMachine.exec()`
+
+.. method:: StateMachine.exec(instr)
+
+    Execute a single PIO instruction. Uses `asm_pio_encode` to encode the
+    instruction from the given string *instr*.
+
+    >>> sm.exec("set(0, 1)")
+
+.. method:: StateMachine.get(buf=None, shift=0)
+
+    Pull a word from the state machine's RX FIFO.
+
+    If the FIFO is empty, it blocks until data arrives (i.e. the state machine
+    pushes a word).
+
+    The value is shifted right by *shift* bits before returning, i.e. the
+    return value is ``word >> shift``.
+
+.. method:: StateMachine.put(value, shift=0)
+
+    Push a word onto the state machine's TX FIFO.
+
+    If the FIFO is full, it blocks until there is space (i.e. the state machine
+    pulls a word).
+
+    The value is first shifted left by *shift* bits, i.e. the state machine
+    receives ``value << shift``.
+
+.. method:: StateMachine.rx_fifo()
+
+    Returns the number of words in the state machine's RX FIFO. A value of 0
+    indicates the FIFO is empty.
+
+    Useful for checking if data is waiting to be read, before calling
+    `StateMachine.get()`.
+
+.. method:: StateMachine.tx_fifo()
+
+    Returns the number of words in the state machine's TX FIFO. A value of 0
+    indicates the FIFO is empty.
+
+    Useful for checking if there is space to push another word using
+    `StateMachine.put()`.
+
+.. method:: StateMachine.irq(handler=None, trigger=0|1, hard=False)
+
+     Returns the IRQ object for the given StateMachine.
+
+     Optionally configure it.
+
--- a/docs/library/rp2.rst
+++ b/docs/library/rp2.rst
@ -0,0 +1,83 @@
+.. currentmodule:: rp2
+
+:mod:`rp2` --- functionality specific to the RP2040
+===================================================
+
+.. module:: rp2
+    :synopsis: functionality specific to the RP2
+
+The ``rp2`` module contains functions and classes specific to the RP2040, as
+used in the Raspberry Pi Pico.
+
+See the `RP2040 Python datasheet
+<https://datasheets.raspberrypi.org/pico/raspberry-pi-pico-python-sdk.pdf>`_
+for more information, and `pico-micropython-examples
+<https://github.com/raspberrypi/pico-micropython-examples/tree/master/pio>`_
+for example code.
+
+
+PIO related functions
+---------------------
+
+The ``rp2`` module includes functions for assembling PIO programs.
+
+For running PIO programs, see :class:`rp2.StateMachine`.
+
+.. function:: asm_pio(*, out_init=None, set_init=None, sideset_init=None, in_shiftdir=0, out_shiftdir=0, autopush=False, autopull=False, push_thresh=32, pull_thresh=32, fifo_join=PIO.JOIN_NONE)
+
+    Assemble a PIO program.
+
+    The following parameters control the initial state of the GPIO pins, as one
+    of `PIO.IN_LOW`, `PIO.IN_HIGH`, `PIO.OUT_LOW` or `PIO.OUT_HIGH`. If the
+    program uses more than one pin, provide a tuple, e.g.
+    ``out_init=(PIO.OUT_LOW, PIO.OUT_LOW)``.
+
+    - *out_init* configures the pins used for ``out()`` instructions.
+    - *set_init* configures the pins used for ``set()`` instructions. There can
+      be at most 5.
+    - *sideset_init* configures the pins used side-setting. There can be at
+      most 5.
+
+    The following parameters are used by default, but can be overriden in
+    `StateMachine.init()`:
+
+    - *in_shiftdir* is the default direction the ISR will shift, either
+      `PIO.SHIFT_LEFT` or `PIO.SHIFT_RIGHT`.
+    - *out_shiftdir* is the default direction the OSR will shift, either
+      `PIO.SHIFT_LEFT` or `PIO.SHIFT_RIGHT`.
+    - *push_thresh* is the threshold in bits before auto-push or conditional
+      re-pushing is triggered.
+    - *pull_thresh* is the threshold in bits before auto-push or conditional
+      re-pushing is triggered.
+
+    The remaining parameters are:
+
+    - *autopush* configures whether auto-push is enabled.
+    - *autopull* configures whether auto-pull is enabled.
+    - *fifo_join* configures whether the 4-word TX and RX FIFOs should be
+      combined into a single 8-word FIFO for one direction only. The options
+      are `PIO.JOIN_NONE`, `PIO.JOIN_RX` and `PIO.JOIN_TX`.
+
+.. function:: asm_pio_encode(instr, sideset_count)
+
+    Assemble a single PIO instruction. You usually want to use `asm_pio()`
+    instead.
+
+    >>> rp2.asm_pio_encode("set(0, 1)", 0)
+    57345
+
+.. class:: PIOASMError
+
+    This exception is raised from `asm_pio()` or `asm_pio_encode()` if there is
+    an error assembling a PIO program.
+
+
+Classes
+-------
+
+.. toctree::
+    :maxdepth: 1
+
+    rp2.Flash.rst
+    rp2.PIO.rst
+    rp2.StateMachine.rst