parlio_tx_unit_handle_t tx_unit = NULL;
parlio_tx_unit_config_t config = {
    .clk_src = PARLIO_CLK_SRC_DEFAULT,      // 选择默认的时钟源
    .data_width = 4,                        // 数据宽度为 4 位
    .clk_in_gpio_num = -1,                  // 不使用外部时钟源
    .valid_gpio_num = EXAMPLE_PIN_CS,       // 使用有效信号作为片选
    .clk_out_gpio_num = EXAMPLE_PIN_CLK,
    .data_gpio_nums = {
        EXAMPLE_PIN_DATA0,
        EXAMPLE_PIN_DATA1,
        EXAMPLE_PIN_DATA2,
        EXAMPLE_PIN_DATA3,
    },
    .output_clk_freq_hz = 10 * 1000 * 1000, // 输出时钟频率为 10 MHz
    .trans_queue_depth = 32,                // 待处理事务队列深度为 32
    .max_transfer_size = 256,               // 一次传输的最大传输大小为 256 字节
    .sample_edge = PARLIO_SAMPLE_EDGE_NEG,  // 在时钟下降沿采样数据
    .flags = {
        .invert_valid_out = true, // 有效信号默认高电平有效，通过反转，我们用来模拟 QPI 的时序中的片选信号 CS
    }
};
// 创建 TX 单元实例
ESP_ERROR_CHECK(parlio_new_tx_unit(&config, &tx_unit));
// 使能 TX 单元
ESP_ERROR_CHECK(parlio_tx_unit_enable(tx_unit));

如果当前芯片中所有的 TX 单元都已经被申请使用，那么 :cpp:func:`parlio_new_tx_unit` 函数会返回 :c:macro:`ESP_ERR_NOT_FOUND` 错误。

调用 :cpp:func:`parlio_tx_unit_enable` 和 :cpp:func:`parlio_tx_unit_disable` 函数时，需要成对使用。这意味着，你不能连续调用两次 :cpp:func:`parlio_tx_unit_enable` 或 :cpp:func:`parlio_tx_unit_disable` 函数。这种成对调用的原则确保了资源的正确管理和释放。

请注意，TX 单元使能后会检查当前的作业队列，一旦队列中存在尚未开始的传输事务，驱动将立即发起一次传输。

#define PAYLOAD_SIZE 128

// 配置 TX 单元传输参数
parlio_transmit_config_t transmit_config = {
    .idle_value = 0x00, // 空闲状态下所有数据线均为低电平
};

// 准备需要发送的数据
uint8_t payload[PAYLOAD_SIZE] = {0};
for (int i = 0; i < PAYLOAD_SIZE; i++) {
    payload[i] = i;
}

// 第一次调用 parlio_tx_unit_transmit 时，没有传输事务正在执行，立即开始本次传输事务
ESP_ERROR_CHECK(parlio_tx_unit_transmit(tx_unit, payload, PAYLOAD_SIZE * sizeof(uint8_t) * 8, &transmit_config));
// 第二次调用 parlio_tx_unit_transmit 时，前一个事务可能还没有完成，驱动将第二个事务发送到作业队列中，并在前一个事务完成后的 ISR 上下文中进行调度
ESP_ERROR_CHECK(parlio_tx_unit_transmit(tx_unit, payload, PAYLOAD_SIZE * sizeof(uint8_t) * 8, &transmit_config));
// （可选）等待 TX 单元完成所有事务
ESP_ERROR_CHECK(parlio_tx_unit_wait_all_done(tx_unit, -1));

