v2.0.0
Enumerations | Functions
pio_instructions
Hardware APIs » hardware_pio

PIO instruction encoding. More...

## Enumerations
enum | pio_src_dest { pio_pins = 0u , pio_x = 1u , pio_y = 2u , pio_null = 3u | 0x20u | 0x80u , pio_pindirs = 4u | 0x08u | 0x40u | 0x80u , pio_exec_mov = 4u | 0x08u | 0x10u | 0x20u | 0x40u , pio_status = 5u | 0x08u | 0x10u | 0x20u | 0x80u , pio_pc = 5u | 0x08u | 0x20u | 0x40u , pio_isr = 6u | 0x20u , pio_osr = 7u | 0x10u | 0x20u , pio_exec_out = 7u | 0x08u | 0x20u | 0x40u | 0x80u }
| Enumeration of values to pass for source/destination args for instruction encoding functions. More...

## Functions
static uint | pio_encode_delay (uint cycles)
| Encode just the delay slot bits of an instruction. More...
static uint | pio_encode_sideset (uint sideset_bit_count, uint value)
| Encode just the side set bits of an instruction (in non optional side set mode) More...
static uint | pio_encode_sideset_opt (uint sideset_bit_count, uint value)
| Encode just the side set bits of an instruction (in optional -`opt` side set mode) More...
static uint | pio_encode_jmp (uint addr)
| Encode an unconditional JMP instruction. More...
static uint | pio_encode_jmp_not_x (uint addr)
| Encode a conditional JMP if scratch X zero instruction. More...
static uint | pio_encode_jmp_x_dec (uint addr)
| Encode a conditional JMP if scratch X non-zero (and post-decrement X) instruction. More...
static uint | pio_encode_jmp_not_y (uint addr)
| Encode a conditional JMP if scratch Y zero instruction. More...
static uint | pio_encode_jmp_y_dec (uint addr)
| Encode a conditional JMP if scratch Y non-zero (and post-decrement Y) instruction. More...
static uint | pio_encode_jmp_x_ne_y (uint addr)
| Encode a conditional JMP if scratch X not equal scratch Y instruction. More...
static uint | pio_encode_jmp_pin (uint addr)
| Encode a conditional JMP if input pin high instruction. More...
static uint | pio_encode_jmp_not_osre (uint addr)
| Encode a conditional JMP if output shift register not empty instruction. More...
static uint | pio_encode_wait_gpio (bool polarity, uint gpio)
| Encode a WAIT for GPIO pin instruction. More...
static uint | pio_encode_wait_pin (bool polarity, uint pin)
| Encode a WAIT for pin instruction. More...
static uint | pio_encode_wait_irq (bool polarity, bool relative, uint irq)
| Encode a WAIT for IRQ instruction. More...
static uint | pio_encode_in (enum pio_src_dest src, uint count)
| Encode an IN instruction. More...
static uint | pio_encode_out (enum pio_src_dest dest, uint count)
| Encode an OUT instruction. More...
static uint | pio_encode_push (bool if_full, bool block)
| Encode a PUSH instruction. More...
static uint | pio_encode_pull (bool if_empty, bool block)
| Encode a PULL instruction. More...
static uint | pio_encode_mov (enum pio_src_dest dest, enum pio_src_dest src)
| Encode a MOV instruction. More...
static uint | pio_encode_mov_not (enum pio_src_dest dest, enum pio_src_dest src)
| Encode a MOV instruction with bit invert. More...
static uint | pio_encode_mov_reverse (enum pio_src_dest dest, enum pio_src_dest src)
| Encode a MOV instruction with bit reverse. More...
static uint | pio_encode_irq_set (bool relative, uint irq)
| Encode a IRQ SET instruction. More...
static uint | pio_encode_irq_wait (bool relative, uint irq)
| Encode a IRQ WAIT instruction. More...
static uint | pio_encode_irq_clear (bool relative, uint irq)
| Encode a IRQ CLEAR instruction. More...
static uint | pio_encode_set (enum pio_src_dest dest, uint value)
| Encode a SET instruction. More...
static uint | pio_encode_nop (void)
| Encode a NOP instruction. More...

## Detailed Description

PIO instruction encoding.

Functions for generating PIO instruction encodings programmatically. In debug builds `PARAM_ASSERTIONS_ENABLED_PIO_INSTRUCTIONS` can be set to 1 to enable validation of encoding function parameters.

For fuller descriptions of the instructions in question see the "RP2040 Datasheet"

## Enumeration Type Documentation

## ◆ pio_src_dest

enum pio_src_dest

Enumeration of values to pass for source/destination args for instruction encoding functions.

Note
  Not all values are suitable for all functions. Validity is only checked in debug mode when `PARAM_ASSERTIONS_ENABLED_PIO_INSTRUCTIONS` is 1

## Function Documentation

## ◆ pio_encode_delay()

static uint pio_encode_delay | ( | uint | cycles | ) |
| inlinestatic

Encode just the delay slot bits of an instruction.

