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