From 5020fbce1c8e13c73b3a738a15ee3b32af0b1236 Mon Sep 17 00:00:00 2001 From: morris Date: Mon, 8 Aug 2022 15:47:30 +0800 Subject: [PATCH] driver: add doc on how to unregister event callbacks Closes https://github.com/espressif/esp-idf/pull/9523 --- components/driver/gptimer.c | 2 +- components/driver/include/driver/gptimer.h | 3 ++- components/driver/include/driver/mcpwm_cap.h | 2 ++ components/driver/include/driver/mcpwm_cmpr.h | 2 ++ components/driver/include/driver/mcpwm_fault.h | 2 ++ components/driver/include/driver/mcpwm_oper.h | 2 ++ components/driver/include/driver/mcpwm_timer.h | 3 +++ components/driver/include/driver/pulse_cnt.h | 3 ++- components/driver/mcpwm/mcpwm_timer.c | 2 +- components/driver/pulse_cnt.c | 2 +- 10 files changed, 18 insertions(+), 5 deletions(-) diff --git a/components/driver/gptimer.c b/components/driver/gptimer.c index 21a5597088..5edc6b7eac 100644 --- a/components/driver/gptimer.c +++ b/components/driver/gptimer.c @@ -245,7 +245,6 @@ esp_err_t gptimer_register_event_callbacks(gptimer_handle_t timer, const gptimer { gptimer_group_t *group = NULL; ESP_RETURN_ON_FALSE(timer && cbs, ESP_ERR_INVALID_ARG, TAG, "invalid argument"); - ESP_RETURN_ON_FALSE(timer->fsm == GPTIMER_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "timer not in init state"); group = timer->group; int group_id = group->group_id; int timer_id = timer->timer_id; @@ -261,6 +260,7 @@ esp_err_t gptimer_register_event_callbacks(gptimer_handle_t timer, const gptimer // lazy install interrupt service if (!timer->intr) { + ESP_RETURN_ON_FALSE(timer->fsm == GPTIMER_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "timer not in init state"); // if user wants to control the interrupt allocation more precisely, we can expose more flags in `gptimer_config_t` int isr_flags = timer->flags.intr_shared ? ESP_INTR_FLAG_SHARED | GPTIMER_INTR_ALLOC_FLAGS : GPTIMER_INTR_ALLOC_FLAGS; ESP_RETURN_ON_ERROR(esp_intr_alloc_intrstatus(timer_group_periph_signals.groups[group_id].timer_irq_id[timer_id], isr_flags, diff --git a/components/driver/include/driver/gptimer.h b/components/driver/include/driver/gptimer.h index e6fe50420d..1f4f9cd9a8 100644 --- a/components/driver/include/driver/gptimer.h +++ b/components/driver/include/driver/gptimer.h @@ -138,7 +138,8 @@ esp_err_t gptimer_get_raw_count(gptimer_handle_t timer, uint64_t *value); * @brief Set callbacks for GPTimer * * @note User registered callbacks are expected to be runnable within ISR context - * @note This function should be called when the timer is in the init state (i.e. before calling `gptimer_enable()`) + * @note The first call to this function needs to be before the call to `gptimer_enable` + * @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL. * * @param[in] timer Timer handle created by `gptimer_new_timer()` * @param[in] cbs Group of callback functions diff --git a/components/driver/include/driver/mcpwm_cap.h b/components/driver/include/driver/mcpwm_cap.h index 54aa3db59b..782b7042ab 100644 --- a/components/driver/include/driver/mcpwm_cap.h +++ b/components/driver/include/driver/mcpwm_cap.h @@ -168,6 +168,8 @@ typedef struct { /** * @brief Set event callbacks for MCPWM capture channel * + * @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL. + * * @param[in] cap_channel MCPWM capture channel handle, allocated by `mcpwm_new_capture_channel()` * @param[in] cbs Group of callback functions * @param[in] user_data User data, which will be passed to callback functions directly diff --git a/components/driver/include/driver/mcpwm_cmpr.h b/components/driver/include/driver/mcpwm_cmpr.h index d539f8a220..8ebae75736 100644 --- a/components/driver/include/driver/mcpwm_cmpr.h +++ b/components/driver/include/driver/mcpwm_cmpr.h @@ -63,6 +63,8 @@ typedef struct { /** * @brief Set event callbacks for MCPWM comparator * + * @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL. + * * @param[in] cmpr MCPWM comparator handle, allocated by `mcpwm_new_comparator()` * @param[in] cbs Group of callback functions * @param[in] user_data User data, which will be passed to callback functions directly diff --git a/components/driver/include/driver/mcpwm_fault.h b/components/driver/include/driver/mcpwm_fault.h index ddc635c679..e9833c4996 100644 --- a/components/driver/include/driver/mcpwm_fault.h +++ b/components/driver/include/driver/mcpwm_fault.h @@ -97,6 +97,8 @@ typedef struct { /** * @brief Set event callbacks for MCPWM fault * + * @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL. + * * @param[in] fault MCPWM GPIO fault handle, allocated by `mcpwm_new_gpio_fault()` * @param[in] cbs Group of callback functions * @param[in] user_data User data, which will be passed to callback functions directly diff --git a/components/driver/include/driver/mcpwm_oper.h b/components/driver/include/driver/mcpwm_oper.h index 5f89f806fc..bc30887295 100644 --- a/components/driver/include/driver/mcpwm_oper.h +++ b/components/driver/include/driver/mcpwm_oper.h @@ -119,6 +119,8 @@ typedef struct { /** * @brief Set event callbacks for MCPWM operator * + * @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL. + * * @param[in] oper MCPWM operator handle, allocated by `mcpwm_new_operator()` * @param[in] cbs Group of callback functions * @param[in] user_data User data, which will be passed to callback functions directly diff --git a/components/driver/include/driver/mcpwm_timer.h b/components/driver/include/driver/mcpwm_timer.h index 3bcec03ab5..1cb1d6d8cf 100644 --- a/components/driver/include/driver/mcpwm_timer.h +++ b/components/driver/include/driver/mcpwm_timer.h @@ -107,6 +107,9 @@ esp_err_t mcpwm_timer_start_stop(mcpwm_timer_handle_t timer, mcpwm_timer_start_s /** * @brief Set event callbacks for MCPWM timer * + * @note The first call to this function needs to be before the call to `mcpwm_timer_enable` + * @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL. + * * @param[in] timer MCPWM timer handle, allocated by `mcpwm_new_timer()` * @param[in] cbs Group of callback functions * @param[in] user_data User data, which will be passed to callback functions directly diff --git a/components/driver/include/driver/pulse_cnt.h b/components/driver/include/driver/pulse_cnt.h index ccaffead23..cef84b447f 100644 --- a/components/driver/include/driver/pulse_cnt.h +++ b/components/driver/include/driver/pulse_cnt.h @@ -233,7 +233,8 @@ esp_err_t pcnt_unit_get_count(pcnt_unit_handle_t unit, int *value); * @brief Set event callbacks for PCNT unit * * @note User registered callbacks are expected to be runnable within ISR context - * @note This function is only allowed to be called when the unit is in the init state (i.e. before calling `pcnt_unit_enable()`) + * @note The first call to this function needs to be before the call to `pcnt_unit_enable` + * @note User can deregister a previously registered callback by calling this function and setting the callback member in the `cbs` structure to NULL. * * @param[in] unit PCNT unit handle created by `pcnt_new_unit()` * @param[in] cbs Group of callback functions diff --git a/components/driver/mcpwm/mcpwm_timer.c b/components/driver/mcpwm/mcpwm_timer.c index 09c22c287d..31ff2ded68 100644 --- a/components/driver/mcpwm/mcpwm_timer.c +++ b/components/driver/mcpwm/mcpwm_timer.c @@ -166,7 +166,6 @@ esp_err_t mcpwm_del_timer(mcpwm_timer_handle_t timer) esp_err_t mcpwm_timer_register_event_callbacks(mcpwm_timer_handle_t timer, const mcpwm_timer_event_callbacks_t *cbs, void *user_data) { ESP_RETURN_ON_FALSE(timer && cbs, ESP_ERR_INVALID_ARG, TAG, "invalid argument"); - ESP_RETURN_ON_FALSE(timer->fsm == MCPWM_TIMER_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "timer not in init state"); mcpwm_group_t *group = timer->group; int group_id = group->group_id; int timer_id = timer->timer_id; @@ -189,6 +188,7 @@ esp_err_t mcpwm_timer_register_event_callbacks(mcpwm_timer_handle_t timer, const // lazy install interrupt service if (!timer->intr) { + ESP_RETURN_ON_FALSE(timer->fsm == MCPWM_TIMER_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "timer not in init state"); int isr_flags = MCPWM_INTR_ALLOC_FLAG; ESP_RETURN_ON_ERROR(esp_intr_alloc_intrstatus(mcpwm_periph_signals.groups[group_id].irq_id, isr_flags, (uint32_t)mcpwm_ll_intr_get_status_reg(hal->dev), MCPWM_LL_EVENT_TIMER_MASK(timer_id), diff --git a/components/driver/pulse_cnt.c b/components/driver/pulse_cnt.c index cb4081673d..6f8237d109 100644 --- a/components/driver/pulse_cnt.c +++ b/components/driver/pulse_cnt.c @@ -366,7 +366,6 @@ esp_err_t pcnt_unit_register_event_callbacks(pcnt_unit_handle_t unit, const pcnt { ESP_RETURN_ON_FALSE(unit && cbs, ESP_ERR_INVALID_ARG, TAG, "invalid argument"); // unit event callbacks should be registered in init state - ESP_RETURN_ON_FALSE(unit->fsm == PCNT_UNIT_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "unit not in init state"); pcnt_group_t *group = unit->group; int group_id = group->group_id; int unit_id = unit->unit_id; @@ -382,6 +381,7 @@ esp_err_t pcnt_unit_register_event_callbacks(pcnt_unit_handle_t unit, const pcnt // lazy install interrupt service if (!unit->intr) { + ESP_RETURN_ON_FALSE(unit->fsm == PCNT_UNIT_FSM_INIT, ESP_ERR_INVALID_STATE, TAG, "unit not in init state"); int isr_flags = PCNT_INTR_ALLOC_FLAGS; ESP_RETURN_ON_ERROR(esp_intr_alloc_intrstatus(pcnt_periph_signals.groups[group_id].irq, isr_flags, (uint32_t)pcnt_ll_get_intr_status_reg(group->hal.dev), PCNT_LL_UNIT_WATCH_EVENT(unit_id),