Note
  This function does not return a valid instruction encoding; instead it returns an encoding of the delay slot suitable for `OR`ing with the result of an encoding function for an actual instruction. Care should be taken when combining the results of this function with the results of pio_encode_sideset and pio_encode_sideset_opt as they share the same bits within the instruction encoding.

Parameters

  cycles | the number of cycles 0-31 (or less if side set is being used)

Returns
  the delay slot bits to be ORed with an instruction encoding

## ◆ pio_encode_in()

static uint pio_encode_in | ( | enum pio_src_dest | src,
|  | uint | count
| ) |  |
| inlinestatic

Encode an IN instruction.

This is the equivalent of `IN <src>, <count>`

Parameters

  src | The source to take data from
  count | The number of bits 1-32

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_irq_clear()

static uint pio_encode_irq_clear | ( | bool | relative,
|  | uint | irq
| ) |  |
| inlinestatic

Encode a IRQ CLEAR instruction.

This is the equivalent of `IRQ CLEAR <irq> <relative>`

Parameters

  relative | true for a `IRQ CLEAR <irq> REL`, false for regular `IRQ CLEAR <irq>`
  irq | the irq number 0-7

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_irq_set()

static uint pio_encode_irq_set | ( | bool | relative,
|  | uint | irq
| ) |  |
| inlinestatic

Encode a IRQ SET instruction.

This is the equivalent of `IRQ SET <irq> <relative>`

Parameters

  relative | true for a `IRQ SET <irq> REL`, false for regular `IRQ SET <irq>`
  irq | the irq number 0-7

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_irq_wait()

static uint pio_encode_irq_wait | ( | bool | relative,
|  | uint | irq
| ) |  |
| inlinestatic

Encode a IRQ WAIT instruction.

This is the equivalent of `IRQ WAIT <irq> <relative>`

Parameters

  relative | true for a `IRQ WAIT <irq> REL`, false for regular `IRQ WAIT <irq>`
  irq | the irq number 0-7

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_jmp()

static uint pio_encode_jmp | ( | uint | addr | ) |
| inlinestatic

Encode an unconditional JMP instruction.

This is the equivalent of `JMP <addr>`

Parameters

  addr | The target address 0-31 (an absolute address within the PIO instruction memory)

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_jmp_not_osre()

static uint pio_encode_jmp_not_osre | ( | uint | addr | ) |
| inlinestatic

Encode a conditional JMP if output shift register not empty instruction.

This is the equivalent of `JMP !OSRE <addr>`

Parameters

  addr | The target address 0-31 (an absolute address within the PIO instruction memory)

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_jmp_not_x()

static uint pio_encode_jmp_not_x | ( | uint | addr | ) |
| inlinestatic

Encode a conditional JMP if scratch X zero instruction.

This is the equivalent of `JMP !X <addr>`

Parameters

  addr | The target address 0-31 (an absolute address within the PIO instruction memory)

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_jmp_not_y()

static uint pio_encode_jmp_not_y | ( | uint | addr | ) |
| inlinestatic

Encode a conditional JMP if scratch Y zero instruction.

This is the equivalent of `JMP !Y <addr>`

Parameters

  addr | The target address 0-31 (an absolute address within the PIO instruction memory)

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_jmp_pin()

static uint pio_encode_jmp_pin | ( | uint | addr | ) |
| inlinestatic

Encode a conditional JMP if input pin high instruction.

This is the equivalent of `JMP PIN <addr>`

Parameters

  addr | The target address 0-31 (an absolute address within the PIO instruction memory)

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_jmp_x_dec()

static uint pio_encode_jmp_x_dec | ( | uint | addr | ) |
| inlinestatic

Encode a conditional JMP if scratch X non-zero (and post-decrement X) instruction.

This is the equivalent of `JMP X-- <addr>`

Parameters

  addr | The target address 0-31 (an absolute address within the PIO instruction memory)

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_jmp_x_ne_y()

static uint pio_encode_jmp_x_ne_y | ( | uint | addr | ) |
| inlinestatic

Encode a conditional JMP if scratch X not equal scratch Y instruction.

This is the equivalent of `JMP X!=Y <addr>`

Parameters

  addr | The target address 0-31 (an absolute address within the PIO instruction memory)

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_jmp_y_dec()

static uint pio_encode_jmp_y_dec | ( | uint | addr | ) |
| inlinestatic

Encode a conditional JMP if scratch Y non-zero (and post-decrement Y) instruction.

This is the equivalent of `JMP Y-- <addr>`

Parameters

  addr | The target address 0-31 (an absolute address within the PIO instruction memory)

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_mov()

static uint pio_encode_mov | ( | enum pio_src_dest | dest,
|  | enum pio_src_dest | src
| ) |  |
| inlinestatic

Encode a MOV instruction.

This is the equivalent of `MOV <dest>, <src>`

Parameters

  dest | The destination to write data to
  src | The source to take data from

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_mov_not()

static uint pio_encode_mov_not | ( | enum pio_src_dest | dest,
|  | enum pio_src_dest | src
| ) |  |
| inlinestatic

