Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
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>
- Loading branch information
Showing
6 changed files
with
359 additions
and
2 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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`. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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`. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 | ||
This comment has been minimized.
Sorry, something went wrong.
This comment has been minimized.
Sorry, something went wrong. |
||
`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 |
Typo:
overriden -> overridden