- :cpp:member:`parlio_transmit_config_t::idle_value` 设置 TX 单元发送完毕后空闲状态时数据线上的值。该值在调用 :cpp:func:`parlio_tx_unit_disable` 禁用 TX 单元后依然会保持。
:SOC_BITSCRAMBLER_SUPPORTED: - :cpp:member:`parlio_transmit_config_t::bitscrambler_program` 指向比特调节器程序的二进制文件的指针。若此次传输不使用比特调节器，则设置为 ``NULL``。
- :cpp:member:`parlio_transmit_config_t::flags` 通常用来微调传输的一些行为，包括以下选项
- :cpp:member:`parlio_transmit_config_t::flags::queue_nonblocking` 设置当传输队列满的时候该函数是否需要等待。如果该值设置为 ``true`` 那么当遇到队列满的时候，该函数会立即返回错误代码 :c:macro:`ESP_ERR_INVALID_STATE`。否则，函数会阻塞当前线程，直到传输队列有空档。
:SOC_PARLIO_TX_SUPPORT_LOOP_TRANSMISSION: - :cpp:member:`parlio_transmit_config_t::flags::loop_transmission` 设置为 ``true``，会启用无限循环发送机制。此时，除非手动调用 :cpp:func:`parlio_tx_unit_disable`，否则发送不会停止，也不会生成“完成发送”事件。由于循环由 DMA 控制， TX 单元可以在几乎不需要 CPU 干预的情况下，生成周期性序列。

static bool test_parlio_tx_done_callback(parlio_tx_unit_handle_t tx_unit, const parlio_tx_done_event_data_t *edata, void *user_ctx)
{
    // 处理事件回调的一般流程：
    // 1. 从 user_ctx 中拿到用户上下文数据（需事先从 test_parlio_tx_done_callback 中传入）
    // 2. 执行用户自定义操作
    // 3. 返回上述操作期间是否有高优先级的任务被唤醒了，以便通知调度器做切换任务

    BaseType_t high_task_wakeup = pdFalse;
    // 将 FreeRTOS 任务句柄作为用户上下文
    QTaskHandle_t task = (TaskHandle_t)user_ctx;
    // 在传输完成时，我们向指定任务发送任务通知
    vTaskNotifyGiveFromISR(task, &high_task_wakeup);
    // 返回高优先级任务是否已被该函数唤醒
    return (high_task_wakeup == pdTRUE);
}

parlio_tx_event_callbacks_t cbs = {
    // 将 test_parlio_tx_done_callback 作为传输事务完成的事件回调函数
    .on_trans_done = test_parlio_tx_done_callback,
};
ESP_ERROR_CHECK(parlio_tx_unit_register_event_callbacks(tx_unit, &cbs, xTaskGetCurrentTaskHandle()));

ESP_ERROR_CHECK(parlio_tx_unit_disable(tx_unit));
ESP_ERROR_CHECK(parlio_del_tx_unit(tx_unit));

parlio_tx_unit_handle_t tx_unit = NULL;
parlio_tx_unit_config_t config = {
    .clk_src = PARLIO_CLK_SRC_EXTERNAL,         // 选择外部时钟源
    .data_width = 4,                            // 数据宽度为 4 位
    .clk_in_gpio_num = EXAMPLE_PIN_CLK_IN,      // 设置外部时钟源输入引脚
    .input_clk_src_freq_hz = 10 * 1000 * 1000,  // 外部时钟源频率为 10 MHz
    .valid_gpio_num = -1,                       // 不使用有效信号
    .clk_out_gpio_num = EXAMPLE_PIN_CLK_OUT,
    .data_gpio_nums = {
        EXAMPLE_PIN_DATA0,
        EXAMPLE_PIN_DATA1,
        EXAMPLE_PIN_DATA2,
        EXAMPLE_PIN_DATA3,
    },
    .output_clk_freq_hz = 5 * 1000 * 1000, // 输出时钟频率为 5 MHz。注意，不能超过输入时钟频率
    .trans_queue_depth = 32,
    .max_transfer_size = 256,
    .sample_edge = PARLIO_SAMPLE_EDGE_NEG,  // 在时钟下降沿采样数据
};
// 创建 TX 单元实例
ESP_ERROR_CHECK(parlio_new_tx_unit(&config, &tx_unit));
// 使能 TX 单元
ESP_ERROR_CHECK(parlio_tx_unit_enable(tx_unit));

// 配置 TX 单元传输参数
parlio_transmit_config_t transmit_config = {
    .idle_value = 0x00, // 空闲状态下所有数据线均为低电平
};

