pioduino/esp-idf
1
0
Fork 0
Code Issues Pull Requests Actions 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
components/app_trace/include/esp_app_trace.h
+10 -10
View File
@@ -46,7 +46,7 @@ void esp_apptrace_down_buffer_config(uint8_t *buf, uint32_t size);
/**
* @brief Allocates buffer for trace data.
* After data in buffer are ready to be sent off esp_apptrace_buffer_put must be called to indicate it.
* Once the data in the buffer is ready to be sent, esp_apptrace_buffer_put must be called to indicate it.
*
* @param dest Indicates HW interface to send data.
* @param size Size of data to write to trace buffer.
@@ -57,8 +57,8 @@ void esp_apptrace_down_buffer_config(uint8_t *buf, uint32_t size);
uint8_t *esp_apptrace_buffer_get(esp_apptrace_dest_t dest, uint32_t size, uint32_t tmo);
/**
* @brief Indicates that the data in buffer are ready to be sent off.
* This function is a counterpart of and must be preceeded by esp_apptrace_buffer_get.
* @brief Indicates that the data in the buffer is ready to be sent.
* This function is a counterpart of and must be preceded by esp_apptrace_buffer_get.
*
* @param dest Indicates HW interface to send data. Should be identical to the same parameter in call to esp_apptrace_buffer_get.
* @param ptr Address of trace buffer to release. Should be the value returned by call to esp_apptrace_buffer_get.
@@ -81,7 +81,7 @@ esp_err_t esp_apptrace_buffer_put(esp_apptrace_dest_t dest, uint8_t *ptr, uint32
esp_err_t esp_apptrace_write(esp_apptrace_dest_t dest, const void *data, uint32_t size, uint32_t tmo);
/**
* @brief vprintf-like function to sent log messages to host via specified HW interface.
* @brief vprintf-like function to send log messages to host via specified HW interface.
*
* @param dest Indicates HW interface to send data.
* @param tmo Timeout for operation (in us). Use ESP_APPTRACE_TMO_INFINITE to wait indefinitely.
@@ -93,7 +93,7 @@ esp_err_t esp_apptrace_write(esp_apptrace_dest_t dest, const void *data, uint32_
int esp_apptrace_vprintf_to(esp_apptrace_dest_t dest, uint32_t tmo, const char *fmt, va_list ap);
/**
* @brief vprintf-like function to sent log messages to host.
* @brief vprintf-like function to send log messages to host.
*
* @param fmt Address of format string.
* @param ap List of arguments.
@@ -114,7 +114,7 @@ esp_err_t esp_apptrace_flush(esp_apptrace_dest_t dest, uint32_t tmo);
/**
* @brief Flushes remaining data in trace buffer to host without locking internal data.
* This is special version of esp_apptrace_flush which should be called from panic handler.
* This is a special version of esp_apptrace_flush which should be called from panic handler.
*
* @param dest Indicates HW interface to flush data on.
* @param min_sz Threshold for flushing data. If current filling level is above this value, data will be flushed. TRAX destinations only.
@@ -138,7 +138,7 @@ esp_err_t esp_apptrace_read(esp_apptrace_dest_t dest, void *data, uint32_t *size
/**
* @brief Retrieves incoming data buffer if any.
* After data in buffer are processed esp_apptrace_down_buffer_put must be called to indicate it.
* Once data in the buffer is processed, esp_apptrace_down_buffer_put must be called to indicate it.
*
* @param dest Indicates HW interface to receive data.
* @param size Address to store size of available data in down buffer. Must be initialized with requested value.
@@ -149,8 +149,8 @@ esp_err_t esp_apptrace_read(esp_apptrace_dest_t dest, void *data, uint32_t *size
uint8_t *esp_apptrace_down_buffer_get(esp_apptrace_dest_t dest, uint32_t *size, uint32_t tmo);
/**
* @brief Indicates that the data in down buffer are processed.
* This function is a counterpart of and must be preceeded by esp_apptrace_down_buffer_get.
* @brief Indicates that the data in the down buffer is processed.
* This function is a counterpart of and must be preceded by esp_apptrace_down_buffer_get.
*
* @param dest Indicates HW interface to receive data. Should be identical to the same parameter in call to esp_apptrace_down_buffer_get.
* @param ptr Address of trace buffer to release. Should be the value returned by call to esp_apptrace_down_buffer_get.
@@ -245,7 +245,7 @@ int esp_apptrace_fseek(esp_apptrace_dest_t dest, void *stream, long offset, int
int esp_apptrace_ftell(esp_apptrace_dest_t dest, void *stream);
/**
* @brief Indicates to the host that all file operations are completed.
* @brief Indicates to the host that all file operations are complete.
* This function should be called after all file operations are finished and
* indicate to the host that it can perform cleanup operations (close open files etc.).
*
components/app_update/include/esp_ota_ops.h
+5 -5
View File
@@ -112,17 +112,17 @@ esp_err_t esp_ota_begin(const esp_partition_t* partition, size_t image_size, esp
esp_err_t esp_ota_write(esp_ota_handle_t handle, const void* data, size_t size);
/**
* @brief Write OTA update data to partition
* @brief Write OTA update data to partition at an offset
*
* This function can write data in non contiguous manner.
* If flash encryption is enabled, data should be 16 byte aligned.
* This function can write data in non-contiguous manner.
* If flash encryption is enabled, data should be 16 bytes aligned.
*
* @param handle Handle obtained from esp_ota_begin
* @param data Data buffer to write
* @param size Size of data buffer in bytes
* @param offset Offset in flash partition
*
* @note While performing OTA, if the packets arrive out of order, esp_ota_write_with_offset() can be used to write data in non contiguous manner.
* @note While performing OTA, if the packets arrive out of order, esp_ota_write_with_offset() can be used to write data in non-contiguous manner.
* Use of esp_ota_write_with_offset() in combination with esp_ota_write() is not recommended.
*
* @return
@@ -327,7 +327,7 @@ typedef enum {
/**
* @brief Revokes the old signature digest. To be called in the application after the rollback logic.
*
* Relevant for Secure boot v2 on ESP32-S2 where upto 3 key digests can be stored (Key #N-1, Key #N, Key #N+1).
* Relevant for Secure boot v2 on ESP32-S2, ESP32-S3, ESP32-C3, ESP32-H2 where upto 3 key digests can be stored (Key #N-1, Key #N, Key #N+1).
* When key #N-1 used to sign an app is invalidated, an OTA update is to be sent with an app signed with key #N-1 & Key #N.
* After successfully booting the OTA app should call this function to revoke Key #N-1.
*
components/console/esp_console.h
+3 -3
View File
@@ -311,7 +311,7 @@ struct esp_console_repl_s {
* @param[in] repl_config REPL configuration
* @param[out] ret_repl return REPL handle after initialization succeed, return NULL otherwise
*
* @note This is a all-in-one function to establish the environment needed for REPL, includes:
* @note This is an all-in-one function to establish the environment needed for REPL, includes:
* - Install the UART driver on the console UART (8n1, 115200, REF_TICK clock source)
* - Configures the stdin/stdout to go through the UART driver
* - Initializes linenoise
@@ -356,7 +356,7 @@ esp_err_t esp_console_new_repl_usb_cdc(const esp_console_dev_usb_cdc_config_t *d
* @param[in] repl_config REPL configuration
* @param[out] ret_repl return REPL handle after initialization succeed, return NULL otherwise
*
* @note This is a all-in-one function to establish the environment needed for REPL, includes:
* @note This is an all-in-one function to establish the environment needed for REPL, includes:
* - Initializes linenoise
* - Spawn new thread to run REPL in the background
*
@@ -374,7 +374,7 @@ esp_err_t esp_console_new_repl_usb_serial_jtag(const esp_console_dev_usb_serial_
/**
* @brief Start REPL environment
* @param[in] repl REPL handle returned from esp_console_new_repl_xxx
* @note Once the REPL got started, it won't be stopped until user call repl->del(repl) to destory the REPL environment.
* @note Once the REPL gets started, it won't be stopped until the user calls repl->del(repl) to destroy the REPL environment.
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_STATE, if repl has started already
components/driver/i2s.c
+15 -15
View File
@@ -84,8 +84,8 @@ typedef struct {
i2s_port_t i2s_num; /*!< I2S port number*/
int queue_size; /*!< I2S event queue size*/
QueueHandle_t i2s_queue; /*!< I2S queue handler*/
int dma_buf_count; /*!< DMA buffer count, number of buffer*/
int dma_buf_len; /*!< DMA buffer length, length of each buffer*/
int dma_desc_num; /*!< DMA buffer count, number of buffer*/
int dma_frame_num; /*!< DMA buffer length, length of each buffer*/
uint32_t last_buf_size; /*!< DMA last buffer size */
i2s_dma_t *tx; /*!< DMA Tx buffer*/
i2s_dma_t *rx; /*!< DMA Rx buffer*/
@@ -662,9 +662,9 @@ static inline uint32_t i2s_get_buf_size(i2s_port_t i2s_num)
uint32_t bytes_per_sample = ((p_i2s[i2s_num]->hal_cfg.sample_bits + 15) / 16) * 2;
/* The DMA buffer limitation is 4092 bytes */
uint32_t bytes_per_frame = bytes_per_sample * p_i2s[i2s_num]->hal_cfg.active_chan;
p_i2s[i2s_num]->dma_buf_len = (p_i2s[i2s_num]->dma_buf_len * bytes_per_frame > I2S_DMA_BUFFER_MAX_SIZE) ?
I2S_DMA_BUFFER_MAX_SIZE / bytes_per_frame : p_i2s[i2s_num]->dma_buf_len;
return p_i2s[i2s_num]->dma_buf_len * bytes_per_frame;
p_i2s[i2s_num]->dma_frame_num = (p_i2s[i2s_num]->dma_frame_num * bytes_per_frame > I2S_DMA_BUFFER_MAX_SIZE) ?
I2S_DMA_BUFFER_MAX_SIZE / bytes_per_frame : p_i2s[i2s_num]->dma_frame_num;
return p_i2s[i2s_num]->dma_frame_num * bytes_per_frame;
}
/**
@@ -680,7 +680,7 @@ static esp_err_t i2s_delete_dma_buffer(i2s_port_t i2s_num, i2s_dma_t *dma_obj)
{
ESP_RETURN_ON_FALSE(dma_obj, ESP_ERR_INVALID_ARG, TAG, "I2S DMA object can't be NULL");
/* Loop to destroy every descriptor and buffer */
for (int cnt = 0; cnt < p_i2s[i2s_num]->dma_buf_count; cnt++) {
for (int cnt = 0; cnt < p_i2s[i2s_num]->dma_desc_num; cnt++) {
if (dma_obj->desc && dma_obj->desc[cnt]) {
free(dma_obj->desc[cnt]);
dma_obj->desc[cnt] = NULL;
@@ -707,7 +707,7 @@ static esp_err_t i2s_alloc_dma_buffer(i2s_port_t i2s_num, i2s_dma_t *dma_obj)
esp_err_t ret = ESP_OK;
ESP_GOTO_ON_FALSE(dma_obj, ESP_ERR_INVALID_ARG, err, TAG, "I2S DMA object can't be NULL");
uint32_t buf_cnt = p_i2s[i2s_num]->dma_buf_count;
uint32_t buf_cnt = p_i2s[i2s_num]->dma_desc_num;
for (int cnt = 0; cnt < buf_cnt; cnt++) {
/* Allocate DMA buffer */
dma_obj->buf[cnt] = (char *) heap_caps_calloc(dma_obj->buf_size, sizeof(char), MALLOC_CAP_DMA);
@@ -733,7 +733,7 @@ static esp_err_t i2s_alloc_dma_buffer(i2s_port_t i2s_num, i2s_dma_t *dma_obj)
/* Link to the next descriptor */
dma_obj->desc[cnt]->empty = (uint32_t)((cnt < (buf_cnt - 1)) ? (dma_obj->desc[cnt + 1]) : dma_obj->desc[0]);
}
ESP_LOGI(TAG, "DMA Malloc info, datalen=blocksize=%d, dma_buf_count=%d", dma_obj->buf_size, buf_cnt);
ESP_LOGI(TAG, "DMA Malloc info, datalen=blocksize=%d, dma_desc_num=%d", dma_obj->buf_size, buf_cnt);
return ESP_OK;
err:
/* Delete DMA buffer if failed to allocate memory */
@@ -819,7 +819,7 @@ static esp_err_t i2s_create_dma_object(i2s_port_t i2s_num, i2s_dma_t **dma)
{
ESP_RETURN_ON_FALSE(dma, ESP_ERR_INVALID_ARG, TAG, "DMA object secondary pointer is NULL");
ESP_RETURN_ON_FALSE((*dma == NULL), ESP_ERR_INVALID_ARG, TAG, "DMA object has been created");
uint32_t buf_cnt = p_i2s[i2s_num]->dma_buf_count;
uint32_t buf_cnt = p_i2s[i2s_num]->dma_desc_num;
/* Allocate new DMA structure */
*dma = (i2s_dma_t *) malloc(sizeof(i2s_dma_t));
ESP_RETURN_ON_FALSE(*dma, ESP_ERR_NO_MEM, TAG, "DMA object allocate failed");
@@ -866,7 +866,7 @@ esp_err_t i2s_zero_dma_buffer(i2s_port_t i2s_num)
/* Clear I2S RX DMA buffer */
if (p_i2s[i2s_num]->rx && p_i2s[i2s_num]->rx->buf != NULL && p_i2s[i2s_num]->rx->buf_size != 0) {
for (int i = 0; i < p_i2s[i2s_num]->dma_buf_count; i++) {
for (int i = 0; i < p_i2s[i2s_num]->dma_desc_num; i++) {
memset(p_i2s[i2s_num]->rx->buf[i], 0, p_i2s[i2s_num]->rx->buf_size);
}
}
@@ -879,7 +879,7 @@ esp_err_t i2s_zero_dma_buffer(i2s_port_t i2s_num)
size_t zero_bytes = 0, bytes_written;
i2s_write(i2s_num, (void *)&zero_bytes, bytes_left, &bytes_written, portMAX_DELAY);
}
for (int i = 0; i < p_i2s[i2s_num]->dma_buf_count; i++) {
for (int i = 0; i < p_i2s[i2s_num]->dma_desc_num; i++) {
memset(p_i2s[i2s_num]->tx->buf[i], 0, p_i2s[i2s_num]->tx->buf_size);
}
}
@@ -1808,8 +1808,8 @@ static esp_err_t i2s_driver_init(i2s_port_t i2s_num, const i2s_config_t *i2s_con
/* I2S driver configuration assignment */
p_i2s[i2s_num]->i2s_num = i2s_num;
p_i2s[i2s_num]->dma_buf_count = i2s_config->dma_buf_count;
p_i2s[i2s_num]->dma_buf_len = i2s_config->dma_buf_len;
p_i2s[i2s_num]->dma_desc_num = i2s_config->dma_desc_num;
p_i2s[i2s_num]->dma_frame_num = i2s_config->dma_frame_num;
p_i2s[i2s_num]->last_buf_size = 0;
p_i2s[i2s_num]->use_apll = i2s_config->use_apll;
p_i2s[i2s_num]->fixed_mclk = i2s_config->fixed_mclk;
@@ -1918,8 +1918,8 @@ esp_err_t i2s_driver_install(i2s_port_t i2s_num, const i2s_config_t *i2s_config,
ESP_RETURN_ON_FALSE((i2s_num < I2S_NUM_MAX), ESP_ERR_INVALID_ARG, TAG, "i2s_num error");
ESP_RETURN_ON_FALSE(i2s_config, ESP_ERR_INVALID_ARG, TAG, "I2S configuration must not be NULL");
/* Check the size of DMA buffer */
ESP_RETURN_ON_FALSE((i2s_config->dma_buf_count >= 2 && i2s_config->dma_buf_count <= 128), ESP_ERR_INVALID_ARG, TAG, "I2S buffer count less than 128 and more than 2");
ESP_RETURN_ON_FALSE((i2s_config->dma_buf_len >= 8 && i2s_config->dma_buf_len <= 1024), ESP_ERR_INVALID_ARG, TAG, "I2S buffer length at most 1024 and more than 8");
ESP_RETURN_ON_FALSE((i2s_config->dma_desc_num >= 2 && i2s_config->dma_desc_num <= 128), ESP_ERR_INVALID_ARG, TAG, "I2S buffer count less than 128 and more than 2");
ESP_RETURN_ON_FALSE((i2s_config->dma_frame_num >= 8 && i2s_config->dma_frame_num <= 1024), ESP_ERR_INVALID_ARG, TAG, "I2S buffer length at most 1024 and more than 8");
/* Step 2: Allocate driver object and register to platform */
i2s_obj_t *pre_alloc_i2s_obj = calloc(1, sizeof(i2s_obj_t));
components/driver/include/driver/i2s.h
+9 -2
View File
@@ -96,8 +96,15 @@ typedef struct {
i2s_channel_fmt_t channel_format; /*!< I2S channel format.*/
i2s_comm_format_t communication_format; /*!< I2S communication format */
int intr_alloc_flags; /*!< Flags used to allocate the interrupt. One or multiple (ORred) ESP_INTR_FLAG_* values. See esp_intr_alloc.h for more info */
int dma_buf_count; /*!< I2S DMA Buffer Count */
int dma_buf_len; /*!< I2S DMA Buffer Length */
union {
int dma_desc_num; /*!< The total number of descriptors used by I2S DMA to receive/transmit data */
int dma_buf_count __attribute__((deprecated)); /*!< This is an alias to 'dma_desc_num' for backward compatibility */
};
union {
int dma_frame_num; /*!< Frame number for one-time sampling. Frame here means the total data from all the channels in a WS cycle */
int dma_buf_len __attribute__((deprecated)); /*!< This is an alias to 'dma_frame_num' for backward compatibility */
};
bool use_apll; /*!< I2S using APLL as main I2S clock, enable it to get accurate clock */
bool tx_desc_auto_clear; /*!< I2S auto clear tx descriptor if there is underflow condition (helps in avoiding noise in case of data unavailability) */
int fixed_mclk; /*!< I2S using fixed MCLK output. If use_apll = true and fixed_mclk > 0, then the clock output for i2s is fixed and equal to the fixed_mclk value. If fixed_mclk set, mclk_multiple won't take effect */
components/driver/test/adc_dma_test/test_esp32.c
+2 -2
View File
@@ -59,8 +59,8 @@ static void example_i2s_init(void)
.bits_per_sample = EXAMPLE_I2S_SAMPLE_BITS,
.channel_format = EXAMPLE_I2S_FORMAT,
.intr_alloc_flags = 0,
.dma_buf_count = 2,
.dma_buf_len = 1024,
.dma_desc_num = 2,
.dma_frame_num = 1024,
.use_apll = 0,
};
components/driver/test/dac_dma_test/test_esp32.c
+2 -2
View File
@@ -61,8 +61,8 @@ static void example_i2s_init(void)
.bits_per_sample = EXAMPLE_I2S_SAMPLE_BITS,
.channel_format = EXAMPLE_I2S_FORMAT,
.intr_alloc_flags = 0,
.dma_buf_count = 2,
.dma_buf_len = 1024,
.dma_desc_num = 2,
.dma_frame_num = 1024,
.use_apll = 0,
};
//install and start i2s driver
components/driver/test/test_adc2_with_wifi.c
+2 -2
View File
@@ -228,8 +228,8 @@ static void i2s_adc_init(void)
.bits_per_sample = SAMPLE_BITS,
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.intr_alloc_flags = 0,
.dma_buf_count = 2,
.dma_buf_len = 1024,
.dma_desc_num = 2,
.dma_frame_num = 1024,
.use_apll = 0,
};
// install and start I2S driver
components/driver/test/test_i2s.c
+24 -24
View File
@@ -143,8 +143,8 @@ TEST_CASE("I2S basic driver install, uninstall, set pin test", "[i2s]")
.bits_per_sample = SAMPLE_BITS,
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.communication_format = I2S_COMM_FORMAT_STAND_I2S,
.dma_buf_count = 6,
.dma_buf_len = 60,
.dma_desc_num = 6,
.dma_frame_num = 60,
.use_apll = 0,
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
#if SOC_I2S_SUPPORTS_TDM
@@ -174,9 +174,9 @@ TEST_CASE("I2S basic driver install, uninstall, set pin test", "[i2s]")
//error param test
TEST_ASSERT(i2s_driver_install(I2S_NUM_MAX, &i2s_config, 0, NULL) == ESP_ERR_INVALID_ARG);
TEST_ASSERT(i2s_driver_install(I2S_NUM_0, NULL, 0, NULL) == ESP_ERR_INVALID_ARG);
i2s_config.dma_buf_count = 1;
i2s_config.dma_desc_num = 1;
TEST_ASSERT(i2s_driver_install(I2S_NUM_0, &i2s_config, 0, NULL) == ESP_ERR_INVALID_ARG);
i2s_config.dma_buf_count = 129;
i2s_config.dma_desc_num = 129;
TEST_ASSERT(i2s_driver_install(I2S_NUM_0, &i2s_config, 0, NULL) == ESP_ERR_INVALID_ARG);
TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, i2s_driver_uninstall(I2S_NUM_0));
}
@@ -190,8 +190,8 @@ TEST_CASE("I2S Loopback test(master tx and rx)", "[i2s]")
.bits_per_sample = SAMPLE_BITS,
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.communication_format = I2S_COMM_FORMAT_STAND_I2S,
.dma_buf_count = 6,
.dma_buf_len = 100,
.dma_desc_num = 6,
.dma_frame_num = 100,
.use_apll = 0,
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
#if SOC_I2S_SUPPORTS_TDM
@@ -265,8 +265,8 @@ TEST_CASE("I2S TDM Loopback test(master tx and rx)", "[i2s]")
.communication_format = I2S_COMM_FORMAT_STAND_I2S,
.total_chan = 4,
.chan_mask = I2S_TDM_ACTIVE_CH0 | I2S_TDM_ACTIVE_CH1 | I2S_TDM_ACTIVE_CH2 | I2S_TDM_ACTIVE_CH3,
.dma_buf_count = 6,
.dma_buf_len = 100,
.dma_desc_num = 6,
.dma_frame_num = 100,
.use_apll = 0,
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
};
@@ -332,8 +332,8 @@ TEST_CASE("I2S write and read test(master tx and slave rx)", "[i2s]")
.bits_per_sample = SAMPLE_BITS,
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.communication_format = I2S_COMM_FORMAT_STAND_I2S,
.dma_buf_count = 6,
.dma_buf_len = 100,
.dma_desc_num = 6,
.dma_frame_num = 100,
.use_apll = 0,
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
#if SOC_I2S_SUPPORTS_TDM
@@ -363,8 +363,8 @@ TEST_CASE("I2S write and read test(master tx and slave rx)", "[i2s]")
.bits_per_sample = SAMPLE_BITS,
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.communication_format = I2S_COMM_FORMAT_STAND_I2S,
.dma_buf_count = 6,
.dma_buf_len = 100,
.dma_desc_num = 6,
.dma_frame_num = 100,
.use_apll = 0,
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
#if SOC_I2S_SUPPORTS_TDM
@@ -436,8 +436,8 @@ TEST_CASE("I2S write and read test(master rx and slave tx)", "[i2s]")
.bits_per_sample = SAMPLE_BITS,
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.communication_format = I2S_COMM_FORMAT_STAND_I2S,
.dma_buf_count = 6,
.dma_buf_len = 100,
.dma_desc_num = 6,
.dma_frame_num = 100,
.use_apll = 1,
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
#if SOC_I2S_SUPPORTS_TDM
@@ -467,8 +467,8 @@ TEST_CASE("I2S write and read test(master rx and slave tx)", "[i2s]")
.bits_per_sample = SAMPLE_BITS,
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT, //2-channels
.communication_format = I2S_COMM_FORMAT_STAND_I2S,
.dma_buf_count = 6,
.dma_buf_len = 100,
.dma_desc_num = 6,
.dma_frame_num = 100,
.use_apll = 1,
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
#if SOC_I2S_SUPPORTS_TDM
@@ -541,8 +541,8 @@ TEST_CASE("I2S memory leaking test", "[i2s]")
.bits_per_sample = SAMPLE_BITS,
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.communication_format = I2S_COMM_FORMAT_STAND_I2S,
.dma_buf_count = 6,
.dma_buf_len = 100,
.dma_desc_num = 6,
.dma_frame_num = 100,
.use_apll = 0,
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
#if SOC_I2S_SUPPORTS_TDM
@@ -599,8 +599,8 @@ TEST_CASE("I2S APLL clock variation test", "[i2s]")
.bits_per_sample = SAMPLE_BITS,
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.communication_format = I2S_COMM_FORMAT_STAND_I2S,
.dma_buf_count = 6,
.dma_buf_len = 60,
.dma_desc_num = 6,
.dma_frame_num = 60,
.use_apll = true,
.intr_alloc_flags = 0,
#if SOC_I2S_SUPPORTS_TDM
@@ -650,8 +650,8 @@ TEST_CASE("I2S adc test", "[i2s]")
.bits_per_sample = SAMPLE_BITS,
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.intr_alloc_flags = 0,
.dma_buf_count = 2,
.dma_buf_len = 1024,
.dma_desc_num = 2,
.dma_frame_num = 1024,
.use_apll = 0,
};
// install and start I2S driver
@@ -717,8 +717,8 @@ TEST_CASE("I2S dac test", "[i2s]")
.bits_per_sample = SAMPLE_BITS,
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.communication_format = I2S_COMM_FORMAT_STAND_I2S,
.dma_buf_count = 6,
.dma_buf_len = 60,
.dma_desc_num = 6,
.dma_frame_num = 60,
.use_apll = 0,
.intr_alloc_flags = ESP_INTR_FLAG_LEVEL1,
};
components/esp_event/include/esp_event.h
+53 -61
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
components/esp_event/include/esp_event_legacy.h
+11 -19
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
*
components/esp_lcd/test/test_i80_lcd_panel.c
+2 -2
View File
@@ -591,8 +591,8 @@ TEST_CASE("i80 and i2s driver coexistance", "[lcd][i2s]")
.bits_per_sample = 16,
.channel_format = I2S_CHANNEL_FMT_RIGHT_LEFT,
.communication_format = I2S_COMM_FORMAT_STAND_I2S,
.dma_buf_count = 6,
.dma_buf_len = 60,
.dma_desc_num = 6,
.dma_frame_num = 60,
};
// I2S driver won't be installed as the same I2S port has been used by LCD
TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, i2s_driver_install(0, &i2s_config, 0, NULL));
components/esp_ringbuf/include/freertos/ringbuf.h
+11 -19
View File
@@ -1,16 +1,8 @@
// Copyright 2015-2019 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
*/
#ifndef FREERTOS_RINGBUF_H
#define FREERTOS_RINGBUF_H
@@ -82,7 +74,7 @@ typedef struct xSTATIC_RINGBUFFER {
* @brief Create a ring buffer
*
* @param[in] xBufferSize Size of the buffer in bytes. Note that items require
* space for overhead in no-split/allow-split buffers
* space for a header in no-split/allow-split buffers
* @param[in] xBufferType Type of ring buffer, see documentation.
*
* @note xBufferSize of no-split/allow-split buffers will be rounded up to the nearest 32-bit aligned size.
@@ -111,7 +103,7 @@ RingbufHandle_t xRingbufferCreateNoSplit(size_t xItemSize, size_t xItemNum);
* @param[in] xBufferSize Size of the buffer in bytes.
* @param[in] xBufferType Type of ring buffer, see documentation
* @param[in] pucRingbufferStorage Pointer to the ring buffer's storage area.
* Storage area must of the same size as specified by xBufferSize
* Storage area must have the same size as specified by xBufferSize
* @param[in] pxStaticRingbuffer Pointed to a struct of type StaticRingbuffer_t
* which will be used to hold the ring buffer's data structure
*
@@ -182,7 +174,7 @@ BaseType_t xRingbufferSendFromISR(RingbufHandle_t xRingbuffer,
*
* Attempt to allocate buffer for an item to be sent into the ring buffer. This
* function will block until enough free space is available or until it
* timesout.
* times out.
*
* The item, as well as the following items ``SendAcquire`` or ``Send`` after it,
* will not be able to be read from the ring buffer until this item is actually
@@ -407,7 +399,7 @@ void vRingbufferDelete(RingbufHandle_t xRingbuffer);
*
* @note The max item size for a no-split buffer is limited to
* ((buffer_size/2)-header_size). This limit is imposed so that an item
* of max item size can always be sent to the an empty no-split buffer
* of max item size can always be sent to an empty no-split buffer
* regardless of the internal positions of the buffer's read/write/free
* pointers.
*
@@ -486,8 +478,8 @@ BaseType_t xRingbufferRemoveFromQueueSetRead(RingbufHandle_t xRingbuffer, QueueS
/**
* @brief Get information about ring buffer status
*
* Get information of the a ring buffer's current status such as
* free/read/write pointer positions, and number of items waiting to be retrieved.
* Get information of a ring buffer's current status such as
* free/read/write/acquire pointer positions, and number of items waiting to be retrieved.
* Arguments can be set to NULL if they are not required.
*
* @param[in] xRingbuffer Ring buffer to remove from the queue set
components/esp_system/include/esp_system.h
+8 -16
View File
@@ -1,16 +1,8 @@
// Copyright 2015-2016 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
*/
#ifndef __ESP_SYSTEM_H__
#define __ESP_SYSTEM_H__
@@ -86,7 +78,7 @@ esp_err_t esp_unregister_shutdown_handler(shutdown_handler_t handle);
*
* This function can be called both from PRO and APP CPUs.
* After successful restart, CPU reset reason will be SW_CPU_RESET.
* Peripherals (except for WiFi, BT, UART0, SPI1, and legacy timers) are not reset.
* Peripherals (except for Wi-Fi, BT, UART0, SPI1, and legacy timers) are not reset.
* This function does not return.
*/
void esp_restart(void) __attribute__ ((noreturn));
@@ -100,7 +92,7 @@ esp_reset_reason_t esp_reset_reason(void);
/**
* @brief Get the size of available heap.
*
* Note that the returned value may be larger than the maximum contiguous block
* @note Note that the returned value may be larger than the maximum contiguous block
* which can be allocated.
*
* @return Available heap size, in bytes.
@@ -110,7 +102,7 @@ uint32_t esp_get_free_heap_size(void);
/**
* @brief Get the size of available internal heap.
*
* Note that the returned value may be larger than the maximum contiguous block
* @note Note that the returned value may be larger than the maximum contiguous block
* which can be allocated.
*
* @return Available internal heap size, in bytes.
components/heap/include/esp_heap_caps.h
+16 -16
View File
@@ -39,9 +39,9 @@ extern "C" {
#define MALLOC_CAP_INVALID (1<<31) ///< Memory can't be used / list end marker
/**
* @brief callback called when a allocation operation fails, if registered
* @brief callback called when an allocation operation fails, if registered
* @param size in bytes of failed allocation
* @param caps capabillites requested of failed allocation
* @param caps capabilities requested of failed allocation
* @param function_name function which generated the failure
*/
typedef void (*esp_alloc_failed_hook_t) (size_t size, uint32_t caps, const char * function_name);
@@ -100,7 +100,7 @@ void heap_caps_free( void *ptr);
void *heap_caps_realloc( void *ptr, size_t size, uint32_t caps);
/**
* @brief Allocate a aligned chunk of memory which has the given capabilities
* @brief Allocate an aligned chunk of memory which has the given capabilities
*
* Equivalent semantics to libc aligned_alloc(), for capability-aware memory.
* @param alignment How the pointer received needs to be aligned
@@ -119,12 +119,12 @@ void *heap_caps_aligned_alloc(size_t alignment, size_t size, uint32_t caps);
* @brief Used to deallocate memory previously allocated with heap_caps_aligned_alloc
*
* @param ptr Pointer to the memory allocated
* @note This function is deprecated, plase consider using heap_caps_free() instead
* @note This function is deprecated, please consider using heap_caps_free() instead
*/
void __attribute__((deprecated)) heap_caps_aligned_free(void *ptr);
/**
* @brief Allocate a aligned chunk of memory which has the given capabilities. The initialized value in the memory is set to zero.
* @brief Allocate an aligned chunk of memory which has the given capabilities. The initialized value in the memory is set to zero.
*
* @param alignment How the pointer received needs to be aligned
* must be a power of two
@@ -175,7 +175,7 @@ size_t heap_caps_get_total_size(uint32_t caps);
* This function takes all regions capable of having the given capabilities allocated in them
* and adds up the free space they have.
*
* Note that because of heap fragmentation it is probably not possible to allocate a single block of memory
* @note Note that because of heap fragmentation it is probably not possible to allocate a single block of memory
* of this size. Use heap_caps_get_largest_free_block() for this purpose.
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
@@ -189,11 +189,11 @@ size_t heap_caps_get_free_size( uint32_t caps );
/**
* @brief Get the total minimum free memory of all regions with the given capabilities
*
* This adds all the low water marks of the regions capable of delivering the memory
* This adds all the low watermarks of the regions capable of delivering the memory
* with the given capabilities.
*
* Note the result may be less than the global all-time minimum available heap of this kind, as "low water marks" are
* tracked per-region. Individual regions' heaps may have reached their "low water marks" at different points in time. However
* @note Note the result may be less than the global all-time minimum available heap of this kind, as "low watermarks" are
* tracked per-region. Individual regions' heaps may have reached their "low watermarks" at different points in time. However,
* this result still gives a "worst case" indication for all-time minimum free heap.
*
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
@@ -211,7 +211,7 @@ size_t heap_caps_get_minimum_free_size( uint32_t caps );
* @param caps Bitwise OR of MALLOC_CAP_* flags indicating the type
* of memory
*
* @return Size of largest free block in bytes.
* @return Size of the largest free block in bytes.
*/
size_t heap_caps_get_largest_free_block( uint32_t caps );
@@ -219,8 +219,8 @@ size_t heap_caps_get_largest_free_block( uint32_t caps );
/**
* @brief Get heap info for all regions with the given capabilities.
*
* Calls multi_heap_info() on all heaps which share the given capabilities. The information returned is an aggregate
* across all matching heaps. The meanings of fields are the same as defined for multi_heap_info_t, except that
* Calls multi_heap_info() on all heaps which share the given capabilities. The information returned is an aggregate
* across all matching heaps. The meanings of fields are the same as defined for multi_heap_info_t, except that
* ``minimum_free_bytes`` has the same caveats described in heap_caps_get_minimum_free_size().
*
* @param info Pointer to a structure which will be filled with relevant
@@ -285,7 +285,7 @@ bool heap_caps_check_integrity(uint32_t caps, bool print_errors);
* This can be useful if debugging heap integrity for corruption at a known address,
* as it has a lower overhead than checking all heap regions. Note that if the corrupt
* address moves around between runs (due to timing or other factors) then this approach
* won't work and you should call heap_caps_check_integrity or
* won't work, and you should call heap_caps_check_integrity or
* heap_caps_check_integrity_all instead.
*
* @note The entire heap region around the address is checked, not only the adjacent
@@ -321,14 +321,14 @@ void heap_caps_malloc_extmem_enable(size_t limit);
* or fail to allocate memories with any of the parameters.
*
* @param size Size, in bytes, of the amount of memory to allocate
* @param num Number of variable paramters
* @param num Number of variable parameters
*
* @return A pointer to the memory allocated on success, NULL on failure
*/
void *heap_caps_malloc_prefer( size_t size, size_t num, ... );
/**
* @brief Allocate a chunk of memory as preference in decreasing order.
* @brief Reallocate a chunk of memory as preference in decreasing order.
*
* @param ptr Pointer to previously allocated memory, or NULL for a new allocation.
* @param size Size of the new buffer requested, or 0 to free the buffer.
@@ -382,7 +382,7 @@ void heap_caps_dump_all(void);
* @brief Return the size that a particular pointer was allocated with.
*
* @param ptr Pointer to currently allocated heap memory. Must be a pointer value previously
* returned by heap_caps_malloc,malloc,calloc, etc. and not yet freed.
* returned by heap_caps_malloc, malloc, calloc, etc. and not yet freed.
*
* @note The app will crash with an assertion failure if the pointer is not valid.
*
components/heap/include/multi_heap.h
+9 -17
View File
@@ -1,16 +1,8 @@
// Copyright 2015-2016 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
#include <stdint.h>
#include <stdlib.h>
@@ -55,7 +47,7 @@ void *multi_heap_malloc(multi_heap_handle_t heap, size_t size);
*
* @param heap Handle to a registered heap.
* @param p NULL, or a pointer previously returned from multi_heap_aligned_alloc() for the same heap.
* @note This function is deprecated, consider using multi_heap_free() instead
* @note This function is deprecated, consider using multi_heap_free() instead
*/
void __attribute__((deprecated)) multi_heap_aligned_free(multi_heap_handle_t heap, void *p);
@@ -130,7 +122,7 @@ void multi_heap_dump(multi_heap_handle_t heap);
/** @brief Check heap integrity
*
* Walks the heap and checks all heap data structures are valid. If any errors are detected, an error-specific message
* can be optionally printed to stderr. Print behaviour can be overriden at compile time by defining
* can be optionally printed to stderr. Print behaviour can be overridden at compile time by defining
* MULTI_CHECK_FAIL_PRINTF in multi_heap_platform.h.
*
* @param heap Handle to a registered heap.
@@ -157,7 +149,7 @@ size_t multi_heap_free_size(multi_heap_handle_t heap);
*
* Equivalent to the minimum_free_bytes member returned by multi_heap_get_info().
*
* Returns the lifetime "low water mark" of possible values returned from multi_free_heap_size(), for the specified
* Returns the lifetime "low watermark" of possible values returned from multi_free_heap_size(), for the specified
* heap.
*
* @param heap Handle to a registered heap.
@@ -169,7 +161,7 @@ size_t multi_heap_minimum_free_size(multi_heap_handle_t heap);
typedef struct {
size_t total_free_bytes; ///< Total free bytes in the heap. Equivalent to multi_free_heap_size().
size_t total_allocated_bytes; ///< Total bytes allocated to data in the heap.
size_t largest_free_block; ///< Size of largest free block in the heap. This is the largest malloc-able size.
size_t largest_free_block; ///< Size of the largest free block in the heap. This is the largest malloc-able size.
size_t minimum_free_bytes; ///< Lifetime minimum free heap size. Equivalent to multi_minimum_free_heap_size().
size_t allocated_blocks; ///< Number of (variable size) blocks allocated in the heap.
size_t free_blocks; ///< Number of (variable size) free blocks in the heap.
components/log/include/esp_log.h
+10 -10
View File
@@ -58,9 +58,8 @@ extern esp_log_level_t esp_log_default_level;
*
* If logging for given component has already been enabled, changes previous setting.
*
* Note that this function can not raise log level above the level set using
* @note Note that this function can not raise log level above the level set using
* CONFIG_LOG_MAXIMUM_LEVEL setting in menuconfig.
*
* To raise log level above the default one for a given file, define
* LOG_LOCAL_LEVEL to one of the ESP_LOG_* values, before including
* esp_log.h in this file.
@@ -74,7 +73,7 @@ extern esp_log_level_t esp_log_default_level;
void esp_log_level_set(const char* tag, esp_log_level_t level);
/**
* @brief Get log level for given tag, can be used to avoid expensive log statements
* @brief Get log level for a given tag, can be used to avoid expensive log statements
*
* @param tag Tag of the log to query current level. Must be a non-NULL zero terminated
* string.
@@ -121,8 +120,8 @@ uint32_t esp_log_timestamp(void);
* 0 on startup, this can be set to the correct time with an SNTP sync,
* or manually with standard POSIX time functions.
*
* Currently this will not get used in logging from binary blobs
* (i.e WiFi & Bluetooth libraries), these will still print the RTOS tick time.
* Currently, this will not get used in logging from binary blobs
* (i.e. Wi-Fi & Bluetooth libraries), these will still print the RTOS tick time.
*
* @return timestamp, in "HH:MM:SS.sss"
*/
@@ -212,7 +211,7 @@ void esp_log_writev(esp_log_level_t level, const char* tag, const char* format,
* W (195) log_example: 0x3ffb4290 77 6f 72 6b 69 6e 67 20 61 6c 6f 6e 67 20 77 69 |working along wi|
* W (205) log_example: 0x3ffb42a0 74 68 20 74 68 65 20 49 44 46 2e 00 |th the IDF..|
*
* It is highly recommend to use terminals with over 102 text width.
* It is highly recommended to use terminals with over 102 text width.
*
* @param tag description tag
* @param buffer Pointer to the buffer array
@@ -297,7 +296,8 @@ void esp_log_writev(esp_log_level_t level, const char* tag, const char* format,
/** @endcond */
/// macro to output logs in startup code, before heap allocator and syscalls have been initialized. log at ``ESP_LOG_ERROR`` level. @see ``printf``,``ESP_LOGE``,``ESP_DRAM_LOGE``
/// macro to output logs in startup code, before heap allocator and syscalls have been initialized.
/// Log at ``ESP_LOG_ERROR`` level. @see ``printf``,``ESP_LOGE``,``ESP_DRAM_LOGE``
#define portGET_ARGUMENT_COUNT_INNER(zero, one, count, ...) count
/**
@@ -394,8 +394,8 @@ void esp_log_writev(esp_log_level_t level, const char* tag, const char* format,
*
* @param tag tag of the log, which can be used to change the log level by ``esp_log_level_set`` at runtime.
* @param level level of the output log.
* @param format format of the output log. see ``printf``
* @param ... variables to be replaced into the log. see ``printf``
* @param format format of the output log. See ``printf``
* @param ... variables to be replaced into the log. See ``printf``
*
* @see ``printf``
*/
@@ -447,7 +447,7 @@ void esp_log_writev(esp_log_level_t level, const char* tag, const char* format,
/**
* @brief Macro to output logs when the cache is disabled. log at ``ESP_LOG_ERROR`` level.
* @brief Macro to output logs when the cache is disabled. Log at ``ESP_LOG_ERROR`` level.
*
* @note Unlike normal logging macros, it's possible to use this macro when interrupts are
* disabled or inside an ISR.
components/lwip/include/apps/esp_sntp.h
+7 -15
View File
@@ -1,16 +1,8 @@
// Copyright 2015-2019 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
*/
#ifndef __ESP_SNTP_H__
#define __ESP_SNTP_H__
@@ -28,7 +20,7 @@ extern "C" {
* The user has the ability to redefine this function in order
* to re-define its functionality. This function has two time update modes,
* which can be set via the sntp_set_sync_mode() function.
* Two modes are available:
* Two available modes are as follows:
* - the first is an immediate update when receiving time from the sntp server,
* - the second is a smooth time update (if the time error is no more than 35 minutes,
* and an immediate update if the error is more than 35 minutes).
@@ -83,7 +75,7 @@ void sntp_sync_time(struct timeval *tv);
/**
* @brief Set the sync mode
*
* Allowable two mode: SNTP_SYNC_MODE_IMMED and SNTP_SYNC_MODE_SMOOTH.
* Modes allowed: SNTP_SYNC_MODE_IMMED and SNTP_SYNC_MODE_SMOOTH.
* @param sync_mode Sync mode.
*/
void sntp_set_sync_mode(sntp_sync_mode_t sync_mode);