1 /*
2  * Copyright (c) 2020 Raspberry Pi (Trading) Ltd.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  */
6 
7 #ifndef _HARDWARE_PIO_H
8 #define _HARDWARE_PIO_H
9 
10 #include "pico.h"
11 #include "hardware/address_mapped.h"
12 #include "hardware/structs/pio.h"
13 #include "hardware/gpio.h"
14 #include "hardware/regs/dreq.h"
15 #include "hardware/pio_instructions.h"
16 
17 // PICO_CONFIG: PARAM_ASSERTIONS_ENABLED_HARDWARE_PIO, Enable/disable assertions in the hardware_pio module, type=bool, default=0, group=hardware_pio
18 #ifndef PARAM_ASSERTIONS_ENABLED_HARDWARE_PIO
19 #ifdef PARAM_ASSERTIONS_ENABLED_PIO // backwards compatibility with SDK < 2.0.0
20 #define PARAM_ASSERTIONS_ENABLED_HARDWARE_PIO PARAM_ASSERTIONS_ENABLED_PIO
21 #else
22 #define PARAM_ASSERTIONS_ENABLED_HARDWARE_PIO 0
23 #endif
24 #endif
25 
26 // PICO_CONFIG: PICO_PIO_VERSION, PIO hardware version, type=int, default=0 on RP2040 and 1 on RP2350, group=hardware_pio
27 #ifndef PICO_PIO_VERSION
28 #if PIO_GPIOBASE_BITS
29 #define PICO_PIO_VERSION 1
30 #else
31 #define PICO_PIO_VERSION 0
32 #endif
33 #endif
34 
35 // PICO_CONFIG: PICO_PIO_CLKDIV_ROUND_NEAREST, True if floating point PIO clock divisors should be rounded to the nearest possible clock divisor rather than rounding down, type=bool, default=PICO_CLKDIV_ROUND_NEAREST, group=hardware_pio
36 #ifndef PICO_PIO_CLKDIV_ROUND_NEAREST
37 #define PICO_PIO_CLKDIV_ROUND_NEAREST PICO_CLKDIV_ROUND_NEAREST
38 #endif
39 
40 /** \file hardware/pio.h
41  *  \defgroup hardware_pio hardware_pio
42  *
43  * \brief Programmable I/O (PIO) API
44  *
45  * A programmable input/output block (PIO) is a versatile hardware interface which
46  * can support a number of different IO standards.
47  *
48  * \if rp2040_specific
49  * There are two PIO blocks in the RP2040.
50  * \endif
51  *
52  * \if rp2350_specific
53  * There are three PIO blocks in the RP2350
54  * \endif
55  *
56  * Each PIO is programmable in the same sense as a processor: the four state machines independently
57  * execute short, sequential programs, to manipulate GPIOs and transfer data. Unlike a general
58  * purpose processor, PIO state machines are highly specialised for IO, with a focus on determinism,
59  * precise timing, and close integration with fixed-function hardware. Each state machine is equipped
60  * with:
61  *  * Two 32-bit shift registers – either direction, any shift count
62  *  * Two 32-bit scratch registers
63  *  * 4×32 bit bus FIFO in each direction (TX/RX), reconfigurable as 8×32 in a single direction
64  *  * Fractional clock divider (16 integer, 8 fractional bits)
65  *  * Flexible GPIO mapping
66  *  * DMA interface, sustained throughput up to 1 word per clock from system DMA
67  *  * IRQ flag set/clear/status
68  *
69  * Full details of the PIO can be found in the appropriate RP-series datasheet. Note that there are
70  * additional features in the RP2350 PIO implementation that mean care should be taken when writing PIO
71  * code that needs to run on both the RP2040 and the RP2350.
72  *
73  * \anchor pio_sm_pins
74  * \if rp2040_specific
75  * On RP2040, pin numbers may always be specified from 0-31
76  * \endif
77  *
78  * \if rp2350_specific
79  * On RP2350A, pin numbers may always be specified from 0-31.
80  *
81  * On RP2350B, there are 48 pins but each PIO instance can only address 32 pins (the PIO
82  * instance either addresses pins 0-31 or 16-47 based on \ref pio_set_gpio_base). The
83  * `pio_sm_` methods that directly affect the hardware always take _real_ pin numbers in the full range, however:
84  *
85  * * If `PICO_PIO_USE_GPIO_BASE != 1` then the 5th bit of the pin number is ignored. This is done so
86  *   that programs compiled for boards with RP2350A do not incur the extra overhead of dealing with higher pins that don't exist.
87  *   Effectively these functions behave exactly like RP2040 in this case.
88  *   Note that `PICO_PIO_USE_GPIO_BASE` is defaulted to 0 if `PICO_RP2350A` is 1
89  * * If `PICO_PIO_USE_GPIO_BASE == 1` then the passed pin numbers are adjusted internally by subtracting
90  *   the GPIO base to give a pin number in the range 0-31 from the PIO's perspective
91  *
92  * You can set `PARAM_ASSERTIONS_ENABLED_HARDWARE_PIO = 1` to enable parameter checking to debug pin (or other) issues with
93  * hardware_pio methods.
94  *
95  * Note that pin masks follow the same rules as individual pins; bit N of a 32-bit or 64-bit mask always refers to pin N.
96  * \endif
97  */
98 
99 #ifdef __cplusplus
100 extern "C" {
101 #endif
102 
103 static_assert(PIO_SM0_SHIFTCTRL_FJOIN_RX_LSB == PIO_SM0_SHIFTCTRL_FJOIN_TX_LSB + 1, "");
104 
105 /** \brief FIFO join states
106  *  \ingroup hardware_pio
107  */
108 enum pio_fifo_join {
109     PIO_FIFO_JOIN_NONE = 0,    ///< TX FIFO length=4 is used for transmit, RX FIFO length=4 is used for receive
110     PIO_FIFO_JOIN_TX = 1,      ///< TX FIFO length=8 is used for transmit, RX FIFO is disabled
111     PIO_FIFO_JOIN_RX = 2,      ///< RX FIFO length=8 is used for receive, TX FIFO is disabled
112 #if PICO_PIO_VERSION > 0
113     PIO_FIFO_JOIN_TXGET = 4,   ///< TX FIFO length=4 is used for transmit, RX FIFO is disabled; space is used for "get" instructions or processor writes
114     PIO_FIFO_JOIN_TXPUT = 8,   ///< TX FIFO length=4 is used for transmit, RX FIFO is disabled; space is used for "put" instructions or processor reads
115     PIO_FIFO_JOIN_PUTGET = 12, ///< TX FIFO length=4 is used for transmit, RX FIFO is disabled; space is used for "put"/"get" instructions with no processor access
116 #endif
117 };
118 
119 /** \brief MOV status types
120  *  \ingroup hardware_pio
121  */
122 enum pio_mov_status_type {
123     STATUS_TX_LESSTHAN = 0,
124     STATUS_RX_LESSTHAN = 1,
125 #if PICO_PIO_VERSION > 0
126     STATUS_IRQ_SET = 2
127 #endif
128 };
129 
130 typedef pio_hw_t *PIO;
131 
132 /** Identifier for the first (PIO 0) hardware PIO instance (for use in PIO functions).
133  *
134  * e.g. pio_gpio_init(pio0, 5)
135  *
136  *  \ingroup hardware_pio
137  */
138 #define pio0 pio0_hw
139 
140 /** Identifier for the second (PIO 1) hardware PIO instance (for use in PIO functions).
141  *
142  * e.g. pio_gpio_init(pio1, 5)
143  *
144  *  \ingroup hardware_pio
145  */
146 #define pio1 pio1_hw
147 
148 #if NUM_PIOS > 2
149 /** Identifier for the third (PIO 2) hardware PIO instance (for use in PIO functions).
150  *
151  * e.g. pio_gpio_init(pio2, 5)
152  *
153  *  \ingroup hardware_pio
154  */
155 #define pio2 pio2_hw
156 #endif
157 
158 #if PICO_PIO_VERSION > 0
159 #ifndef PICO_PIO_USE_GPIO_BASE
160 // PICO_CONFIG: PICO_PIO_USE_GPIO_BASE, Enable code for handling more than 32 PIO pins, type=bool, default=true when supported and when the device has more than 32 pins, group=hardware_pio
161 #define PICO_PIO_USE_GPIO_BASE ((NUM_BANK0_GPIOS) > 32)
162 #endif
163 #endif
164 
165 /**
166  * \def PIO_NUM(pio)
167  * \ingroup hardware_pio
168  * \hideinitializer
169  * \brief Returns the PIO number for a PIO instance
170  *
171  * Note this macro is intended to resolve at compile time, and does no parameter checking
172  */
173 #ifndef PIO_NUM
174 static_assert(PIO1_BASE - PIO0_BASE == (1u << 20), "hardware layout mismatch");
175 #define PIO_NUM(pio) (((uintptr_t)(pio) - PIO0_BASE) >> 20)
176 #endif
177 
178 /**
179  * \def PIO_INSTANCE(pio_num)
180  * \ingroup hardware_pio
181  * \hideinitializer
182  * \brief Returns the PIO instance with the given PIO number
183  *
184  * Note this macro is intended to resolve at compile time, and does no parameter checking
185  */
186 #ifndef PIO_INSTANCE
187 static_assert(PIO1_BASE - PIO0_BASE == (1u << 20), "hardware layout mismatch");
188 #define PIO_INSTANCE(instance) ((pio_hw_t *)(PIO0_BASE + (instance) * (1u << 20)))
189 #endif
190 
191 /**
192  * \def PIO_FUNCSEL_NUM(pio, gpio)
193  * \ingroup hardware_pio
194  * \hideinitializer
195  * \brief Returns \ref gpio_function_t needed to select the PIO function for the given PIO instance on the given GPIO
196  *
197  * Note this macro is intended to resolve at compile time, and does no parameter checking
198  */
199 #ifndef PIO_FUNCSEL_NUM
200 #define PIO_FUNCSEL_NUM(pio, gpio) ((gpio_function_t) (GPIO_FUNC_PIO0 + PIO_NUM(pio)))
201 #endif
202 
203 /**
204  * \def PIO_DREQ_NUM(pio, sm, is_tx)
205  * \ingroup hardware_pio
206  * \hideinitializer
207  * \brief Returns the \ref dreq_num_t used for pacing DMA transfers to or from a given state machine's FIFOs on this PIO instance.
208  * If is_tx is true, then it is for transfers to the PIO state machine TX FIFO else for transfers from the PIO state machine RX FIFO.
209  *
210  * Note this macro is intended to resolve at compile time, and does no parameter checking
211  */
212 #ifndef PIO_DREQ_NUM
213 static_assert(DREQ_PIO0_TX1 == DREQ_PIO0_TX0 + 1, "");
214 static_assert(DREQ_PIO0_TX2 == DREQ_PIO0_TX0 + 2, "");
215 static_assert(DREQ_PIO0_TX3 == DREQ_PIO0_TX0 + 3, "");
216 static_assert(DREQ_PIO0_RX0 == DREQ_PIO0_TX0 + NUM_PIO_STATE_MACHINES, "");
217 static_assert(DREQ_PIO1_RX0 == DREQ_PIO1_TX0 + NUM_PIO_STATE_MACHINES, "");
218 #define PIO_DREQ_NUM(pio, sm, is_tx) ((sm) + (((is_tx) ? 0 : NUM_PIO_STATE_MACHINES) + PIO_NUM(pio) * (DREQ_PIO1_TX0 - DREQ_PIO0_TX0)))
219 #endif
220 
221 /**
222  * \def PIO_IRQ_NUM(pio)
223  * \ingroup hardware_pio
224  * \hideinitializer
225  * \brief Returns the \ref irq_num_t for processor interrupts from the given PIO instance
226  *
227  * Note this macro is intended to resolve at compile time, and does no parameter checking
228  */
229 #ifndef PIO_IRQ_NUM
230 #define PIO_IRQ_NUM(pio, irqn) (PIO0_IRQ_0 + NUM_PIO_IRQS * PIO_NUM(pio) + (irqn))
231 #endif
232 
233 /** \brief PIO state machine configuration
234  *  \defgroup sm_config sm_config
235  *  \ingroup hardware_pio
236  *
237  * A PIO block needs to be configured, these functions provide helpers to set up configuration
238  * structures. See \ref pio_sm_set_config
239  *
240  * \anchor sm_config_pins
241  * \if rp2040_specific
242  * On RP2040, pin numbers may always be specified from 0-31
243  * \endif
244  *
245  * \if rp2350_specific
246  * On RP2350A, pin numbers may always be specified from 0-31.
247  *
248  * On RP2350B, there are 48 pins but each PIO instance can only address 32 pins (the PIO
249  * instance either addresses pins 0-31 or 16-47 based on \ref pio_set_gpio_base). The
250  * `sm_config_` state machine configuration always take _real_ pin numbers in the full range, however:
251  *
252  * * If `PICO_PIO_USE_GPIO_BASE != 1` then the 5th bit of the pin number is ignored. This is done so
253  *   that programs compiled for boards with RP2350A do not incur the extra overhead of dealing with higher pins that don't exist.
254  *   Effectively these functions behave exactly like RP2040 in this case.
255  *   Note that `PICO_PIO_USE_GPIO_BASE` is defaulted to 0 if `PICO_RP2350A` is 1
256  * * If `PICO_PIO_USE_GPIO_BASE == 1` then the state machine configuration stores the actual pin numbers in the range 0-47.
257  *   Of course in this scenario, it is possible to make an invalid configuration (one which uses pins in both the ranges
258  *   0-15 and 32-47).
259  *
260  *   \ref pio_sm_set_config (or \ref pio_sm_init which calls it) attempts to apply the configuration to a particular PIO's state machine,
261  *   and will return PICO_ERROR_BAD_ALIGNMENT if the configuration cannot be applied due to the above problem,
262  *   or if the PIO's GPIO base (see \ref pio_set_gpio_base) does not allow access to the required pins.
263  *
264  *   To be clear, \ref pio_sm_set_config does not change the PIO's GPIO base for you; you must configre the PIO's
265  *   GPIO base before calling the method, however you can use \ref pio_claim_free_sm_and_add_program_for_gpio_range
266  *   to find/configure a PIO instance suitable for a partiular GPIO range.
267  *
268  * You can set `PARAM_ASSERTIONS_ENABLED_HARDWARE_PIO = 1` to enable parameter checking to debug pin (or other) issues with
269  * hardware_pio methods.
270  * \endif
271  */
272 
273 /** \brief PIO Configuration structure
274  *  \ingroup sm_config
275  *
276  * This structure is an in-memory representation of the configuration that can be applied to a PIO
277  * state machine later using pio_sm_set_config() or pio_sm_init().
278  */
279 typedef struct {
280     uint32_t clkdiv;
281     uint32_t execctrl;
282     uint32_t shiftctrl;
283     uint32_t pinctrl;
284 #if PICO_PIO_USE_GPIO_BASE
285 #define PINHI_ALL_PINCTRL_LSBS ((1u << PIO_SM0_PINCTRL_IN_BASE_LSB) | (1u << PIO_SM0_PINCTRL_OUT_BASE_LSB) | \
286                                (1u << PIO_SM0_PINCTRL_SET_BASE_LSB) | (1u << PIO_SM0_PINCTRL_SIDESET_BASE_LSB))
287 // note we put the out_special pin starting at bit 20
288 #define PINHI_EXECCTRL_LSB 20
289 static_assert( (1u << PINHI_EXECCTRL_LSB) > (PINHI_ALL_PINCTRL_LSBS * 0x1f), "");
290 #define PINHI_ALL_PIN_LSBS ((1u << PINHI_EXECCTRL_LSB) |(1u << PIO_SM0_PINCTRL_IN_BASE_LSB) | (1u << PIO_SM0_PINCTRL_OUT_BASE_LSB) | \
291                                (1u << PIO_SM0_PINCTRL_SET_BASE_LSB) | (1u << PIO_SM0_PINCTRL_SIDESET_BASE_LSB))
292     // each 5-bit field which would usually be used for the pin_base in pin_ctrl, is used for:
293     // 0b11111 - corresponding field not specified
294     // 0b00000 - pin is in range 0-15
295     // 0b00001 - pin is in range 16-31
296     // 0b00010 - pin is in range 32-47
297     uint32_t pinhi;
298 #endif
299 } pio_sm_config;
300 
check_sm_param(__unused uint sm)301 static inline void check_sm_param(__unused uint sm) {
302     valid_params_if(HARDWARE_PIO, sm < NUM_PIO_STATE_MACHINES);
303 }
304 
check_sm_mask(__unused uint mask)305 static inline void check_sm_mask(__unused uint mask) {
306     valid_params_if(HARDWARE_PIO, mask < (1u << NUM_PIO_STATE_MACHINES));
307 }
308 
check_pio_param(__unused PIO pio)309 static inline void check_pio_param(__unused PIO pio) {
310 #if NUM_PIOS == 2
311     valid_params_if(HARDWARE_PIO, pio == pio0 || pio == pio1);
312 #elif NUM_PIOS == 3
313     valid_params_if(HARDWARE_PIO, pio == pio0 || pio == pio1 || pio == pio2);
314 #endif
315 }
316 
check_pio_pin_param(__unused uint pin)317 static inline void check_pio_pin_param(__unused uint pin) {
318 #if !PICO_PIO_USE_GPIO_BASE
319     invalid_params_if(HARDWARE_PIO, pin >= 32);
320 #else
321     // pin base allows us to move up 16 pins at a time
322     invalid_params_if(HARDWARE_PIO, pin >= ((NUM_BANK0_GPIOS + 15u)&~15u));
323 #endif
324 }
325 
326 /*! \brief Set the base of the 'out' pins in a state machine configuration
327  *  \ingroup sm_config
328  *
329  * 'out' pins can overlap with the 'in', 'set' and 'sideset' pins
330  *
331  * \param c Pointer to the configuration structure to modify
332  * \param out_base First pin to set as output. See \ref sm_config_pins "sm_config_ pins" for more detail on pin arguments
333  */
sm_config_set_out_pin_base(pio_sm_config * c,uint out_base)334 static inline void sm_config_set_out_pin_base(pio_sm_config *c, uint out_base) {
335     check_pio_pin_param(out_base);
336     c->pinctrl = (c->pinctrl & ~PIO_SM0_PINCTRL_OUT_BASE_BITS) |
337                  ((out_base & 31) << PIO_SM0_PINCTRL_OUT_BASE_LSB);
338 #if PICO_PIO_USE_GPIO_BASE
339     c->pinhi = (c->pinhi & ~(31u << PIO_SM0_PINCTRL_OUT_BASE_LSB)) |
340                     ((out_base >> 4) << PIO_SM0_PINCTRL_OUT_BASE_LSB);
341 #endif
342 }
343 
344 /*! \brief Set the number of 'out' pins in a state machine configuration
345  *  \ingroup sm_config
346  *
347  * 'out' pins can overlap with the 'in', 'set' and 'sideset' pins
348  *
349  * \param c Pointer to the configuration structure to modify
350  * \param out_count 0-32 Number of pins to set.
351  */
sm_config_set_out_pin_count(pio_sm_config * c,uint out_count)352 static inline void sm_config_set_out_pin_count(pio_sm_config *c, uint out_count) {
353     valid_params_if(HARDWARE_PIO, out_count <= 32);
354     c->pinctrl = (c->pinctrl & ~PIO_SM0_PINCTRL_OUT_COUNT_BITS) |
355                  (out_count << PIO_SM0_PINCTRL_OUT_COUNT_LSB);
356 }
357 
358 /*! \brief Set the 'out' pins in a state machine configuration
359  *  \ingroup sm_config
360  *
361  * 'out' pins can overlap with the 'in', 'set' and 'sideset' pins
362  *
363  * \param c Pointer to the configuration structure to modify
364  * \param out_base First pin to set as output. See \ref sm_config_pins "sm_config_ pins" for more detail on pin arguments
365  * \param out_count 0-32 Number of pins to set.
366  */
sm_config_set_out_pins(pio_sm_config * c,uint out_base,uint out_count)367 static inline void sm_config_set_out_pins(pio_sm_config *c, uint out_base, uint out_count) {
368     sm_config_set_out_pin_base(c, out_base);
369     sm_config_set_out_pin_count(c, out_count);
370 }
371 
372 /*! \brief Set the base of the 'set' pins in a state machine configuration
373  *  \ingroup sm_config
374  *
375  * 'set' pins can overlap with the 'in', 'out' and 'sideset' pins
376  *
377  * \param c Pointer to the configuration structure to modify
378  * \param set_base First pin to use as 'set'. See \ref sm_config_pins "sm_config_ pins" for more detail on pin arguments
379  */
sm_config_set_set_pin_base(pio_sm_config * c,uint set_base)380 static inline void sm_config_set_set_pin_base(pio_sm_config *c, uint set_base) {
381     check_pio_pin_param(set_base);
382     c->pinctrl = (c->pinctrl & ~PIO_SM0_PINCTRL_SET_BASE_BITS) |
383                  ((set_base & 31) << PIO_SM0_PINCTRL_SET_BASE_LSB);
384 #if PICO_PIO_USE_GPIO_BASE
385     c->pinhi = (c->pinhi & ~(31u << PIO_SM0_PINCTRL_SET_BASE_LSB)) |
386                     ((set_base >> 4) << PIO_SM0_PINCTRL_SET_BASE_LSB);
387 #endif
388 }
389 
390 /*! \brief Set the count of 'set' pins in a state machine configuration
391  *  \ingroup sm_config
392  *
393  * 'set' pins can overlap with the 'in', 'out' and 'sideset' pins
394  *
395  * \param c Pointer to the configuration structure to modify
396  * \param set_count 0-5 Number of pins to set.
397  */
sm_config_set_set_pin_count(pio_sm_config * c,uint set_count)398 static inline void sm_config_set_set_pin_count(pio_sm_config *c, uint set_count) {
399     valid_params_if(HARDWARE_PIO, set_count <= 5);
400     c->pinctrl = (c->pinctrl & ~PIO_SM0_PINCTRL_SET_COUNT_BITS) |
401                  (set_count << PIO_SM0_PINCTRL_SET_COUNT_LSB);
402 }
403 
404 /*! \brief Set the 'set' pins in a state machine configuration
405  *  \ingroup sm_config
406  *
407  * 'set' pins can overlap with the 'in', 'out' and 'sideset' pins
408  *
409  * \param c Pointer to the configuration structure to modify
410  * \param set_base First pin to use as 'set'. See \ref sm_config_pins "sm_config_ pins" for more detail on pin arguments
411  * \param set_count 0-5 Number of pins to set.
412  */
sm_config_set_set_pins(pio_sm_config * c,uint set_base,uint set_count)413 static inline void sm_config_set_set_pins(pio_sm_config *c, uint set_base, uint set_count) {
414     sm_config_set_set_pin_base(c, set_base);
415     sm_config_set_set_pin_count(c, set_count);
416 }
417 
418 /*! \brief Set the base of the 'in' pins in a state machine configuration
419  *  \ingroup sm_config
420  *
421  * 'in' pins can overlap with the 'out', 'set' and 'sideset' pins
422  *
423  * \param c Pointer to the configuration structure to modify
424  * \param in_base First pin to use as input. See \ref sm_config_pins "sm_config_ pins" for more detail on pin arguments
425  */
sm_config_set_in_pin_base(pio_sm_config * c,uint in_base)426 static inline void sm_config_set_in_pin_base(pio_sm_config *c, uint in_base) {
427     check_pio_pin_param(in_base);
428     c->pinctrl = (c->pinctrl & ~PIO_SM0_PINCTRL_IN_BASE_BITS) |
429                  ((in_base & 31) << PIO_SM0_PINCTRL_IN_BASE_LSB);
430 #if PICO_PIO_USE_GPIO_BASE
431     c->pinhi = (c->pinhi & ~(31u << PIO_SM0_PINCTRL_IN_BASE_LSB)) |
432                     ((in_base >> 4) << PIO_SM0_PINCTRL_IN_BASE_LSB);
433 #endif
434 }
435 
436 /*! \brief Set the base for the 'in' pins in a state machine configuration
437  *  \ingroup sm_config
438  *
439  * 'in' pins can overlap with the 'out', 'set' and 'sideset' pins
440  *
441  * \param c Pointer to the configuration structure to modify
442  * \param in_base First pin to use as input. See \ref sm_config_pins "sm_config_ pins" for more detail on pin arguments
443  */
sm_config_set_in_pins(pio_sm_config * c,uint in_base)444 static inline void sm_config_set_in_pins(pio_sm_config *c, uint in_base) {
445     sm_config_set_in_pin_base(c, in_base);
446 }
447 
448 /*! \brief Set the count of 'in' pins in a state machine configuration
449  *  \ingroup sm_config
450  *
451  * When reading pins using the IN pin mapping, this many (low) bits will be read, with the rest taking
452  * the value zero.
453  *
454  * \if rp2040_specific
455  * RP2040 does not have the ability to mask unused input pins, so the in_count must be 32
456  * \endif
457  *
458  * \param c Pointer to the configuration structure to modify
459  * \param in_count 1-32 The number of pins to include when reading via the IN pin mapping
460  */
sm_config_set_in_pin_count(pio_sm_config * c,uint in_count)461 static inline void sm_config_set_in_pin_count(pio_sm_config *c, uint in_count) {
462 #if PICO_PIO_VERSION == 0
463     // can't be changed from 32 on PIO v0
464     ((void)c);
465     valid_params_if(HARDWARE_PIO, in_count == 32);
466 #else
467     valid_params_if(HARDWARE_PIO, in_count && in_count <= 32);
468     c->shiftctrl = (c->shiftctrl & ~PIO_SM0_SHIFTCTRL_IN_COUNT_BITS) |
469                    ((in_count & 0x1fu) << PIO_SM0_SHIFTCTRL_IN_COUNT_LSB);
470 #endif
471 }
472 
473 /*! \brief Set the base of the 'sideset' pins in a state machine configuration
474  *  \ingroup sm_config
475  *
476  * 'sideset' pins can overlap with the 'in', 'out' and 'set' pins
477  *
478  * \param c Pointer to the configuration structure to modify
479  * \param sideset_base First pin to use for 'side set'. See \ref sm_config_pins "sm_config_ pins" for more detail on pin arguments
480  */
sm_config_set_sideset_pin_base(pio_sm_config * c,uint sideset_base)481 static inline void sm_config_set_sideset_pin_base(pio_sm_config *c, uint sideset_base) {
482     check_pio_pin_param(sideset_base);
483     c->pinctrl = (c->pinctrl & ~PIO_SM0_PINCTRL_SIDESET_BASE_BITS) |
484                  ((sideset_base & 31) << PIO_SM0_PINCTRL_SIDESET_BASE_LSB);
485 #if PICO_PIO_USE_GPIO_BASE
486     c->pinhi = (c->pinhi & ~(31u << PIO_SM0_PINCTRL_SIDESET_BASE_LSB)) |
487                     ((sideset_base >> 4) << PIO_SM0_PINCTRL_SIDESET_BASE_LSB);
488 #endif
489 }
490 
491 /*! \brief Set the 'sideset' pins in a state machine configuration
492  *  \ingroup sm_config
493  *
494  * This method is identical to \ref sm_config_set_sideset_pin_base, and is provided
495  * for backwards compatibility
496  *
497  * 'sideset' pins can overlap with the 'in', 'out' and 'set' pins
498  *
499  * \param c Pointer to the configuration structure to modify
500  * \param sideset_base First pin to use for 'side set'. See \ref sm_config_pins "sm_config_ pins" for more detail on pin arguments
501  */
sm_config_set_sideset_pins(pio_sm_config * c,uint sideset_base)502 static inline void sm_config_set_sideset_pins(pio_sm_config *c, uint sideset_base) {
503     sm_config_set_sideset_pin_base(c, sideset_base);
504 }
505 
506 /*! \brief Set the 'sideset' options in a state machine configuration
507  *  \ingroup sm_config
508  *
509  * \param c Pointer to the configuration structure to modify
510  * \param bit_count Number of bits to steal from delay field in the instruction for use of side set (max 5)
511  * \param optional True if the topmost side set bit is used as a flag for whether to apply side set on that instruction
512  * \param pindirs True if the side set affects pin directions rather than values
513  */
sm_config_set_sideset(pio_sm_config * c,uint bit_count,bool optional,bool pindirs)514 static inline void sm_config_set_sideset(pio_sm_config *c, uint bit_count, bool optional, bool pindirs) {
515     valid_params_if(HARDWARE_PIO, bit_count <= 5);
516     valid_params_if(HARDWARE_PIO, !optional || bit_count >= 1);
517     c->pinctrl = (c->pinctrl & ~PIO_SM0_PINCTRL_SIDESET_COUNT_BITS) |
518                  (bit_count << PIO_SM0_PINCTRL_SIDESET_COUNT_LSB);
519     c->execctrl = (c->execctrl & ~(PIO_SM0_EXECCTRL_SIDE_EN_BITS | PIO_SM0_EXECCTRL_SIDE_PINDIR_BITS)) |
520                   (bool_to_bit(optional) << PIO_SM0_EXECCTRL_SIDE_EN_LSB) |
521                   (bool_to_bit(pindirs) << PIO_SM0_EXECCTRL_SIDE_PINDIR_LSB);
522 }
523 
524 /*! \brief Set the state machine clock divider (from integer and fractional parts - 16:8) in a state machine configuration
525  *  \ingroup sm_config
526  *
527  * The clock divider can slow the state machine's execution to some rate below
528  * the system clock frequency, by enabling the state machine on some cycles
529  * but not on others, in a regular pattern. This can be used to generate e.g.
530  * a given UART baud rate. See the datasheet for further detail.
531  *
532  * \param c Pointer to the configuration structure to modify
533  * \param div_int Integer part of the divisor
534  * \param div_frac8 Fractional part in 1/256ths
535  * \sa sm_config_set_clkdiv()
536  */
sm_config_set_clkdiv_int_frac8(pio_sm_config * c,uint32_t div_int,uint8_t div_frac8)537 static inline void sm_config_set_clkdiv_int_frac8(pio_sm_config *c, uint32_t div_int, uint8_t div_frac8) {
538     static_assert(REG_FIELD_WIDTH(PIO_SM0_CLKDIV_INT) == 16, "");
539     invalid_params_if(HARDWARE_PIO, div_int >> 16);
540     invalid_params_if(HARDWARE_PIO, div_int == 0 && div_frac8 != 0);
541     static_assert(REG_FIELD_WIDTH(PIO_SM0_CLKDIV_FRAC) == 8, "");
542     c->clkdiv =
543             (((uint)div_frac8) << PIO_SM0_CLKDIV_FRAC_LSB) |
544             (((uint)div_int) << PIO_SM0_CLKDIV_INT_LSB);
545 }
546 
547 // backwards compatibility
sm_config_set_clkdiv_int_frac(pio_sm_config * c,uint16_t div_int,uint8_t div_frac8)548 static inline void sm_config_set_clkdiv_int_frac(pio_sm_config *c, uint16_t div_int, uint8_t div_frac8) {
549     sm_config_set_clkdiv_int_frac8(c, div_int, div_frac8);
550 }
551 
pio_calculate_clkdiv8_from_float(float div,uint32_t * div_int,uint8_t * div_frac8)552 static inline void pio_calculate_clkdiv8_from_float(float div, uint32_t *div_int, uint8_t *div_frac8) {
553     valid_params_if(HARDWARE_PIO, div >= 1 && div <= 65536);
554     const int frac_bit_count = REG_FIELD_WIDTH(PIO_SM0_CLKDIV_FRAC);
555 #if PICO_PIO_CLKDIV_ROUND_NEAREST
556     div += 0.5f / (1 << frac_bit_count); // round to the nearest 1/256
557 #endif
558     *div_int = (uint16_t)div;
559     // not a strictly necessary check, but if this changes, then this method should
560     // probably no longer be used in favor of one with a larger fraction
561     static_assert(REG_FIELD_WIDTH(PIO_SM0_CLKDIV_FRAC) == 8, "");
562     if (*div_int == 0) {
563         *div_frac8 = 0;
564     } else {
565         *div_frac8 = (uint8_t)((div - (float)*div_int) * (1u << frac_bit_count));
566     }
567 }
568 
569 // backwards compatibility
pio_calculate_clkdiv_from_float(float div,uint16_t * div_int16,uint8_t * div_frac8)570 static inline void pio_calculate_clkdiv_from_float(float div, uint16_t *div_int16, uint8_t *div_frac8) {
571     uint32_t div_int;
572     pio_calculate_clkdiv8_from_float(div, &div_int, div_frac8);
573     *div_int16 = (uint16_t) div_int;
574 }
575 
576 /*! \brief Set the state machine clock divider (from a floating point value) in a state machine configuration
577  *  \ingroup sm_config
578  *
579  * The clock divider slows the state machine's execution by masking the
580  * system clock on some cycles, in a repeating pattern, so that the state
581  * machine does not advance. Effectively this produces a slower clock for the
582  * state machine to run from, which can be used to generate e.g. a particular
583  * UART baud rate. See the datasheet for further detail.
584  *
585  * \param c Pointer to the configuration structure to modify
586  * \param div The fractional divisor to be set. 1 for full speed. An integer clock divisor of n
587  *  will cause the state machine to run 1 cycle in every n.
588  *  Note that for small n, the jitter introduced by a fractional divider (e.g. 2.5) may be unacceptable
589  *  although it will depend on the use case.
590  */
sm_config_set_clkdiv(pio_sm_config * c,float div)591 static inline void sm_config_set_clkdiv(pio_sm_config *c, float div) {
592     uint32_t div_int;
593     uint8_t div_frac8;
594     pio_calculate_clkdiv8_from_float(div, &div_int, &div_frac8);
595     sm_config_set_clkdiv_int_frac8(c, div_int, div_frac8);
596 }
597 
598 /*! \brief Set the wrap addresses in a state machine configuration
599  *  \ingroup sm_config
600  *
601  * \param c Pointer to the configuration structure to modify
602  * \param wrap_target the instruction memory address to wrap to
603  * \param wrap        the instruction memory address after which to set the program counter to wrap_target
604  *                    if the instruction does not itself update the program_counter
605  */
sm_config_set_wrap(pio_sm_config * c,uint wrap_target,uint wrap)606 static inline void sm_config_set_wrap(pio_sm_config *c, uint wrap_target, uint wrap) {
607     valid_params_if(HARDWARE_PIO, wrap < PIO_INSTRUCTION_COUNT);
608     valid_params_if(HARDWARE_PIO, wrap_target < PIO_INSTRUCTION_COUNT);
609     c->execctrl = (c->execctrl & ~(PIO_SM0_EXECCTRL_WRAP_TOP_BITS | PIO_SM0_EXECCTRL_WRAP_BOTTOM_BITS)) |
610                   (wrap_target << PIO_SM0_EXECCTRL_WRAP_BOTTOM_LSB) |
611                   (wrap << PIO_SM0_EXECCTRL_WRAP_TOP_LSB);
612 }
613 
614 /*! \brief Set the 'jmp' pin in a state machine configuration
615  *  \ingroup sm_config
616  *
617  * \param c Pointer to the configuration structure to modify
618  * \param pin The raw GPIO pin number to use as the source for a `jmp pin` instruction. See \ref sm_config_pins "sm_config_ pins" for more detail on pin arguments
619  */
sm_config_set_jmp_pin(pio_sm_config * c,uint pin)620 static inline void sm_config_set_jmp_pin(pio_sm_config *c, uint pin) {
621     check_pio_pin_param(pin);
622     c->execctrl = (c->execctrl & ~PIO_SM0_EXECCTRL_JMP_PIN_BITS) |
623                   ((pin & 31) << PIO_SM0_EXECCTRL_JMP_PIN_LSB);
624 #if PICO_PIO_USE_GPIO_BASE
625     c->pinhi = (c->pinhi & ~(31u << 20)) |
626                ((pin >> 4) << 20);
627 #endif
628 }
629 
630 /*! \brief Setup 'in' shifting parameters in a state machine configuration
631  *  \ingroup sm_config
632  *
633  * \param c Pointer to the configuration structure to modify
634  * \param shift_right true to shift ISR to right, false to shift ISR to left
635  * \param autopush whether autopush is enabled
636  * \param push_threshold threshold in bits to shift in before auto/conditional re-pushing of the ISR
637  */
sm_config_set_in_shift(pio_sm_config * c,bool shift_right,bool autopush,uint push_threshold)638 static inline void sm_config_set_in_shift(pio_sm_config *c, bool shift_right, bool autopush, uint push_threshold) {
639     valid_params_if(HARDWARE_PIO, push_threshold <= 32);
640     c->shiftctrl = (c->shiftctrl &
641                     ~(PIO_SM0_SHIFTCTRL_IN_SHIFTDIR_BITS |
642                       PIO_SM0_SHIFTCTRL_AUTOPUSH_BITS |
643                       PIO_SM0_SHIFTCTRL_PUSH_THRESH_BITS)) |
644                    (bool_to_bit(shift_right) << PIO_SM0_SHIFTCTRL_IN_SHIFTDIR_LSB) |
645                    (bool_to_bit(autopush) << PIO_SM0_SHIFTCTRL_AUTOPUSH_LSB) |
646                    ((push_threshold & 0x1fu) << PIO_SM0_SHIFTCTRL_PUSH_THRESH_LSB);
647 }
648 
649 /*! \brief Setup 'out' shifting parameters in a state machine configuration
650  *  \ingroup sm_config
651  *
652  * \param c Pointer to the configuration structure to modify
653  * \param shift_right true to shift OSR to right, false to shift OSR to left
654  * \param autopull whether autopull is enabled
655  * \param pull_threshold threshold in bits to shift out before auto/conditional re-pulling of the OSR
656  */
sm_config_set_out_shift(pio_sm_config * c,bool shift_right,bool autopull,uint pull_threshold)657 static inline void sm_config_set_out_shift(pio_sm_config *c, bool shift_right, bool autopull, uint pull_threshold) {
658     valid_params_if(HARDWARE_PIO, pull_threshold <= 32);
659     c->shiftctrl = (c->shiftctrl &
660                     ~(PIO_SM0_SHIFTCTRL_OUT_SHIFTDIR_BITS |
661                       PIO_SM0_SHIFTCTRL_AUTOPULL_BITS |
662                       PIO_SM0_SHIFTCTRL_PULL_THRESH_BITS)) |
663                    (bool_to_bit(shift_right) << PIO_SM0_SHIFTCTRL_OUT_SHIFTDIR_LSB) |
664                    (bool_to_bit(autopull) << PIO_SM0_SHIFTCTRL_AUTOPULL_LSB) |
665                    ((pull_threshold & 0x1fu) << PIO_SM0_SHIFTCTRL_PULL_THRESH_LSB);
666 }
667 
668 /*! \brief Setup the FIFO joining in a state machine configuration
669  *  \ingroup sm_config
670  *
671  * \param c Pointer to the configuration structure to modify
672  * \param join Specifies the join type. \see enum pio_fifo_join
673  */
sm_config_set_fifo_join(pio_sm_config * c,enum pio_fifo_join join)674 static inline void sm_config_set_fifo_join(pio_sm_config *c, enum pio_fifo_join join) {
675     valid_params_if(HARDWARE_PIO, join == PIO_FIFO_JOIN_NONE || join == PIO_FIFO_JOIN_TX || join == PIO_FIFO_JOIN_RX
676 #if PICO_PIO_VERSION > 0
677         || join == PIO_FIFO_JOIN_TXPUT || join == PIO_FIFO_JOIN_TXGET || join == PIO_FIFO_JOIN_PUTGET
678 #endif
679     );
680 #if PICO_PIO_VERSION == 0
681     c->shiftctrl = (c->shiftctrl & (uint)~(PIO_SM0_SHIFTCTRL_FJOIN_TX_BITS | PIO_SM0_SHIFTCTRL_FJOIN_RX_BITS)) |
682                    (((uint)join) << PIO_SM0_SHIFTCTRL_FJOIN_TX_LSB);
683 #else
684     c->shiftctrl = (c->shiftctrl & (uint)~(PIO_SM0_SHIFTCTRL_FJOIN_TX_BITS | PIO_SM0_SHIFTCTRL_FJOIN_RX_BITS |
685                                            PIO_SM0_SHIFTCTRL_FJOIN_RX_PUT_BITS | PIO_SM0_SHIFTCTRL_FJOIN_RX_GET_BITS)) |
686                    (((uint)(join & 3)) << PIO_SM0_SHIFTCTRL_FJOIN_TX_LSB) |
687                    (((uint)(join >> 2)) << PIO_SM0_SHIFTCTRL_FJOIN_RX_GET_LSB);
688 #endif
689 }
690 
691 /*! \brief Set special 'out' operations in a state machine configuration
692  *  \ingroup sm_config
693  *
694  * \param c Pointer to the configuration structure to modify
695  * \param sticky to enable 'sticky' output (i.e. re-asserting most recent OUT/SET pin values on subsequent cycles)
696  * \param has_enable_pin true to enable auxiliary OUT enable pin
697  * \param enable_bit_index Data bit index for auxiliary OUT enable.
698 */
sm_config_set_out_special(pio_sm_config * c,bool sticky,bool has_enable_pin,uint enable_bit_index)699 static inline void sm_config_set_out_special(pio_sm_config *c, bool sticky, bool has_enable_pin, uint enable_bit_index) {
700     c->execctrl = (c->execctrl &
701                    (uint)~(PIO_SM0_EXECCTRL_OUT_STICKY_BITS | PIO_SM0_EXECCTRL_INLINE_OUT_EN_BITS |
702                      PIO_SM0_EXECCTRL_OUT_EN_SEL_BITS)) |
703                   (bool_to_bit(sticky) << PIO_SM0_EXECCTRL_OUT_STICKY_LSB) |
704                   (bool_to_bit(has_enable_pin) << PIO_SM0_EXECCTRL_INLINE_OUT_EN_LSB) |
705                   ((enable_bit_index << PIO_SM0_EXECCTRL_OUT_EN_SEL_LSB) & PIO_SM0_EXECCTRL_OUT_EN_SEL_BITS);
706 }
707 
708 /*! \brief Set source for 'mov status' in a state machine configuration
709  *  \ingroup sm_config
710  *
711  * \param c Pointer to the configuration structure to modify
712  * \param status_sel the status operation selector. \see enum pio_mov_status_type
713  * \param status_n parameter for the mov status operation (currently a bit count)
714  */
sm_config_set_mov_status(pio_sm_config * c,enum pio_mov_status_type status_sel,uint status_n)715 static inline void sm_config_set_mov_status(pio_sm_config *c, enum pio_mov_status_type status_sel, uint status_n) {
716     valid_params_if(HARDWARE_PIO,
717                     status_sel == STATUS_TX_LESSTHAN || status_sel == STATUS_RX_LESSTHAN
718 #if PICO_PIO_VERSION > 0
719                     || status_sel == STATUS_IRQ_SET
720 #endif
721     );
722     c->execctrl = (c->execctrl
723                   & ~(PIO_SM0_EXECCTRL_STATUS_SEL_BITS | PIO_SM0_EXECCTRL_STATUS_N_BITS))
724                   | ((((uint)status_sel) << PIO_SM0_EXECCTRL_STATUS_SEL_LSB) & PIO_SM0_EXECCTRL_STATUS_SEL_BITS)
725                   | ((status_n << PIO_SM0_EXECCTRL_STATUS_N_LSB) & PIO_SM0_EXECCTRL_STATUS_N_BITS);
726 }
727 
728 /*! \brief  Get the default state machine configuration
729  *  \ingroup sm_config
730  *
731  * Setting | Default
732  * --------|--------
733  * Out Pins | 32 starting at 0
734  * Set Pins | 0 starting at 0
735  * In Pins | 32 starting at 0
736  * Side Set Pins (base) | 0
737  * Side Set | disabled
738  * Wrap | wrap=31, wrap_to=0
739  * In Shift | shift_direction=right, autopush=false, push_threshold=32
740  * Out Shift | shift_direction=right, autopull=false, pull_threshold=32
741  * Jmp Pin | 0
742  * Out Special | sticky=false, has_enable_pin=false, enable_pin_index=0
743  * Mov Status | status_sel=STATUS_TX_LESSTHAN, n=0
744  *
745  * \return the default state machine configuration which can then be modified.
746  */
pio_get_default_sm_config(void)747 static inline pio_sm_config pio_get_default_sm_config(void) {
748     pio_sm_config c = {};
749 #if PICO_PIO_USE_GPIO_BASE
750     c.pinhi = -1;
751 #endif
752     sm_config_set_clkdiv_int_frac8(&c, 1, 0);
753     sm_config_set_wrap(&c, 0, 31);
754     sm_config_set_in_shift(&c, true, false, 32);
755     sm_config_set_out_shift(&c, true, false, 32);
756     return c;
757 }
758 
759 /*! \brief Return the base GPIO base for the PIO instance
760  *  \ingroup hardware_pio
761  *
762  * \if rp2040_specific
763  * This method always return 0 in RP2040
764  * \endif
765  *
766  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
767  * \return the current GPIO base for the PIO instance
768   */
pio_get_gpio_base(PIO pio)769 static inline uint pio_get_gpio_base(PIO pio) {
770 #if PICO_PIO_VERSION > 0
771     return pio->gpiobase;
772 #else
773     ((void)pio);
774     return 0;
775 #endif
776 }
777 
check_pio_pin_mask64(__unused PIO pio,__unused uint sm,__unused uint64_t pinmask)778 static inline void check_pio_pin_mask64(__unused PIO pio, __unused uint sm, __unused uint64_t pinmask) {
779     // check no pins are set in the mask which are incompatible with the pio
780 #if PICO_PIO_USE_GPIO_BASE
781     valid_params_if(HARDWARE_PIO, (pinmask & ~(0xffffffffull << pio_get_gpio_base(pio))) == 0);
782 #else
783     valid_params_if(HARDWARE_PIO, (pinmask & ~0xffffffffull) == 0);
784 #endif
785 }
786 
787 /*! \brief Apply a state machine configuration to a state machine
788  *  \ingroup hardware_pio
789  *
790  * \if rp2350_specific
791  * See \ref sm_config_pins "sm_config_ pins" for more detail on why this method might fail on RP2350B
792  * \endif
793  * \param pio Handle to PIO instance; e.g. \ref pio0 or \ref pio1
794  * \param sm State machine index (0..3)
795  * \param config the configuration to apply
796  * \return PICO_OK (0) on success, negative error code otherwise
797 */
pio_sm_set_config(PIO pio,uint sm,const pio_sm_config * config)798 static inline int pio_sm_set_config(PIO pio, uint sm, const pio_sm_config *config) {
799     check_pio_param(pio);
800     check_sm_param(sm);
801     pio->sm[sm].clkdiv = config->clkdiv;
802     pio->sm[sm].shiftctrl = config->shiftctrl;
803 #if PICO_PIO_USE_GPIO_BASE
804     uint used = (~config->pinhi >> 4) & PINHI_ALL_PIN_LSBS;
805     // configs that use pins 0-15
806     uint gpio_under_16 = (~config->pinhi) & (~config->pinhi >> 1) & used;
807     // configs that use pins 32-47
808     uint gpio_over_32 = (config->pinhi >> 1) & used;
809     uint gpio_base = pio_get_gpio_base(pio);
810     invalid_params_if_and_return(PIO, gpio_under_16 && gpio_base, PICO_ERROR_BAD_ALIGNMENT);
811     invalid_params_if_and_return(PIO, gpio_over_32 && !gpio_base, PICO_ERROR_BAD_ALIGNMENT);
812     // flip the top bit of any used (execctrl/pinctrl) values to turn:
813     // bit6(32) + 0-15  -> base(16) + 16-31
814     // bit6(0)  + 16-31 -> base(16) + 0-15
815     static_assert(PINHI_EXECCTRL_LSB == 20, ""); // we use shifts to mask off bits below
816     pio->sm[sm].execctrl = config->execctrl ^ (gpio_base ? ((used >> 20) << (PIO_SM0_EXECCTRL_JMP_PIN_LSB + 4)) : 0);
817     pio->sm[sm].pinctrl = config->pinctrl ^ (gpio_base ? ((used << 12) >> 8) : 0);
818 #else
819     pio->sm[sm].execctrl = config->execctrl;
820     pio->sm[sm].pinctrl = config->pinctrl;
821 #endif
822     return PICO_OK;
823 }
824 
825 /*! \brief Return the instance number of a PIO instance
826  *  \ingroup hardware_pio
827  *
828  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
829  * \return the PIO instance number (0, 1, ...)
830  */
pio_get_index(PIO pio)831 static inline uint pio_get_index(PIO pio) {
832     check_pio_param(pio);
833     return PIO_NUM(pio);
834 }
835 
836 /*! \brief Return the funcsel number of a PIO instance
837  *  \ingroup hardware_pio
838  *
839  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
840  * \return the PIO instance number (0, 1, ...)
841  * \see gpio_function
842  */
pio_get_funcsel(PIO pio)843 static inline uint pio_get_funcsel(PIO pio) {
844     check_pio_param(pio);
845     return PIO_FUNCSEL_NUM(pio, 0); // note GPIO currently unused, so won't bother updating API
846 }
847 
848 /*! \brief Convert PIO instance to hardware instance
849  *  \ingroup hardware_pio
850  *
851  * \param instance Instance of PIO, 0 or 1
852  * \return the PIO hardware instance
853  */
pio_get_instance(uint instance)854 static inline PIO pio_get_instance(uint instance) {
855     invalid_params_if(HARDWARE_PIO, instance >= NUM_PIOS);
856     return PIO_INSTANCE(instance);
857 }
858 
859 /*! \brief Setup the function select for a GPIO to use output from the given PIO instance
860  *  \ingroup hardware_pio
861  *
862  * PIO appears as an alternate function in the GPIO muxing, just like an SPI
863  * or UART. This function configures that multiplexing to connect a given PIO
864  * instance to a GPIO. Note that this is not necessary for a state machine to
865  * be able to read the *input* value from a GPIO, but only for it to set the
866  * output value or output enable.
867  *
868  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
869  * \param pin the GPIO pin whose function select to set
870  */
pio_gpio_init(PIO pio,uint pin)871 static inline void pio_gpio_init(PIO pio, uint pin) {
872     check_pio_param(pio);
873     valid_params_if(HARDWARE_PIO, pin < NUM_BANK0_GPIOS);
874     gpio_set_function(pin, PIO_FUNCSEL_NUM(pio, pin));
875 }
876 
877 /*! \brief Return the DREQ to use for pacing transfers to/from a particular state machine FIFO
878  *  \ingroup hardware_pio
879  *
880  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
881  * \param sm State machine index (0..3)
882  * \param is_tx true for sending data to the state machine, false for receiving data from the state machine
883  */
pio_get_dreq(PIO pio,uint sm,bool is_tx)884 static inline uint pio_get_dreq(PIO pio, uint sm, bool is_tx) {
885     check_pio_param(pio);
886     check_sm_param(sm);
887     return PIO_DREQ_NUM(pio, sm, is_tx);
888 }
889 
890 typedef struct pio_program {
891     const uint16_t *instructions;
892     uint8_t length;
893     int8_t origin; // required instruction memory origin or -1
894     uint8_t pio_version;
895 #if PICO_PIO_VERSION > 0
896     uint8_t used_gpio_ranges; // bitmap with one bit per 16 pins
897 #endif
898 } pio_program_t;
899 
900 /*! \brief Set the base GPIO base for the PIO instance
901  *  \ingroup hardware_pio
902  *
903  * Since an individual PIO accesses only 32 pins, to be able to access more pins, the PIO
904  * instance must specify a base GPIO where the instance's "pin 0" maps. For RP2350 the valid
905  * values are 0 and 16, indicating the PIO instance has access to pins 0-31, or 16-47 respectively.
906  *
907  * NOTE: This method simply changes the underlying PIO register, it does not detect or attempt
908  * to prevent any side effects this change will have on in use state machines on this PIO.
909  *
910  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
911  * \param gpio_base the GPIO base (either 0 or 16)
912  * \return PICO_OK (0) on success, error code otherwise
913  */
914 int pio_set_gpio_base(PIO pio, uint gpio_base);
915 
916 /*! \brief Determine whether the given program can (at the time of the call) be loaded onto the PIO instance
917  *  \ingroup hardware_pio
918  *
919  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
920  * \param program the program definition
921  * \return true if the program can be loaded;
922  *         false if not, e.g. if there is not suitable space in the instruction memory
923  */
924 bool pio_can_add_program(PIO pio, const pio_program_t *program);
925 
926 /*! \brief Determine whether the given program can (at the time of the call) be loaded onto the PIO instance starting at a particular location
927  *  \ingroup hardware_pio
928  *
929  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
930  * \param program the program definition
931  * \param offset the instruction memory offset wanted for the start of the program
932  * \return true if the program can be loaded at that location;
933  *         false if not, e.g. if there is not space in the instruction memory
934  */
935 bool pio_can_add_program_at_offset(PIO pio, const pio_program_t *program, uint offset);
936 
937 /*! \brief Attempt to load the program
938  *  \ingroup hardware_pio
939  *
940  * \see pio_can_add_program() if you need to check whether the program can be loaded
941  *
942  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
943  * \param program the program definition
944  * \return the instruction memory offset the program is loaded at, or negative for error (for
945  * backwards compatibility with prior SDK the error value is -1 i.e. PICO_ERROR_GENERIC)
946  */
947 int pio_add_program(PIO pio, const pio_program_t *program);
948 
949 /*! \brief Attempt to load the program at the specified instruction memory offset
950  *  \ingroup hardware_pio
951  *
952  * \see pio_can_add_program_at_offset() if you need to check whether the program can be loaded
953  *
954  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
955  * \param program the program definition
956  * \param offset the instruction memory offset wanted for the start of the program
957  * \return the instruction memory offset the program is loaded at, or negative for error (for
958  * backwards compatibility with prior SDK the error value is -1 i.e. PICO_ERROR_GENERIC)
959  */
960 int pio_add_program_at_offset(PIO pio, const pio_program_t *program, uint offset);
961 
962 /*! \brief Remove a program from a PIO instance's instruction memory
963  *  \ingroup hardware_pio
964  *
965  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
966  * \param program the program definition
967  * \param loaded_offset the loaded offset returned when the program was added
968  */
969 void pio_remove_program(PIO pio, const pio_program_t *program, uint loaded_offset);
970 
971 /*! \brief Clears all of a PIO instance's instruction memory
972  *  \ingroup hardware_pio
973  *
974  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
975  */
976 void pio_clear_instruction_memory(PIO pio);
977 
978 /*! \brief Resets the state machine to a consistent state, and configures it
979  *  \ingroup hardware_pio
980  *
981  * This method:
982  * - Disables the state machine (if running)
983  * - Clears the FIFOs
984  * - Applies the configuration specified by 'config'
985  * - Resets any internal state e.g. shift counters
986  * - Jumps to the initial program location given by 'initial_pc'
987  *
988  * The state machine is left disabled on return from this call.
989  *
990 * * \if rp2350_specific
991  * See \ref sm_config_pins "sm_config_ pins" for more detail on why this method might fail on RP2350B
992  * \endif
993  *
994  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
995  * \param sm State machine index (0..3)
996  * \param initial_pc the initial program memory offset to run from
997  * \param config the configuration to apply (or NULL to apply defaults)
998  * \return PICO_OK, or < 0 for an error (see \enum pico_error_codes)
999  */
1000 int pio_sm_init(PIO pio, uint sm, uint initial_pc, const pio_sm_config *config);
1001 
1002 /*! \brief Enable or disable a PIO state machine
1003  *  \ingroup hardware_pio
1004  *
1005  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1006  * \param sm State machine index (0..3)
1007  * \param enabled true to enable the state machine; false to disable
1008  */
pio_sm_set_enabled(PIO pio,uint sm,bool enabled)1009 static inline void pio_sm_set_enabled(PIO pio, uint sm, bool enabled) {
1010     check_pio_param(pio);
1011     check_sm_param(sm);
1012     pio->ctrl = (pio->ctrl & ~(1u << sm)) | (bool_to_bit(enabled) << sm);
1013 }
1014 
1015 /*! \brief Enable or disable multiple PIO state machines
1016  *  \ingroup hardware_pio
1017  *
1018  * Note that this method just sets the enabled state of the state machine;
1019  * if now enabled they continue exactly from where they left off.
1020  *
1021  * \see pio_enable_sm_mask_in_sync() if you wish to enable multiple state machines
1022  * and ensure their clock dividers are in sync.
1023  *
1024  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1025  * \param mask bit mask of state machine indexes to modify the enabled state of
1026  * \param enabled true to enable the state machines; false to disable
1027  */
pio_set_sm_mask_enabled(PIO pio,uint32_t mask,bool enabled)1028 static inline void pio_set_sm_mask_enabled(PIO pio, uint32_t mask, bool enabled) {
1029     check_pio_param(pio);
1030     check_sm_mask(mask);
1031     pio->ctrl = (pio->ctrl & ~mask) | (enabled ? mask : 0u);
1032 }
1033 
1034 #if PICO_PIO_VERSION > 0
1035 /*! \brief Enable or disable multiple PIO state machines
1036  *  \ingroup hardware_pio
1037  *
1038  * Note that this method just sets the enabled state of the state machine;
1039  * if now enabled they continue exactly from where they left off.
1040  *
1041  * \see pio_enable_sm_mask_in_sync() if you wish to enable multiple state machines
1042  * and ensure their clock dividers are in sync.
1043  *
1044  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1045  * \param mask_prev bit mask of state machine indexes to modify the enabled state of, in the next-lower numbered PIO instance
1046  * \param mask bit mask of state machine indexes to modify the enabled state of, in this PIO instance
1047  * \param mask bit mask of state machine indexes to modify the enabled state of, in the next-higher numbered PIO instance
1048  * \param enabled true to enable the state machines; false to disable
1049  */
pio_set_sm_multi_mask_enabled(PIO pio,uint32_t mask_prev,uint32_t mask,uint32_t mask_next,bool enabled)1050 static inline void pio_set_sm_multi_mask_enabled(PIO pio, uint32_t mask_prev, uint32_t mask, uint32_t mask_next, bool enabled) {
1051     check_pio_param(pio);
1052     check_sm_mask(mask);
1053     pio->ctrl = (pio->ctrl & ~(mask << PIO_CTRL_SM_ENABLE_LSB)) |
1054                 (enabled ? ((mask << PIO_CTRL_SM_ENABLE_LSB) & PIO_CTRL_SM_ENABLE_BITS) : 0) |
1055                 (enabled ? PIO_CTRL_NEXTPREV_SM_ENABLE_BITS : PIO_CTRL_NEXTPREV_SM_DISABLE_BITS) |
1056                 ((mask_prev << PIO_CTRL_PREV_PIO_MASK_LSB) & PIO_CTRL_PREV_PIO_MASK_BITS) |
1057                 ((mask_next << PIO_CTRL_NEXT_PIO_MASK_LSB) & PIO_CTRL_NEXT_PIO_MASK_BITS);
1058 
1059 }
1060 #endif
1061 
1062 /*! \brief Restart a state machine with a known state
1063  *  \ingroup hardware_pio
1064  *
1065  * This method clears the ISR, shift counters, clock divider counter
1066  * pin write flags, delay counter, latched EXEC instruction, and IRQ wait condition.
1067  *
1068  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1069  * \param sm State machine index (0..3)
1070  */
pio_sm_restart(PIO pio,uint sm)1071 static inline void pio_sm_restart(PIO pio, uint sm) {
1072     check_pio_param(pio);
1073     check_sm_param(sm);
1074     hw_set_bits(&pio->ctrl, 1u << (PIO_CTRL_SM_RESTART_LSB + sm));
1075 }
1076 
1077 /*! \brief Restart multiple state machine with a known state
1078  *  \ingroup hardware_pio
1079  *
1080  * This method clears the ISR, shift counters, clock divider counter
1081  * pin write flags, delay counter, latched EXEC instruction, and IRQ wait condition.
1082  *
1083  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1084  * \param mask bit mask of state machine indexes to modify the enabled state of
1085  */
pio_restart_sm_mask(PIO pio,uint32_t mask)1086 static inline void pio_restart_sm_mask(PIO pio, uint32_t mask) {
1087     check_pio_param(pio);
1088     check_sm_mask(mask);
1089     hw_set_bits(&pio->ctrl, (mask << PIO_CTRL_SM_RESTART_LSB) & PIO_CTRL_SM_RESTART_BITS);
1090 }
1091 
1092 /*! \brief Restart a state machine's clock divider from a phase of 0
1093  *  \ingroup hardware_pio
1094  *
1095  * Each state machine's clock divider is a free-running piece of hardware,
1096  * that generates a pattern of clock enable pulses for the state machine,
1097  * based *only* on the configured integer/fractional divisor. The pattern of
1098  * running/halted cycles slows the state machine's execution to some
1099  * controlled rate.
1100  *
1101  * This function clears the divider's integer and fractional phase
1102  * accumulators so that it restarts this pattern from the beginning. It is
1103  * called automatically by pio_sm_init() but can also be called at a later
1104  * time, when you enable the state machine, to ensure precisely consistent
1105  * timing each time you load and run a given PIO program.
1106  *
1107  * More commonly this hardware mechanism is used to synchronise the execution
1108  * clocks of multiple state machines -- see pio_clkdiv_restart_sm_mask().
1109  *
1110  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1111  * \param sm State machine index (0..3)
1112  */
pio_sm_clkdiv_restart(PIO pio,uint sm)1113 static inline void pio_sm_clkdiv_restart(PIO pio, uint sm) {
1114     check_pio_param(pio);
1115     check_sm_param(sm);
1116     hw_set_bits(&pio->ctrl, 1u << (PIO_CTRL_CLKDIV_RESTART_LSB + sm));
1117 }
1118 
1119 /*! \brief Restart multiple state machines' clock dividers from a phase of 0.
1120  *  \ingroup hardware_pio
1121  *
1122  * Each state machine's clock divider is a free-running piece of hardware,
1123  * that generates a pattern of clock enable pulses for the state machine,
1124  * based *only* on the configured integer/fractional divisor. The pattern of
1125  * running/halted cycles slows the state machine's execution to some
1126  * controlled rate.
1127  *
1128  * This function simultaneously clears the integer and fractional phase
1129  * accumulators of multiple state machines' clock dividers. If these state
1130  * machines all have the same integer and fractional divisors configured,
1131  * their clock dividers will run in precise deterministic lockstep from this
1132  * point.
1133  *
1134  * With their execution clocks synchronised in this way, it is then safe to
1135  * e.g. have multiple state machines performing a 'wait irq' on the same flag,
1136  * and all clear it on the same cycle.
1137  *
1138  * Also note that this function can be called whilst state machines are
1139  * running (e.g. if you have just changed the clock divisors of some state
1140  * machines and wish to resynchronise them), and that disabling a state
1141  * machine does not halt its clock divider: that is, if multiple state
1142  * machines have their clocks synchronised, you can safely disable and
1143  * re-enable one of the state machines without losing synchronisation.
1144  *
1145  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1146  * \param mask bit mask of state machine indexes to modify the enabled state of
1147  */
pio_clkdiv_restart_sm_mask(PIO pio,uint32_t mask)1148 static inline void pio_clkdiv_restart_sm_mask(PIO pio, uint32_t mask) {
1149     check_pio_param(pio);
1150     check_sm_mask(mask);
1151     hw_set_bits(&pio->ctrl, (mask << PIO_CTRL_CLKDIV_RESTART_LSB) & PIO_CTRL_CLKDIV_RESTART_BITS);
1152 }
1153 
1154 #if PICO_PIO_VERSION > 0
1155 /*! \brief Restart multiple state machines' clock dividers on multiple PIOs from a phase of 0.
1156  *  \ingroup hardware_pio
1157  *
1158  * Each state machine's clock divider is a free-running piece of hardware,
1159  * that generates a pattern of clock enable pulses for the state machine,
1160  * based *only* on the configured integer/fractional divisor. The pattern of
1161  * running/halted cycles slows the state machine's execution to some
1162  * controlled rate.
1163  *
1164  * This function simultaneously clears the integer and fractional phase
1165  * accumulators of multiple state machines' clock dividers. If these state
1166  * machines all have the same integer and fractional divisors configured,
1167  * their clock dividers will run in precise deterministic lockstep from this
1168  * point.
1169  *
1170  * With their execution clocks synchronised in this way, it is then safe to
1171  * e.g. have multiple state machines performing a 'wait irq' on the same flag,
1172  * and all clear it on the same cycle.
1173  *
1174  * Also note that this function can be called whilst state machines are
1175  * running (e.g. if you have just changed the clock divisors of some state
1176  * machines and wish to resynchronise them), and that disabling a state
1177  * machine does not halt its clock divider: that is, if multiple state
1178  * machines have their clocks synchronised, you can safely disable and
1179  * re-enable one of the state machines without losing synchronisation.
1180  *
1181  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1182  * \param mask_prev bit mask of state machine indexes to modify the enabled state of, in the next-lower numbered PIO instance
1183  * \param mask bit mask of state machine indexes to modify the enabled state of, in this PIO instance
1184  * \param mask_next bit mask of state machine indexes to modify the enabled state of, in the next-higher numbered PIO instance
1185  */
pio_clkdiv_restart_sm_multi_mask(PIO pio,uint32_t mask_prev,uint32_t mask,uint32_t mask_next)1186 static inline void pio_clkdiv_restart_sm_multi_mask(PIO pio, uint32_t mask_prev, uint32_t mask, uint32_t mask_next) {
1187     check_pio_param(pio);
1188     check_sm_mask(mask);
1189     hw_set_bits(&pio->ctrl, ((mask << PIO_CTRL_CLKDIV_RESTART_LSB) & PIO_CTRL_CLKDIV_RESTART_BITS) |
1190                             PIO_CTRL_NEXTPREV_CLKDIV_RESTART_BITS |
1191                             ((mask_prev << PIO_CTRL_PREV_PIO_MASK_LSB) & PIO_CTRL_PREV_PIO_MASK_BITS) |
1192                             ((mask_next << PIO_CTRL_NEXT_PIO_MASK_LSB) & PIO_CTRL_NEXT_PIO_MASK_BITS));
1193 }
1194 #endif
1195 
1196 /*! \brief Enable multiple PIO state machines synchronizing their clock dividers
1197  *  \ingroup hardware_pio
1198  *
1199  * This is equivalent to calling both pio_set_sm_mask_enabled() and
1200  * pio_clkdiv_restart_sm_mask() on the *same* clock cycle. All state machines
1201  * specified by 'mask' are started simultaneously and, assuming they have the
1202  * same clock divisors, their divided clocks will stay precisely synchronised.
1203  *
1204  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1205  * \param mask bit mask of state machine indexes to modify the enabled state of
1206  */
pio_enable_sm_mask_in_sync(PIO pio,uint32_t mask)1207 static inline void pio_enable_sm_mask_in_sync(PIO pio, uint32_t mask) {
1208     check_pio_param(pio);
1209     check_sm_mask(mask);
1210     hw_set_bits(&pio->ctrl,
1211         ((mask << PIO_CTRL_CLKDIV_RESTART_LSB) & PIO_CTRL_CLKDIV_RESTART_BITS) |
1212         ((mask << PIO_CTRL_SM_ENABLE_LSB) & PIO_CTRL_SM_ENABLE_BITS));
1213 }
1214 
1215 #if PICO_PIO_VERSION > 0
1216 /*! \brief Enable multiple PIO state machines on multiple PIOs synchronizing their clock dividers
1217  *  \ingroup hardware_pio
1218  *
1219  * This is equivalent to calling both pio_set_sm_multi_mask_enabled() and
1220  * pio_clkdiv_restart_sm_multi_mask() on the *same* clock cycle. All state machines
1221  * specified by 'mask' are started simultaneously and, assuming they have the
1222  * same clock divisors, their divided clocks will stay precisely synchronised.
1223  *
1224  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1225  * \param mask_prev bit mask of state machine indexes to modify the enabled state of, in the next-lower numbered PIO instance
1226  * \param mask bit mask of state machine indexes to modify the enabled state of, in this PIO instance
1227  * \param mask_next bit mask of state machine indexes to modify the enabled state of, in the next-higher numbered PIO instance
1228  */
pio_enable_sm_multi_mask_in_sync(PIO pio,uint32_t mask_prev,uint32_t mask,uint32_t mask_next)1229 static inline void pio_enable_sm_multi_mask_in_sync(PIO pio, uint32_t mask_prev, uint32_t mask, uint32_t mask_next) {
1230     check_pio_param(pio);
1231     check_sm_mask(mask);
1232     check_pio_param(pio);
1233     check_sm_mask(mask);
1234     hw_set_bits(&pio->ctrl, ((mask << PIO_CTRL_CLKDIV_RESTART_LSB) & PIO_CTRL_CLKDIV_RESTART_BITS) |
1235                             ((mask << PIO_CTRL_SM_ENABLE_LSB) & PIO_CTRL_SM_ENABLE_BITS) |
1236                             PIO_CTRL_NEXTPREV_CLKDIV_RESTART_BITS | PIO_CTRL_NEXTPREV_SM_ENABLE_BITS |
1237                             ((mask_prev << PIO_CTRL_PREV_PIO_MASK_LSB) & PIO_CTRL_PREV_PIO_MASK_BITS) |
1238                             ((mask_next << PIO_CTRL_NEXT_PIO_MASK_LSB) & PIO_CTRL_NEXT_PIO_MASK_BITS));
1239 }
1240 #endif
1241 
1242 /*! \brief PIO interrupt source numbers for pio related IRQs
1243  * \ingroup hardware_pio
1244  */
1245 typedef enum pio_interrupt_source {
1246     pis_interrupt0 = PIO_INTR_SM0_LSB,                        ///< PIO interrupt 0 is raised
1247     pis_interrupt1 = PIO_INTR_SM1_LSB,                        ///< PIO interrupt 1 is raised
1248     pis_interrupt2 = PIO_INTR_SM2_LSB,                        ///< PIO interrupt 2 is raised
1249     pis_interrupt3 = PIO_INTR_SM3_LSB,                        ///< PIO interrupt 3 is raised
1250 #if PICO_PIO_VERSION > 0
1251     pis_interrupt4 = PIO_INTR_SM4_LSB,                        ///< PIO interrupt 4 is raised
1252     pis_interrupt5 = PIO_INTR_SM5_LSB,                        ///< PIO interrupt 5 is raised
1253     pis_interrupt6 = PIO_INTR_SM6_LSB,                        ///< PIO interrupt 6 is raised
1254     pis_interrupt7 = PIO_INTR_SM7_LSB,                        ///< PIO interrupt 7 is raised
1255 #endif
1256     pis_sm0_tx_fifo_not_full = PIO_INTR_SM0_TXNFULL_LSB,      ///< State machine 0 TX FIFO is not full
1257     pis_sm1_tx_fifo_not_full = PIO_INTR_SM1_TXNFULL_LSB,      ///< State machine 1 TX FIFO is not full
1258     pis_sm2_tx_fifo_not_full = PIO_INTR_SM2_TXNFULL_LSB,      ///< State machine 2 TX FIFO is not full
1259     pis_sm3_tx_fifo_not_full = PIO_INTR_SM3_TXNFULL_LSB,      ///< State machine 3 TX FIFO is not full
1260     pis_sm0_rx_fifo_not_empty = PIO_INTR_SM0_RXNEMPTY_LSB,    ///< State machine 0 RX FIFO is not empty
1261     pis_sm1_rx_fifo_not_empty = PIO_INTR_SM1_RXNEMPTY_LSB,    ///< State machine 1 RX FIFO is not empty
1262     pis_sm2_rx_fifo_not_empty = PIO_INTR_SM2_RXNEMPTY_LSB,    ///< State machine 2 RX FIFO is not empty
1263     pis_sm3_rx_fifo_not_empty = PIO_INTR_SM3_RXNEMPTY_LSB,    ///< State machine 3 RX FIFO is not empty
1264 } pio_interrupt_source_t;
1265 
1266 /*! \brief  Enable/Disable a single source on a PIO's IRQ 0
1267  *  \ingroup hardware_pio
1268  *
1269  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1270  * \param source the source number (see \ref pio_interrupt_source)
1271  * \param enabled true to enable IRQ 0 for the source, false to disable.
1272  */
pio_set_irq0_source_enabled(PIO pio,pio_interrupt_source_t source,bool enabled)1273 static inline void pio_set_irq0_source_enabled(PIO pio, pio_interrupt_source_t source, bool enabled) {
1274     check_pio_param(pio);
1275     invalid_params_if(HARDWARE_PIO, source >= 32u || (1u << source) > PIO_INTR_BITS);
1276     if (enabled)
1277         hw_set_bits(&pio->inte0, 1u << source);
1278     else
1279         hw_clear_bits(&pio->inte0, 1u << source);
1280 }
1281 
1282 /*! \brief  Enable/Disable a single source on a PIO's IRQ 1
1283  *  \ingroup hardware_pio
1284  *
1285  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1286  * \param source the source number (see \ref pio_interrupt_source)
1287  * \param enabled true to enable IRQ 0 for the source, false to disable.
1288  */
pio_set_irq1_source_enabled(PIO pio,pio_interrupt_source_t source,bool enabled)1289 static inline void pio_set_irq1_source_enabled(PIO pio, pio_interrupt_source_t source, bool enabled) {
1290     check_pio_param(pio);
1291     invalid_params_if(HARDWARE_PIO, source >= 32 || (1u << source) > PIO_INTR_BITS);
1292     if (enabled)
1293         hw_set_bits(&pio->inte1, 1u << source);
1294     else
1295         hw_clear_bits(&pio->inte1, 1u << source);
1296 }
1297 
1298 /*! \brief  Enable/Disable multiple sources on a PIO's IRQ 0
1299  *  \ingroup hardware_pio
1300  *
1301  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1302  * \param source_mask Mask of bits, one for each source number (see \ref pio_interrupt_source) to affect
1303  * \param enabled true to enable all the sources specified in the mask on IRQ 0, false to disable all the sources specified in the mask on IRQ 0
1304  */
pio_set_irq0_source_mask_enabled(PIO pio,uint32_t source_mask,bool enabled)1305 static inline void pio_set_irq0_source_mask_enabled(PIO pio, uint32_t source_mask, bool enabled) {
1306     check_pio_param(pio);
1307     invalid_params_if(HARDWARE_PIO, source_mask > PIO_INTR_BITS);
1308     if (enabled) {
1309         hw_set_bits(&pio->inte0, source_mask);
1310     } else {
1311         hw_clear_bits(&pio->inte0, source_mask);
1312     }
1313 }
1314 
1315 /*! \brief  Enable/Disable multiple sources on a PIO's IRQ 1
1316  *  \ingroup hardware_pio
1317  *
1318  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1319  * \param source_mask Mask of bits, one for each source number (see \ref pio_interrupt_source) to affect
1320  * \param enabled true to enable all the sources specified in the mask on IRQ 1, false to disable all the source specified in the mask on IRQ 1
1321  */
pio_set_irq1_source_mask_enabled(PIO pio,uint32_t source_mask,bool enabled)1322 static inline void pio_set_irq1_source_mask_enabled(PIO pio, uint32_t source_mask, bool enabled) {
1323     check_pio_param(pio);
1324     invalid_params_if(HARDWARE_PIO, source_mask > PIO_INTR_BITS);
1325     if (enabled) {
1326         hw_set_bits(&pio->inte1, source_mask);
1327     } else {
1328         hw_clear_bits(&pio->inte1, source_mask);
1329     }
1330 }
1331 
1332 /*! \brief  Enable/Disable a single source on a PIO's specified (0/1) IRQ index
1333  *  \ingroup hardware_pio
1334  *
1335  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1336  * \param irq_index the IRQ index; either 0 or 1
1337  * \param source the source number (see \ref pio_interrupt_source)
1338  * \param enabled true to enable the source on the specified IRQ, false to disable.
1339  */
pio_set_irqn_source_enabled(PIO pio,uint irq_index,pio_interrupt_source_t source,bool enabled)1340 static inline void pio_set_irqn_source_enabled(PIO pio, uint irq_index, pio_interrupt_source_t source, bool enabled) {
1341     invalid_params_if(HARDWARE_PIO, irq_index > NUM_PIO_IRQS);
1342     invalid_params_if(HARDWARE_PIO, source >= 32 || (1u << source) > PIO_INTR_BITS);
1343     if (enabled)
1344         hw_set_bits(&pio->irq_ctrl[irq_index].inte, 1u << source);
1345     else
1346         hw_clear_bits(&pio->irq_ctrl[irq_index].inte, 1u << source);
1347 }
1348 
1349 /*! \brief  Enable/Disable multiple sources on a PIO's specified (0/1) IRQ index
1350  *  \ingroup hardware_pio
1351  *
1352  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1353  * \param irq_index the IRQ index; either 0 or 1
1354  * \param source_mask Mask of bits, one for each source number (see \ref pio_interrupt_source) to affect
1355  * \param enabled true to enable all the sources specified in the mask on the specified IRQ, false to disable all the sources specified in the mask on the specified IRQ
1356  */
pio_set_irqn_source_mask_enabled(PIO pio,uint irq_index,uint32_t source_mask,bool enabled)1357 static inline void pio_set_irqn_source_mask_enabled(PIO pio, uint irq_index, uint32_t source_mask, bool enabled) {
1358     invalid_params_if(HARDWARE_PIO, irq_index > NUM_PIO_IRQS);
1359     static_assert(NUM_PIO_IRQS == 2, "");
1360     invalid_params_if(HARDWARE_PIO, source_mask > PIO_INTR_BITS);
1361     if (enabled) {
1362         hw_set_bits(&pio->irq_ctrl[irq_index].inte, source_mask);
1363     } else {
1364         hw_clear_bits(&pio->irq_ctrl[irq_index].inte, source_mask);
1365     }
1366 }
1367 
1368 /*! \brief  Determine if a particular PIO interrupt is set
1369  *  \ingroup hardware_pio
1370  *
1371  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1372  * \param pio_interrupt_num the PIO interrupt number 0-7
1373  * \return true if corresponding PIO interrupt is currently set
1374  */
pio_interrupt_get(PIO pio,uint pio_interrupt_num)1375 static inline bool pio_interrupt_get(PIO pio, uint pio_interrupt_num) {
1376     check_pio_param(pio);
1377     invalid_params_if(HARDWARE_PIO, pio_interrupt_num >= 8);
1378     return pio->irq & (1u << pio_interrupt_num);
1379 }
1380 
1381 /*! \brief  Clear a particular PIO interrupt
1382  *  \ingroup hardware_pio
1383  *
1384  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1385  * \param pio_interrupt_num the PIO interrupt number 0-7
1386  */
pio_interrupt_clear(PIO pio,uint pio_interrupt_num)1387 static inline void pio_interrupt_clear(PIO pio, uint pio_interrupt_num) {
1388     check_pio_param(pio);
1389     invalid_params_if(HARDWARE_PIO, pio_interrupt_num >= 8);
1390     pio->irq = (1u << pio_interrupt_num);
1391 }
1392 
1393 /*! \brief Return the current program counter for a state machine
1394  *  \ingroup hardware_pio
1395  *
1396  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1397  * \param sm State machine index (0..3)
1398  * \return the program counter
1399  */
pio_sm_get_pc(PIO pio,uint sm)1400 static inline uint8_t pio_sm_get_pc(PIO pio, uint sm) {
1401     check_pio_param(pio);
1402     check_sm_param(sm);
1403     return (uint8_t) pio->sm[sm].addr;
1404 }
1405 
1406 /*! \brief Immediately execute an instruction on a state machine
1407  *  \ingroup hardware_pio
1408  *
1409  * This instruction is executed instead of the next instruction in the normal control flow on the state machine.
1410  * Subsequent calls to this method replace the previous executed
1411  * instruction if it is still running. \see pio_sm_is_exec_stalled() to see if an executed instruction
1412  * is still running (i.e. it is stalled on some condition)
1413  *
1414  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1415  * \param sm State machine index (0..3)
1416  * \param instr the encoded PIO instruction
1417  */
pio_sm_exec(PIO pio,uint sm,uint instr)1418 inline static void pio_sm_exec(PIO pio, uint sm, uint instr) {
1419     check_pio_param(pio);
1420     check_sm_param(sm);
1421     pio->sm[sm].instr = instr;
1422 }
1423 
1424 /*! \brief Determine if an instruction set by pio_sm_exec() is stalled executing
1425  *  \ingroup hardware_pio
1426  *
1427  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1428  * \param sm State machine index (0..3)
1429  * \return true if the executed instruction is still running (stalled)
1430  */
pio_sm_is_exec_stalled(PIO pio,uint sm)1431 static inline bool pio_sm_is_exec_stalled(PIO pio, uint sm) {
1432     check_pio_param(pio);
1433     check_sm_param(sm);
1434     return pio->sm[sm].execctrl & PIO_SM0_EXECCTRL_EXEC_STALLED_BITS;
1435 }
1436 
1437 /*! \brief Immediately execute an instruction on a state machine and wait for it to complete
1438  *  \ingroup hardware_pio
1439  *
1440  * This instruction is executed instead of the next instruction in the normal control flow on the state machine.
1441  * Subsequent calls to this method replace the previous executed
1442  * instruction if it is still running. \see pio_sm_is_exec_stalled() to see if an executed instruction
1443  * is still running (i.e. it is stalled on some condition)
1444  *
1445  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1446  * \param sm State machine index (0..3)
1447  * \param instr the encoded PIO instruction
1448  */
pio_sm_exec_wait_blocking(PIO pio,uint sm,uint instr)1449 static inline void pio_sm_exec_wait_blocking(PIO pio, uint sm, uint instr) {
1450     check_pio_param(pio);
1451     check_sm_param(sm);
1452     pio_sm_exec(pio, sm, instr);
1453     while (pio_sm_is_exec_stalled(pio, sm)) tight_loop_contents();
1454 }
1455 
1456 /*! \brief Set the current wrap configuration for a state machine
1457  *  \ingroup hardware_pio
1458  *
1459  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1460  * \param sm State machine index (0..3)
1461  * \param wrap_target the instruction memory address to wrap to
1462  * \param wrap        the instruction memory address after which to set the program counter to wrap_target
1463  *                    if the instruction does not itself update the program_counter
1464  */
pio_sm_set_wrap(PIO pio,uint sm,uint wrap_target,uint wrap)1465 static inline void pio_sm_set_wrap(PIO pio, uint sm, uint wrap_target, uint wrap) {
1466     check_pio_param(pio);
1467     check_sm_param(sm);
1468     valid_params_if(HARDWARE_PIO, wrap < PIO_INSTRUCTION_COUNT);
1469     valid_params_if(HARDWARE_PIO, wrap_target < PIO_INSTRUCTION_COUNT);
1470     pio->sm[sm].execctrl =
1471             (pio->sm[sm].execctrl & ~(PIO_SM0_EXECCTRL_WRAP_TOP_BITS | PIO_SM0_EXECCTRL_WRAP_BOTTOM_BITS)) |
1472             (wrap_target << PIO_SM0_EXECCTRL_WRAP_BOTTOM_LSB) |
1473             (wrap << PIO_SM0_EXECCTRL_WRAP_TOP_LSB);
1474 }
1475 
1476 /*! \brief Set the current 'out' pins for a state machine
1477  *  \ingroup hardware_pio
1478  *
1479  * 'out' pins can overlap with the 'in', 'set' and 'sideset' pins
1480  *
1481  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1482  * \param sm State machine index (0..3)
1483  * \param out_base First pin to set as output. See \ref pio_sm_pins "pio_sm_ pins" for more detail on pin arguments
1484  * \param out_count 0-32 Number of pins to set.
1485  */
pio_sm_set_out_pins(PIO pio,uint sm,uint out_base,uint out_count)1486 static inline void pio_sm_set_out_pins(PIO pio, uint sm, uint out_base, uint out_count) {
1487     check_pio_param(pio);
1488     check_sm_param(sm);
1489 #if PICO_PIO_USE_GPIO_BASE
1490     out_base -= pio_get_gpio_base(pio);
1491 #endif
1492     valid_params_if(HARDWARE_PIO, out_base < 32);
1493     valid_params_if(HARDWARE_PIO, out_count <= 32);
1494     pio->sm[sm].pinctrl = (pio->sm[sm].pinctrl & ~(PIO_SM0_PINCTRL_OUT_BASE_BITS | PIO_SM0_PINCTRL_OUT_COUNT_BITS)) |
1495                  (out_base << PIO_SM0_PINCTRL_OUT_BASE_LSB) |
1496                  (out_count << PIO_SM0_PINCTRL_OUT_COUNT_LSB);
1497 }
1498 
1499 
1500 /*! \brief Set the current 'set' pins for a state machine
1501  *  \ingroup hardware_pio
1502  *
1503  * 'set' pins can overlap with the 'in', 'out' and 'sideset' pins
1504  *
1505  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1506  * \param sm State machine index (0..3)
1507  * \param set_base First pin to set as 'set'. See \ref pio_sm_pins "pio_sm_ pins" for more detail on pin arguments
1508  * \param set_count 0-5 Number of pins to set.
1509  */
pio_sm_set_set_pins(PIO pio,uint sm,uint set_base,uint set_count)1510 static inline void pio_sm_set_set_pins(PIO pio, uint sm, uint set_base, uint set_count) {
1511     check_pio_param(pio);
1512     check_sm_param(sm);
1513 #if PICO_PIO_USE_GPIO_BASE
1514     set_base -= pio_get_gpio_base(pio);
1515 #endif
1516     valid_params_if(HARDWARE_PIO, set_base < 32);
1517     valid_params_if(HARDWARE_PIO, set_count <= 5);
1518     pio->sm[sm].pinctrl = (pio->sm[sm].pinctrl & ~(PIO_SM0_PINCTRL_SET_BASE_BITS | PIO_SM0_PINCTRL_SET_COUNT_BITS)) |
1519                  (set_base << PIO_SM0_PINCTRL_SET_BASE_LSB) |
1520                  (set_count << PIO_SM0_PINCTRL_SET_COUNT_LSB);
1521 }
1522 
1523 /*! \brief Set the current 'in' pins for a state machine
1524  *  \ingroup hardware_pio
1525  *
1526  * 'in' pins can overlap with the 'out', 'set' and 'sideset' pins
1527  *
1528  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1529  * \param sm State machine index (0..3)
1530  * \param in_base First pin to use as input. See \ref pio_sm_pins "pio_sm_ pins" for more detail on pin arguments
1531  */
pio_sm_set_in_pins(PIO pio,uint sm,uint in_base)1532 static inline void pio_sm_set_in_pins(PIO pio, uint sm, uint in_base) {
1533     check_pio_param(pio);
1534     check_sm_param(sm);
1535 #if PICO_PIO_USE_GPIO_BASE
1536     in_base -= pio_get_gpio_base(pio);
1537 #endif
1538     valid_params_if(HARDWARE_PIO, in_base < 32);
1539     pio->sm[sm].pinctrl = (pio->sm[sm].pinctrl & ~PIO_SM0_PINCTRL_IN_BASE_BITS) |
1540                  (in_base << PIO_SM0_PINCTRL_IN_BASE_LSB);
1541 }
1542 
1543 /*! \brief Set the current 'sideset' pins for a state machine
1544  *  \ingroup hardware_pio
1545  *
1546  * 'sideset' pins can overlap with the 'in', 'out' and 'set' pins
1547  *
1548  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1549  * \param sm State machine index (0..3)
1550  * \param sideset_base Base pin for 'side set'. See \ref pio_sm_pins "pio_sm_ pins" for more detail on pin arguments
1551  */
pio_sm_set_sideset_pins(PIO pio,uint sm,uint sideset_base)1552 static inline void pio_sm_set_sideset_pins(PIO pio, uint sm, uint sideset_base) {
1553     check_pio_param(pio);
1554     check_sm_param(sm);
1555 #if PICO_PIO_USE_GPIO_BASE
1556     sideset_base -= pio_get_gpio_base(pio);
1557 #endif
1558     valid_params_if(HARDWARE_PIO, sideset_base < 32);
1559     pio->sm[sm].pinctrl = (pio->sm[sm].pinctrl & ~PIO_SM0_PINCTRL_SIDESET_BASE_BITS) |
1560                  (sideset_base << PIO_SM0_PINCTRL_SIDESET_BASE_LSB);
1561 }
1562 
1563 /*! \brief Set the 'jmp' pin for a state machine
1564  *  \ingroup hardware_pio
1565  *
1566  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1567  * \param sm State machine index (0..3)
1568  * \param pin The pin number to use as the source for a `jmp pin` instruction. See \ref pio_sm_pins "pio_sm_ pins" for more detail on pin arguments
1569  */
1570 
pio_sm_set_jmp_pin(PIO pio,uint sm,uint pin)1571 static inline void pio_sm_set_jmp_pin(PIO pio, uint sm, uint pin) {
1572     check_pio_param(pio);
1573     check_sm_param(sm);
1574 #if PICO_PIO_USE_GPIO_BASE
1575     pin -= pio_get_gpio_base(pio);
1576 #endif
1577     valid_params_if(HARDWARE_PIO, pin < 32);
1578     pio->sm[sm].execctrl =
1579         (pio->sm[sm].execctrl & ~PIO_SM0_EXECCTRL_JMP_PIN_BITS)
1580         | (pin << PIO_SM0_EXECCTRL_JMP_PIN_LSB);
1581 }
1582 
1583 /*! \brief Write a word of data to a state machine's TX FIFO
1584  *  \ingroup hardware_pio
1585  *
1586  * This is a raw FIFO access that does not check for fullness. If the FIFO is
1587  * full, the FIFO contents and state are not affected by the write attempt.
1588  * Hardware sets the TXOVER sticky flag for this FIFO in FDEBUG, to indicate
1589  * that the system attempted to write to a full FIFO.
1590  *
1591  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1592  * \param sm State machine index (0..3)
1593  * \param data the 32 bit data value
1594  *
1595  * \sa pio_sm_put_blocking()
1596  */
pio_sm_put(PIO pio,uint sm,uint32_t data)1597 static inline void pio_sm_put(PIO pio, uint sm, uint32_t data) {
1598     check_pio_param(pio);
1599     check_sm_param(sm);
1600     pio->txf[sm] = data;
1601 }
1602 
1603 /*! \brief Read a word of data from a state machine's RX FIFO
1604  *  \ingroup hardware_pio
1605  *
1606  * This is a raw FIFO access that does not check for emptiness. If the FIFO is
1607  * empty, the hardware ignores the attempt to read from the FIFO (the FIFO
1608  * remains in an empty state following the read) and the sticky RXUNDER flag
1609  * for this FIFO is set in FDEBUG to indicate that the system tried to read
1610  * from this FIFO when empty. The data returned by this function is undefined
1611  * when the FIFO is empty.
1612  *
1613  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1614  * \param sm State machine index (0..3)
1615  *
1616  * \sa pio_sm_get_blocking()
1617  */
pio_sm_get(PIO pio,uint sm)1618 static inline uint32_t pio_sm_get(PIO pio, uint sm) {
1619     check_pio_param(pio);
1620     check_sm_param(sm);
1621     return pio->rxf[sm];
1622 }
1623 
1624 /*! \brief Determine if a state machine's RX FIFO is full
1625  *  \ingroup hardware_pio
1626  *
1627  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1628  * \param sm State machine index (0..3)
1629  * \return true if the RX FIFO is full
1630  */
pio_sm_is_rx_fifo_full(PIO pio,uint sm)1631 static inline bool pio_sm_is_rx_fifo_full(PIO pio, uint sm) {
1632     check_pio_param(pio);
1633     check_sm_param(sm);
1634     return (pio->fstat & (1u << (PIO_FSTAT_RXFULL_LSB + sm))) != 0;
1635 }
1636 
1637 /*! \brief Determine if a state machine's RX FIFO is empty
1638  *  \ingroup hardware_pio
1639  *
1640  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1641  * \param sm State machine index (0..3)
1642  * \return true if the RX FIFO is empty
1643  */
pio_sm_is_rx_fifo_empty(PIO pio,uint sm)1644 static inline bool pio_sm_is_rx_fifo_empty(PIO pio, uint sm) {
1645     check_pio_param(pio);
1646     check_sm_param(sm);
1647     return (pio->fstat & (1u << (PIO_FSTAT_RXEMPTY_LSB + sm))) != 0;
1648 }
1649 
1650 /*! \brief Return the number of elements currently in a state machine's RX FIFO
1651  *  \ingroup hardware_pio
1652  *
1653  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1654  * \param sm State machine index (0..3)
1655  * \return the number of elements in the RX FIFO
1656  */
pio_sm_get_rx_fifo_level(PIO pio,uint sm)1657 static inline uint pio_sm_get_rx_fifo_level(PIO pio, uint sm) {
1658     check_pio_param(pio);
1659     check_sm_param(sm);
1660     uint bitoffs = PIO_FLEVEL_RX0_LSB + sm * (PIO_FLEVEL_RX1_LSB - PIO_FLEVEL_RX0_LSB);
1661     const uint32_t mask = PIO_FLEVEL_RX0_BITS >> PIO_FLEVEL_RX0_LSB;
1662     return (pio->flevel >> bitoffs) & mask;
1663 }
1664 
1665 /*! \brief Determine if a state machine's TX FIFO is full
1666  *  \ingroup hardware_pio
1667  *
1668  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1669  * \param sm State machine index (0..3)
1670  * \return true if the TX FIFO is full
1671  */
pio_sm_is_tx_fifo_full(PIO pio,uint sm)1672 static inline bool pio_sm_is_tx_fifo_full(PIO pio, uint sm) {
1673     check_pio_param(pio);
1674     check_sm_param(sm);
1675     return (pio->fstat & (1u << (PIO_FSTAT_TXFULL_LSB + sm))) != 0;
1676 }
1677 
1678 /*! \brief Determine if a state machine's TX FIFO is empty
1679  *  \ingroup hardware_pio
1680  *
1681  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1682  * \param sm State machine index (0..3)
1683  * \return true if the TX FIFO is empty
1684  */
pio_sm_is_tx_fifo_empty(PIO pio,uint sm)1685 static inline bool pio_sm_is_tx_fifo_empty(PIO pio, uint sm) {
1686     check_pio_param(pio);
1687     check_sm_param(sm);
1688     return (pio->fstat & (1u << (PIO_FSTAT_TXEMPTY_LSB + sm))) != 0;
1689 }
1690 
1691 /*! \brief Return the number of elements currently in a state machine's TX FIFO
1692  *  \ingroup hardware_pio
1693  *
1694  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1695  * \param sm State machine index (0..3)
1696  * \return the number of elements in the TX FIFO
1697  */
pio_sm_get_tx_fifo_level(PIO pio,uint sm)1698 static inline uint pio_sm_get_tx_fifo_level(PIO pio, uint sm) {
1699     check_pio_param(pio);
1700     check_sm_param(sm);
1701     unsigned int bitoffs = PIO_FLEVEL_TX0_LSB + sm * (PIO_FLEVEL_TX1_LSB - PIO_FLEVEL_TX0_LSB);
1702     const uint32_t mask = PIO_FLEVEL_TX0_BITS >> PIO_FLEVEL_TX0_LSB;
1703     return (pio->flevel >> bitoffs) & mask;
1704 }
1705 
1706 /*! \brief Write a word of data to a state machine's TX FIFO, blocking if the FIFO is full
1707  *  \ingroup hardware_pio
1708  *
1709  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1710  * \param sm State machine index (0..3)
1711  * \param data the 32 bit data value
1712  */
pio_sm_put_blocking(PIO pio,uint sm,uint32_t data)1713 static inline void pio_sm_put_blocking(PIO pio, uint sm, uint32_t data) {
1714     check_pio_param(pio);
1715     check_sm_param(sm);
1716     while (pio_sm_is_tx_fifo_full(pio, sm)) tight_loop_contents();
1717     pio_sm_put(pio, sm, data);
1718 }
1719 
1720 /*! \brief Read a word of data from a state machine's RX FIFO, blocking if the FIFO is empty
1721  *  \ingroup hardware_pio
1722  *
1723  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1724  * \param sm State machine index (0..3)
1725  */
pio_sm_get_blocking(PIO pio,uint sm)1726 static inline uint32_t pio_sm_get_blocking(PIO pio, uint sm) {
1727     check_pio_param(pio);
1728     check_sm_param(sm);
1729     while (pio_sm_is_rx_fifo_empty(pio, sm)) tight_loop_contents();
1730     return pio_sm_get(pio, sm);
1731 }
1732 
1733 /*! \brief Empty out a state machine's TX FIFO
1734  *  \ingroup hardware_pio
1735  *
1736  * This method executes `pull` instructions on the state machine until the TX
1737  * FIFO is empty. This disturbs the contents of the OSR, so see also
1738  * pio_sm_clear_fifos() which clears both FIFOs but leaves the state machine's
1739  * internal state undisturbed.
1740  *
1741  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1742  * \param sm State machine index (0..3)
1743  *
1744  * \sa pio_sm_clear_fifos()
1745  */
1746 void pio_sm_drain_tx_fifo(PIO pio, uint sm);
1747 
1748 /*! \brief set the current clock divider for a state machine using a 16:8 fraction
1749  *  \ingroup hardware_pio
1750  *
1751  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1752  * \param sm State machine index (0..3)
1753  * \param div_int the integer part of the clock divider
1754  * \param div_frac8 the fractional part of the clock divider in 1/256s
1755  */
pio_sm_set_clkdiv_int_frac8(PIO pio,uint sm,uint32_t div_int,uint8_t div_frac8)1756 static inline void pio_sm_set_clkdiv_int_frac8(PIO pio, uint sm, uint32_t div_int, uint8_t div_frac8) {
1757     check_pio_param(pio);
1758     check_sm_param(sm);
1759     static_assert(REG_FIELD_WIDTH(PIO_SM0_CLKDIV_INT) == 16, "");
1760     invalid_params_if(HARDWARE_PIO, div_int >> 16);
1761     invalid_params_if(HARDWARE_PIO, div_int == 0 && div_frac8 != 0);
1762     static_assert(REG_FIELD_WIDTH(PIO_SM0_CLKDIV_FRAC) == 8, "");
1763     pio->sm[sm].clkdiv =
1764             (((uint)div_frac8) << PIO_SM0_CLKDIV_FRAC_LSB) |
1765             (((uint)div_int) << PIO_SM0_CLKDIV_INT_LSB);
1766 }
1767 
1768 // backwards compatibility
pio_sm_set_clkdiv_int_frac(PIO pio,uint sm,uint16_t div_int,uint8_t div_frac8)1769 static inline void pio_sm_set_clkdiv_int_frac(PIO pio, uint sm, uint16_t div_int, uint8_t div_frac8) {
1770     pio_sm_set_clkdiv_int_frac8(pio, sm, div_int, div_frac8);
1771 }
1772 
1773 /*! \brief set the current clock divider for a state machine
1774  *  \ingroup hardware_pio
1775  *
1776  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1777  * \param sm State machine index (0..3)
1778  * \param div the floating point clock divider
1779  */
pio_sm_set_clkdiv(PIO pio,uint sm,float div)1780 static inline void pio_sm_set_clkdiv(PIO pio, uint sm, float div) {
1781     check_pio_param(pio);
1782     check_sm_param(sm);
1783     uint32_t div_int;
1784     uint8_t div_frac8;
1785     pio_calculate_clkdiv8_from_float(div, &div_int, &div_frac8);
1786     pio_sm_set_clkdiv_int_frac8(pio, sm, div_int, div_frac8);
1787 }
1788 
1789 /*! \brief Clear a state machine's TX and RX FIFOs
1790  *  \ingroup hardware_pio
1791  *
1792  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1793  * \param sm State machine index (0..3)
1794  */
pio_sm_clear_fifos(PIO pio,uint sm)1795 static inline void pio_sm_clear_fifos(PIO pio, uint sm) {
1796     // changing the FIFO join state clears the fifo
1797     check_pio_param(pio);
1798     check_sm_param(sm);
1799     hw_xor_bits(&pio->sm[sm].shiftctrl, PIO_SM0_SHIFTCTRL_FJOIN_RX_BITS);
1800     hw_xor_bits(&pio->sm[sm].shiftctrl, PIO_SM0_SHIFTCTRL_FJOIN_RX_BITS);
1801 }
1802 
1803 /*! \brief Use a state machine to set a value on all pins for the PIO instance
1804  *  \ingroup hardware_pio
1805  *
1806  * This method repeatedly reconfigures the target state machine's pin configuration and executes 'set' instructions to set values on all 32 pins,
1807  * before restoring the state machine's pin configuration to what it was.
1808  *
1809  * This method is provided as a convenience to set initial pin states, and should not be used against a state machine that is enabled.
1810  * Note: This method only works for pins < 32. To use with pins >= 32 call pio_sm_set_pins64
1811  *
1812  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1813  * \param sm State machine index (0..3) to use
1814  * \param pin_values the pin values to set. See \ref pio_sm_pins "pio_sm_ pins" for more detail on pin arguments
1815  */
1816 void pio_sm_set_pins(PIO pio, uint sm, uint32_t pin_values);
1817 
1818 /*! \brief Use a state machine to set a value on all pins for the PIO instance
1819  *  \ingroup hardware_pio
1820  *
1821  * This method repeatedly reconfigures the target state machine's pin configuration and executes 'set' instructions to set values on all 32 pins,
1822  * before restoring the state machine's pin configuration to what it was.
1823  *
1824  * This method is provided as a convenience to set initial pin states, and should not be used against a state machine that is enabled.
1825  *
1826  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1827  * \param sm State machine index (0..3) to use
1828  * \param pin_values the pin values to set. See \ref pio_sm_pins "pio_sm_ pins" for more detail on pin arguments
1829  */
1830 void pio_sm_set_pins64(PIO pio, uint sm, uint64_t pin_values);
1831 
1832 /*! \brief Use a state machine to set a value on multiple pins for the PIO instance
1833  *  \ingroup hardware_pio
1834  *
1835  * This method repeatedly reconfigures the target state machine's pin configuration and executes 'set' instructions to set values on up to 32 pins,
1836  * before restoring the state machine's pin configuration to what it was.
1837  *
1838  * This method is provided as a convenience to set initial pin states, and should not be used against a state machine that is enabled.
1839 * Note: This method only works for pins < 32. To use with pins >= 32 call pio_sm_set_pins_with_mask64
1840  *
1841  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1842  * \param sm State machine index (0..3) to use
1843  * \param pin_values the pin values to set (if the corresponding bit in pin_mask is set)
1844  * \param pin_mask a bit for each pin to indicate whether the corresponding pin_value for that pin should be applied. See \ref pio_sm_pins "pio_sm_ pins" for more detail on pin arguments
1845  */
1846 void pio_sm_set_pins_with_mask(PIO pio, uint sm, uint32_t pin_values, uint32_t pin_mask);
1847 
1848 /*! \brief Use a state machine to set a value on multiple pins for the PIO instance
1849  *  \ingroup hardware_pio
1850  *
1851  * This method repeatedly reconfigures the target state machine's pin configuration and executes 'set' instructions to set values on up to 32 pins,
1852  * before restoring the state machine's pin configuration to what it was.
1853  *
1854  * This method is provided as a convenience to set initial pin states, and should not be used against a state machine that is enabled.
1855  *
1856  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1857  * \param sm State machine index (0..3) to use
1858  * \param pin_values the pin values to set (if the corresponding bit in pin_mask is set)
1859  * \param pin_mask a bit for each pin to indicate whether the corresponding pin_value for that pin should be applied. See \ref pio_sm_pins "pio_sm_ pins" for more detail on pin arguments
1860  */
1861 void pio_sm_set_pins_with_mask64(PIO pio, uint sm, uint64_t pin_values, uint64_t pin_mask);
1862 
1863 /*! \brief Use a state machine to set the pin directions for multiple pins for the PIO instance
1864  *  \ingroup hardware_pio
1865  *
1866  * This method repeatedly reconfigures the target state machine's pin configuration and executes 'set' instructions to set pin directions on up to 32 pins,
1867  * before restoring the state machine's pin configuration to what it was.
1868  *
1869  * This method is provided as a convenience to set initial pin directions, and should not be used against a state machine that is enabled.
1870  * Note: This method only works for pins < 32. To use with pins >= 32 call pio_sm_set_pindirs_with_mask64
1871  *
1872  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1873  * \param sm State machine index (0..3) to use
1874  * \param pin_dirs the pin directions to set - 1 = out, 0 = in (if the corresponding bit in pin_mask is set)
1875  * \param pin_mask a bit for each pin to indicate whether the corresponding pin_value for that pin should be applied.
1876  */
1877 void pio_sm_set_pindirs_with_mask(PIO pio, uint sm, uint32_t pin_dirs, uint32_t pin_mask);
1878 
1879 /*! \brief Use a state machine to set the pin directions for multiple pins for the PIO instance
1880  *  \ingroup hardware_pio
1881  *
1882  * This method repeatedly reconfigures the target state machine's pin configuration and executes 'set' instructions to set pin directions on up to 32 pins,
1883  * before restoring the state machine's pin configuration to what it was.
1884  *
1885  * This method is provided as a convenience to set initial pin directions, and should not be used against a state machine that is enabled.
1886  *
1887  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1888  * \param sm State machine index (0..3) to use
1889  * \param pin_dirs the pin directions to set - 1 = out, 0 = in (if the corresponding bit in pin_mask is set)
1890  * \param pin_mask a bit for each pin to indicate whether the corresponding pin_value for that pin should be applied.
1891  */
1892 void pio_sm_set_pindirs_with_mask64(PIO pio, uint sm, uint64_t pin_dirs, uint64_t pin_mask);
1893 
1894 /*! \brief Use a state machine to set the same pin direction for multiple consecutive pins for the PIO instance
1895  *  \ingroup hardware_pio
1896  *
1897  * This method repeatedly reconfigures the target state machine's pin configuration and executes 'set' instructions to set the pin direction on consecutive pins,
1898  * before restoring the state machine's pin configuration to what it was.
1899  *
1900  * This method is provided as a convenience to set initial pin directions, and should not be used against a state machine that is enabled.
1901  *
1902  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1903  * \param sm State machine index (0..3) to use
1904  * \param pins_base the first pin to set a direction for. See \ref pio_sm_pins "pio_sm_ pins" for more detail on pin arguments
1905  * \param pin_count the count of consecutive pins to set the direction for
1906  * \param is_out the direction to set; true = out, false = in
1907  * \return PICO_OK (0) on success, error code otherwise
1908  */
1909 int pio_sm_set_consecutive_pindirs(PIO pio, uint sm, uint pins_base, uint pin_count, bool is_out);
1910 
1911 /*! \brief Mark a state machine as used
1912  *  \ingroup hardware_pio
1913  *
1914  * Method for cooperative claiming of hardware. Will cause a panic if the state machine
1915  * is already claimed. Use of this method by libraries detects accidental
1916  * configurations that would fail in unpredictable ways.
1917  *
1918  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1919  * \param sm State machine index (0..3)
1920  */
1921 void pio_sm_claim(PIO pio, uint sm);
1922 
1923 /*! \brief Mark multiple state machines as used
1924  *  \ingroup hardware_pio
1925  *
1926  * Method for cooperative claiming of hardware. Will cause a panic if any of the state machines
1927  * are already claimed. Use of this method by libraries detects accidental
1928  * configurations that would fail in unpredictable ways.
1929  *
1930  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1931  * \param sm_mask Mask of state machine indexes
1932  */
1933 void pio_claim_sm_mask(PIO pio, uint sm_mask);
1934 
1935 /*! \brief Mark a state machine as no longer used
1936  *  \ingroup hardware_pio
1937  *
1938  * Method for cooperative claiming of hardware.
1939  *
1940  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1941  * \param sm State machine index (0..3)
1942  */
1943 void pio_sm_unclaim(PIO pio, uint sm);
1944 
1945 /*! \brief Claim a free state machine on a PIO instance
1946  *  \ingroup hardware_pio
1947  *
1948  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1949  * \param required if true the function will panic if none are available
1950  * \return the state machine index or negative if required was false, and none were free (for
1951  * backwards compatibility with prior SDK the error value is -1 i.e. PICO_ERROR_GENERIC)
1952  */
1953 int pio_claim_unused_sm(PIO pio, bool required);
1954 
1955 /*! \brief Determine if a PIO state machine is claimed
1956  *  \ingroup hardware_pio
1957  *
1958  * \param pio The PIO instance; e.g. \ref pio0 or \ref pio1
1959  * \param sm State machine index (0..3)
1960  * \return true if claimed, false otherwise
1961  * \see pio_sm_claim
1962  * \see pio_claim_sm_mask
1963  */
1964 bool pio_sm_is_claimed(PIO pio, uint sm);
1965 
1966 /*! \brief Finds a PIO and statemachine and adds a program into PIO memory
1967  *  \ingroup hardware_pio
1968  *
1969  * \param program PIO program to add
1970  * \param pio Returns the PIO hardware instance or NULL if no PIO is available
1971  * \param sm Returns the index of the PIO state machine that was claimed
1972  * \param offset Returns the instruction memory offset of the start of the program
1973  * \return true on success, false otherwise
1974  * \see pio_remove_program_unclaim_sm
1975  */
1976 bool pio_claim_free_sm_and_add_program(const pio_program_t *program, PIO *pio, uint *sm, uint *offset);
1977 
1978 /*! \brief Finds a PIO and statemachine and adds a program into PIO memory
1979  *  \ingroup hardware_pio
1980  *
1981  * This variation of \ref pio_claim_free_sm_and_add_program is useful on RP2350 QFN80 where the "GPIO Base"
1982  * must be set per PIO instance to either address the 32 GPIOs (0->31) or the 32 GPIOS (16-47). No single
1983  * PIO instance can interact with both pins 0->15 or 32->47 at the same time.
1984  *
1985  * This method takes additional information about the GPIO pins needed (via gpio_base and gpio_count),
1986  * and optionally will set the GPIO base (\see pio_set_gpio_base) of an unused PIO instance if necessary
1987  *
1988  * \param program PIO program to add
1989  * \param pio Returns the PIO hardware instance or NULL if no PIO is available
1990  * \param sm Returns the index of the PIO state machine that was claimed
1991  * \param offset Returns the instruction memory offset of the start of the program
1992  * \param gpio_base the lowest GPIO number required (0-47 on RP2350B, 0-31 otherwise)
1993  * \param gpio_count the count of GPIOs required
1994  * \param set_gpio_base if there is no free SM on a PIO instance with the right GPIO base, and there IS an unused PIO
1995  *                      instance, then that PIO will be reconfigured so that this method can succeed
1996  *
1997  * \return true on success, false otherwise
1998  * \see pio_remove_program_unclaim_sm
1999  */
2000 bool pio_claim_free_sm_and_add_program_for_gpio_range(const pio_program_t *program, PIO *pio, uint *sm, uint *offset, uint gpio_base, uint gpio_count, bool set_gpio_base);
2001 
2002 /*! \brief Removes a program from PIO memory and unclaims the state machine
2003  *  \ingroup hardware_pio
2004  *
2005  * \param program PIO program to remove from memory
2006  * \param pio PIO hardware instance being used
2007  * \param sm PIO state machine that was claimed
2008  * \param offset offset of the program in PIO memory
2009  * \see pio_claim_free_sm_and_add_program
2010  */
2011 void pio_remove_program_and_unclaim_sm(const pio_program_t *program, PIO pio, uint sm, uint offset);
2012 
2013 /*! \brief Return an IRQ for a PIO hardware instance
2014  *  \ingroup hardware_pio
2015  *
2016  * \param pio PIO hardware instance
2017  * \param irqn 0 for PIOx_IRQ_0 or 1 for PIOx_IRQ_1 etc where x is the PIO number
2018  * \return The IRQ number to use for the PIO
2019  */
pio_get_irq_num(PIO pio,uint irqn)2020 static inline int pio_get_irq_num(PIO pio, uint irqn) {
2021     check_pio_param(pio);
2022     valid_params_if(HARDWARE_PIO, irqn < NUM_PIO_IRQS);
2023     return PIO_IRQ_NUM(pio, irqn);
2024 }
2025 
2026 /*! \brief Return the interrupt source for a state machines TX FIFO not full interrupt
2027  *  \ingroup hardware_pio
2028  *
2029  * \param sm State machine index (0..3)
2030  * \return The interrupt source number for use in \ref pio_set_irqn_source_enabled or similar functions
2031  */
pio_get_tx_fifo_not_full_interrupt_source(uint sm)2032 static inline pio_interrupt_source_t pio_get_tx_fifo_not_full_interrupt_source(uint sm) {
2033     check_sm_param(sm);
2034     return ((pio_interrupt_source_t)(pis_sm0_tx_fifo_not_full + sm));
2035 }
2036 
2037 /*! \brief Return the interrupt source for a state machines RX FIFO not empty interrupt
2038  *  \ingroup hardware_pio
2039  *
2040  * \param sm State machine index (0..3)
2041  * \return The interrupt source number for use in \ref pio_set_irqn_source_enabled or similar functions
2042  */
pio_get_rx_fifo_not_empty_interrupt_source(uint sm)2043 static inline pio_interrupt_source_t pio_get_rx_fifo_not_empty_interrupt_source(uint sm) {
2044     check_sm_param(sm);
2045     return ((pio_interrupt_source_t)(pis_sm0_rx_fifo_not_empty + sm));
2046 }
2047 
2048 #ifdef __cplusplus
2049 }
2050 #endif
2051 
2052 #endif // _PIO_H_
2053