// 准备需要发送的数据
uint8_t payload[PAYLOAD_SIZE] = {0};
for (int i = 0; i < PAYLOAD_SIZE; i++) {
    payload[i] = i;
}

// 开始传输事务
ESP_ERROR_CHECK(parlio_tx_unit_transmit(tx_unit, payload, PAYLOAD_SIZE * sizeof(uint8_t) * 8, &transmit_config));

无限循环发送
^^^^^^^^^^^^^^^^^^^^^^^^

{IDF_TARGET_NAME} 支持无限循环发送，即 TX 单元可以在不需要 CPU 干预的情况下，生成周期性序列。通过配置 :cpp:member:`parlio_transmit_config_t::flags::loop_transmission`，我们就可以启用无限循环发送

.. code-block:: c
   :emphasize-lines: 32

    parlio_tx_unit_handle_t tx_unit = NULL;
    parlio_tx_unit_config_t config = {
        .clk_src = PARLIO_CLK_SRC_DEFAULT,      // 选择默认的时钟源
        .data_width = 4,                        // 数据宽度为 4 位
        .clk_in_gpio_num = -1,                  // 不使用外部时钟源
        .valid_gpio_num = -1,                   // 不使用有效信号
        .clk_out_gpio_num = EXAMPLE_PIN_CLK,
        .data_gpio_nums = {
            EXAMPLE_PIN_DATA0,
            EXAMPLE_PIN_DATA1,
            EXAMPLE_PIN_DATA2,
            EXAMPLE_PIN_DATA3,
        },
        .output_clk_freq_hz = 10 * 1000 * 1000, // 输出时钟频率为 10 MHz
        .trans_queue_depth = 32,
        .max_transfer_size = 256,
        .sample_edge = PARLIO_SAMPLE_EDGE_NEG,  // 在时钟下降沿采样数据
        .flags = {
            .invert_valid_out = true,  // 有效信号默认高电平有效，通过反转，我们用来模拟 QPI 的时序中的片选信号 CS
        }
    };
    // 创建 TX 单元实例
    ESP_ERROR_CHECK(parlio_new_tx_unit(&config, &tx_unit));
    // 使能 TX 单元
    ESP_ERROR_CHECK(parlio_tx_unit_enable(tx_unit));

    #define PAYLOAD_SIZE 64

    // 配置 TX 单元传输参数
    parlio_transmit_config_t transmit_config = {
        .idle_value = 0x00, // 空闲状态下所有数据线均为低电平
        .loop_transmission = true, // 启用无限循环发送
    };

    // 准备需要发送的数据
    uint8_t payload[PAYLOAD_SIZE] = {0};
    for (int i = 0; i < PAYLOAD_SIZE; i++) {
        payload[i] = i;
    }

    // 开始循环传输事务
    ESP_ERROR_CHECK(parlio_tx_unit_transmit(tx_unit, payload, PAYLOAD_SIZE * sizeof(uint8_t) * 8, &transmit_config));

循环发送波形如下图所示：

.. wavedrom:: /../_static/diagrams/parlio/parlio_tx/loop_transmission_waveform.json

此时，除非手动调用 :cpp:func:`parlio_tx_unit_disable`，否则发送不会停止，也不会生成“完成发送”事件。

.. note::

    如果启用无限循环发送后需要修改发送内容，可以配置 :cpp:member:`parlio_transmit_config_t::flags::loop_transmission` 并再次调用 :cpp:func:`parlio_tx_unit_transmit` 传入新的 payload buffer，驱动会在旧 buffer 完整发送后，切换到新传入的 buffer。可以通过注册 :cpp:member:`parlio_tx_event_callbacks_t::on_buffer_switched` 为“缓冲区切换”的事件设置回调函数，用户需要自行维护好两块buffer，避免旧 buffer 被提早修改或者回收导致产生数据不连贯的现象。

.. _parlio-tx-bitscrambler-decorator:

配合比特调节器 (BitScrambler) 产生自定义的比特流
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

