eaw/esp-idf
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

i2s: deprecate confusing names

Browse Source
This commit is contained in:
laokaiyao
2021-11-24 13:21:13 +08:00
parent 9044374032
commit fa4e77eb44
44 changed files with 410 additions and 452 deletions
Download Patch File Download Diff File Expand all files Collapse all files

114
components/esp_event/include/esp_event.h
View File

@@ -1,16 +1,8 @@
// Copyright 2018 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
/*
* SPDX-FileCopyrightText: 2018-2021 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#ifndef ESP_EVENT_H_
#define ESP_EVENT_H_
@@ -92,16 +84,16 @@ esp_err_t esp_event_loop_delete_default(void);
/**
* @brief Dispatch events posted to an event loop.
*
* This function is used to dispatch events posted to a loop with no dedicated task, i.e task name was set to NULL
* This function is used to dispatch events posted to a loop with no dedicated task, i.e. task name was set to NULL
* in event_loop_args argument during loop creation. This function includes an argument to limit the amount of time
* it runs, returning control to the caller when that time expires (or some time afterwards). There is no guarantee
* that a call to this function will exit at exactly the time of expiry. There is also no guarantee that events have
* been dispatched during the call, as the function might have spent all of the alloted time waiting on the event queue.
* Once an event has been unqueued, however, it is guaranteed to be dispatched. This guarantee contributes to not being
* able to exit exactly at time of expiry as (1) blocking on internal mutexes is necessary for dispatching the unqueued
* event, and (2) during dispatch of the unqueued event there is no way to control the time occupied by handler code
* execution. The guaranteed time of exit is therefore the alloted time + amount of time required to dispatch
* the last unqueued event.
* been dispatched during the call, as the function might have spent all the allotted time waiting on the event queue.
* Once an event has been dequeued, however, it is guaranteed to be dispatched. This guarantee contributes to not being
* able to exit exactly at time of expiry as (1) blocking on internal mutexes is necessary for dispatching the dequeued
* event, and (2) during dispatch of the dequeued event there is no way to control the time occupied by handler code
* execution. The guaranteed time of exit is therefore the allotted time + amount of time required to dispatch
* the last dequeued event.
*
* In cases where waiting on the queue times out, ESP_OK is returned and not ESP_ERR_TIMEOUT, since it is
* normal behavior.
@@ -134,8 +126,8 @@ esp_err_t esp_event_loop_run(esp_event_loop_handle_t event_loop, TickType_t tick
* also possible. However, registering the same handler to the same event multiple times would cause the
* previous registrations to be overwritten.
*
* @param[in] event_base the base id of the event to register the handler for
* @param[in] event_id the id of the event to register the handler for
* @param[in] event_base the base ID of the event to register the handler for
* @param[in] event_id the ID of the event to register the handler for
* @param[in] event_handler the handler function which gets called when the event is dispatched
* @param[in] event_handler_arg data, aside from event data, that is passed to the handler when it is called
*
@@ -145,7 +137,7 @@ esp_err_t esp_event_loop_run(esp_event_loop_handle_t event_loop, TickType_t tick
* @return
* - ESP_OK: Success
* - ESP_ERR_NO_MEM: Cannot allocate memory for the handler
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event id
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID
* - Others: Fail
*/
esp_err_t esp_event_handler_register(esp_event_base_t event_base,
@@ -163,8 +155,8 @@ esp_err_t esp_event_handler_register(esp_event_base_t event_base,
* specification of the event loop to register the handler to.
*
* @param[in] event_loop the event loop to register this handler function to, must not be NULL
* @param[in] event_base the base id of the event to register the handler for
* @param[in] event_id the id of the event to register the handler for
* @param[in] event_base the base ID of the event to register the handler for
* @param[in] event_id the ID of the event to register the handler for
* @param[in] event_handler the handler function which gets called when the event is dispatched
* @param[in] event_handler_arg data, aside from event data, that is passed to the handler when it is called
*
@@ -174,7 +166,7 @@ esp_err_t esp_event_handler_register(esp_event_base_t event_base,
* @return
* - ESP_OK: Success
* - ESP_ERR_NO_MEM: Cannot allocate memory for the handler
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event id
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID
* - Others: Fail
*/
esp_err_t esp_event_handler_register_with(esp_event_loop_handle_t event_loop,
@@ -202,15 +194,15 @@ esp_err_t esp_event_handler_register_with(esp_event_loop_handle_t event_loop,
* lifetime.
*
* @param[in] event_loop the event loop to register this handler function to, must not be NULL
* @param[in] event_base the base id of the event to register the handler for
* @param[in] event_id the id of the event to register the handler for
* @param[in] event_base the base ID of the event to register the handler for
* @param[in] event_id the ID of the event to register the handler for
* @param[in] event_handler the handler function which gets called when the event is dispatched
* @param[in] event_handler_arg data, aside from event data, that is passed to the handler when it is called
* @param[out] instance An event handler instance object related to the registered event handler and data, can be NULL.
* This needs to be kept if the specific callback instance should be unregistered before deleting the whole
* event loop. Registering the same event handler multiple times is possible and yields distinct instance
* objects. The data can be the same for all registrations.
* If no unregistration is needed but the handler should be deleted when the event loop is deleted,
* If no unregistration is needed, but the handler should be deleted when the event loop is deleted,
* instance can be NULL.
*
* @note the event loop library does not maintain a copy of event_handler_arg, therefore the user should
@@ -219,7 +211,7 @@ esp_err_t esp_event_handler_register_with(esp_event_loop_handle_t event_loop,
* @return
* - ESP_OK: Success
* - ESP_ERR_NO_MEM: Cannot allocate memory for the handler
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event id or instance is NULL
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID or instance is NULL
* - Others: Fail
*/
esp_err_t esp_event_handler_instance_register_with(esp_event_loop_handle_t event_loop,
@@ -235,15 +227,15 @@ esp_err_t esp_event_handler_instance_register_with(esp_event_loop_handle_t event
* This function does the same as esp_event_handler_instance_register_with, except that it registers the
* handler to the default event loop.
*
* @param[in] event_base the base id of the event to register the handler for
* @param[in] event_id the id of the event to register the handler for
* @param[in] event_base the base ID of the event to register the handler for
* @param[in] event_id the ID of the event to register the handler for
* @param[in] event_handler the handler function which gets called when the event is dispatched
* @param[in] event_handler_arg data, aside from event data, that is passed to the handler when it is called
* @param[out] instance An event handler instance object related to the registered event handler and data, can be NULL.
* This needs to be kept if the specific callback instance should be unregistered before deleting the whole
* event loop. Registering the same event handler multiple times is possible and yields distinct instance
* objects. The data can be the same for all registrations.
* If no unregistration is needed but the handler should be deleted when the event loop is deleted,
* If no unregistration is needed, but the handler should be deleted when the event loop is deleted,
* instance can be NULL.
*
* @note the event loop library does not maintain a copy of event_handler_arg, therefore the user should
@@ -252,7 +244,7 @@ esp_err_t esp_event_handler_instance_register_with(esp_event_loop_handle_t event
* @return
* - ESP_OK: Success
* - ESP_ERR_NO_MEM: Cannot allocate memory for the handler
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event id or instance is NULL
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID or instance is NULL
* - Others: Fail
*/
esp_err_t esp_event_handler_instance_register(esp_event_base_t event_base,
@@ -267,7 +259,7 @@ esp_err_t esp_event_handler_instance_register(esp_event_base_t event_base,
* @note This function is obsolete and will be deprecated soon, please use esp_event_handler_instance_unregister()
* instead.
*
* Unregisters a handler so it will no longer be called during dispatch.
* Unregisters a handler, so it will no longer be called during dispatch.
* Handlers can be unregistered for any combination of event_base and event_id which were previously registered.
* To unregister a handler, the event_base and event_id arguments must match exactly the arguments passed to
* esp_event_handler_register() when that handler was registered. Passing ESP_EVENT_ANY_BASE and/or ESP_EVENT_ANY_ID
@@ -278,11 +270,11 @@ esp_err_t esp_event_handler_instance_register(esp_event_base_t event_base,
* unregistered. This avoids accidental unregistration of handlers registered by other users or components.
*
* @param[in] event_base the base of the event with which to unregister the handler
* @param[in] event_id the id of the event with which to unregister the handler
* @param[in] event_id the ID of the event with which to unregister the handler
* @param[in] event_handler the handler to unregister
*
* @return ESP_OK success
* @return ESP_ERR_INVALID_ARG invalid combination of event base and event id
* @return ESP_ERR_INVALID_ARG invalid combination of event base and event ID
* @return others fail
*/
esp_err_t esp_event_handler_unregister(esp_event_base_t event_base,
@@ -300,12 +292,12 @@ esp_err_t esp_event_handler_unregister(esp_event_base_t event_base,
*
* @param[in] event_loop the event loop with which to unregister this handler function, must not be NULL
* @param[in] event_base the base of the event with which to unregister the handler
* @param[in] event_id the id of the event with which to unregister the handler
* @param[in] event_id the ID of the event with which to unregister the handler
* @param[in] event_handler the handler to unregister
*
* @return
* - ESP_OK: Success
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event id
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID
* - Others: Fail
*/
esp_err_t esp_event_handler_unregister_with(esp_event_loop_handle_t event_loop,
@@ -316,7 +308,7 @@ esp_err_t esp_event_handler_unregister_with(esp_event_loop_handle_t event_loop,
/**
* @brief Unregister a handler instance from a specific event loop.
*
* Unregisters a handler instance so it will no longer be called during dispatch.
* Unregisters a handler instance, so it will no longer be called during dispatch.
* Handler instances can be unregistered for any combination of event_base and event_id which were previously
* registered. To unregister a handler instance, the event_base and event_id arguments must match exactly the
* arguments passed to esp_event_handler_instance_register() when that handler instance was registered.
@@ -329,12 +321,12 @@ esp_err_t esp_event_handler_unregister_with(esp_event_loop_handle_t event_loop,
*
* @param[in] event_loop the event loop with which to unregister this handler function, must not be NULL
* @param[in] event_base the base of the event with which to unregister the handler
* @param[in] event_id the id of the event with which to unregister the handler
* @param[in] event_id the ID of the event with which to unregister the handler
* @param[in] instance the instance object of the registration to be unregistered
*
* @return
* - ESP_OK: Success
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event id
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID
* - Others: Fail
*/
esp_err_t esp_event_handler_instance_unregister_with(esp_event_loop_handle_t event_loop,
@@ -349,12 +341,12 @@ esp_err_t esp_event_handler_instance_unregister_with(esp_event_loop_handle_t eve
* handler instance from the default event loop.
*
* @param[in] event_base the base of the event with which to unregister the handler
* @param[in] event_id the id of the event with which to unregister the handler
* @param[in] event_id the ID of the event with which to unregister the handler
* @param[in] instance the instance object of the registration to be unregistered
*
* @return
* - ESP_OK: Success
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event id
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID
* - Others: Fail
*/
esp_err_t esp_event_handler_instance_unregister(esp_event_base_t event_base,
@@ -364,11 +356,11 @@ esp_err_t esp_event_handler_instance_unregister(esp_event_base_t event_base,
/**
* @brief Posts an event to the system default event loop. The event loop library keeps a copy of event_data and manages
* the copy's lifetime automatically (allocation + deletion); this ensures that the data the
* handler recieves is always valid.
* handler receives is always valid.
*
* @param[in] event_base the event base that identifies the event
* @param[in] event_id the event id that identifies the event
* @param[in] event_data the data, specific to the event occurence, that gets passed to the handler
* @param[in] event_id the event ID that identifies the event
* @param[in] event_data the data, specific to the event occurrence, that gets passed to the handler
* @param[in] event_data_size the size of the event data
* @param[in] ticks_to_wait number of ticks to block on a full event queue
*
@@ -376,7 +368,7 @@ esp_err_t esp_event_handler_instance_unregister(esp_event_base_t event_base,
* - ESP_OK: Success
* - ESP_ERR_TIMEOUT: Time to wait for event queue to unblock expired,
* queue full when posting from ISR
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event id
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID
* - Others: Fail
*/
esp_err_t esp_event_post(esp_event_base_t event_base,
@@ -388,15 +380,15 @@ esp_err_t esp_event_post(esp_event_base_t event_base,
/**
* @brief Posts an event to the specified event loop. The event loop library keeps a copy of event_data and manages
* the copy's lifetime automatically (allocation + deletion); this ensures that the data the
* handler recieves is always valid.
* handler receives is always valid.
*
* This function behaves in the same manner as esp_event_post_to, except the additional specification of the event loop
* to post the event to.
*
* @param[in] event_loop the event loop to post to, must not be NULL
* @param[in] event_base the event base that identifies the event
* @param[in] event_id the event id that identifies the event
* @param[in] event_data the data, specific to the event occurence, that gets passed to the handler
* @param[in] event_id the event ID that identifies the event
* @param[in] event_data the data, specific to the event occurrence, that gets passed to the handler
* @param[in] event_data_size the size of the event data
* @param[in] ticks_to_wait number of ticks to block on a full event queue
*
@@ -404,7 +396,7 @@ esp_err_t esp_event_post(esp_event_base_t event_base,
* - ESP_OK: Success
* - ESP_ERR_TIMEOUT: Time to wait for event queue to unblock expired,
* queue full when posting from ISR
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event id
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID
* - Others: Fail
*/
esp_err_t esp_event_post_to(esp_event_loop_handle_t event_loop,
@@ -419,8 +411,8 @@ esp_err_t esp_event_post_to(esp_event_loop_handle_t event_loop,
* @brief Special variant of esp_event_post for posting events from interrupt handlers.
*
* @param[in] event_base the event base that identifies the event
* @param[in] event_id the event id that identifies the event
* @param[in] event_data the data, specific to the event occurence, that gets passed to the handler
* @param[in] event_id the event ID that identifies the event
* @param[in] event_data the data, specific to the event occurrence, that gets passed to the handler
* @param[in] event_data_size the size of the event data; max is 4 bytes
* @param[out] task_unblocked an optional parameter (can be NULL) which indicates that an event task with
* higher priority than currently running task has been unblocked by the posted event;
@@ -433,7 +425,7 @@ esp_err_t esp_event_post_to(esp_event_loop_handle_t event_loop,
* @return
* - ESP_OK: Success
* - ESP_FAIL: Event queue for the default event loop full
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event id,
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID,
* data size of more than 4 bytes
* - Others: Fail
*/
@@ -448,8 +440,8 @@ esp_err_t esp_event_isr_post(esp_event_base_t event_base,
*
* @param[in] event_loop the event loop to post to, must not be NULL
* @param[in] event_base the event base that identifies the event
* @param[in] event_id the event id that identifies the event
* @param[in] event_data the data, specific to the event occurence, that gets passed to the handler
* @param[in] event_id the event ID that identifies the event
* @param[in] event_data the data, specific to the event occurrence, that gets passed to the handler
* @param[in] event_data_size the size of the event data
* @param[out] task_unblocked an optional parameter (can be NULL) which indicates that an event task with
* higher priority than currently running task has been unblocked by the posted event;
@@ -462,7 +454,7 @@ esp_err_t esp_event_isr_post(esp_event_base_t event_base,
* @return
* - ESP_OK: Success
* - ESP_FAIL: Event queue for the loop full
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event id,
* - ESP_ERR_INVALID_ARG: Invalid combination of event base and event ID,
* data size of more than 4 bytes
* - Others: Fail
*/
@@ -492,18 +484,18 @@ esp_err_t esp_event_isr_post_to(esp_event_loop_handle_t event_loop,
where:
event loop
format: address,name rx:total_recieved dr:total_dropped
format: address,name rx:total_received dr:total_dropped
where:
address - memory address of the event loop
name - name of the event loop, 'none' if no dedicated task
total_recieved - number of successfully posted events
total_received - number of successfully posted events
total_dropped - number of events unsuccessfully posted due to queue being full
handler
format: address ev:base,id inv:total_invoked run:total_runtime
where:
address - address of the handler function
base,id - the event specified by event base and id this handler executes
base,id - the event specified by event base and ID this handler executes
total_invoked - number of times this handler has been invoked
total_runtime - total amount of time used for invoking this handler

30
components/esp_event/include/esp_event_legacy.h
View File

@@ -1,16 +1,8 @@
// Copyright 2015-2018 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
/*
* SPDX-FileCopyrightText: 2015-2021 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#pragma once
@@ -27,7 +19,7 @@ extern "C" {
/** System event types enumeration */
typedef enum {
SYSTEM_EVENT_WIFI_READY = 0, /*!< ESP32 WiFi ready */
SYSTEM_EVENT_WIFI_READY = 0, /*!< ESP32 Wi-Fi ready */
SYSTEM_EVENT_SCAN_DONE, /*!< ESP32 finish scanning AP */
SYSTEM_EVENT_STA_START, /*!< ESP32 station start */
SYSTEM_EVENT_STA_STOP, /*!< ESP32 station stop */
@@ -142,7 +134,7 @@ typedef esp_err_t (*system_event_handler_t)(esp_event_base_t event_base,
TickType_t ticks_to_wait);
/**
* @brief Send a event to event task
* @brief Send an event to event task
*
* @note This API is part of the legacy event system. New code should use event library API in esp_event.h
*
@@ -156,15 +148,15 @@ typedef esp_err_t (*system_event_handler_t)(esp_event_base_t event_base,
esp_err_t esp_event_send(system_event_t *event) __attribute__ ((deprecated));
/**
* @brief Send a event to event task
* @brief Send an event to event task
*
* @note This API is used by WiFi Driver only.
* @note This API is used by Wi-Fi Driver only.
*
* Other task/modules, such as the tcpip_adapter, can call this API to send an event to event task
*
* @param[in] event_base the event base that identifies the event
* @param[in] event_id the event id that identifies the event
* @param[in] event_data the data, specific to the event occurence, that gets passed to the handler
* @param[in] event_id the event ID that identifies the event
* @param[in] event_data the data, specific to the event occurrence, that gets passed to the handler
* @param[in] event_data_size the size of the event data
* @param[in] ticks_to_wait number of ticks to block on a full event queue
*