PIO Underlying Principles Deep‑Dive: Side‑Set to Instruction Execution

Detailed Explanation of PIO Functions and Features

1. Side-set Characteristics

.program spi_tx_fast ; 定义了一个名为 spi_tx_fast 的程序
.side_set 1 ; 设置侧集数据位数为1
  
loop: 
    out pins, 1 side 0 ；将1个数据位传输到GPIO引脚1上,同时使用Side-set操作设置将其设置为低电平
    jmp loop side 1 ; 这行指令跳转回 loop 标签,同时 Side-set 操作设置将其设置为高电平

2. Program Reentry

.program squarewave 
    set pindirs, 1 ; 步骤1：设置引脚为输出模式（1个周期）
again: 
    set pins, 1 [1] ; 步骤2：引脚置高，延时1周期（共2个周期：指令1个+延时1个）
    set pins, 0 ; 步骤3：引脚置低（1个周期）
    jmp again ; 步骤4：跳转回again（1个周期）

.program squarewave_wrap ; 折返版方波程序
    set pindirs, 1 ; 初始化：设置引脚为输出模式（1个周期）
.wrap_target ; 标记折返起始地址（WRAP_BOTTOM = 1）
    set pins, 1 [1] ; 引脚置高，延时1周期（共2个周期）
    set pins, 0 [1] ; 引脚置低，延时1周期（共2个周期）
.wrap ; 标记折返结束地址（WRAP_TOP = 2）

// -------------------------------------------------- // 
// This file is autogenerated by pioasm; do not edit! // 
// -------------------------------------------------- // 
  
#pragma once 

# 如果没有定义 PICO_NO_HARDWARE,则会包含 hardware/pio.h 头文件,它定义了 PIO 相关的数据结构和函数
#if !PICO_NO_HARDWARE 
#include "hardware/pio.h" 
#endif 
  
// --------------- // 
// squarewave_wrap // 
// --------------- // 

# 两个宏定义了程序中 .wrap_target 和 .wrap 指令的位置
#define squarewave_wrap_wrap_target 1 
#define squarewave_wrap_wrap 2 

# 数组包含了 squarewave_wrap 程序的指令序列
static const uint16_t squarewave_wrap_program_instructions[] = { 
    0xe081, // 0: set pindirs, 1  
    // .wrap_target 
    0xe101, // 1: set pins, 1 [1] 
    0xe100, // 2: set pins, 0 [1]  
    // .wrap 
 }; 

# 如果没有定义 PICO_NO_HARDWARE
#if !PICO_NO_HARDWARE 
# 定义一个 squarewave_wrap_program 结构体,其中包含了程序的指令序列和长度等信息
static const struct pio_program squarewave_wrap_program = { 
    .instructions = squarewave_wrap_program_instructions, 
    .length = 3, 
    .origin = -1, 
}; 

# 返回一个默认的状态机配置,其中设置了 .wrap_target 和 .wrap 的位置
static inline pio_sm_config squarewave_wrap_program_get_default_config(uint offset) { 
    pio_sm_config c = pio_get_default_sm_config(); 
    sm_config_set_wrap(&c, offset + squarewave_wrap_wrap_target, offset + 
    squarewave_wrap_wrap); 
    return c; 
 } 
#endif

3. FIFO Merge

4. Auto-ejection and Auto-loading

.program manual_pull 
.side_set 1 opt ; 设置 Side-set 侧集操作位数为1，opt 以指定 side <value> 对于指令是可选的
  
.wrap_target ; 标记了 .wrap 指令的目标位置
    set x, 2 ; 将寄存器 x 初始化为 2，这个寄存器会用于控制循环次数
    pull side 1 [1] ; 执行手动拉取操作,如果没有 TX 数据,则会在这里等待
bitloop: ; 这里定义了一个标签,用于循环输出数据位
    out pins, 1 side 0 [1] ; 将 1 位数据移位输出到 GPIO 引脚,同时将 Side-set 设置为 0,用于控制时钟
    jmp x-- bitloop side 1 [1] ; 递减寄存器 x,如果不为 0,则跳转回 bitloop 标签
    out pins, 1 side 0 ; 输出最后一位数据,Side-set 设置为 0
