mirror of
https://github.com/espressif/esp-idf.git
synced 2026-06-04 20:26:38 +03:00
docs: Fix broken links
This commit is contained in:
Zhang Shuxian
@@ -43,7 +43,7 @@ To install an ADC instance, set up the required initial configuration structure
|
||||
|
||||
.. todo::
|
||||
|
||||
Add ULP ADC-related docs here.
|
||||
Add ULP ADC-related docs here.
|
||||
|
||||
After setting up the initial configurations for the ADC, call :cpp:func:`adc_oneshot_new_unit` with the prepared :cpp:type:`adc_oneshot_unit_init_cfg_t`. This function will return an ADC unit handle if the allocation is successful.
|
||||
|
||||
@@ -200,7 +200,7 @@ Above functions are guaranteed to be thread-safe. Therefore, you can call them f
|
||||
Kconfig Options
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
- :ref:`CONFIG_ADC_ONESHOT_CTRL_FUNC_IN_IRAM` controls where to place the ADC fast read function (IRAM or Flash), see `IRAM Safe <#iram-safe>`__ for more details.
|
||||
- :ref:`CONFIG_ADC_ONESHOT_CTRL_FUNC_IN_IRAM` controls where to place the ADC fast read function (IRAM or Flash), see :ref:`adc-oneshot-iram-safe` for more details.
|
||||
|
||||
|
||||
Application Examples
|
||||
|
||||
@@ -14,10 +14,10 @@ Functional Overview
|
||||
|
||||
.. list::
|
||||
|
||||
- `BitScrambler Assembly <#bitscrambler-assembly>`__ covers how a BitScrambler assembly program is structured.
|
||||
- `Build System Integration <#bitscrambler-build>`__ covers how BitScrambler programs are integrated in the ESP-IDF build system.
|
||||
- `Resource Allocation and Program Loading <#bitscrambler-load>`__ covers how to allocate BitScrambler instances and how to load a program into them.
|
||||
- `Loopback Mode <#bitscrambler-loopback>`__ covers how to use the BitScrambler in loopback mode.
|
||||
- :ref:`bitscrambler-assembly` covers how a BitScrambler assembly program is structured.
|
||||
- :ref:`bitscrambler-build` covers how BitScrambler programs are integrated in the ESP-IDF build system.
|
||||
- :ref:`bitscrambler-load` covers how to allocate BitScrambler instances and how to load a program into them.
|
||||
- :ref:`bitscrambler-loopback` covers how to use the BitScrambler in loopback mode.
|
||||
|
||||
.. _bitscrambler-assembly:
|
||||
|
||||
@@ -215,6 +215,8 @@ Loopback Mode
|
||||
|
||||
The BitScrambler supports a loopback mode which is useful for data transformations that do not involve a peripheral. The loopback mode occupies both the TX and RX channels of the BitScrambler, although only the TX BitScrambler actually executes code. Note that even if loopback mode does not involve a peripheral, one still needs to be selected; the peripheral does not need to be initialized or used, but if it is, its DMA features will be unavailable.
|
||||
|
||||
.. _bitscrambler-load:
|
||||
|
||||
Resource Allocation and Program Loading
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
@@ -114,19 +114,19 @@ Categorized by functionality, the APIs of Capacitive Touch Sensor mainly include
|
||||
|
||||
.. list::
|
||||
|
||||
- `Touch Sensor Controller Management <#touch-ctrl>`__
|
||||
- `Touch Sensor Channel Management <#touch-chan>`__
|
||||
- `Filter Configuration <#touch-filter>`__
|
||||
- `Callback <#touch-callback>`__
|
||||
- `Enable and Disable <#touch-enable>`__
|
||||
- `Continuous Scan <#touch-conti-scan>`__
|
||||
- `Oneshot Scan <#touch-oneshot-scan>`__
|
||||
- `Read Measurement Data <#touch-read>`__
|
||||
:SOC_TOUCH_SUPPORT_BENCHMARK: - `Benchmark Configuration <#touch-benchmark>`__
|
||||
:SOC_TOUCH_SUPPORT_WATERPROOF: - `Waterproof Configuration <#touch-waterproof>`__
|
||||
:SOC_TOUCH_SUPPORT_PROX_SENSING: - `Proximity Sensing Configuration <#touch-prox-sensing>`__
|
||||
:SOC_TOUCH_SUPPORT_SLEEP_WAKEUP: - `Sleep Wake-up Configuration <#touch-sleep-wakeup>`__
|
||||
:SOC_TOUCH_SUPPORT_DENOISE_CHAN: - `Denoise Channel Configuration <#touch-denoise-chan>`__
|
||||
- :ref:`touch-ctrl`
|
||||
- :ref:`touch-chan`
|
||||
- :ref:`touch-filter`
|
||||
- :ref:`touch-callback`
|
||||
- :ref:`touch-enable`
|
||||
- :ref:`touch-conti-scan`
|
||||
- :ref:`touch-oneshot-scan`
|
||||
- :ref:`touch-read`
|
||||
:SOC_TOUCH_SUPPORT_BENCHMARK: - :ref:`touch-benchmark`
|
||||
:SOC_TOUCH_SUPPORT_WATERPROOF: - :ref:`touch-waterproof`
|
||||
:SOC_TOUCH_SUPPORT_PROX_SENSING: - :ref:`touch-prox-sensing`
|
||||
:SOC_TOUCH_SUPPORT_SLEEP_WAKEUP: - :ref:`touch-sleep-wakeup`
|
||||
:SOC_TOUCH_SUPPORT_DENOISE_CHAN: - :ref:`touch-denoise-chan`
|
||||
|
||||
.. _touch-ctrl:
|
||||
|
||||
@@ -322,10 +322,10 @@ Call :cpp:func:`touch_channel_read_data` to read the data with different types.
|
||||
// Read the smooth data
|
||||
ESP_ERROR_CHECK(touch_channel_read_data(chan_handle, TOUCH_CHAN_DATA_TYPE_SMOOTH, smooth_data));
|
||||
|
||||
.. _touch-benchmark:
|
||||
|
||||
.. only:: SOC_TOUCH_SUPPORT_BENCHMARK
|
||||
|
||||
.. _touch-benchmark:
|
||||
|
||||
Benchmark Configuration
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -339,10 +339,10 @@ Call :cpp:func:`touch_channel_read_data` to read the data with different types.
|
||||
};
|
||||
ESP_ERROR_CHECK(touch_channel_config_benchmark(chan_handle, &benchmark_cfg));
|
||||
|
||||
.. _touch-waterproof:
|
||||
|
||||
.. only:: SOC_TOUCH_SUPPORT_WATERPROOF
|
||||
|
||||
.. _touch-waterproof:
|
||||
|
||||
Waterproof Configuration
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -365,10 +365,10 @@ Call :cpp:func:`touch_channel_read_data` to read the data with different types.
|
||||
// Deregister waterproof function
|
||||
ESP_ERROR_CHECK(touch_sensor_config_waterproof(sens_handle, NULL));
|
||||
|
||||
.. _touch-prox-sensing:
|
||||
|
||||
.. only:: SOC_TOUCH_SUPPORT_PROX_SENSING
|
||||
|
||||
.. _touch-prox-sensing:
|
||||
|
||||
Proximity Sensing Configuration
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -398,10 +398,11 @@ Call :cpp:func:`touch_channel_read_data` to read the data with different types.
|
||||
// Deregister the proximity sensing
|
||||
ESP_ERROR_CHECK(touch_sensor_config_proximity_sensing(sens_handle, NULL));
|
||||
|
||||
.. _touch-sleep-wakeup:
|
||||
|
||||
.. only:: SOC_TOUCH_SUPPORT_SLEEP_WAKEUP
|
||||
|
||||
.. _touch-sleep-wakeup:
|
||||
|
||||
Sleep Wake-up Configuration
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -444,10 +445,10 @@ Call :cpp:func:`touch_channel_read_data` to read the data with different types.
|
||||
// Register the deep sleep wake-up
|
||||
ESP_ERROR_CHECK(touch_sensor_config_sleep_wakeup(sens_handle, &deep_slp_cfg));
|
||||
|
||||
.. _touch-denoise-chan:
|
||||
|
||||
.. only:: SOC_TOUCH_SUPPORT_DENOISE_CHAN
|
||||
|
||||
.. _touch-denoise-chan:
|
||||
|
||||
Denoise Channel Configuration
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
@@ -77,6 +77,8 @@ When the power management is enabled (i.e., :ref:`CONFIG_PM_ENABLE` is on), the
|
||||
|
||||
When using DAC driver in continuous mode, it can prevent the system from changing or stopping the clock source in DMA or cosine mode by acquiring a power management lock. When the clock source is generated from APB, the lock type will be set to :cpp:enumerator:`esp_pm_lock_type_t::ESP_PM_APB_FREQ_MAX`. When the clock source is APLL (only in DMA mode), it will be set to :cpp:enumerator:`esp_pm_lock_type_t::ESP_PM_NO_LIGHT_SLEEP`. Whenever the DAC is converting (i.e., DMA or cosine wave generator is working), the driver guarantees that the power management lock is acquired after calling :cpp:func:`dac_continuous_enable`. Likewise, the driver will release the lock when :cpp:func:`dac_continuous_disable` is called.
|
||||
|
||||
.. _dac-iram-safe:
|
||||
|
||||
IRAM Safe
|
||||
^^^^^^^^^
|
||||
|
||||
@@ -98,7 +100,7 @@ All the public DAC APIs are guaranteed to be thread safe by the driver, which me
|
||||
Kconfig Options
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
- :ref:`CONFIG_DAC_ISR_IRAM_SAFE` controls whether the default ISR handler can work when cache is disabled. See `IRAM Safe <#iram-safe>`__ for more information.
|
||||
- :ref:`CONFIG_DAC_ISR_IRAM_SAFE` controls whether the default ISR handler can work when cache is disabled. See :ref:`dac-iram-safe` for more information.
|
||||
- :ref:`CONFIG_DAC_ENABLE_DEBUG_LOG` is used to enable the debug log output. Enable this option increases the firmware binary size.
|
||||
|
||||
.. only:: esp32
|
||||
|
||||
@@ -58,13 +58,15 @@ Functional Overview
|
||||
|
||||
The I2C driver offers following services:
|
||||
|
||||
- `Resource Allocation <#resource-allocation>`__ - covers how to allocate I2C bus with properly set of configurations. It also covers how to recycle the resources when they finished working.
|
||||
- `I2C Master Controller <#i2c-master-controller>`__ - covers behavior of I2C master controller. Introduce data transmit, data receive, and data transmit and receive.
|
||||
- `I2C Slave Controller <#i2c-slave-controller>`__ - covers behavior of I2C slave controller. Involve data transmit and data receive.
|
||||
- `Power Management <#power-management>`__ - describes how different source clock will affect power consumption.
|
||||
- `IRAM Safe <#iram-safe>`__ - describes tips on how to make the I2C interrupt work better along with a disabled cache.
|
||||
- `Thread Safety <#thread-safety>`__ - lists which APIs are guaranteed to be thread safe by the driver.
|
||||
- `Kconfig Options <#kconfig-options>`__ - lists the supported Kconfig options that can bring different effects to the driver.
|
||||
- :ref:`i2c-resource-allocation` - covers how to allocate I2C bus with properly set of configurations. It also covers how to recycle the resources when they finished working.
|
||||
- :ref:`i2c-master-controller` - covers behavior of I2C master controller. Introduce data transmit, data receive, and data transmit and receive.
|
||||
- :ref:`i2c-slave-controller` - covers behavior of I2C slave controller. Involve data transmit and data receive.
|
||||
- :ref:`i2c-power-management` - describes how different source clock will affect power consumption.
|
||||
- :ref:`i2c-iram-safe` - describes tips on how to make the I2C interrupt work better along with a disabled cache.
|
||||
- :ref:`i2c-thread-safety` - lists which APIs are guaranteed to be thread safe by the driver.
|
||||
- :ref:`i2c-kconfig-options` - lists the supported Kconfig options that can bring different effects to the driver.
|
||||
|
||||
.. _i2c-resource-allocation:
|
||||
|
||||
Resource Allocation
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
@@ -87,7 +89,7 @@ I2C master bus requires the configuration that specified by :cpp:type:`i2c_maste
|
||||
- :cpp:member:`i2c_master_bus_config_t::i2c_port` sets the I2C port used by the controller.
|
||||
- :cpp:member:`i2c_master_bus_config_t::sda_io_num` sets the GPIO number for the serial data bus (SDA).
|
||||
- :cpp:member:`i2c_master_bus_config_t::scl_io_num` sets the GPIO number for the serial clock bus (SCL).
|
||||
- :cpp:member:`i2c_master_bus_config_t::clk_source` selects the source clock for I2C bus. The available clocks are listed in :cpp:type:`i2c_clock_source_t`. For the effect on power consumption of different clock source, please refer to `Power Management <#power-management>`__ section.
|
||||
- :cpp:member:`i2c_master_bus_config_t::clk_source` selects the source clock for I2C bus. The available clocks are listed in :cpp:type:`i2c_clock_source_t`. For the effect on power consumption of different clock source, please refer to :ref:`i2c-power-management` section.
|
||||
- :cpp:member:`i2c_master_bus_config_t::glitch_ignore_cnt` sets the glitch period of master bus, if the glitch period on the line is less than this value, it can be filtered out, typically value is 7.
|
||||
- :cpp:member:`i2c_master_bus_config_t::intr_priority` sets the priority of the interrupt. If set to ``0`` , then the driver will use a interrupt with low or medium priority (priority level may be one of 1, 2 or 3), otherwise use the priority indicated by :cpp:member:`i2c_master_bus_config_t::intr_priority`. Please use the number form (1, 2, 3) , not the bitmask form ((1<<1), (1<<2), (1<<3)).
|
||||
- :cpp:member:`i2c_master_bus_config_t::trans_queue_depth` sets the depth of internal transfer queue. Only valid in asynchronous transaction.
|
||||
@@ -200,7 +202,7 @@ I2C slave requires the configuration specified by :cpp:type:`i2c_slave_config_t`
|
||||
- :cpp:member:`i2c_slave_config_t::i2c_port` sets the I2C port used by the controller.
|
||||
- :cpp:member:`i2c_slave_config_t::sda_io_num` sets the GPIO number for serial data bus (SDA).
|
||||
- :cpp:member:`i2c_slave_config_t::scl_io_num` sets the GPIO number for serial clock bus (SCL).
|
||||
- :cpp:member:`i2c_slave_config_t::clk_source` selects the source clock for I2C bus. The available clocks are listed in :cpp:type:`i2c_clock_source_t`. For the effect on power consumption of different clock source, please refer to `Power Management <#power-management>`__ section.
|
||||
- :cpp:member:`i2c_slave_config_t::clk_source` selects the source clock for I2C bus. The available clocks are listed in :cpp:type:`i2c_clock_source_t`. For the effect on power consumption of different clock source, please refer to :ref:`i2c-power-management` section.
|
||||
- :cpp:member:`i2c_slave_config_t::send_buf_depth` sets the sending software buffer length.
|
||||
- :cpp:member:`i2c_slave_config_t::receive_buf_depth` sets the receiving software buffer length.
|
||||
- :cpp:member:`i2c_slave_config_t::intr_priority` sets the priority of the interrupt. If set to ``0`` , then the driver will use a interrupt with low or medium priority (priority level may be one of 1, 2 or 3), otherwise use the priority indicated by :cpp:member:`i2c_slave_config_t::intr_priority`. Please use the number form (1, 2, 3), instead of the bitmask form ((1<<1), (1<<2), (1<<3)). Please pay attention that once the interrupt priority is set, it cannot be changed until :cpp:func:`i2c_del_slave_device` is called.
|
||||
@@ -231,6 +233,7 @@ Uninstall I2C slave device
|
||||
|
||||
If a previously installed I2C bus is no longer needed, it's recommended to recycle the resource by calling :cpp:func:`i2c_del_slave_device`, so that to release the underlying hardware.
|
||||
|
||||
.. _i2c-master-controller:
|
||||
|
||||
I2C Master Controller
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
@@ -484,6 +487,8 @@ The principle of read operations is the same as that of write operations. Note t
|
||||
|
||||
i2c_master_execute_defined_operations(dev_handle, i2c_ops, sizeof(i2c_ops) / sizeof(i2c_operation_job_t), -1);
|
||||
|
||||
.. _i2c-slave-controller:
|
||||
|
||||
I2C Slave Controller
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -613,6 +618,8 @@ I2C slave event callbacks are listed in the :cpp:type:`i2c_slave_event_callbacks
|
||||
- :cpp:member:`i2c_slave_event_callbacks_t::on_request` sets a callback function for request event.
|
||||
- :cpp:member:`i2c_slave_event_callbacks_t::on_receive` sets a callback function for receive event. The function prototype is declared in :cpp:type:`i2c_slave_received_callback_t`.
|
||||
|
||||
.. _i2c-power-management:
|
||||
|
||||
Power Management
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -630,6 +637,8 @@ Power Management
|
||||
|
||||
If the controller clock source is selected to :cpp:enumerator:`I2C_CLK_SRC_XTAL`, then the driver won't install power management lock for it, which is more suitable for a low power application as long as the source clock can still provide sufficient resolution.
|
||||
|
||||
.. _i2c-iram-safe:
|
||||
|
||||
IRAM Safe
|
||||
^^^^^^^^^
|
||||
|
||||
@@ -643,6 +652,8 @@ There's a Kconfig option :ref:`CONFIG_I2C_ISR_IRAM_SAFE` that will:
|
||||
|
||||
This will allow the interrupt to run while the cache is disabled but will come at the cost of increased IRAM consumption.
|
||||
|
||||
.. _i2c-thread-safety:
|
||||
|
||||
Thread Safety
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
@@ -662,10 +673,12 @@ I2C slave operation functions are also guaranteed to be thread safe by bus opera
|
||||
|
||||
Other functions are not guaranteed to be thread-safe. Thus, you should avoid calling them in different tasks without mutex protection.
|
||||
|
||||
.. _i2c-kconfig-options:
|
||||
|
||||
Kconfig Options
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
- :ref:`CONFIG_I2C_ISR_IRAM_SAFE` controls whether the default ISR handler can work when cache is disabled, see also `IRAM Safe <#iram-safe>`__ for more information.
|
||||
- :ref:`CONFIG_I2C_ISR_IRAM_SAFE` controls whether the default ISR handler can work when cache is disabled, see also :ref:`i2c-iram-safe` for more information.
|
||||
- :ref:`CONFIG_I2C_ENABLE_DEBUG_LOG` is used to enable the debug log at the cost of increased firmware binary size.
|
||||
|
||||
Application Examples
|
||||
|
||||
@@ -296,6 +296,8 @@ To satisfy the high quality audio requirement, following advanced APIs are provi
|
||||
- :cpp:func:`i2s_channel_preload_data`: Preloading audio data into the I2S internal cache, enabling the TX channel to immediately send data upon activation, thereby reducing the initial audio output delay.
|
||||
- :cpp:func:`i2s_channel_tune_rate`: Dynamically fine-tuning the audio rate at runtime to match the speed of the audio data producer and consumer, thereby preventing the accumulation or shortage of intermediate buffered data that caused by rate mismatches.
|
||||
|
||||
.. _i2s-iram-safe:
|
||||
|
||||
IRAM Safe
|
||||
^^^^^^^^^
|
||||
|
||||
@@ -317,7 +319,7 @@ All the public I2S APIs are guaranteed to be thread safe by the driver, which me
|
||||
Kconfig Options
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
- :ref:`CONFIG_I2S_ISR_IRAM_SAFE` controls whether the default ISR handler can work when the cache is disabled. See `IRAM Safe <#iram-safe>`__ for more information.
|
||||
- :ref:`CONFIG_I2S_ISR_IRAM_SAFE` controls whether the default ISR handler can work when the cache is disabled. See :ref:`i2s-iram-safe` for more information.
|
||||
- :ref:`CONFIG_I2S_ENABLE_DEBUG_LOG` is used to enable the debug log output. Enable this option increases the firmware binary size.
|
||||
|
||||
Application Example
|
||||
|
||||
@@ -17,15 +17,17 @@ Functional Overview
|
||||
|
||||
This document covers the following sections:
|
||||
|
||||
- `Resource Allocation <#resource-allocation>`__ - covers how to allocate JPEG resources with properly set of configurations. It also covers how to recycle the resources when they finished working.
|
||||
- `Finite State Machine <#finite-state-machine>`__ - covers JPEG workflow. Introduce how jpeg driver uses internal resources and its software process.
|
||||
- `JPEG Decoder Engine <#jpeg-decoder-engine>`__ - covers behavior of JPEG decoder engine. Introduce how to use decoder engine functions to decode an image (from jpg format to raw format).
|
||||
- `JPEG Encoder Engine <#jpeg-encoder-engine>`__ - covers behavior of JPEG encoder engine. Introduce how to use encoder engine functions to encode an image (from raw format to jpg format).
|
||||
- `Performance Overview <#performance-overview>`__ - covers encoder and decoder performance.
|
||||
- `Pixel Storage Layout for Different Color Formats <#pixel-storage-layout-for-different-color-formats>`__ - covers color space order overview required in this JPEG decoder and encoder.
|
||||
- `Thread Safety <#thread-safety>`__ - lists which APIs are guaranteed to be thread safe by the driver.
|
||||
- `Power Management <#power-management>`__ - describes how JPEG driver would be affected by power consumption.
|
||||
- `Kconfig Options <#kconfig-options>`__ - lists the supported Kconfig options that can bring different effects to the driver.
|
||||
- :ref:`jpeg-resource-allocation` - covers how to allocate JPEG resources with properly set of configurations. It also covers how to recycle the resources when they finished working.
|
||||
- :ref:`jpeg-finite-state-machine` - covers JPEG workflow. Introduce how jpeg driver uses internal resources and its software process.
|
||||
- :ref:`jpeg-decoder-engine` - covers behavior of JPEG decoder engine. Introduce how to use decoder engine functions to decode an image (from jpg format to raw format).
|
||||
- :ref:`jpeg-encoder-engine` - covers behavior of JPEG encoder engine. Introduce how to use encoder engine functions to encode an image (from raw format to jpg format).
|
||||
- :ref:`jpeg-performance-overview` - covers encoder and decoder performance.
|
||||
- :ref:`jpeg-pixel-storage-layout` - covers color space order overview required in this JPEG decoder and encoder.
|
||||
- :ref:`jpeg-thread-safety` - lists which APIs are guaranteed to be thread safe by the driver.
|
||||
- :ref:`jpeg-power-management` - describes how JPEG driver would be affected by power consumption.
|
||||
- :ref:`jpeg-kconfig-options` - lists the supported Kconfig options that can bring different effects to the driver.
|
||||
|
||||
.. _jpeg-resource-allocation:
|
||||
|
||||
Resource Allocation
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
@@ -85,6 +87,8 @@ If a previously installed JPEG engine is no longer needed, it's recommended to r
|
||||
|
||||
ESP_ERROR_CHECK(jpeg_del_encoder_engine(encoder_engine));
|
||||
|
||||
.. _jpeg-finite-state-machine:
|
||||
|
||||
Finite State Machine
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -96,6 +100,8 @@ The JPEG driver usage of hardware resources and its process workflow are shown i
|
||||
|
||||
JPEG finite state machine
|
||||
|
||||
.. _jpeg-decoder-engine:
|
||||
|
||||
JPEG Decoder Engine
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -158,6 +164,8 @@ There are some tips that can help you use this driver more accurately:
|
||||
|
||||
3. The width and height of output picture would be 16 bytes aligned if original picture is compressed by YUV420 or YUV422. For example, if the input picture is 1080*1920, the output picture will be 1088*1920. That is the restriction of jpeg protocol. Please provide sufficient output buffer memory.
|
||||
|
||||
.. _jpeg-encoder-engine:
|
||||
|
||||
JPEG Encoder Engine
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -213,6 +221,8 @@ There are some tips that can help you use this driver more accurately:
|
||||
|
||||
3. The compression ratio depends on the chosen `image_quality` and the content of the image itself. Generally, a higher `image_quality` value obviously results in better image quality but a smaller compression ratio. As for the image content, it is hard to give any specific guidelines, so this question is out of the scope of this document. Generally, the baseline JPEG compression ratio can vary from 40:1 to 10:1. Please take the actual situation into account.
|
||||
|
||||
.. _jpeg-performance-overview:
|
||||
|
||||
Performance Overview
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -344,6 +354,8 @@ JPEG encoder performance
|
||||
.. [#] Format of Original Image
|
||||
.. [#] Down sampling method
|
||||
|
||||
.. _jpeg-pixel-storage-layout:
|
||||
|
||||
Pixel Storage Layout for Different Color Formats
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -420,11 +432,15 @@ In the following picture, each small block means one byte.
|
||||
|
||||
YUV420 pixel order
|
||||
|
||||
.. _jpeg-thread-safety:
|
||||
|
||||
Thread Safety
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
The factory function :cpp:func:`jpeg_new_decoder_engine`, :cpp:func:`jpeg_decoder_get_info`, :cpp:func:`jpeg_decoder_process`, and :cpp:func:`jpeg_del_decoder_engine` are guaranteed to be thread safe by the driver, which means, user can call them from different RTOS tasks without protection by extra locks.
|
||||
|
||||
.. _jpeg-power-management:
|
||||
|
||||
Power Management
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
@@ -432,6 +448,8 @@ When power management is enabled (i.e., :ref:`CONFIG_PM_ENABLE` is set), the sys
|
||||
|
||||
Whenever the user is decoding or encoding via JPEG (i.e., calling :cpp:func:`jpeg_encoder_process` or :cpp:func:`jpeg_decoder_process`), the driver guarantees that the power management lock is acquired by setting it to :cpp:enumerator:`esp_pm_lock_type_t::ESP_PM_CPU_FREQ_MAX`. Once the encoding or decoding is finished, the driver releases the lock and the system can enter Light-sleep.
|
||||
|
||||
.. _jpeg-kconfig-options:
|
||||
|
||||
Kconfig Options
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
|
||||
@@ -107,6 +107,8 @@ The :cpp:func:`mcpwm_new_operator` will return a pointer to the allocated operat
|
||||
|
||||
On the contrary, calling :cpp:func:`mcpwm_del_operator` function will free the allocated operator object.
|
||||
|
||||
.. _mcpwm-comparators:
|
||||
|
||||
MCPWM Comparators
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -138,6 +140,8 @@ The :cpp:func:`mcpwm_new_generator` will return a pointer to the allocated gener
|
||||
|
||||
On the contrary, calling the :cpp:func:`mcpwm_del_generator` function will free the allocated generator object.
|
||||
|
||||
.. _mcpwm-faults:
|
||||
|
||||
MCPWM Faults
|
||||
~~~~~~~~~~~~
|
||||
|
||||
@@ -159,6 +163,8 @@ The :cpp:func:`mcpwm_new_soft_fault` function will return a pointer to the alloc
|
||||
|
||||
On the contrary, calling the :cpp:func:`mcpwm_del_fault` function will free the allocated fault object, this function works for both software and GPIO fault.
|
||||
|
||||
.. _mcpwm-sync-sources:
|
||||
|
||||
MCPWM Sync Sources
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -186,6 +192,8 @@ Last but not least, to allocate a software sync source, you can call the :cpp:fu
|
||||
|
||||
On the contrary, calling the :cpp:func:`mcpwm_del_sync_src` function will free the allocated sync source object. This function works for all types of sync sources.
|
||||
|
||||
.. _mcpwm-capture-timer-and-channels:
|
||||
|
||||
MCPWM Capture Timer and Channels
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
@@ -257,7 +265,9 @@ The callback functions above are called within the ISR context, so they should *
|
||||
|
||||
The parameter ``user_data`` of the :cpp:func:`mcpwm_timer_register_event_callbacks` function is used to save your own context. It is passed to each callback function directly.
|
||||
|
||||
This function will lazy the install interrupt service for the MCPWM timer without enabling it. It is only allowed to be called before :cpp:func:`mcpwm_timer_enable`, otherwise the :c:macro:`ESP_ERR_INVALID_STATE` error will be returned. See also `Enable and Disable timer <#enable-and-disable-timer>`__ for more information.
|
||||
This function will lazy the install interrupt service for the MCPWM timer without enabling it. It is only allowed to be called before :cpp:func:`mcpwm_timer_enable`, otherwise the :c:macro:`ESP_ERR_INVALID_STATE` error will be returned. See also :ref:`mcpwm-enable-and-disable-timer` for more information.
|
||||
|
||||
.. _mcpwm-enable-and-disable-timer:
|
||||
|
||||
Enable and Disable Timer
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@@ -266,7 +276,7 @@ Before doing IO control to the timer, you need to enable the timer first, by cal
|
||||
|
||||
* switches the timer state from **init** to **enable**.
|
||||
* enables the interrupt service if it has been lazy installed by :cpp:func:`mcpwm_timer_register_event_callbacks`.
|
||||
* acquire a proper power management lock if a specific clock source (e.g., PLL_160M clock) is selected. See also `Power management <#power-management>`__ for more information.
|
||||
* acquire a proper power management lock if a specific clock source (e.g., PLL_160M clock) is selected. See also :ref:`mcpwm-power-management` for more information.
|
||||
|
||||
On the contrary, calling :cpp:func:`mcpwm_timer_disable` will put the timer driver back to the **init** state, disable the interrupt service and release the power management lock.
|
||||
|
||||
@@ -337,7 +347,7 @@ Set Generator Action on Compare Event
|
||||
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.
|
||||
- :cpp:member:`mcpwm_gen_compare_event_action_t::comparator` specifies the comparator handle. See :ref:`mcpwm-comparators` for how to allocate a comparator.
|
||||
- :cpp:member:`mcpwm_gen_compare_event_action_t::action` specifies the generator action to be taken. The supported actions are listed in :cpp:type:`mcpwm_generator_action_t`.
|
||||
|
||||
There is a helper macro :c:macro:`MCPWM_GEN_COMPARE_EVENT_ACTION` to simplify the construction of a compare event action entry.
|
||||
@@ -348,7 +358,7 @@ Set Generator Action on Fault Event
|
||||
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.
|
||||
- :cpp:member:`mcpwm_gen_fault_event_action_t::fault` specifies the fault used for the trigger. See :ref:`mcpwm-faults` for how to allocate a fault.
|
||||
- :cpp:member:`mcpwm_gen_fault_event_action_t::action` specifies the generator action to be taken. The supported actions are listed in :cpp:type:`mcpwm_generator_action_t`.
|
||||
|
||||
When no free trigger slot is left in the operator to which the generator belongs, this function will return the :c:macro:`ESP_ERR_NOT_FOUND` error. [1]_
|
||||
@@ -363,7 +373,7 @@ Set Generator Action on Sync Event
|
||||
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.
|
||||
- :cpp:member:`mcpwm_gen_sync_event_action_t::sync` specifies the sync source used for the trigger. See :ref:`mcpwm-sync-sources` for how to allocate a sync source.
|
||||
- :cpp:member:`mcpwm_gen_sync_event_action_t::action` specifies the generator action to be taken. The supported actions are listed in :cpp:type:`mcpwm_generator_action_t`.
|
||||
|
||||
When no free trigger slot is left in the operator to which the generator belongs, this function will return the :c:macro:`ESP_ERR_NOT_FOUND` error. [1]_
|
||||
@@ -503,7 +513,7 @@ Dual Edge Symmetric Waveform - Complementary
|
||||
Dead Time
|
||||
^^^^^^^^^
|
||||
|
||||
In power electronics, the rectifier and inverter are commonly used. This requires the use of a rectifier bridge and an inverter bridge. Each bridge arm has two power electronic devices, such as MOSFET, IGBT, etc. The two MOSFETs on the same arm can not conduct at the same time, otherwise there will be a short circuit. The fact is that, although the PWM wave shows it is turning off the switch, the MOSFET still needs a small time window to make that happen. This requires an extra delay to be added to the existing PWM wave generated by setting `Generator Actions on Events <#generator-actions-on-events>`__.
|
||||
In power electronics, the rectifier and inverter are commonly used. This requires the use of a rectifier bridge and an inverter bridge. Each bridge arm has two power electronic devices, such as MOSFET, IGBT, etc. The two MOSFETs on the same arm can not conduct at the same time, otherwise there will be a short circuit. The fact is that, although the PWM wave shows it is turning off the switch, the MOSFET still needs a small time window to make that happen. This requires an extra delay to be added to the existing PWM wave generated by setting :ref:`mcpwm-generator-actions-on-events`.
|
||||
|
||||
The dead time driver works like a **decorator**. This is also reflected in the function parameters of :cpp:func:`mcpwm_generator_set_dead_time`, where it takes the primary generator handle (``in_generator``), and returns a new generator (``out_generator``) after applying the dead time. Please note, if the ``out_generator`` and ``in_generator`` are the same, it means you are adding the time delay to the PWM waveform in an "in-place" fashion. In turn, if the ``out_generator`` and ``in_generator`` are different, it means you are deriving a new PWM waveform from the existing ``in_generator``.
|
||||
|
||||
@@ -530,7 +540,7 @@ Dead time specific configuration is listed in the :cpp:type:`mcpwm_dead_time_con
|
||||
|
||||
.. note::
|
||||
|
||||
It is also possible to generate the required dead time by setting `Generator Actions on Events <#generator-actions-on-events>`__, especially by controlling edge placement using different comparators. However, if the more classical edge delay-based dead time with polarity control is required, then the dead time submodule should be used.
|
||||
It is also possible to generate the required dead time by setting :ref:`mcpwm-generator-actions-on-events`, especially by controlling edge placement using different comparators. However, if the more classical edge delay-based dead time with polarity control is required, then the dead time submodule should be used.
|
||||
|
||||
|
||||
.. _mcpwm-classical-pwm-waveforms-and-dead-time-configurations:
|
||||
@@ -845,7 +855,7 @@ Synchronization
|
||||
|
||||
When a sync signal is taken by the MCPWM timer, the timer will be forced into a predefined **phase**, where the phase is determined by count value and count direction. You can set the sync phase by calling :cpp:func:`mcpwm_timer_set_phase_on_sync`. The sync phase configuration is defined in :cpp:type:`mcpwm_timer_sync_phase_config_t` structure:
|
||||
|
||||
- :cpp:member:`mcpwm_timer_sync_phase_config_t::sync_src` sets the sync signal source. See `MCPWM Sync Sources <#mcpwm-sync-sources>`__ for how to create a sync source object. Specifically, if this is set to ``NULL``, the driver will disable the sync feature for the MCPWM timer.
|
||||
- :cpp:member:`mcpwm_timer_sync_phase_config_t::sync_src` sets the sync signal source. See :ref:`mcpwm-sync-sources` for how to create a sync source object. Specifically, if this is set to ``NULL``, the driver will disable the sync feature for the MCPWM timer.
|
||||
- :cpp:member:`mcpwm_timer_sync_phase_config_t::count_value` sets the count value to load when the sync signal is taken.
|
||||
- :cpp:member:`mcpwm_timer_sync_phase_config_t::direction` sets the count direction when the sync signal is taken.
|
||||
|
||||
@@ -853,9 +863,9 @@ When a sync signal is taken by the MCPWM timer, the timer will be forced into a
|
||||
|
||||
When the MCPWM timer is working in :cpp:enumerator:`MCPWM_TIMER_COUNT_MODE_UP_DOWN` mode, special attention needs to be taken. In this mode, counter range ``[0 -> peak-1]`` belongs to the **increment** phase, and counter range ``[peak -> 1]`` belongs to the **decrement** phase. Thus if you set the :cpp:member:`mcpwm_timer_sync_phase_config_t::count_value` to zero, you may also want to set the :cpp:member:`mcpwm_timer_sync_phase_config_t::direction` to :cpp:enumerator:`MCPWM_TIMER_DIRECTION_UP`. Otherwise, the timer will be continue with the decrement phase, and the count value underflows to ``peak``.
|
||||
|
||||
Likewise, the `MCPWM Capture Timer <#mcpwm-capture-timer-and-channels>`__ can be synced as well. You can set the sync phase for the capture timer by calling :cpp:func:`mcpwm_capture_timer_set_phase_on_sync`. The sync phase configuration is defined in :cpp:type:`mcpwm_capture_timer_sync_phase_config_t` structure:
|
||||
Likewise, the :ref:`MCPWM Capture Timer <mcpwm-capture-timer-and-channels>` can be synced as well. You can set the sync phase for the capture timer by calling :cpp:func:`mcpwm_capture_timer_set_phase_on_sync`. The sync phase configuration is defined in :cpp:type:`mcpwm_capture_timer_sync_phase_config_t` structure:
|
||||
|
||||
- :cpp:member:`mcpwm_capture_timer_sync_phase_config_t::sync_src` sets the sync signal source. See `MCPWM Sync Sources <#mcpwm-sync-sources>`__ for how to create a sync source object. Specifically, if this is set to ``NULL``, the driver will disable the sync feature for the MCPWM capture timer.
|
||||
- :cpp:member:`mcpwm_capture_timer_sync_phase_config_t::sync_src` sets the sync signal source. See :ref:`mcpwm-sync-sources` for how to create a sync source object. Specifically, if this is set to ``NULL``, the driver will disable the sync feature for the MCPWM capture timer.
|
||||
- :cpp:member:`mcpwm_capture_timer_sync_phase_config_t::count_value` sets the count value to load when the sync signal is taken.
|
||||
- :cpp:member:`mcpwm_capture_timer_sync_phase_config_t::direction` sets the count direction when the sync signal is taken. Note that, different from MCPWM Timer, the capture timer can only support one count direction: :cpp:enumerator:`MCPWM_TIMER_DIRECTION_UP`.
|
||||
|
||||
@@ -906,7 +916,7 @@ The basic functionality of MCPWM capture is to record the time when any pulse ed
|
||||
|
||||
MCPWM BLDC with Hall Sensor
|
||||
|
||||
The capture timer is usually connected to several capture channels. Please refer to `MCPWM Capture Timer and Channels <#mcpwm-capture-timer-and-channels>`__ for more information about resource allocation.
|
||||
The capture timer is usually connected to several capture channels. Please refer to :ref:`mcpwm-capture-timer-and-channels` for more information about resource allocation.
|
||||
|
||||
Register Capture Event Callbacks
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@@ -934,7 +944,7 @@ Enable and Disable Capture Timer
|
||||
Before doing IO control to the capture timer, you need to enable the timer first, by calling :cpp:func:`mcpwm_capture_timer_enable`. Internally, this function:
|
||||
|
||||
* switches the capture timer state from **init** to **enable**.
|
||||
* acquires a proper power management lock if a specific clock source (e.g., APB clock) is selected. See also `Power management <#power-management>`__ for more information.
|
||||
* acquires a proper power management lock if a specific clock source (e.g., APB clock) is selected. See also :ref:`mcpwm-power-management` for more information.
|
||||
|
||||
On the contrary, calling :cpp:func:`mcpwm_capture_timer_disable` will put the timer driver back to **init** state, and release the power management lock.
|
||||
|
||||
@@ -1030,7 +1040,7 @@ The following function is allowed to run under the ISR context, as the driver us
|
||||
- :cpp:func:`mcpwm_comparator_set_compare_value`
|
||||
- :cpp:func:`mcpwm_timer_set_period`
|
||||
|
||||
Other functions that are not related to `Resource Allocation and Initialization <#resource-allocation-and-initialization>`__, are not thread-safe. Thus, you should avoid calling them in different tasks without mutex protection.
|
||||
Other functions that are not related to :ref:`mcpwm-resource-allocation-and-initialization`, are not thread-safe. Thus, you should avoid calling them in different tasks without mutex protection.
|
||||
|
||||
|
||||
.. _mcpwm-kconfig-options:
|
||||
|
||||
@@ -657,7 +657,7 @@ API Reference
|
||||
|
||||
|
||||
.. [1]
|
||||
Different ESP chip series might have different numbers of RMT channels. Please refer to [`TRM <{IDF_TARGET_TRM_EN_URL}#rmt>`__] for details. The driver does not forbid you from applying for more RMT channels, but it returns an error when there are no hardware resources available. Please always check the return value when doing `Resource Allocation <#resource-allocation>`__.
|
||||
Different ESP chip series might have different numbers of RMT channels. Please refer to [`TRM <{IDF_TARGET_TRM_EN_URL}#rmt>`__] for details. The driver does not forbid you from applying for more RMT channels, but it returns an error when there are no hardware resources available. Please always check the return value when doing :ref:`rmt-resource-allocation`.
|
||||
|
||||
.. [2]
|
||||
The callback function, e.g., :cpp:member:`rmt_tx_event_callbacks_t::on_trans_done`, and the functions invoked by itself should also reside in IRAM, users need to take care of this by themselves.
|
||||
|
||||
Reference in New Issue
Block a user