feat(esp_repl): Implement the component logic

SoucheSouche · SoucheSouche · commit b6992a5fedde · 2025-08-20T14:01:55.000+02:00
diff --git a/esp_repl/esp_repl.c b/esp_repl/esp_repl.c
@@ -4,6 +4,180 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 #include <stdbool.h>
+#include "freertos/FreeRTOS.h"
+#include "freertos/semphr.h"
 #include "esp_repl.h"
 #include "esp_err.h"
 
+typedef enum {
+    ESP_REPL_STATE_RUNNING,
+    ESP_REPL_STATE_STOPPED
+} esp_repl_state_e;
+
+typedef struct esp_repl_state {
+    esp_repl_state_e state;
+    SemaphoreHandle_t mux;
+} esp_repl_state_t;
+
+typedef struct esp_repl_instance {
+    esp_repl_instance_handle_t self;
+    esp_repl_config_t config;
+    esp_repl_state_t state;
+} esp_repl_instance_t;
+
+#define ESP_REPL_CHECK_INSTANCE(handle) do {                                                          \
+    if((handle == NULL) || ((esp_repl_instance_t*)handle->self != (esp_repl_instance_t*)handle)) {    \
+        return ESP_ERR_INVALID_ARG;                                                                   \
+    }                                                                                                 \
+} while(0)
+
+esp_err_t esp_repl_create(esp_repl_instance_handle_t *handle, const esp_repl_config_t *config)
+{
+    if ((config->executor.func == NULL) ||
+            (config->reader.func == NULL) ||
+            (config->max_cmd_line_size == 0)) {
+        return ESP_ERR_INVALID_ARG;
+    }
+
+    esp_repl_instance_t *instance = malloc(sizeof(esp_repl_instance_t));
+    if (!instance) {
+        return ESP_ERR_NO_MEM;
+    }
+
+    instance->config = *config;
+    instance->state.state = ESP_REPL_STATE_STOPPED;
+    instance->self = instance;
+    instance->state.mux = xSemaphoreCreateMutex();
+    if (!instance->state.mux) {
+        free(instance);
+        return ESP_FAIL;
+    }
+
+    /* take the mutex right away to prevent the task to start running until
+     * the user explicitly calls esp_repl_start */
+    xSemaphoreTake(instance->state.mux, portMAX_DELAY);
+
+    *handle = instance;
+    return ESP_OK;
+}
+
+esp_err_t esp_repl_destroy(esp_repl_instance_handle_t handle)
+{
+    ESP_REPL_CHECK_INSTANCE(handle);
+    esp_repl_state_t *state = &handle->state;
+
+    /* the instance has to be not running for esp_repl to destroy it */
+    if (state->state != ESP_REPL_STATE_STOPPED) {
+        return ESP_ERR_INVALID_STATE;
+    }
+
+    vSemaphoreDelete(state->mux);
+
+    free(handle);
+
+    return ESP_OK;
+}
+
+esp_err_t esp_repl_start(esp_repl_instance_handle_t handle)
+{
+    ESP_REPL_CHECK_INSTANCE(handle);
+    esp_repl_state_t *state = &handle->state;
+
+    if (state->state != ESP_REPL_STATE_STOPPED) {
+        return ESP_ERR_INVALID_STATE;
+    }
+    state->state = ESP_REPL_STATE_RUNNING;
+    xSemaphoreGive(state->mux);
+
+    return ESP_OK;
+}
+
+esp_err_t esp_repl_stop(esp_repl_instance_handle_t handle)
+{
+    ESP_REPL_CHECK_INSTANCE(handle);
+    esp_repl_config_t *config = &handle->config;
+    esp_repl_state_t *state = &handle->state;
+
+    if (state->state != ESP_REPL_STATE_RUNNING) {
+        return ESP_ERR_INVALID_STATE;
+    }
+
+    /* update the state to force the while loop in esp_repl to return */
+    state->state = ESP_REPL_STATE_STOPPED;
+
+    /* Call the on_stop callback to let the user unblock reader.func, if provided */
+    if (config->on_stop.func != NULL) {
+        config->on_stop.func(config->on_stop.ctx, handle);
+    }
+
+    /* Wait for esp_repl() to finish and signal completion */
+    xSemaphoreTake(state->mux, portMAX_DELAY);
+
+    /* give it back so destroy can also take/give symmetrically */
+    xSemaphoreGive(state->mux);
+
+    return ESP_OK;
+}
+
+void esp_repl(esp_repl_instance_handle_t handle)
+{
+    if (!handle || handle->self != handle) {
+        return;
+    }
+
+    esp_repl_config_t *config = &handle->config;
+    esp_repl_state_t *state = &handle->state;
+
+    /* allocate memory for the command line buffer */
+    const size_t cmd_line_size = config->max_cmd_line_size;
+    char *cmd_line = calloc(1, cmd_line_size);
+    if (!cmd_line) {
+        return;
+    }
+
+    /* Waiting for task notify. This happens when `esp_repl_start`
+     * function is called. */
+    xSemaphoreTake(state->mux, portMAX_DELAY);
+
+    /* REPL loop */
+    while (state->state == ESP_REPL_STATE_RUNNING) {
+
+        /* try to read a command line */
+        const esp_err_t read_ret = config->reader.func(config->reader.ctx, cmd_line, cmd_line_size);
+
+        /* forward the raw command line to the pre executor callback (e.g., save in history).
+         * this callback is not necessary for the user to register, continue if it isn't */
+        if (config->pre_executor.func != NULL) {
+            config->pre_executor.func(config->pre_executor.ctx, cmd_line, read_ret);
+        }
+
+        /* at this point, if the command is NULL, skip the executing part */
+        if (read_ret != ESP_OK) {
+            continue;
+        }
+
+        /* try to run the command */
+        int cmd_func_ret;
+        const esp_err_t exec_ret = config->executor.func(config->executor.ctx, cmd_line, &cmd_func_ret);
+
+        /* forward the raw command line to the post executor callback (e.g., save in history).
+         * this callback is not necessary for the user to register, continue if it isn't */
+        if (config->post_executor.func != NULL) {
+            config->post_executor.func(config->post_executor.ctx, cmd_line, exec_ret, cmd_func_ret);
+        }
+
+        /* reset the cmd_line for next loop */
+        memset(cmd_line, 0x00, cmd_line_size);
+    }
+
+    /* free the memory allocated for the cmd_line buffer */
+    free(cmd_line);
+
+    /* release the semaphore to indicate esp_repl_stop that the esp_repl returned */
+    xSemaphoreGive(state->mux);
+
+    /* call the on_exit callback before returning from esp_repl */
+    if (config->on_exit.func != NULL) {
+        config->on_exit.func(config->on_exit.ctx, handle);
+    }
+}
diff --git a/esp_repl/include/esp_repl.h b/esp_repl/include/esp_repl.h
@@ -13,6 +13,179 @@ extern "C" {
 #include "esp_err.h"
 
 
+/**
+ * @brief Function prototype for reading input for the REPL.
+ *
+ * @param ctx User-defined context pointer.
+ * @param buf Buffer to store the read data.
+ * @param buf_size Size of the buffer in bytes.
+ *
+ * @return ESP_OK on success, error code otherwise.
+ */
+typedef esp_err_t (*esp_repl_reader_fn)(void *ctx, char *buf, size_t buf_size);
+
+/**
+ * @brief Reader configuration structure for the REPL.
+ */
+typedef struct esp_repl_reader {
+    esp_repl_reader_fn func; /**!< Function to read input */
+    void *ctx;               /**!< Context passed to the reader function */
+} esp_repl_reader_t;
+
+/**
+ * @brief Function prototype called before executing a command.
+ *
+ * @param ctx User-defined context pointer.
+ * @param buf Buffer containing the command.
+ * @param reader_ret_val Return value from the reader function.
+ *
+ * @return ESP_OK to continue execution, error code to abort.
+ */
+typedef esp_err_t (*esp_repl_pre_executor_fn)(void *ctx, char *buf, const esp_err_t reader_ret_val);
+
+/**
+ * @brief Pre-executor configuration structure for the REPL.
+ */
+typedef struct esp_repl_pre_executor {
+    esp_repl_pre_executor_fn func; /**!< Function to run before command execution */
+    void *ctx;                      /**!< Context passed to the pre-executor function */
+} esp_repl_pre_executor_t;
+
+/**
+ * @brief Function prototype to execute a REPL command.
+ *
+ * @param ctx User-defined context pointer.
+ * @param buf Null-terminated command string.
+ * @param ret_val Pointer to store the command return value.
+ *
+ * @return ESP_OK on success, error code otherwise.
+ */
+typedef esp_err_t (*esp_repl_executor_fn)(void *ctx, const char *buf, int *ret_val);
+
+/**
+ * @brief Executor configuration structure for the REPL.
+ */
+typedef struct esp_repl_executor {
+    esp_repl_executor_fn func; /**!< Function to execute commands */
+    void *ctx;                  /**!< Context passed to the executor function */
+} esp_repl_executor_t;
+
+/**
+ * @brief Function prototype called after executing a command.
+ *
+ * @param ctx User-defined context pointer.
+ * @param buf Command that was executed.
+ * @param executor_ret_val Return value from the executor function.
+ * @param cmd_ret_val Command-specific return value.
+ *
+ * @return ESP_OK on success, error code otherwise.
+ */
+typedef esp_err_t (*esp_repl_post_executor_fn)(void *ctx, const char *buf, const esp_err_t executor_ret_val, const int cmd_ret_val);
+
+/**
+ * @brief Post-executor configuration structure for the REPL.
+ */
+typedef struct esp_repl_post_executor {
+    esp_repl_post_executor_fn func; /**!< Function called after command execution */
+    void *ctx;                       /**!< Context passed to the post-executor function */
+} esp_repl_post_executor_t;
+
+/**
+ * @brief Function prototype called when the REPL is stopping.
+ *
+ * This callback allows the user to unblock the reader (or perform other
+ * cleanup) so that the REPL can return from `esp_repl()`.
+ *
+ * @param ctx User-defined context pointer.
+ * @param handle Handle to the REPL instance.
+ */
+typedef void (*esp_repl_on_stop_fn)(void *ctx, esp_linenoise_handle_t handle);
+
+/**
+ * @brief Stop callback configuration structure for the REPL.
+ */
+typedef struct esp_repl_on_stop {
+    esp_repl_on_stop_fn func; /**!< Function called when REPL stop is requested */
+    void *ctx;                /**!< Context passed to the on_stop function */
+} esp_repl_on_stop_t;
+
+/**
+ * @brief Function prototype called when the REPL exits.
+ *
+ * @param ctx User-defined context pointer.
+ * @param handle Handle to the REPL instance.
+ */
+typedef void (*esp_repl_on_exit_fn)(void *ctx, esp_linenoise_handle_t handle);
+
+/**
+ * @brief Exit callback configuration structure for the REPL.
+ */
+typedef struct esp_repl_on_exit {
+    esp_repl_on_exit_fn func; /**!< Function called on REPL exit */
+    void *ctx;                /**!< Context passed to the exit function */
+} esp_repl_on_exit_t;
+
+/**
+ * @brief Configuration structure to initialize a REPL instance.
+ */
+typedef struct esp_repl_config {
+    size_t max_cmd_line_size;        /**!< Maximum allowed command line size */
+    esp_repl_reader_t reader;        /**!< Reader callback and context */
+    esp_repl_pre_executor_t pre_executor;   /**!< Pre-executor callback and context */
+    esp_repl_executor_t executor;           /**!< Executor callback and context */
+    esp_repl_post_executor_t post_executor; /**!< Post-executor callback and context */
+    esp_repl_on_stop_t on_stop;             /**!< Stop callback and context */
+    esp_repl_on_exit_t on_exit;             /**!< Exit callback and context */
+} esp_repl_config_t;
+
+/**
+ * @brief Handle to a REPL instance.
+ */
+typedef struct esp_repl_instance esp_repl_instance_handle_t;
+
+/**
+ * @brief Create a REPL instance.
+ *
+ * @param handle Pointer to store the created REPL instance handle.
+ * @param config Pointer to the configuration structure.
+ *
+ * @return ESP_OK on success, error code otherwise.
+ */
+esp_err_t esp_repl_create(esp_repl_instance_handle_t *handle, const esp_repl_config_t *config);
+
+/**
+ * @brief Destroy a REPL instance.
+ *
+ * @param handle REPL instance handle to destroy.
+ *
+ * @return ESP_OK on success, error code otherwise.
+ */
+esp_err_t esp_repl_destroy(esp_repl_instance_handle_t handle);
+
+/**
+ * @brief Start a REPL instance.
+ *
+ * @param handle REPL instance handle.
+ *
+ * @return ESP_OK on success, error code otherwise.
+ */
+esp_err_t esp_repl_start(esp_repl_instance_handle_t handle);
+
+/**
+ * @brief Stop a REPL instance.
+ *
+ * @param handle REPL instance handle.
+ *
+ * @return ESP_OK on success, error code otherwise.
+ */
+esp_err_t esp_repl_stop(esp_repl_instance_handle_t handle);
+
+/**
+ * @brief Run the REPL loop.
+ *
+ * @param handle REPL instance handle.
+ */
+void esp_repl(esp_repl_instance_handle_t handle);
 
 #ifdef __cplusplus
 }