.wrap ; 无条件跳转回 .wrap_target 标记的位置

.program autopull
.side_set 1 ; 侧集位数1
  
.wrap_target
    out pins, 1 side 0 [1] ; 移出1位数据，侧集时钟置0
    nop side 1 [1] ; 空操作，侧集时钟置1（替代手动跳转）
.wrap 

.program autopull
.side_set 1

.wrap_target
    out pins, 1    side 0      [1]
    nop            side 1      [1]
.wrap

.program somewhat_manual_pull
.side_set 1

.wrap_target
    out pins, 1    side 0      [1]
    pull ifempty   side 1      [1]
.wrap

.program auto_push_pull ; 定义了一个名为 auto_push_pull 的程序

.wrap_target
    out x, 32 ; 将 32 位数据从寄存器 x 自动推送(auto-push)到 TX FIFO
    in x, 32 ; 从 RX FIFO 自动拉取(auto-pull) 32 位数据到寄存器 x
.wrap

#include "tb.h" // TODO this is built against existing sw tree, so that we get printf etc

#include "platform.h"
#include "pio_regs.h"
#include "system.h"
#include "hardware.h"

#include "auto_push_pull.pio.h"

int main()
{
    // 用于初始化测试环境
    tb_init();

    // 加载并配置 PIO 状态机 0 来运行 auto_push_pull 程序
    // 将 auto_push_pull_program 数组中的指令加载到 PIO 指令存储器中
    for (int i = 0; i < count_of(auto_push_pull_program); ++i)
        mm_pio->instr_mem[i] = auto_push_pull_program[i];
    
    // 配置状态机 0 的 SHIFTCTRL 寄存器
    // 启用自动推送和自动拉取功能，设置推送和拉取阈值为 32
    mm_pio->sm[0].shiftctrl =
            (1u << PIO_SM0_SHIFTCTRL_AUTOPUSH_LSB) |
            (1u << PIO_SM0_SHIFTCTRL_AUTOPULL_LSB) |
            (0u << PIO_SM0_SHIFTCTRL_PUSH_THRESH_LSB) |
            (0u << PIO_SM0_SHIFTCTRL_PULL_THRESH_LSB);
    
    // 配置状态机 0 的 EXECCTRL 寄存器，设置 .wrap_target 和 .wrap 指令的位置
    mm_pio->sm[0].execctrl =
            (auto_push_pull_wrap_target << PIO_SM0_EXECCTRL_WRAP_BOTTOM_LSB) |
            (auto_push_pull_wrap << PIO_SM0_EXECCTRL_WRAP_TOP_LSB);

    // 启动状态机 0
    hw_set_bits(&mm_pio->ctrl, 1u << (PIO_CTRL_SM_ENABLE_LSB + 0));

    // 向 TX FIFO 中写入 5 个数据,并从 RX FIFO 中读取并打印出 5 个数据
    for (int i = 0; i < 5; ++i)
        mm_pio->txf[0] = i;
    for (int i = 0; i < 5; ++i)
        printf("%d\n", mm_pio->rxf[0]);

    return 0;
}

4.1 Detailed Explanation of Autopush

// 读取数据并将其使用in指令位移到isr移位寄存器中
isr = shift_in(isr, input())
// 更新isr移位计数器的值，读取了几个数据递增几个数
// 当 isr count 大于32时，记为0
isr count = saturate(isr count + in count)

// 检查接收数据的位数统计 rx count 是否达到了预设的阈值
if rx count >= threshold:
    // 如果接收 FIFO 已满,则暂停程序执行(stall)
    if rx fifo is full:
        stall
    // 如果接收 FIFO 未满
    else:
        // 将 isr 中的数据推出到 RX FIFO
        push(isr)
        // 重置 isr 和 isr count 为 0,准备接收下一个数据包
        isr = 0
        isr count = 0

4.2 Detailed Explanation of Auto-Loading: autopull

