feat(parlio_tx): support to mount bitscrambler

Author: Kainarx

components/esp_driver_parlio/CMakeLists.txt

@@ -8,10 +8,14 @@ if(CONFIG_SOC_PARLIO_SUPPORTED)
                      "src/parlio_rx.c")
 endif()
 
+if(CONFIG_SOC_BITSCRAMBLER_SUPPORTED)
+    list(APPEND srcs "src/parlio_bitscrambler.c")
+endif()
+
 if(${target} STREQUAL "linux")
     set(priv_requires "")
 else()
-    set(priv_requires esp_pm esp_driver_gpio esp_mm)
+    set(priv_requires esp_pm esp_driver_gpio esp_mm esp_driver_bitscrambler)
 endif()
 
 idf_component_register(SRCS ${srcs}

components/esp_driver_parlio/include/driver/parlio_bitscrambler.h

@@ -0,0 +1,51 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdbool.h>
+#include <stdint.h>
+#include "esp_err.h"
+#include "driver/parlio_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief Decorate Parlio TX units with BitScrambler
+ *
+ * @note This function creates a BitScrambler instance and associates it with the Parlio TX unit.
+ *       The decorated TX unit will be able to do some pre-process to the user data with the help of BitScrambler
+ *       Only can be called before enable the TX unit
+ *
+ * @param[in] tx_unit Parlio TX unit handle
+ * @return
+ *      - ESP_OK: Decorate Parlio TX units with BitScrambler success
+ *      - ESP_ERR_INVALID_ARG: Failed because of invalid argument
+ *      - ESP_ERR_INVALID_STATE: Failed because the TX unit is already decorated with BitScrambler
+ *      - ESP_FAIL: Failed because of other error
+ */
+esp_err_t parlio_tx_unit_decorate_bitscrambler(parlio_tx_unit_handle_t tx_unit);
+
+/**
+ * @brief Remove the BitScrambler decoration from the Parlio TX unit
+ *
+ * @note This function removes the BitScrambler decoration from the Parlio TX unit, restoring the original functionality.
+ *       Only can be called before enable the TX unit
+ *
+ * @param[in] tx_unit Parlio TX unit handle
+ * @return
+ *      - ESP_OK: Remove the BitScrambler decoration from the Parlio TX unit success
+ *      - ESP_ERR_INVALID_ARG: Failed because of invalid argument
+ *      - ESP_ERR_INVALID_STATE: Failed because the TX unit is not decorated with BitScrambler
+ *      - ESP_FAIL: Failed because of other error
+ */
+esp_err_t parlio_tx_unit_undecorate_bitscrambler(parlio_tx_unit_handle_t tx_unit);
+
+#ifdef __cplusplus
+}
+#endif

components/esp_driver_parlio/include/driver/parlio_tx.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023-2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -108,23 +108,6 @@ esp_err_t parlio_tx_unit_enable(parlio_tx_unit_handle_t unit);
  */
 esp_err_t parlio_tx_unit_disable(parlio_tx_unit_handle_t unit);
 