我们可以通过编写 :doc:`比特调节器 </api-reference/peripherals/bitscrambler>` 汇编代码来控制 DMA 通路上的数据，进而实现一些简单的编码工作。相较于使用 CPU 做编码工作，比特调节器的性能更高，且不会占用 CPU 资源，但是受限于 BitScrambler 有限的指令存储器空间，它无法实现复杂的编码工作。

编写好比特调节器程序后，通过调用 :cpp:func:`parlio_tx_unit_decorate_bitscrambler` 启用比特调节器。并在 :cpp:member:`parlio_transmit_config_t::bitscrambler_program` 配置本次传输使用比特调节器程序的二进制文件。不同的传输事务可以使用不同的比特调节器程序。该二进制文件必须符合比特调节器的汇编语言规范，并且在运行时会被加载到比特调节器的指令存储器中。如何编写并编译比特调节器程序请参考 :doc:`比特调节器编程指南 </api-reference/peripherals/bitscrambler>`。

.. only:: esp32p4

    .. note::

        由于硬件限制，在 rev3.0 之前的芯片版本上，使用比特调节器生成的比特流与原本比特流相比，长度不能发生变化，否则可能会发生传输阻塞或数据丢失。

:cpp:func:`parlio_tx_unit_decorate_bitscrambler` 和 :cpp:func:`parlio_tx_unit_undecorate_bitscrambler` 需要成对使用。在删除 TX 单元时，需要先调用 :cpp:func:`parlio_tx_unit_undecorate_bitscrambler` 移除比特调节器。

除了关闭时钟源外，系统在进入睡眠模式时还可以关闭 TX 单元的电源以进一步降低功耗。要实现这一点，需要将 :cpp:member:`parlio_tx_unit_config_t::flags::allow_pd` 设置为 ``true``。在系统进入睡眠模式之前，TX 单元的寄存器上下文会被备份到内存中，并在系统唤醒后恢复。请注意，启用此选项虽然可以降低功耗，但会增加内存的使用量。因此，在使用该功能时需要在功耗和内存消耗之间进行权衡。

请注意，在启用该选项后，所有的中断回调函数及其上下文数据 **必须存放在内部存储空间** 中。因为在 Cache 被禁用时，系统无法从 Flash 中加载数据和指令。

.. note::

    当启用了以下选项时，系统在进行 Flash 读写操作时不会自动禁用 Cache, 因此无需启用 :ref:`CONFIG_PARLIO_TX_ISR_CACHE_SAFE`。

    .. list::
        :SOC_SPI_MEM_SUPPORT_AUTO_SUSPEND: - :ref:`CONFIG_SPI_FLASH_AUTO_SUSPEND`
        :SOC_SPIRAM_XIP_SUPPORTED: - :ref:`CONFIG_SPIRAM_XIP_FROM_PSRAM`

但是，中断处理程序调用的用户回调函数和用户上下文数据仍然可能位于 Flash 中，缓存缺失的问题还是会存在，这需要用户自己将回调函数和数据放入内部 RAM 中，比如使用 :c:macro:`IRAM_ATTR` 和 :c:macro:`DRAM_ATTR`。

- :example:`peripherals/parlio/parlio_tx/simple_rgb_led_matrix` 演示了如何使用 {IDF_TARGET_NAME} 的 TX 单元驱动支持 HUB75 接口的 RGB LED 矩阵板，并使用 LVGL 库来展示简单的 UI 元素。
:SOC_PARLIO_TX_SUPPORT_LOOP_TRANSMISSION: - :example:`peripherals/parlio/parlio_tx/advanced_rgb_led_matrix` 演示了如何使用 {IDF_TARGET_NAME} 的 TX 单元的无限循环发送特性支持 HUB75 接口的 RGB LED 矩阵板。相比 simple_rgb_led_matrix 示例，不需要手动执行循环扫描，使用更加灵活。
:SOC_PARLIO_LCD_SUPPORTED: - :example:`peripherals/lcd/parlio_simulate` 演示了如何使用并行 IO 外设的 TX 单元驱动 SPI 或 I80 接口的屏幕。