feat(bitscrambler): add enable and disable function

Author: Kainarx

components/esp_driver_bitscrambler/include/driver/bitscrambler.h

@@ -114,6 +114,30 @@ esp_err_t bitscrambler_start(bitscrambler_handle_t handle);
  */
 esp_err_t bitscrambler_reset(bitscrambler_handle_t handle);
 
+/**
+ * @brief Enable BitScrambler
+ * @note  This function should be called before bitscrambler_load_program, bitscrambler_load_lut, bitscrambler_reset and bitscrambler_start.
+ *
+ * @param handle BitScrambler handle
+ *
+ * @return
+ *        - ESP_OK
+ *        - ESP_ERR_INVALID_ARG: Invalid handle
+ */
+esp_err_t bitscrambler_enable(bitscrambler_handle_t handle);
+
+/**
+ * @brief Disable BitScrambler
+ * @note  This function should be called before bitscrambler_free.
+ *
+ * @param handle BitScrambler handle
+ *
+ * @return
+ *        - ESP_OK
+ *        - ESP_ERR_INVALID_ARG: Invalid handle
+ */
+esp_err_t bitscrambler_disable(bitscrambler_handle_t handle);
+
 #ifdef __cplusplus
 }
 #endif

components/esp_driver_bitscrambler/linker.lf

@@ -4,3 +4,6 @@ entries:
     if BITSCRAMBLER_CTRL_FUNC_IN_IRAM = y:
         bitscrambler: bitscrambler_reset (noflash)
         bitscrambler: bitscrambler_start (noflash)
+        bitscrambler: bitscrambler_load_program (noflash)
+        bitscrambler: bitscrambler_enable (noflash)
+        bitscrambler: bitscrambler_disable (noflash)

components/esp_driver_bitscrambler/src/bitscrambler.c