-/**
- * @brief Type of Parallel IO TX done event data
- */
-typedef struct {
-} parlio_tx_done_event_data_t;
-
-/**
- * @brief Prototype of parlio tx event callback
- * @param[in] tx_unit Parallel IO TX unit that created by `parlio_new_tx_unit`
- * @param[in] edata Point to Parallel IO TX event data. The lifecycle of this pointer memory is inside this function,
- *                  user should copy it into static memory if used outside this function.
- * @param[in] user_ctx User registered context, passed from `parlio_tx_unit_register_event_callbacks`
- *
- * @return Whether a high priority task has been waken up by this callback function
- */
-typedef bool (*parlio_tx_done_callback_t)(parlio_tx_unit_handle_t tx_unit, const parlio_tx_done_event_data_t *edata, void *user_ctx);
-
 /**
  * @brief Group of Parallel IO TX callbacks
  * @note The callbacks are all running under ISR environment
@@ -157,6 +140,7 @@ esp_err_t parlio_tx_unit_register_event_callbacks(parlio_tx_unit_handle_t tx_uni
  */
 typedef struct {
     uint32_t idle_value; /*!< The value on the data line when the parallel IO is in idle state */
+    const void *bitscrambler_program; /*!< BitScrambler program binary, NULL if not use BitScrambler */
     struct {
         uint32_t queue_nonblocking : 1; /*!< If set, when the transaction queue is full, driver will not block the thread but return directly */
         uint32_t loop_transmission : 1; /*!< If set, the transmission will be repeated continuously, until the tx_unit is disabled by `parlio_tx_unit_disable` */

components/esp_driver_parlio/include/driver/parlio_types.h

@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2023 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2023-2025 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -31,6 +31,23 @@ typedef struct parlio_rx_unit_t *parlio_rx_unit_handle_t;
  */
 typedef struct parlio_rx_delimiter_t *parlio_rx_delimiter_handle_t;
 
+/**
+ * @brief Type of Parallel IO TX done event data
+ */
+typedef struct {
+} parlio_tx_done_event_data_t;
+
+/**
+ * @brief Prototype of parlio tx event callback
+ * @param[in] tx_unit Parallel IO TX unit that created by `parlio_new_tx_unit`
+ * @param[in] edata Point to Parallel IO TX event data. The lifecycle of this pointer memory is inside this function,
+ *                  user should copy it into static memory if used outside this function.
+ * @param[in] user_ctx User registered context, passed from `parlio_tx_unit_register_event_callbacks`
+ *
+ * @return Whether a high priority task has been waken up by this callback function
+ */
+typedef bool (*parlio_tx_done_callback_t)(parlio_tx_unit_handle_t tx_unit, const parlio_tx_done_event_data_t *edata, void *user_ctx);
+
 #ifdef __cplusplus
 }
 #endif

components/esp_driver_parlio/src/parlio_bitscrambler.c

@@ -0,0 +1,83 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <string.h>
+#include "esp_log.h"
+#include "esp_check.h"
+#include "driver/parlio_tx.h"
+#include "driver/bitscrambler.h"
+#include "parlio_priv.h"
+
+static esp_err_t parlio_tx_unit_bs_enable(parlio_tx_unit_handle_t tx_unit, parlio_tx_trans_desc_t *t)
+{
+    if (t->bitscrambler_program) {
+        ESP_RETURN_ON_ERROR(bitscrambler_enable(tx_unit->bs_handle), TAG, "enable bitscrambler failed");
+        ESP_RETURN_ON_ERROR(bitscrambler_load_program(tx_unit->bs_handle, t->bitscrambler_program), TAG, "load bitscrambler program failed");
+        ESP_RETURN_ON_ERROR(bitscrambler_reset(tx_unit->bs_handle), TAG, "reset bitscrambler failed");
+        ESP_RETURN_ON_ERROR(bitscrambler_start(tx_unit->bs_handle), TAG, "start bitscrambler failed");
+    }
+    return ESP_OK;
+}
+
+static esp_err_t parlio_tx_unit_bs_disable(parlio_tx_unit_handle_t tx_unit)
+{
+    ESP_RETURN_ON_ERROR(bitscrambler_disable(tx_unit->bs_handle), TAG, "disable bitscrambler failed");
+    return ESP_OK;
+}
+
+esp_err_t parlio_tx_unit_decorate_bitscrambler(parlio_tx_unit_handle_t tx_unit)
+{
+    ESP_RETURN_ON_FALSE(tx_unit, ESP_ERR_INVALID_ARG, TAG, "invalid TX unit");
+
+    // bitscrambler function is used under Parlio TX ISR context
+    // if the cache is disabled, all functions called by ISR must be in IRAM
+#if CONFIG_PARLIO_TX_ISR_CACHE_SAFE && !CONFIG_BITSCRAMBLER_CTRL_FUNC_IN_IRAM
+    ESP_RETURN_ON_FALSE(false, ESP_ERR_INVALID_STATE, TAG, "CONFIG_BITSCRAMBLER_CTRL_FUNC_IN_IRAM must be enabled");
+#endif
+
+    // check if already decorated
+    if (tx_unit->bs_handle) {
+        ESP_RETURN_ON_ERROR(ESP_ERR_INVALID_STATE, TAG, "TX unit already decorated with BitScrambler");
+    }
+
+    // create BitScrambler instance
+    bitscrambler_config_t bs_config = {
+        .dir = BITSCRAMBLER_DIR_TX,
+        .attach_to = SOC_BITSCRAMBLER_ATTACH_PARL_IO,
+    };
+
+    parlio_tx_fsm_t expected_fsm = PARLIO_TX_FSM_INIT;
+    if (atomic_compare_exchange_strong(&tx_unit->fsm, &expected_fsm, PARLIO_TX_FSM_WAIT)) {
+        ESP_RETURN_ON_ERROR(bitscrambler_new(&bs_config, &tx_unit->bs_handle), TAG, "create bitscrambler failed");
+        tx_unit->bs_enable_fn = parlio_tx_unit_bs_enable;
+        tx_unit->bs_disable_fn = parlio_tx_unit_bs_disable;
+        atomic_store(&tx_unit->fsm, PARLIO_TX_FSM_INIT);
+    } else {
+        ESP_RETURN_ON_ERROR(ESP_ERR_INVALID_STATE, TAG, "TX unit is not in init state");
+    }
+    return ESP_OK;
+}
+
+esp_err_t parlio_tx_unit_undecorate_bitscrambler(parlio_tx_unit_handle_t tx_unit)
+{
+    ESP_RETURN_ON_FALSE(tx_unit != NULL, ESP_ERR_INVALID_ARG, TAG, "invalid TX unit");
+
+    // check if already decorated
+    if (!tx_unit->bs_handle) {
+        ESP_RETURN_ON_ERROR(ESP_ERR_INVALID_STATE, TAG, "TX unit not decorated with BitScrambler yet");
+    }
+    parlio_tx_fsm_t expected_fsm = PARLIO_TX_FSM_INIT;
+    if (atomic_compare_exchange_strong(&tx_unit->fsm, &expected_fsm, PARLIO_TX_FSM_WAIT)) {
+        bitscrambler_free(tx_unit->bs_handle);
+        tx_unit->bs_handle = NULL;
+        tx_unit->bs_enable_fn = NULL;
+        tx_unit->bs_disable_fn = NULL;
+        atomic_store(&tx_unit->fsm, PARLIO_TX_FSM_INIT);
+    } else {
+        ESP_RETURN_ON_ERROR(ESP_ERR_INVALID_STATE, TAG, "TX unit is not in init state");
+    }
+    return ESP_OK;
+}

components/esp_driver_parlio/src/parlio_priv.h

@@ -38,6 +38,7 @@
 #include "rom/cache.h"
 #include "esp_heap_caps.h"
 #include "driver/parlio_types.h"
+#include "driver/bitscrambler.h"
 #include "esp_cache.h"
 #include "esp_clk_tree.h"
 #include "esp_pm.h"
@@ -122,12 +123,10 @@ typedef enum {
 } parlio_dir_t;
 
 typedef enum {
-    PARLIO_TX_FSM_INIT_WAIT,
     PARLIO_TX_FSM_INIT,
-    PARLIO_TX_FSM_ENABLE_WAIT,
     PARLIO_TX_FSM_ENABLE,
-    PARLIO_TX_FSM_RUN_WAIT,
     PARLIO_TX_FSM_RUN,
+    PARLIO_TX_FSM_WAIT,
 } parlio_tx_fsm_t;
 
 typedef struct parlio_unit_t *parlio_unit_base_handle_t;
@@ -150,6 +149,52 @@ struct parlio_unit_t {
     parlio_group_t  *group;   // group handle
 };
 
+typedef struct {
+    uint32_t idle_value; // Parallel IO bus idle value
+    const void *payload; // payload to be transmitted
+    size_t payload_bits; // payload size in bits
+    int dma_link_idx;  // index of DMA link list
+    const void *bitscrambler_program; // bitscrambler program binary
+    struct {
+        uint32_t loop_transmission : 1; // whether the transmission is in loop mode
+    } flags;                           // Extra configuration flags
+} parlio_tx_trans_desc_t;
+
+// original function pointer type definition
+
+typedef esp_err_t (*parlio_tx_bs_enable_fn_t)(parlio_tx_unit_handle_t tx_unit, parlio_tx_trans_desc_t *t);
+typedef esp_err_t (*parlio_tx_bs_disable_fn_t)(parlio_tx_unit_handle_t tx_unit);
+
+typedef struct parlio_tx_unit_t {
+    struct parlio_unit_t base; // base unit
+    size_t data_width;     // data width
+    intr_handle_t intr;    // allocated interrupt handle
+    esp_pm_lock_handle_t pm_lock;   // power management lock
+    gdma_channel_handle_t dma_chan; // DMA channel
+    gdma_link_list_handle_t dma_link[PARLIO_DMA_LINK_NUM]; // DMA link list handle
+    size_t int_mem_align; // Alignment for internal memory
+    size_t ext_mem_align; // Alignment for external memory
+#if CONFIG_PM_ENABLE
+    char pm_lock_name[PARLIO_PM_LOCK_NAME_LEN_MAX]; // pm lock name
+#endif
+    portMUX_TYPE spinlock;     // prevent resource accessing by user and interrupt concurrently
+    uint32_t out_clk_freq_hz;  // output clock frequency
+    parlio_clock_source_t clk_src;  // Parallel IO internal clock source
+    size_t max_transfer_bits;  // maximum transfer size in bits
+    size_t queue_depth;        // size of transaction queue
+    size_t num_trans_inflight; // indicates the number of transactions that are undergoing but not recycled to ready_queue
+    QueueHandle_t trans_queues[PARLIO_TX_QUEUE_MAX]; // transaction queues
+    parlio_tx_trans_desc_t *cur_trans; // points to current transaction
+    uint32_t idle_value_mask;          // mask of idle value
+    _Atomic parlio_tx_fsm_t fsm;       // Driver FSM state
+    parlio_tx_done_callback_t on_trans_done; // callback function when the transmission is done
+    void *user_data;                   // user data passed to the callback function
+    bitscrambler_handle_t bs_handle;   // bitscrambler handle
+    parlio_tx_bs_enable_fn_t bs_enable_fn;   // bitscrambler enable function
+    parlio_tx_bs_disable_fn_t bs_disable_fn; // bitscrambler disable function
+    parlio_tx_trans_desc_t trans_desc_pool[];   // transaction descriptor pool
+} parlio_tx_unit_t;
+
 /**
  * @brief Register the rx or tx unit to the parlio group
  *