Encode a MOV instruction with bit invert.

This is the equivalent of `MOV <dest>, ~<src>`

Parameters

  dest | The destination to write inverted data to
  src | The source to take data from

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_mov_reverse()

static uint pio_encode_mov_reverse | ( | enum pio_src_dest | dest,
|  | enum pio_src_dest | src
| ) |  |
| inlinestatic

Encode a MOV instruction with bit reverse.

This is the equivalent of `MOV <dest>, ::<src>`

Parameters

  dest | The destination to write bit reversed data to
  src | The source to take data from

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_nop()

static uint pio_encode_nop | ( | void |  | ) |
| inlinestatic

Encode a NOP instruction.

This is the equivalent of `NOP` which is itself encoded as `MOV y, y`

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_out()

static uint pio_encode_out | ( | enum pio_src_dest | dest,
|  | uint | count
| ) |  |
| inlinestatic

Encode an OUT instruction.

This is the equivalent of `OUT <src>, <count>`

Parameters

  dest | The destination to write data to
  count | The number of bits 1-32

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_pull()

static uint pio_encode_pull | ( | bool | if_empty,
|  | bool | block
| ) |  |
| inlinestatic

Encode a PULL instruction.

This is the equivalent of `PULL <if_empty>, <block>`

Parameters

  if_empty | true for `PULL IF_EMPTY ...`, false for `PULL ...`
  block | true for `PULL ... BLOCK`, false for `PULL ...`

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_push()

static uint pio_encode_push | ( | bool | if_full,
|  | bool | block
| ) |  |
| inlinestatic

Encode a PUSH instruction.

This is the equivalent of `PUSH <if_full>, <block>`

Parameters

  if_full | true for `PUSH IF_FULL ...`, false for `PUSH ...`
  block | true for `PUSH ... BLOCK`, false for `PUSH ...`

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_set()

static uint pio_encode_set | ( | enum pio_src_dest | dest,
|  | uint | value
| ) |  |
| inlinestatic

Encode a SET instruction.

This is the equivalent of `SET <dest>, <value>`

Parameters

  dest | The destination to apply the value to
  value | The value 0-31

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_sideset()

static uint pio_encode_sideset | ( | uint | sideset_bit_count,
|  | uint | value
| ) |  |
| inlinestatic

Encode just the side set bits of an instruction (in non optional side set mode)

Note
  This function does not return a valid instruction encoding; instead it returns an encoding of the side set bits suitable for `OR`ing with the result of an encoding function for an actual instruction. Care should be taken when combining the results of this function with the results of pio_encode_delay as they share the same bits within the instruction encoding.

Parameters

  sideset_bit_count | number of side set bits as would be specified via `.sideset` in pioasm
  value | the value to sideset on the pins

Returns
  the side set bits to be ORed with an instruction encoding

## ◆ pio_encode_sideset_opt()

static uint pio_encode_sideset_opt | ( | uint | sideset_bit_count,
|  | uint | value
| ) |  |
| inlinestatic

Encode just the side set bits of an instruction (in optional -`opt` side set mode)

Note
  This function does not return a valid instruction encoding; instead it returns an encoding of the side set bits suitable for `OR`ing with the result of an encoding function for an actual instruction. Care should be taken when combining the results of this function with the results of pio_encode_delay as they share the same bits within the instruction encoding.

Parameters

  sideset_bit_count | number of side set bits as would be specified via `.sideset <n> opt` in pioasm
  value | the value to sideset on the pins

Returns
  the side set bits to be ORed with an instruction encoding

## ◆ pio_encode_wait_gpio()

static uint pio_encode_wait_gpio | ( | bool | polarity,
|  | uint | gpio
| ) |  |
| inlinestatic

Encode a WAIT for GPIO pin instruction.

This is the equivalent of `WAIT <polarity> GPIO <gpio>`

Parameters

  polarity | true for `WAIT 1`, false for `WAIT 0`
  gpio | The real GPIO number 0-31

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_wait_irq()

static uint pio_encode_wait_irq | ( | bool | polarity,
|  | bool | relative,
|  | uint | irq
| ) |  |
| inlinestatic

Encode a WAIT for IRQ instruction.

This is the equivalent of `WAIT <polarity> IRQ <irq> <relative>`

Parameters

  polarity | true for `WAIT 1`, false for `WAIT 0`
  relative | true for a `WAIT IRQ <irq> REL`, false for regular `WAIT IRQ <irq>`
  irq | the irq number 0-7

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt

## ◆ pio_encode_wait_pin()

static uint pio_encode_wait_pin | ( | bool | polarity,
|  | uint | pin
| ) |  |
| inlinestatic

Encode a WAIT for pin instruction.

This is the equivalent of `WAIT <polarity> PIN <pin>`

Parameters

  polarity | true for `WAIT 1`, false for `WAIT 0`
  pin | The pin number 0-31 relative to the executing SM's input pin mapping

Returns
  The instruction encoding with 0 delay and no side set value

See also
  pio_encode_delay, pio_encode_sideset, pio_encode_sideset_opt