// 若是执行了 MOV 或 PULL 指令
if MOV or PULL:
    // 将输出移位寄存器 (OSR) 的位数统计 osr count 重置为 0
    osr count = 0

// 检查 OSR 的位数统计 osr count 是否达到了预设的阈值
if osr count >= threshold:
    // 如果发送 FIFO 不为空
    if tx fifo not empty:
        // 发送 FIFO 中拉取 (PULL) 数据到 OSR 中
        osr = pull()
        // 将 osr count 重置为 0,准备下一次发送
        osr count = 0

// 检查输出移位寄存器 (OSR) 的位数统计 osr count 是否达到了预设的阈值
if osr count >= threshold:
    // 如果发送 FIFO 不为空
    if tx fifo not empty:
        // 从发送 FIFO 中拉取 (PULL) 数据到 OSR 中
        osr = pull()
        // 将 osr count 重置为 0,准备下一次发送
        osr count = 0
    // 无论TX FIFO是否为空，只要到达预设的阈值，暂停程序执行
    stall
// 如果 osr count 未达到阈值
else:
    // 将 OSR 中的数据输出
    output(osr)
    // 将 OSR 向左移位 out count 位,并将新数据填充到低位
    osr = shift(osr, out count)
    // 更新 osr count , 当 osr count 大于32时，记为0
    osr count = saturate(osr count + out count)
    
    // 再次检查 osr count 是否达到阈值
    if osr count >= threshold:
        // 如果发送 FIFO 不为空
        if tx fifo not empty:
            // 从发送 FIFO 中拉取数据到 OSR,并将 osr count 重置为 0
            osr = pull()
            osr count = 0

5. PIO-specific clock divider

6. GPIO Mapping

6.1 Output Priority

6.2 Output Priority

6.3 Input Mapping

6.4 Input Synchronizer

7. Instruction Execution

.program exec_example

hang:
    jmp hang ; 定义了一个标签 hang,并在这里形成一个无限循环跳转
execute:
    out exec, 32
    jmp execute ; 定义了另一个标签 execute,在这里无限循环地将寄存器中的 32 位数据输出并执行

.program instructions_to_push

    out x, 32 ; 将 32 位数据从寄存器 x 输出
    in x, 32 ; 将 32 位数据从输入端口载入到寄存器 x
    push ; 将寄存器 x 中的数据推送到 TX FIFO

#include "tb.h" // TODO this is built against existing sw tree, so that we get printf etc

#include "platform.h"
#include "pio_regs.h"
#include "system.h"
#include "hardware.h"

#include "exec_example.pio.h"

int main()
{
    tb_init();

    // 将 exec_example_program 数组中的指令加载到 PIO 指令存储器中
    for (int i = 0; i < count_of(exec_example_program); ++i)
        mm_pio->instr_mem[i] = exec_example_program[i];

    // 配置状态机 0 的 SHIFTCTRL 寄存器，启用自动拉取功能,并设置拉取计数器阈值为 32
    mm_pio->sm[0].shiftctrl = (1u << PIO_SM0_SHIFTCTRL_AUTOPULL_LSB);

    // 启动状态机 0,使其进入 hang 死循环
    hw_set_bits(&mm_pio->ctrl, 1u << (PIO_CTRL_SM_ENABLE_LSB + 0));

    // 强制状态机跳转到 execute 标签的位置,开始执行 out exec, 32 指令
    mm_pio->sm[0].instr = 0x0000 | 0x1; // jmp execute

    // 写入 instructions_to_push_program 中的指令到TX FIFO
    // 写入一些数据(12345678)到TX FIFO
    mm_pio->txf[0] = instructions_to_push_program[0]; // out x, 32
    mm_pio->txf[0] = 12345678;                        // data to be OUTed
    mm_pio->txf[0] = instructions_to_push_program[1]; // in x, 32
    mm_pio->txf[0] = instructions_to_push_program[2]; // push

    // 等待 RX FIFO 中有数据可读,并将其打印出来
    while (mm_pio->fstat & (1u << PIO_FSTAT_RXEMPTY_LSB))
        ;

    printf("%d\n", mm_pio->rxf[0]);

    return 0;
}