From b76254895cce23278774a9706aa776100da0b0e6 Mon Sep 17 00:00:00 2001 From: morris Date: Sun, 28 Sep 2025 18:35:34 +0800 Subject: [PATCH] refactor(mcpwm): remove varg action setting functions for timer, compare, and brake events --- .../include/driver/mcpwm_fault.h | 1 - .../include/driver/mcpwm_gen.h | 50 ----------- components/esp_driver_mcpwm/src/mcpwm_gen.c | 65 -------------- .../esp_driver_mcpwm/src/mcpwm_private.h | 1 - .../test_apps/mcpwm/main/test_mcpwm_gen.c | 77 ++++++++-------- .../test_apps/mcpwm/main/test_mcpwm_sleep.c | 8 +- docs/en/api-reference/peripherals/mcpwm.rst | 89 ++++++++----------- .../release-5.x/5.0/peripherals.rst | 6 +- .../release-6.x/6.0/peripherals.rst | 23 +++++ .../zh_CN/api-reference/peripherals/mcpwm.rst | 89 ++++++++----------- .../release-5.x/5.0/peripherals.rst | 6 +- .../release-6.x/6.0/peripherals.rst | 23 +++++ .../main/svpwm/esp_svpwm.c | 10 ++- tools/idf_py_actions/hints.yml | 5 ++ 14 files changed, 177 insertions(+), 276 deletions(-) diff --git a/components/esp_driver_mcpwm/include/driver/mcpwm_fault.h b/components/esp_driver_mcpwm/include/driver/mcpwm_fault.h index 5ab70c6dca0..69fa8cb727d 100644 --- a/components/esp_driver_mcpwm/include/driver/mcpwm_fault.h +++ b/components/esp_driver_mcpwm/include/driver/mcpwm_fault.h @@ -8,7 +8,6 @@ #include #include -#include #include "esp_err.h" #include "driver/mcpwm_types.h" diff --git a/components/esp_driver_mcpwm/include/driver/mcpwm_gen.h b/components/esp_driver_mcpwm/include/driver/mcpwm_gen.h index dd3cf089c34..924c0fe9313 100644 --- a/components/esp_driver_mcpwm/include/driver/mcpwm_gen.h +++ b/components/esp_driver_mcpwm/include/driver/mcpwm_gen.h @@ -8,7 +8,6 @@ #include #include -#include #include "esp_err.h" #include "driver/mcpwm_types.h" @@ -84,8 +83,6 @@ typedef struct { */ #define MCPWM_GEN_TIMER_EVENT_ACTION(dir, ev, act) \ (mcpwm_gen_timer_event_action_t) { .direction = dir, .event = ev, .action = act } -#define MCPWM_GEN_TIMER_EVENT_ACTION_END() \ - (mcpwm_gen_timer_event_action_t) { .event = MCPWM_TIMER_EVENT_INVALID } /** * @brief Set generator action on MCPWM timer event @@ -100,21 +97,6 @@ typedef struct { */ esp_err_t mcpwm_generator_set_action_on_timer_event(mcpwm_gen_handle_t gen, mcpwm_gen_timer_event_action_t ev_act); -/** - * @brief Set generator actions on multiple MCPWM timer events - * - * @note This is an aggregation version of `mcpwm_generator_set_action_on_timer_event`, which allows user to set multiple actions in one call. - * - * @param[in] gen MCPWM generator handle, allocated by `mcpwm_new_generator()` - * @param[in] ev_act MCPWM timer event action list, must be terminated by `MCPWM_GEN_TIMER_EVENT_ACTION_END()` - * @return - * - ESP_OK: Set generator actions successfully - * - ESP_ERR_INVALID_ARG: Set generator actions failed because of invalid argument - * - ESP_ERR_INVALID_STATE: Set generator actions failed because of timer is not connected to operator - * - ESP_FAIL: Set generator actions failed because of other error - */ -esp_err_t mcpwm_generator_set_actions_on_timer_event(mcpwm_gen_handle_t gen, mcpwm_gen_timer_event_action_t ev_act, ...); - /** * @brief Generator action on specific comparator event */ @@ -129,8 +111,6 @@ typedef struct { */ #define MCPWM_GEN_COMPARE_EVENT_ACTION(dir, cmp, act) \ (mcpwm_gen_compare_event_action_t) { .direction = dir, .comparator = cmp, .action = act } -#define MCPWM_GEN_COMPARE_EVENT_ACTION_END() \ - (mcpwm_gen_compare_event_action_t) { .comparator = NULL } /** * @brief Set generator action on MCPWM compare event @@ -144,20 +124,6 @@ typedef struct { */ esp_err_t mcpwm_generator_set_action_on_compare_event(mcpwm_gen_handle_t generator, mcpwm_gen_compare_event_action_t ev_act); -/** - * @brief Set generator actions on multiple MCPWM compare events - * - * @note This is an aggregation version of `mcpwm_generator_set_action_on_compare_event`, which allows user to set multiple actions in one call. - * - * @param[in] generator MCPWM generator handle, allocated by `mcpwm_new_generator()` - * @param[in] ev_act MCPWM compare event action list, must be terminated by `MCPWM_GEN_COMPARE_EVENT_ACTION_END()` - * @return - * - ESP_OK: Set generator actions successfully - * - ESP_ERR_INVALID_ARG: Set generator actions failed because of invalid argument - * - ESP_FAIL: Set generator actions failed because of other error - */ -esp_err_t mcpwm_generator_set_actions_on_compare_event(mcpwm_gen_handle_t generator, mcpwm_gen_compare_event_action_t ev_act, ...); - /** * @brief Generator action on specific brake event */ @@ -172,8 +138,6 @@ typedef struct { */ #define MCPWM_GEN_BRAKE_EVENT_ACTION(dir, mode, act) \ (mcpwm_gen_brake_event_action_t) { .direction = dir, .brake_mode = mode, .action = act } -#define MCPWM_GEN_BRAKE_EVENT_ACTION_END() \ - (mcpwm_gen_brake_event_action_t) { .brake_mode = MCPWM_OPER_BRAKE_MODE_INVALID } /** * @brief Set generator action on MCPWM brake event @@ -187,20 +151,6 @@ typedef struct { */ esp_err_t mcpwm_generator_set_action_on_brake_event(mcpwm_gen_handle_t generator, mcpwm_gen_brake_event_action_t ev_act); -/** - * @brief Set generator actions on multiple MCPWM brake events - * - * @note This is an aggregation version of `mcpwm_generator_set_action_on_brake_event`, which allows user to set multiple actions in one call. - * - * @param[in] generator MCPWM generator handle, allocated by `mcpwm_new_generator()` - * @param[in] ev_act MCPWM brake event action list, must be terminated by `MCPWM_GEN_BRAKE_EVENT_ACTION_END()` - * @return - * - ESP_OK: Set generator actions successfully - * - ESP_ERR_INVALID_ARG: Set generator actions failed because of invalid argument - * - ESP_FAIL: Set generator actions failed because of other error - */ -esp_err_t mcpwm_generator_set_actions_on_brake_event(mcpwm_gen_handle_t generator, mcpwm_gen_brake_event_action_t ev_act, ...); - /** * @brief Generator action on specific fault event */ diff --git a/components/esp_driver_mcpwm/src/mcpwm_gen.c b/components/esp_driver_mcpwm/src/mcpwm_gen.c index ca1bc7e1435..db6e5f6c4fb 100644 --- a/components/esp_driver_mcpwm/src/mcpwm_gen.c +++ b/components/esp_driver_mcpwm/src/mcpwm_gen.c @@ -160,37 +160,6 @@ esp_err_t mcpwm_generator_set_action_on_timer_event(mcpwm_gen_handle_t gen, mcpw return ESP_OK; } -esp_err_t mcpwm_generator_set_actions_on_timer_event(mcpwm_gen_handle_t gen, mcpwm_gen_timer_event_action_t ev_act, ...) -{ - ESP_RETURN_ON_FALSE(gen, ESP_ERR_INVALID_ARG, TAG, "invalid argument"); - mcpwm_oper_t *oper = gen->oper; - mcpwm_group_t *group = oper->group; - mcpwm_timer_t *timer = oper->timer; - ESP_RETURN_ON_FALSE(timer, ESP_ERR_INVALID_STATE, TAG, "no timer is connected to the operator"); - mcpwm_gen_timer_event_action_t ev_act_itor = ev_act; - bool invalid_utep = false; - bool invalid_dtez = false; - va_list it = {}; - va_start(it, ev_act); - while (ev_act_itor.event != MCPWM_TIMER_EVENT_INVALID) { - invalid_utep = (timer->count_mode == MCPWM_TIMER_COUNT_MODE_UP_DOWN) && - (ev_act_itor.direction == MCPWM_TIMER_DIRECTION_UP) && - (ev_act_itor.event == MCPWM_TIMER_EVENT_FULL); - invalid_dtez = (timer->count_mode == MCPWM_TIMER_COUNT_MODE_UP_DOWN) && - (ev_act_itor.direction == MCPWM_TIMER_DIRECTION_DOWN) && - (ev_act_itor.event == MCPWM_TIMER_EVENT_EMPTY); - if (invalid_utep || invalid_dtez) { - va_end(it); - ESP_RETURN_ON_FALSE(false, ESP_ERR_INVALID_ARG, TAG, "UTEP and DTEZ can't be reached under MCPWM_TIMER_COUNT_MODE_UP_DOWN mode"); - } - mcpwm_ll_generator_set_action_on_timer_event(group->hal.dev, oper->oper_id, gen->gen_id, - ev_act_itor.direction, ev_act_itor.event, ev_act_itor.action); - ev_act_itor = va_arg(it, mcpwm_gen_timer_event_action_t); - } - va_end(it); - return ESP_OK; -} - esp_err_t mcpwm_generator_set_action_on_compare_event(mcpwm_gen_handle_t gen, mcpwm_gen_compare_event_action_t ev_act) { ESP_RETURN_ON_FALSE(gen, ESP_ERR_INVALID_ARG, TAG, "invalid argument"); @@ -202,23 +171,6 @@ esp_err_t mcpwm_generator_set_action_on_compare_event(mcpwm_gen_handle_t gen, mc return ESP_OK; } -esp_err_t mcpwm_generator_set_actions_on_compare_event(mcpwm_gen_handle_t gen, mcpwm_gen_compare_event_action_t ev_act, ...) -{ - ESP_RETURN_ON_FALSE(gen, ESP_ERR_INVALID_ARG, TAG, "invalid argument"); - mcpwm_oper_t *oper = gen->oper; - mcpwm_group_t *group = oper->group; - mcpwm_gen_compare_event_action_t ev_act_itor = ev_act; - va_list it = {}; - va_start(it, ev_act); - while (ev_act_itor.comparator) { - mcpwm_ll_generator_set_action_on_compare_event(group->hal.dev, oper->oper_id, gen->gen_id, - ev_act_itor.direction, ev_act_itor.comparator->cmpr_id, ev_act_itor.action); - ev_act_itor = va_arg(it, mcpwm_gen_compare_event_action_t); - } - va_end(it); - return ESP_OK; -} - esp_err_t mcpwm_generator_set_action_on_brake_event(mcpwm_gen_handle_t gen, mcpwm_gen_brake_event_action_t ev_act) { ESP_RETURN_ON_FALSE(gen, ESP_ERR_INVALID_ARG, TAG, "invalid argument"); @@ -230,23 +182,6 @@ esp_err_t mcpwm_generator_set_action_on_brake_event(mcpwm_gen_handle_t gen, mcpw return ESP_OK; } -esp_err_t mcpwm_generator_set_actions_on_brake_event(mcpwm_gen_handle_t gen, mcpwm_gen_brake_event_action_t ev_act, ...) -{ - ESP_RETURN_ON_FALSE(gen, ESP_ERR_INVALID_ARG, TAG, "invalid argument"); - mcpwm_oper_t *oper = gen->oper; - mcpwm_group_t *group = oper->group; - mcpwm_gen_brake_event_action_t ev_act_itor = ev_act; - va_list it = {}; - va_start(it, ev_act); - while (ev_act_itor.brake_mode != MCPWM_OPER_BRAKE_MODE_INVALID) { - mcpwm_ll_generator_set_action_on_brake_event(group->hal.dev, oper->oper_id, gen->gen_id, - ev_act_itor.direction, ev_act_itor.brake_mode, ev_act_itor.action); - ev_act_itor = va_arg(it, mcpwm_gen_brake_event_action_t); - } - va_end(it); - return ESP_OK; -} - esp_err_t mcpwm_generator_set_action_on_fault_event(mcpwm_gen_handle_t gen, mcpwm_gen_fault_event_action_t ev_act) { ESP_RETURN_ON_FALSE(gen, ESP_ERR_INVALID_ARG, TAG, "invalid argument"); diff --git a/components/esp_driver_mcpwm/src/mcpwm_private.h b/components/esp_driver_mcpwm/src/mcpwm_private.h index 6c486769e6f..36d806b6000 100644 --- a/components/esp_driver_mcpwm/src/mcpwm_private.h +++ b/components/esp_driver_mcpwm/src/mcpwm_private.h @@ -8,7 +8,6 @@ #include #include -#include #include #include #include "sdkconfig.h" diff --git a/components/esp_driver_mcpwm/test_apps/mcpwm/main/test_mcpwm_gen.c b/components/esp_driver_mcpwm/test_apps/mcpwm/main/test_mcpwm_gen.c index 0d6e73cb3fb..fe389d78e41 100644 --- a/components/esp_driver_mcpwm/test_apps/mcpwm/main/test_mcpwm_gen.c +++ b/components/esp_driver_mcpwm/test_apps/mcpwm/main/test_mcpwm_gen.c @@ -260,10 +260,10 @@ TEST_CASE("mcpwm_generator_action_on_timer_event", "[mcpwm]") TEST_ESP_OK(mcpwm_new_generator(oper, &gen_config, &gen)); printf("set generator to output high on timer full\r\n"); - TEST_ESP_OK(mcpwm_generator_set_actions_on_timer_event(gen, - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_KEEP), - MCPWM_GEN_TIMER_EVENT_ACTION_END())); + TEST_ESP_OK(mcpwm_generator_set_action_on_timer_event(gen, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_HIGH))); + TEST_ESP_OK(mcpwm_generator_set_action_on_timer_event(gen, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_KEEP))); printf("start timer\r\n"); TEST_ESP_OK(mcpwm_timer_start_stop(timer, MCPWM_TIMER_START_NO_STOP)); vTaskDelay(pdMS_TO_TICKS(100)); @@ -272,10 +272,10 @@ TEST_CASE("mcpwm_generator_action_on_timer_event", "[mcpwm]") TEST_ASSERT_EQUAL(1, gpio_get_level(generator_gpio)); printf("set generator to output low on timer full\r\n"); - TEST_ESP_OK(mcpwm_generator_set_actions_on_timer_event(gen, - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_KEEP), - MCPWM_GEN_TIMER_EVENT_ACTION_END())); + TEST_ESP_OK(mcpwm_generator_set_action_on_timer_event(gen, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_LOW))); + TEST_ESP_OK(mcpwm_generator_set_action_on_timer_event(gen, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_KEEP))); printf("start timer\r\n"); TEST_ESP_OK(mcpwm_timer_start_stop(timer, MCPWM_TIMER_START_NO_STOP)); vTaskDelay(pdMS_TO_TICKS(100)); @@ -457,49 +457,48 @@ static void single_edge_active_low(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t g static void pulse_placement(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb) { - TEST_ESP_OK(mcpwm_generator_set_actions_on_compare_event(gena, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); - TEST_ESP_OK(mcpwm_generator_set_actions_on_timer_event(genb, - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_TOGGLE), - MCPWM_GEN_TIMER_EVENT_ACTION_END())); + TEST_ESP_OK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH))); + TEST_ESP_OK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW))); + TEST_ESP_OK(mcpwm_generator_set_action_on_timer_event(genb, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_TOGGLE))); } static void dual_edge_active_low_asym(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb) { - TEST_ESP_OK(mcpwm_generator_set_actions_on_compare_event(gena, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); - TEST_ESP_OK(mcpwm_generator_set_actions_on_timer_event(genb, - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_TIMER_EVENT_ACTION_END())); + TEST_ESP_OK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH))); + TEST_ESP_OK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_LOW))); + TEST_ESP_OK(mcpwm_generator_set_action_on_timer_event(genb, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_LOW))); + TEST_ESP_OK(mcpwm_generator_set_action_on_timer_event(genb, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_HIGH))); } static void dual_edge_active_low_sym(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb) { - TEST_ESP_OK(mcpwm_generator_set_actions_on_compare_event(gena, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpa, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); - TEST_ESP_OK(mcpwm_generator_set_actions_on_compare_event(genb, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); + TEST_ESP_OK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH))); + TEST_ESP_OK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpa, MCPWM_GEN_ACTION_LOW))); + TEST_ESP_OK(mcpwm_generator_set_action_on_compare_event(genb, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_HIGH))); + TEST_ESP_OK(mcpwm_generator_set_action_on_compare_event(genb, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_LOW))); } static void dual_edge_complementary(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb) { - TEST_ESP_OK(mcpwm_generator_set_actions_on_compare_event(gena, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpa, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); - TEST_ESP_OK(mcpwm_generator_set_actions_on_compare_event(genb, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); + TEST_ESP_OK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH))); + TEST_ESP_OK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpa, MCPWM_GEN_ACTION_LOW))); + TEST_ESP_OK(mcpwm_generator_set_action_on_compare_event(genb, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW))); + TEST_ESP_OK(mcpwm_generator_set_action_on_compare_event(genb, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_HIGH))); } TEST_CASE("mcpwm_generator_action_on_compare_event", "[mcpwm]") diff --git a/components/esp_driver_mcpwm/test_apps/mcpwm/main/test_mcpwm_sleep.c b/components/esp_driver_mcpwm/test_apps/mcpwm/main/test_mcpwm_sleep.c index 94aa6b48c8d..eb3d30ebb69 100644 --- a/components/esp_driver_mcpwm/test_apps/mcpwm/main/test_mcpwm_sleep.c +++ b/components/esp_driver_mcpwm/test_apps/mcpwm/main/test_mcpwm_sleep.c @@ -62,10 +62,10 @@ static void test_mcpwm_timer_sleep_retention(bool allow_pd) TEST_ESP_OK(mcpwm_new_generator(oper, &gen_config, &gen)); printf("set generator to output high on timer full\r\n"); - TEST_ESP_OK(mcpwm_generator_set_actions_on_timer_event(gen, - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_KEEP), - MCPWM_GEN_TIMER_EVENT_ACTION_END())); + TEST_ESP_OK(mcpwm_generator_set_action_on_timer_event(gen, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_HIGH))); + TEST_ESP_OK(mcpwm_generator_set_action_on_timer_event(gen, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_KEEP))); // go to sleep esp_sleep_context_t sleep_ctx; diff --git a/docs/en/api-reference/peripherals/mcpwm.rst b/docs/en/api-reference/peripherals/mcpwm.rst index 2255a0b7561..3a9277a7935 100644 --- a/docs/en/api-reference/peripherals/mcpwm.rst +++ b/docs/en/api-reference/peripherals/mcpwm.rst @@ -318,7 +318,7 @@ Generator Actions on Events Set Generator Action on Timer Event ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -One generator can set multiple actions on different timer events, by calling :cpp:func:`mcpwm_generator_set_actions_on_timer_event` with a variable number of action configurations. The action configuration is defined in :cpp:type:`mcpwm_gen_timer_event_action_t`: +A single generator can be configured to perform multiple actions in response to different timer events. To achieve this, invoke :cpp:func:`mcpwm_generator_set_action_on_timer_event` for each desired event-action pair. The details of each action are specified using the :cpp:type:`mcpwm_gen_timer_event_action_t` structure. - :cpp:member:`mcpwm_gen_timer_event_action_t::direction` specifies the timer direction. The supported directions are listed in :cpp:type:`mcpwm_timer_direction_t`. - :cpp:member:`mcpwm_gen_timer_event_action_t::event` specifies the timer event. The supported timer events are listed in :cpp:type:`mcpwm_timer_event_t`. @@ -326,14 +326,10 @@ One generator can set multiple actions on different timer events, by calling :cp There is a helper macro :c:macro:`MCPWM_GEN_TIMER_EVENT_ACTION` to simplify the construction of a timer event action entry. -Please note, the argument list of :cpp:func:`mcpwm_generator_set_actions_on_timer_event` **must** be terminated by :c:macro:`MCPWM_GEN_TIMER_EVENT_ACTION_END`. - -You can also set the timer action one by one by calling :cpp:func:`mcpwm_generator_set_action_on_timer_event` without varargs. - Set Generator Action on Compare Event ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -One generator can set multiple actions on different compare events, by calling :cpp:func:`mcpwm_generator_set_actions_on_compare_event` with a variable number of action configurations. The action configuration is defined in :cpp:type:`mcpwm_gen_compare_event_action_t`: +A single generator can be configured to perform multiple actions in response to different compare events. To achieve this, invoke :cpp:func:`mcpwm_generator_set_action_on_compare_event` for each desired compare event and action pair. The specific action settings are encapsulated in the :cpp:type:`mcpwm_gen_compare_event_action_t` structure. - :cpp:member:`mcpwm_gen_compare_event_action_t::direction` specifies the timer direction. The supported directions are listed in :cpp:type:`mcpwm_timer_direction_t`. - :cpp:member:`mcpwm_gen_compare_event_action_t::comparator` specifies the comparator handle. See `MCPWM Comparators <#mcpwm-comparators>`__ for how to allocate a comparator. @@ -341,14 +337,10 @@ One generator can set multiple actions on different compare events, by calling : There is a helper macro :c:macro:`MCPWM_GEN_COMPARE_EVENT_ACTION` to simplify the construction of a compare event action entry. -Please note, the argument list of :cpp:func:`mcpwm_generator_set_actions_on_compare_event` **must** be terminated by :c:macro:`MCPWM_GEN_COMPARE_EVENT_ACTION_END`. - -You can also set the compare action one by one by calling :cpp:func:`mcpwm_generator_set_action_on_compare_event` without varargs. - Set Generator Action on Fault Event ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -One generator can set action on fault based trigger events, by calling :cpp:func:`mcpwm_generator_set_action_on_fault_event` with an action configurations. The action configuration is defined in :cpp:type:`mcpwm_gen_fault_event_action_t`: +A single generator can be configured to perform multiple actions in response to fault events. To achieve this, invoke :cpp:func:`mcpwm_generator_set_action_on_fault_event` for each desired action. The specific actions to be taken are described by the :cpp:type:`mcpwm_gen_fault_event_action_t` structure. - :cpp:member:`mcpwm_gen_fault_event_action_t::direction` specifies the timer direction. The supported directions are listed in :cpp:type:`mcpwm_timer_direction_t`. - :cpp:member:`mcpwm_gen_fault_event_action_t::fault` specifies the fault used for the trigger. See `MCPWM Faults <#mcpwm-faults>`__ for how to allocate a fault. @@ -360,12 +352,10 @@ The trigger only support GPIO fault. when the input is not a GPIO fault, this fu There is a helper macro :c:macro:`MCPWM_GEN_FAULT_EVENT_ACTION` to simplify the construction of a trigger event action entry. -Please note, fault event does not have variadic function like :cpp:func:`mcpwm_generator_set_actions_on_fault_event`. - Set Generator Action on Sync Event ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -One generator can set action on sync based trigger events, by calling :cpp:func:`mcpwm_generator_set_action_on_sync_event` with an action configurations. The action configuration is defined in :cpp:type:`mcpwm_gen_sync_event_action_t`: +A single generator can be configured to perform multiple actions in response to different synchronization events. This is achieved by invoking :cpp:func:`mcpwm_generator_set_action_on_sync_event` for each desired event-action pair. The specific action to be taken for each synchronization event is described by the :cpp:type:`mcpwm_gen_sync_event_action_t` structure. - :cpp:member:`mcpwm_gen_sync_event_action_t::direction` specifies the timer direction. The supported directions are listed in :cpp:type:`mcpwm_timer_direction_t`. - :cpp:member:`mcpwm_gen_sync_event_action_t::sync` specifies the sync source used for the trigger. See `MCPWM Sync Sources <#mcpwm-sync-sources>`__ for how to allocate a sync source. @@ -377,8 +367,6 @@ The trigger only support one sync action, regardless of the kinds. When set sync There is a helper macro :c:macro:`MCPWM_GEN_SYNC_EVENT_ACTION` to simplify the construction of a trigger event action entry. -Please note, sync event does not have variadic function like :cpp:func:`mcpwm_generator_set_actions_on_sync_event`. - .. _mcpwm-classical-pwm-waveforms-and-generator-configurations: @@ -439,13 +427,12 @@ Pulse Placement Asymmetric Waveform static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb) { - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(genb, - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_TOGGLE), - MCPWM_GEN_TIMER_EVENT_ACTION_END())); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_timer_event(genb, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_TOGGLE))); } Dual Edge Asymmetric Waveform - Active Low @@ -457,14 +444,14 @@ Dual Edge Asymmetric Waveform - Active Low static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb) { - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(genb, - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_TIMER_EVENT_ACTION_END())); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_LOW))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_timer_event(genb, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_LOW))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_timer_event(genb, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_HIGH))); } Dual Edge Symmetric Waveform - Active Low @@ -476,14 +463,14 @@ Dual Edge Symmetric Waveform - Active Low static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb) { - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpa, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(genb, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpa, MCPWM_GEN_ACTION_LOW))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(genb, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_HIGH))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(genb, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_LOW))); } Dual Edge Symmetric Waveform - Complementary @@ -495,14 +482,14 @@ Dual Edge Symmetric Waveform - Complementary static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb) { - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpa, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(genb, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpa, MCPWM_GEN_ACTION_LOW))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(genb, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(genb, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_HIGH))); } @@ -797,7 +784,7 @@ The way that MCPWM operator reacts to the fault is called **Brake**. The MCPWM o Set Generator Action on Brake Event ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -One generator can set multiple actions on different brake events, by calling :cpp:func:`mcpwm_generator_set_actions_on_brake_event` with a variable number of action configurations. The action configuration is defined in :cpp:type:`mcpwm_gen_brake_event_action_t`: +A single generator can be configured to perform multiple actions in response to brake events. To achieve this, invoke :cpp:func:`mcpwm_generator_set_action_on_brake_event` for each desired action. The specific actions available for configuration are defined in :cpp:type:`mcpwm_gen_brake_event_action_t`. - :cpp:member:`mcpwm_gen_brake_event_action_t::direction` specifies the timer direction. The supported directions are listed in :cpp:type:`mcpwm_timer_direction_t`. - :cpp:member:`mcpwm_gen_brake_event_action_t::brake_mode` specifies the brake mode. The supported brake modes are listed in the :cpp:type:`mcpwm_operator_brake_mode_t`. @@ -805,10 +792,6 @@ One generator can set multiple actions on different brake events, by calling :cp There is a helper macro :c:macro:`MCPWM_GEN_BRAKE_EVENT_ACTION` to simplify the construction of a brake event action entry. -Please note, the argument list of :cpp:func:`mcpwm_generator_set_actions_on_brake_event` **must** be terminated by :c:macro:`MCPWM_GEN_BRAKE_EVENT_ACTION_END`. - -You can also set the brake action one by one by calling :cpp:func:`mcpwm_generator_set_action_on_brake_event` without varargs. - Register Fault Event Callbacks ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -843,7 +826,7 @@ This function will lazy the install interrupt service for the MCPWM operator, wh Generator Force Actions ^^^^^^^^^^^^^^^^^^^^^^^ -Software can override generator output level at runtime, by calling :cpp:func:`mcpwm_generator_set_force_level`. The software force level always has a higher priority than other event actions set in e.g., :cpp:func:`mcpwm_generator_set_actions_on_timer_event`. +Software can override generator output level at runtime, by calling :cpp:func:`mcpwm_generator_set_force_level`. The software force level always has a higher priority than other event actions set in e.g., :cpp:func:`mcpwm_generator_set_action_on_timer_event`. - Set the ``level`` to -1 means to disable the force action, and the generator's output level will be controlled by the event actions again. - Set the ``hold_on`` to true, and the force output level will keep alive until it is removed by assigning ``level`` to -1. diff --git a/docs/en/migration-guides/release-5.x/5.0/peripherals.rst b/docs/en/migration-guides/release-5.x/5.0/peripherals.rst index 6307800887a..7534d5e0ad2 100644 --- a/docs/en/migration-guides/release-5.x/5.0/peripherals.rst +++ b/docs/en/migration-guides/release-5.x/5.0/peripherals.rst @@ -433,12 +433,12 @@ LCD ^^^^^^^^^^^^^^^^^^^^^^^^^ - ``mcpwm_gpio_init`` and ``mcpwm_set_pin``: GPIO configurations are moved to submodule's own configuration. e.g., set the PWM GPIO in :cpp:member:`mcpwm_generator_config_t::gen_gpio_num`. - - ``mcpwm_init``: To get an expected PWM waveform, users need to allocated at least one MCPWM timer and MCPWM operator, then connect them by calling :cpp:func:`mcpwm_operator_connect_timer`. After that, users should set the generator's actions on various events by calling e.g., :cpp:func:`mcpwm_generator_set_actions_on_timer_event`, :cpp:func:`mcpwm_generator_set_actions_on_compare_event`. + - ``mcpwm_init``: To get an expected PWM waveform, users need to allocated at least one MCPWM timer and MCPWM operator, then connect them by calling :cpp:func:`mcpwm_operator_connect_timer`. After that, users should set the generator's actions on various events by calling e.g., :cpp:func:`mcpwm_generator_set_action_on_timer_event`, :cpp:func:`mcpwm_generator_set_action_on_compare_event`. - ``mcpwm_group_set_resolution``: in the new driver, the group resolution is fixed to the maximum, usually it is 80 MHz. - ``mcpwm_timer_set_resolution``: MCPWM Timer resolution is set in :cpp:member:`mcpwm_timer_config_t::resolution_hz`. - ``mcpwm_set_frequency``: PWM frequency is determined by :cpp:member:`mcpwm_timer_config_t::resolution_hz`, :cpp:member:`mcpwm_timer_config_t::count_mode` and :cpp:member:`mcpwm_timer_config_t::period_ticks`. - ``mcpwm_set_duty``: To set the PWM duty cycle, users should call :cpp:func:`mcpwm_comparator_set_compare_value` to change comparator's threshold. - - ``mcpwm_set_duty_type``: There is no preset duty cycle types. The duty cycle type is configured by setting different generator actions. e.g., :cpp:func:`mcpwm_generator_set_actions_on_timer_event`. + - ``mcpwm_set_duty_type``: There is no preset duty cycle types. The duty cycle type is configured by setting different generator actions. e.g., :cpp:func:`mcpwm_generator_set_action_on_timer_event`. - ``mcpwm_set_signal_high`` and ``mcpwm_set_signal_low`` are replaced by :cpp:func:`mcpwm_generator_set_force_level`. In the new driver, it is implemented by setting force action for the generator, instead of changing the duty cycle to 0% or 100% at the background. - ``mcpwm_start`` and ``mcpwm_stop`` are replaced by :cpp:func:`mcpwm_timer_start_stop`. You have more modes to start and stop the MCPWM timer, see :cpp:type:`mcpwm_timer_start_stop_cmd_t`. - ``mcpwm_carrier_init`` is replaced by :cpp:func:`mcpwm_operator_apply_carrier`. @@ -450,7 +450,7 @@ LCD - ``mcpwm_carrier_output_invert`` is replaced by :cpp:member:`mcpwm_carrier_config_t::invert_before_modulate` and :cpp:member:`mcpwm_carrier_config_t::invert_after_modulate`. - ``mcpwm_deadtime_enable`` and ``mcpwm_deadtime_disable`` are replaced by :cpp:func:`mcpwm_generator_set_dead_time`. - ``mcpwm_fault_init`` is replaced by :cpp:func:`mcpwm_new_gpio_fault`. - - ``mcpwm_fault_set_oneshot_mode``, ``mcpwm_fault_set_cyc_mode`` are replaced by :cpp:func:`mcpwm_operator_set_brake_on_fault` and :cpp:func:`mcpwm_generator_set_actions_on_brake_event`. + - ``mcpwm_fault_set_oneshot_mode``, ``mcpwm_fault_set_cyc_mode`` are replaced by :cpp:func:`mcpwm_operator_set_brake_on_fault` and :cpp:func:`mcpwm_generator_set_action_on_brake_event`. - ``mcpwm_capture_enable`` is removed. It is duplicated to :cpp:func:`mcpwm_capture_enable_channel`. - ``mcpwm_capture_disable`` is removed. It is duplicated to :cpp:func:`mcpwm_capture_capture_disable_channel`. - ``mcpwm_capture_enable_channel`` and ``mcpwm_capture_disable_channel`` are replaced by :cpp:func:`mcpwm_capture_channel_enable` and :cpp:func:`mcpwm_capture_channel_disable`. diff --git a/docs/en/migration-guides/release-6.x/6.0/peripherals.rst b/docs/en/migration-guides/release-6.x/6.0/peripherals.rst index d3bca07ce0d..5270ed6a4f7 100644 --- a/docs/en/migration-guides/release-6.x/6.0/peripherals.rst +++ b/docs/en/migration-guides/release-6.x/6.0/peripherals.rst @@ -85,6 +85,29 @@ The ``io_od_mode`` member in the :cpp:type:`rmt_tx_channel_config_t` configurati The legacy MCPWM driver ``driver/mcpwm.h`` is deprecated since version 5.0 (see :ref:`deprecate_mcpwm_legacy_driver`). Starting from version 6.0, the legacy driver is completely removed. The new driver is placed in the :component:`esp_driver_mcpwm`, and the header file path is ``driver/mcpwm_prelude``. + Variadic Generator APIs are Removed + ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + The legacy variadic ("varg") generator APIs have been removed in this release. Code that used vararg-style calls for generator action setup must be migrated to the explicit, typed APIs. These APIs use configuration structs and clearly-typed setter functions (for example, :cpp:type:`mcpwm_generator_config_t`, :cpp:type:`mcpwm_gen_timer_event_action_t` and :cpp:type:`mcpwm_generator_set_action_on_timer_event`). + + Migration steps (summary): + + - Replace varg-style action configuration with helper structs/macros and dedicated setter functions:: + + .. code-block:: c + + /* Old (varg) */ + mcpwm_generator_set_actions_on_compare_event(my_generator, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, my_comparator, MCPWM_GEN_ACTION_LOW), + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, my_comparator, MCPWM_GEN_ACTION_HIGH), + MCPWM_GEN_COMPARE_EVENT_ACTION_END()); + + /* New */ + mcpwm_generator_set_action_on_compare_event(my_generator, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, my_comparator, MCPWM_GEN_ACTION_LOW)); + mcpwm_generator_set_action_on_compare_event(my_generator, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, my_comparator, MCPWM_GEN_ACTION_HIGH)); + GPIO ---- diff --git a/docs/zh_CN/api-reference/peripherals/mcpwm.rst b/docs/zh_CN/api-reference/peripherals/mcpwm.rst index 3bf8cd5feee..db502aed84f 100644 --- a/docs/zh_CN/api-reference/peripherals/mcpwm.rst +++ b/docs/zh_CN/api-reference/peripherals/mcpwm.rst @@ -318,7 +318,7 @@ MCPWM 比较器可以在定时器计数器等于比较值时发送通知。若 设置生成器对定时器事件执行的操作 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -调用 :cpp:func:`mcpwm_generator_set_actions_on_timer_event` 并辅以若干操作配置，可以针对不同的定时器事件，为生成器设置不同的操作。操作配置定义在 :cpp:type:`mcpwm_gen_timer_event_action_t` 中： +单个生成器可以针对不同的定时器事件配置多种操作。为此，应针对每个事件-操作对分别调用 :cpp:func:`mcpwm_generator_set_action_on_timer_event`。每个操作的详细配置通过结构体 :cpp:type:`mcpwm_gen_timer_event_action_t` 指定。 - :cpp:member:`mcpwm_gen_timer_event_action_t::direction` 指定定时器计数方向，可以调用 :cpp:type:`mcpwm_timer_direction_t` 查看支持的方向。 - :cpp:member:`mcpwm_gen_timer_event_action_t::event` 指定定时器事件，可以调用 :cpp:type:`mcpwm_timer_event_t` 查看支持的定时器事件。 @@ -326,14 +326,10 @@ MCPWM 比较器可以在定时器计数器等于比较值时发送通知。若 可借助辅助宏 :c:macro:`MCPWM_GEN_TIMER_EVENT_ACTION` 构建定时器事件操作条目。 -需注意，:cpp:func:`mcpwm_generator_set_actions_on_timer_event` 的参数列表 **必须** 以 :c:macro:`MCPWM_GEN_TIMER_EVENT_ACTION_END` 结束。 - -也可以调用 :cpp:func:`mcpwm_generator_set_action_on_timer_event` 逐一设置定时器操作，无需涉及变量参数。 - 设置生成器对比较器事件执行的操作 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -调用 :cpp:func:`mcpwm_generator_set_actions_on_compare_event` 并辅以若干操作配置，可以针对不同的比较器事件，为生成器设置不同的操作。操作配置定义在 :cpp:type:`mcpwm_gen_compare_event_action_t` 中： +单个生成器可以针对不同的比较器事件配置多种操作。为此，应针对每个比较事件-操作对分别调用 :cpp:func:`mcpwm_generator_set_action_on_compare_event`。每个操作的详细配置通过结构体 :cpp:type:`mcpwm_gen_compare_event_action_t` 指定。 - :cpp:member:`mcpwm_gen_compare_event_action_t::direction` 指定定时器计数方向，可以调用 :cpp:type:`mcpwm_timer_direction_t` 查看支持的方向。 - :cpp:member:`mcpwm_gen_compare_event_action_t::comparator` 指定比较器句柄。有关分配比较器的方法，请参见 `MCPWM 比较器`_。 @@ -341,14 +337,10 @@ MCPWM 比较器可以在定时器计数器等于比较值时发送通知。若 可借助辅助宏 :c:macro:`MCPWM_GEN_COMPARE_EVENT_ACTION` 构建比较事件操作条目。 -需注意，:cpp:func:`mcpwm_generator_set_actions_on_compare_event` 的参数列表 **必须** 以 :c:macro:`MCPWM_GEN_COMPARE_EVENT_ACTION_END` 结束。 - -也可以调用 :cpp:func:`mcpwm_generator_set_action_on_compare_event` 逐一设置比较器操作，无需涉及变量参数。 - 设置生成器对故障事件执行的操作 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -调用 :cpp:func:`mcpwm_generator_set_action_on_fault_event` 并辅以操作配置，可以针对故障事件，为生成器设置操作。操作配置定义在 :cpp:type:`mcpwm_gen_fault_event_action_t` 中： +单个发生器可以配置为在故障事件发生时执行多个操作。要实现此功能，请针对每个期望的操作调用 :cpp:func:`mcpwm_generator_set_action_on_fault_event`。具体的操作由 :cpp:type:`mcpwm_gen_fault_event_action_t` 结构体描述。 - :cpp:member:`mcpwm_gen_fault_event_action_t::direction` 指定定时器计数方向，可以调用 :cpp:type:`mcpwm_timer_direction_t` 查看支持的方向。 - :cpp:member:`mcpwm_gen_fault_event_action_t::fault` 指定用于触发器的故障。有关分配故障的方法，请参见 `MCPWM 故障`_。 @@ -360,12 +352,10 @@ MCPWM 比较器可以在定时器计数器等于比较值时发送通知。若 可借助辅助宏 :c:macro:`MCPWM_GEN_FAULT_EVENT_ACTION` 构建触发事件操作条目。 -需注意，故障事件没有类似 :cpp:func:`mcpwm_generator_set_actions_on_fault_event` 这样的可变参数函数。 - 设置生成器对同步事件执行的操作 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -调用 :cpp:func:`mcpwm_generator_set_action_on_sync_event` 并辅以操作配置，可以针对同步事件，为生成器设置操作。操作配置定义在 :cpp:type:`mcpwm_gen_sync_event_action_t` 中： +单个生成器可以针对不同的同步事件配置多种操作。为此，应针对每个同步事件-操作对分别调用 :cpp:func:`mcpwm_generator_set_action_on_sync_event`。每个操作的详细配置通过结构体 :cpp:type:`mcpwm_gen_sync_event_action_t` 指定。 - :cpp:member:`mcpwm_gen_sync_event_action_t::direction` 指定定时器计数方向，可以调用 :cpp:type:`mcpwm_timer_direction_t` 查看支持的方向。 - :cpp:member:`mcpwm_gen_sync_event_action_t::sync` 指定用于触发器的同步源。有关分配同步源的方法，请参见 `MCPWM 同步源`_。 @@ -377,8 +367,6 @@ MCPWM 比较器可以在定时器计数器等于比较值时发送通知。若 可借助辅助宏 :c:macro:`MCPWM_GEN_SYNC_EVENT_ACTION` 构建触发事件操作条目。 -需注意，同步事件没有类似 :cpp:func:`mcpwm_generator_set_actions_on_sync_event` 这样的可变参数函数。 - .. _mcpwm-classical-pwm-waveforms-and-generator-configurations: @@ -439,13 +427,12 @@ MCPWM 比较器可以在定时器计数器等于比较值时发送通知。若 static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb) { - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(genb, - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_TOGGLE), - MCPWM_GEN_TIMER_EVENT_ACTION_END())); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_timer_event(genb, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_TOGGLE))); } 双沿不对称波形 - 低电平有效 @@ -457,14 +444,14 @@ MCPWM 比较器可以在定时器计数器等于比较值时发送通知。若 static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb) { - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_timer_event(genb, - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_TIMER_EVENT_ACTION_END())); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_LOW))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_timer_event(genb, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, MCPWM_TIMER_EVENT_EMPTY, MCPWM_GEN_ACTION_LOW))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_timer_event(genb, + MCPWM_GEN_TIMER_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, MCPWM_TIMER_EVENT_FULL, MCPWM_GEN_ACTION_HIGH))); } 双沿对称波形 - 低电平有效 @@ -476,14 +463,14 @@ MCPWM 比较器可以在定时器计数器等于比较值时发送通知。若 static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb) { - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpa, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(genb, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpa, MCPWM_GEN_ACTION_LOW))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(genb, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_HIGH))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(genb, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_LOW))); } 双沿对称波形 - 互补 @@ -495,14 +482,14 @@ MCPWM 比较器可以在定时器计数器等于比较值时发送通知。若 static void gen_action_config(mcpwm_gen_handle_t gena, mcpwm_gen_handle_t genb, mcpwm_cmpr_handle_t cmpa, mcpwm_cmpr_handle_t cmpb) { - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(gena, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpa, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); - ESP_ERROR_CHECK(mcpwm_generator_set_actions_on_compare_event(genb, - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION_END())); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpa, MCPWM_GEN_ACTION_HIGH))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(gena, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpa, MCPWM_GEN_ACTION_LOW))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(genb, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, cmpb, MCPWM_GEN_ACTION_LOW))); + ESP_ERROR_CHECK(mcpwm_generator_set_action_on_compare_event(genb, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, cmpb, MCPWM_GEN_ACTION_HIGH))); } @@ -797,7 +784,7 @@ MCPWM 操作器对故障的响应方式为 **制动**。可以调用 :cpp:func:` 设置发生制动事件时的生成器操作 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -调用 :cpp:func:`mcpwm_generator_set_actions_on_brake_event` 并辅以若干操作配置，可以针对不同的制动事件，为生成器设置不同的对应操作。操作配置定义在 :cpp:type:`mcpwm_gen_brake_event_action_t` 中： +单个生成器可以针对不同的制动事件配置多种操作。为此，应针对每个期望的操作分别调用 :cpp:func:`mcpwm_generator_set_action_on_brake_event`。每个操作的详细配置通过结构体 :cpp:type:`mcpwm_gen_brake_event_action_t` 指定。 - :cpp:member:`mcpwm_gen_brake_event_action_t::direction` 指定定时器的方向，可以调用 :cpp:type:`mcpwm_timer_direction_t` 查看支持的方向。 - :cpp:member:`mcpwm_gen_brake_event_action_t::brake_mode` 指定制动模式，可以调用 :cpp:type:`mcpwm_operator_brake_mode_t` 查看支持的制动模式。 @@ -805,10 +792,6 @@ MCPWM 操作器对故障的响应方式为 **制动**。可以调用 :cpp:func:` 可借助辅助宏 :c:macro:`MCPWM_GEN_BRAKE_EVENT_ACTION` 构建制动事件操作条目。 -需注意， :cpp:func:`mcpwm_generator_set_actions_on_brake_event` 的参数列表 **必须** 以 :c:macro:`MCPWM_GEN_BRAKE_EVENT_ACTION_END` 结束。 - -也可以调用 :cpp:func:`mcpwm_generator_set_action_on_brake_event` 逐一设置制动操作，无需涉及变量参数。 - 注册故障事件回调 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -843,7 +826,7 @@ MCPWM 操作器支持在进行制动操作前发送通知。若有函数需在 生成器强制操作 ^^^^^^^^^^^^^^^^^^^^^^^ -调用 :cpp:func:`mcpwm_generator_set_force_level`，使能软件强制决定运行时的生成器输出电平。相较于通过 :cpp:func:`mcpwm_generator_set_actions_on_timer_event` 配置的其他事件操作，软件强制事件优先级最高。 +调用 :cpp:func:`mcpwm_generator_set_force_level`，使能软件强制决定运行时的生成器输出电平。相较于通过 :cpp:func:`mcpwm_generator_set_action_on_timer_event` 配置的其他事件操作，软件强制事件优先级最高。 - 设置 ``level`` 为 -1，代表禁用强制操作，生成器的输出电平重新交由事件操作控制。 - 设置 ``hold_on`` 为 true，代表强制输出电平将保持不变，直到设置 ``level`` 为 -1 来移除该电平。 diff --git a/docs/zh_CN/migration-guides/release-5.x/5.0/peripherals.rst b/docs/zh_CN/migration-guides/release-5.x/5.0/peripherals.rst index c7161fb0ccc..66bf55c5109 100644 --- a/docs/zh_CN/migration-guides/release-5.x/5.0/peripherals.rst +++ b/docs/zh_CN/migration-guides/release-5.x/5.0/peripherals.rst @@ -433,12 +433,12 @@ LCD ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - ``mcpwm_gpio_init`` 和 ``mcpwm_set_pin``：GPIO 管脚配置在子模块配置中完成，例如在 :cpp:member:`mcpwm_generator_config_t::gen_gpio_num` 中设置 PWM GPIO 管脚。 - - ``mcpwm_init``：为得到预期的 PWM 波形，用户需要至少分配一个 MCPWM 定时器和 MCPWM 运算器，然后通过调用 :cpp:func:`mcpwm_operator_connect_timer` 将二者连接起来。然后，用户需要调用如:cpp:func:`mcpwm_generator_set_actions_on_timer_event`， :cpp:func:`mcpwm_generator_set_actions_on_compare_event` 来设置发生器对不同事件的动作。 + - ``mcpwm_init``：为得到预期的 PWM 波形，用户需要至少分配一个 MCPWM 定时器和 MCPWM 运算器，然后通过调用 :cpp:func:`mcpwm_operator_connect_timer` 将二者连接起来。然后，用户需要调用如:cpp:func:`mcpwm_generator_set_action_on_timer_event`， :cpp:func:`mcpwm_generator_set_action_on_compare_event` 来设置发生器对不同事件的动作。 - ``mcpwm_group_set_resolution``：新驱动中，群组分辨率固定为最大值，通常为 80 MHz。 - ``mcpwm_timer_set_resolution``：MCPWM 定时器的分辨率在 :cpp:member:`mcpwm_timer_config_t::resolution_hz` 中进行设置。 - ``mcpwm_set_frequency``：PWM 频率由 :cpp:member:`mcpwm_timer_config_t::resolution_hz` ，:cpp:member:`mcpwm_timer_config_t::count_mode` 和:cpp:member:`mcpwm_timer_config_t::period_ticks` 决定。 - ``mcpwm_set_duty``：为设置 PWM 占空比，用户应调用 :cpp:func:`mcpwm_comparator_set_compare_value` 来改变比较器的阈值。 - - ``mcpwm_set_duty_type``：新驱动中没有预设的占空比模式，通过设置不同的发生器行为，如 :cpp:func:`mcpwm_generator_set_actions_on_timer_event`，来配置占空比模式。 + - ``mcpwm_set_duty_type``：新驱动中没有预设的占空比模式，通过设置不同的发生器行为，如 :cpp:func:`mcpwm_generator_set_action_on_timer_event`，来配置占空比模式。 - ``mcpwm_set_signal_high`` 和 ``mcpwm_set_signal_low`` 更新为 :cpp:func:`mcpwm_generator_set_force_level`。新驱动中，这是通过为发生器设置力作用来实现的，而不是在后台将占空比改为 0% 或 100%。 - ``mcpwm_start`` 和 ``mcpwm_stop`` 更新为 :cpp:func:`mcpwm_timer_start_stop`。用户可以用更多的模式来启动和停止 MCPWM 定时器，详见 :cpp:type:`mcpwm_timer_start_stop_cmd_t`。 - ``mcpwm_carrier_init`` 更新为 :cpp:func:`mcpwm_operator_apply_carrier`。 @@ -450,7 +450,7 @@ LCD - ``mcpwm_carrier_output_invert`` 更新为 :cpp:member:`mcpwm_carrier_config_t::invert_before_modulate` 和 :cpp:member:`mcpwm_carrier_config_t::invert_after_modulate`。 - ``mcpwm_deadtime_enable`` 与 ``mcpwm_deadtime_disable`` 更新为 :cpp:func:`mcpwm_generator_set_dead_time`。 - ``mcpwm_fault_init`` 更新为 :cpp:func:`mcpwm_new_gpio_fault`。 - - ``mcpwm_fault_set_oneshot_mode`` 与 ``mcpwm_fault_set_cyc_mode`` 更新为 :cpp:func:`mcpwm_operator_set_brake_on_fault` 与 :cpp:func:`mcpwm_generator_set_actions_on_brake_event`。 + - ``mcpwm_fault_set_oneshot_mode`` 与 ``mcpwm_fault_set_cyc_mode`` 更新为 :cpp:func:`mcpwm_operator_set_brake_on_fault` 与 :cpp:func:`mcpwm_generator_set_action_on_brake_event`。 - 由于 ``mcpwm_capture_enable`` 与 :cpp:func:`mcpwm_capture_enable_channel` 重复，因此在更新后被删除。 - 由于 ``mcpwm_capture_disable`` 与 :cpp:func:`mcpwm_capture_capture_disable_channel` 重复，因此在更新后被删除。 - ``mcpwm_capture_enable_channel`` 与 ``mcpwm_capture_disable_channel`` 更新为 :cpp:func:`mcpwm_capture_channel_enable` 与 :cpp:func:`mcpwm_capture_channel_disable`。 diff --git a/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst b/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst index 8c264b19afc..cc5bc305772 100644 --- a/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst +++ b/docs/zh_CN/migration-guides/release-6.x/6.0/peripherals.rst @@ -85,6 +85,29 @@ RMT 旧版的 MCPWM 驱动 ``driver/mcpwm.h`` 在 5.0 的版本中就已经被弃用（请参考 :ref:`deprecate_mcpwm_legacy_driver`）。从 6.0 版本开始，旧版驱动被完全移除。新驱动位于 :component:`esp_driver_mcpwm` 组件中，头文件引用路径为 ``driver/mcpwm_prelude``。 + 可变参数生成器 API 已被移除 + ~~~~~~~~~~~~~~~~~~~~~~~~~~~ + + 本版本中已移除旧版的可变参数（"varg"）生成器 API。原先使用可变参数方式配置生成器动作的代码，需迁移到显式、类型化的 API。这些新 API 使用配置结构体和类型明确的设置函数（例如 :cpp:type:`mcpwm_generator_config_t`、:cpp:type:`mcpwm_gen_timer_event_action_t` 和 :cpp:type:`mcpwm_generator_set_action_on_timer_event`）。 + + 迁移步骤（摘要）： + + - 用辅助结构体/宏和专用设置函数替换 varg 风格的动作配置:: + + .. code-block:: c + + /* 旧版（varg）*/ + mcpwm_generator_set_actions_on_compare_event(my_generator, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, my_comparator, MCPWM_GEN_ACTION_LOW), + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, my_comparator, MCPWM_GEN_ACTION_HIGH), + MCPWM_GEN_COMPARE_EVENT_ACTION_END()); + + /* 新版 */ + mcpwm_generator_set_action_on_compare_event(my_generator, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, my_comparator, MCPWM_GEN_ACTION_LOW)); + mcpwm_generator_set_action_on_compare_event(my_generator, + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, my_comparator, MCPWM_GEN_ACTION_HIGH)); + GPIO ---- diff --git a/examples/peripherals/mcpwm/mcpwm_foc_svpwm_open_loop/main/svpwm/esp_svpwm.c b/examples/peripherals/mcpwm/mcpwm_foc_svpwm_open_loop/main/svpwm/esp_svpwm.c index ee0887bc5f3..630483aeeb7 100644 --- a/examples/peripherals/mcpwm/mcpwm_foc_svpwm_open_loop/main/svpwm/esp_svpwm.c +++ b/examples/peripherals/mcpwm/mcpwm_foc_svpwm_open_loop/main/svpwm/esp_svpwm.c @@ -49,10 +49,12 @@ esp_err_t svpwm_new_inverter(const inverter_config_t *config, inverter_handle_t } for (int i = 0; i < 3; i++) { - ESP_GOTO_ON_ERROR(mcpwm_generator_set_actions_on_compare_event(svpwm_dev->generators[i][0], - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, svpwm_dev->comparators[i], MCPWM_GEN_ACTION_LOW), - MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, svpwm_dev->comparators[i], MCPWM_GEN_ACTION_HIGH), - MCPWM_GEN_COMPARE_EVENT_ACTION_END()), err, TAG, "Set generator actions failed"); + ESP_GOTO_ON_ERROR(mcpwm_generator_set_action_on_compare_event(svpwm_dev->generators[i][0], + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_UP, svpwm_dev->comparators[i], MCPWM_GEN_ACTION_LOW)), + err, TAG, "Set generator UP action failed"); + ESP_GOTO_ON_ERROR(mcpwm_generator_set_action_on_compare_event(svpwm_dev->generators[i][0], + MCPWM_GEN_COMPARE_EVENT_ACTION(MCPWM_TIMER_DIRECTION_DOWN, svpwm_dev->comparators[i], MCPWM_GEN_ACTION_HIGH)), + err, TAG, "Set generator DOWN action failed"); } for (int i = 0; i < 3; i++) { diff --git a/tools/idf_py_actions/hints.yml b/tools/idf_py_actions/hints.yml index 9ab90e82b6c..ce4385d3666 100644 --- a/tools/idf_py_actions/hints.yml +++ b/tools/idf_py_actions/hints.yml @@ -54,6 +54,11 @@ re_variables: ['(esp_spiram_get_chip_size|esp_spiram_get_size)'] hint_variables: ['esp_spiram_get_chip_size and esp_spiram_get_size', 'esp_psram_get_size()'] +- + re: "error: implicit declaration of function '(MCPWM_GEN_TIMER_EVENT_ACTION_END|MCPWM_GEN_COMPARE_EVENT_ACTION_END|MCPWM_GEN_BRAKE_EVENT_ACTION_END)'" + hint: "Macro function '{}()' has been removed. Please don't use variadic APIs when setting MCPWM generator actions." + match_to_output: True + - re: "error: implicit declaration of function 'esp_secure_boot_verify_rsa_signature_block'" hint: "'esp_secure_boot_verify_rsa_signature_block()' has been made private and is no longer available."