@@ -93,11 +93,6 @@ static esp_err_t init_from_config(bitscrambler_t *bs, const bitscrambler_config_
 {
     bs->cfg = *config;                  //Copy config over
     bs->hw = BITSCRAMBLER_LL_GET_HW(0); //there's only one as of now; if there's more, we need to handle them as a pool.
-
-    //Attach to indicated peripheral.
-    bitscrambler_ll_select_peripheral(bs->hw, bs->cfg.dir, config->attach_to);
-    bitscrambler_ll_enable(bs->hw, bs->cfg.dir);
-
     return ESP_OK;
 }
 
@@ -147,8 +142,6 @@ esp_err_t bitscrambler_init_loopback(bitscrambler_handle_t handle, const bitscra
     handle->loopback = true;
     enable_clocks(handle);
     esp_err_t r = init_from_config(handle, config);
-    //Loopback mode also needs RX channel set to the selected peripheral, even if it's not used.
-    bitscrambler_ll_select_peripheral(handle->hw, BITSCRAMBLER_DIR_RX, config->attach_to);
     return r;
 }
 
@@ -271,6 +264,40 @@ esp_err_t bitscrambler_register_extra_clean_up(bitscrambler_handle_t handle, bit
     return ESP_OK;
 }
 
+esp_err_t bitscrambler_enable(bitscrambler_handle_t handle)
+{
+    if (!handle) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    // Attach to indicated peripheral.
+    bitscrambler_ll_select_peripheral(handle->hw, handle->cfg.dir, handle->cfg.attach_to);
+    // bitscrambler_ll_enable(handle->hw, handle->cfg.dir);
+    //enable loopback mode if requested
+    bitscrambler_ll_enable_loopback(handle->hw, handle->loopback);
+    if (handle->loopback) {
+        //Loopback mode also needs RX channel set to the selected peripheral, even if it's not used.
+        bitscrambler_ll_select_peripheral(handle->hw, BITSCRAMBLER_DIR_RX, handle->cfg.attach_to);
+    }
+    bitscrambler_ll_enable(handle->hw, handle->cfg.dir);
+    return ESP_OK;
+}
+
+esp_err_t bitscrambler_disable(bitscrambler_handle_t handle)
+{
+    if (!handle) {
+        return ESP_ERR_INVALID_ARG;
+    }
+    bitscrambler_ll_disable(handle->hw, handle->cfg.dir);
+    // detach from peripheral
+    bitscrambler_ll_select_peripheral(handle->hw, handle->cfg.dir, SOC_BITSCRAMBLER_ATTACH_NONE);
+    if (handle->loopback) {
+        // detach loopback RX channel as well
+        bitscrambler_ll_select_peripheral(handle->hw, BITSCRAMBLER_DIR_RX, SOC_BITSCRAMBLER_ATTACH_NONE);
+    }
+
+    return ESP_OK;
+}
+
 void bitscrambler_free(bitscrambler_handle_t handle)
 {
     if (!handle) {

components/esp_driver_bitscrambler/src/bitscrambler_loopback.c

@@ -141,7 +141,7 @@ esp_err_t bitscrambler_loopback_create(bitscrambler_handle_t *handle, int attach
         .on_recv_eof = trans_done_cb,
     };
     gdma_register_rx_event_callbacks(bs->rx_channel, &rx_cbs, bs);
-
+    ESP_GOTO_ON_ERROR(bitscrambler_enable(&bs->bs), err, TAG, "failed to enable bitscrambler");
     *handle = (bitscrambler_handle_t)bs;
     return ESP_OK;
 
@@ -175,6 +175,7 @@ static void bitscrambler_loopback_free(bitscrambler_loopback_t *bsl)
 static esp_err_t bitscrambler_loopback_cleanup(bitscrambler_handle_t bs, void* user_ctx)
 {
     bitscrambler_loopback_t *bsl = (bitscrambler_loopback_t*)user_ctx;
+    ESP_RETURN_ON_ERROR(bitscrambler_disable(bs), TAG, "failed to disable bitscrambler");
     bitscrambler_loopback_free(bsl);
     return ESP_OK;
 }

components/soc/esp32c5/include/soc/bitscrambler_peri_select.h

@@ -10,6 +10,7 @@
  * Note that these are the values written to HP_SYSTEM_BITSCRAMBLER_PERI_SEL_REG.
  */
 
+#define SOC_BITSCRAMBLER_ATTACH_NONE    -1
 #define SOC_BITSCRAMBLER_ATTACH_GPSPI2  1
 #define SOC_BITSCRAMBLER_ATTACH_UHCI    2
 #define SOC_BITSCRAMBLER_ATTACH_I2S0    3

components/soc/esp32p4/include/soc/bitscrambler_peri_select.h

@@ -10,6 +10,7 @@
  * Note that these are the values written to HP_SYSTEM_BITSCRAMBLER_PERI_SEL_REG.
  */
 
+#define SOC_BITSCRAMBLER_ATTACH_NONE    -1
 #define SOC_BITSCRAMBLER_ATTACH_LCD_CAM 0
 #define SOC_BITSCRAMBLER_ATTACH_GPSPI2  1
 #define SOC_BITSCRAMBLER_ATTACH_GPSPI3  2

docs/en/api-reference/peripherals/bitscrambler.rst

@@ -201,8 +201,12 @@ To use the assembled BitScrambler program, you would refer to it as such:
 
     bitscrambler_handle_t bs;
     [...create bitscrambler instance]
+    bitscrambler_enable(bs);
     bitscrambler_load_program(bs, my_bitscrambler_program);
 
+    [...]
+
+    bitscrambler_disable(bs);
 
 .. _bitscrambler-loopback:
 

docs/zh_CN/api-reference/peripherals/bitscrambler.rst

@@ -201,8 +201,12 @@ LUT 内容元指令
 
     bitscrambler_handle_t bs;
     [...创建比特调节器实例]
+    bitscrambler_enable(bs);
     bitscrambler_load_program(bs, my_bitscrambler_program);
 
+    [...]
+
+    bitscrambler_disable(bs);
 
 .. _bitscrambler-loopback: