mirror of
https://github.com/espressif/esp-idf.git
synced 2024-10-05 20:47:46 -04:00
doc: add api reference for etm driver
This commit is contained in:
morris
parent
4186bd041c
commit
4019e307f1
@ -1,7 +1,77 @@
|
||||
## `esp_hw_support` ##
|
||||
# `esp_hw_support` (G1 component)
|
||||
|
||||
This component contains hardware-related operations for supporting the system. These operations
|
||||
are one level above that of `hal` in that these(1) use system services such as memory allocation, logging, scheduling
|
||||
or (2) may be multi-step operations involving/affecting multiple parts of the SoC.
|
||||
This component contains hardware-related operations for supporting the system. These operations are one level above that of `hal` in that:
|
||||
|
||||
1. it uses system services such as memory allocation, logging, scheduling
|
||||
2. it may be multi-step operations involving/affecting multiple parts of the SoC
|
||||
3. it offers a service for other components vary from multiple layers (G1, G2 and G3) of ESP-IDF
|
||||
|
||||
Implementations that don't fit other components cleanly, but are not worth creating a new component for (yet) may also be placed here as long as they don't pull dependencies other than the core system components.
|
||||
|
||||
## Event-Task Service (esp_etm)
|
||||
|
||||
### esp_etm driver design
|
||||
|
||||
`esp_etm` driver is divided into two parts:
|
||||
|
||||
* The **core** driver, which focuses on ETM channel allocation and offers APIs to connect the channel with ETM tasks and ETM events that come from other peripherals.
|
||||
* **Peripheral** side extensions, e.g. GPTimer support generating different kinds of ETM events, and accept multiple ETM tasks. These extensions are implemented in the peripheral driver, and can be located in different components. Usually, the task and event extensions will simply inherit the interface that defined in the core driver.
|
||||
|
||||
See the following class diagram, we take the GPIO and GPTimer as the example to illustrate the architecture of `esp_etm` driver.
|
||||
|
||||
```mermaid
|
||||
classDiagram
|
||||
esp_etm_channel_t "1" --> "1" esp_etm_event_t : Has
|
||||
esp_etm_channel_t "1" --> "1" esp_etm_task_t : Has
|
||||
class esp_etm_channel_t {
|
||||
-int chan_id
|
||||
-esp_etm_event_t event
|
||||
-esp_etm_task_t task
|
||||
+enable() esp_err_t
|
||||
+disable() esp_err_t
|
||||
+connect(event, task) esp_err_t
|
||||
+dump() esp_err_t
|
||||
}
|
||||
|
||||
class esp_etm_event_t {
|
||||
<<interface>>
|
||||
#int event_id
|
||||
#etm_trigger_peripheral_t trig_periph
|
||||
#del() esp_err_t
|
||||
}
|
||||
|
||||
class esp_etm_task_t {
|
||||
<<interface>>
|
||||
#int task_id
|
||||
#etm_trigger_peripheral_t trig_periph
|
||||
#del() esp_err_t
|
||||
}
|
||||
|
||||
gpio_etm_event_t --|> esp_etm_event_t : Inheritance
|
||||
class gpio_etm_event_t {
|
||||
-int chan_id
|
||||
+bind_gpio(gpio_num_t gpio) esp_err_t
|
||||
}
|
||||
|
||||
gpio_etm_task_t --|> esp_etm_task_t : Inheritance
|
||||
class gpio_etm_task_t {
|
||||
-int chan_id
|
||||
+add_gpio(gpio_num) esp_err_t
|
||||
+rm_gpio(gpio_num) esp_err_t
|
||||
}
|
||||
|
||||
gptimer_t "1" --> "1..*" gptimer_etm_event_t : Has
|
||||
gptimer_t "1" --> "1..*" gptimer_etm_task_t : Has
|
||||
class gptimer_t {
|
||||
-gptimer_etm_event_t[] events
|
||||
-gptimer_etm_task_t[] tasks
|
||||
}
|
||||
|
||||
gptimer_etm_event_t --|> esp_etm_event_t : Inheritance
|
||||
class gptimer_etm_event_t {
|
||||
}
|
||||
|
||||
gptimer_etm_task_t --|> esp_etm_task_t : Inheritance
|
||||
class gptimer_etm_task_t {
|
||||
}
|
||||
```
|
||||
|
||||
22
docs/_static/diagrams/etm/etm_channel.diag
vendored
Normal file
22
docs/_static/diagrams/etm/etm_channel.diag
vendored
Normal file
@ -0,0 +1,22 @@
|
||||
blockdiag etm_channel {
|
||||
default_fontsize = 12;
|
||||
node_width = 200;
|
||||
node_height = 40;
|
||||
|
||||
event_gpio [label = "GPIO Event", shape = "beginpoint", stacked];
|
||||
other_events [shape = "dots"];
|
||||
event_others [label = "Periph Event", shape = "beginpoint", stacked];
|
||||
channels0 [label = "Channel-N", stacked];
|
||||
channels1 [label = "Channel-M", stacked];
|
||||
other_channels [shape = "dots"];
|
||||
task_gpio [label = "GPIO Task", shape = "endpoint", stacked];
|
||||
task_others [label = "Other Tasks", shape = "endpoint", stacked];
|
||||
other_tasks [shape = "dots"];
|
||||
|
||||
event_gpio -> channels0;
|
||||
event_others -> channels1;
|
||||
other_events -> other_channels;
|
||||
channels0 -> task_gpio;
|
||||
channels1 -> task_others;
|
||||
other_channels -> other_tasks;
|
||||
}
|
||||
@ -80,6 +80,8 @@ RMT_DOCS = ['api-reference/peripherals/rmt.rst']
|
||||
|
||||
DAC_DOCS = ['api-reference/peripherals/dac.rst']
|
||||
|
||||
ETM_DOCS = ['api-reference/peripherals/etm.rst']
|
||||
|
||||
TEMP_SENSOR_DOCS = ['api-reference/peripherals/temp_sensor.rst']
|
||||
|
||||
TOUCH_SENSOR_DOCS = ['api-reference/peripherals/touch_pad.rst']
|
||||
@ -164,6 +166,7 @@ conditional_include_dict = {'SOC_BT_SUPPORTED':BT_DOCS,
|
||||
'SOC_PCNT_SUPPORTED':PCNT_DOCS,
|
||||
'SOC_RMT_SUPPORTED':RMT_DOCS,
|
||||
'SOC_DAC_SUPPORTED':DAC_DOCS,
|
||||
'SOC_ETM_SUPPORTED':ETM_DOCS,
|
||||
'SOC_TOUCH_SENSOR_SUPPORTED':TOUCH_SENSOR_DOCS,
|
||||
'SOC_ULP_SUPPORTED':ULP_DOCS,
|
||||
'SOC_RISCV_COPROC_SUPPORTED':RISCV_COPROC_DOCS,
|
||||
|
||||
@ -100,7 +100,6 @@ api-reference/peripherals/hmac
|
||||
api-reference/peripherals/usb_device
|
||||
api-reference/peripherals/sdspi_host
|
||||
api-reference/peripherals/dac
|
||||
api-reference/peripherals/gptimer
|
||||
api-reference/peripherals/touch_element
|
||||
api-reference/peripherals/lcd
|
||||
api-reference/peripherals/secure_element
|
||||
|
||||
@ -67,7 +67,10 @@ INPUT = \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/dac_types.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/dedic_gpio.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/gpio.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/gpio_etm.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/gptimer.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/gptimer_etm.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/gptimer_types.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/i2c.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/i2s_common.h \
|
||||
$(PROJECT_PATH)/components/driver/include/driver/i2s_pdm.h \
|
||||
@ -133,6 +136,7 @@ INPUT = \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/esp_chip_info.h \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/esp_cpu.h \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/esp_crc.h \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/esp_etm.h \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/esp_hmac.h \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/esp_intr_alloc.h \
|
||||
$(PROJECT_PATH)/components/esp_hw_support/include/esp_mac.h \
|
||||
@ -160,6 +164,7 @@ INPUT = \
|
||||
$(PROJECT_PATH)/components/esp_system/include/esp_ipc_isr.h \
|
||||
$(PROJECT_PATH)/components/esp_system/include/esp_ipc.h \
|
||||
$(PROJECT_PATH)/components/esp_system/include/esp_system.h \
|
||||
$(PROJECT_PATH)/components/esp_system/include/esp_systick_etm.h \
|
||||
$(PROJECT_PATH)/components/esp_system/include/esp_task_wdt.h \
|
||||
$(PROJECT_PATH)/components/esp_timer/include/esp_timer.h \
|
||||
$(PROJECT_PATH)/components/esp_wifi/include/esp_mesh.h \
|
||||
|
||||
148
docs/en/api-reference/peripherals/etm.rst
Normal file
148
docs/en/api-reference/peripherals/etm.rst
Normal file
@ -0,0 +1,148 @@
|
||||
Event Task Matrix (ETM)
|
||||
=======================
|
||||
|
||||
Introduction
|
||||
------------
|
||||
|
||||
Normally, if a peripheral X needs to notify peripheral Y of a particular event, this could only be done via a CPU interrupt from peripheral X (where the CPU notifies peripheral Y on behalf of peripheral X). However, in time critical applications, the latency introduced by CPU interrupts is non-negligible. The Event Task Matrix (ETM) module allows subset of peripherals to notify each other of events directly (i.e., without CPU intervention). This allows precise (and low latency) synchronization between peripherals, and lessens the CPU's work load (as the CPU no longer needs handle these events).
|
||||
|
||||
.. blockdiag:: /../_static/diagrams/etm/etm_channel.diag
|
||||
:caption: ETM channels Overview
|
||||
:align: center
|
||||
|
||||
The ETM module has multiple programmable channels, they're used to connect a particular **Event** to a particular **Task**. When an event is activated, the ETM channel will trigger the corresponding task automatically. Peripherals that support ETM functionality will provide their or unique set of events and tasks to be connected by the ETM. An ETM channel can connect any event to any task (even looping back an event to a task of on the same peripheral). However, an ETM channel can only connect one event to one task any time (i.e., 1 to 1 relation). If you want to use different events to trigger the same task, you can set up more ETM channels.
|
||||
|
||||
Typically, with the help of ETM module, you can implement features like:
|
||||
|
||||
- Toggle the GPIO when a timer alarm event happens
|
||||
- Start an ADC conversion when a pulse edge is detected on a GPIO
|
||||
|
||||
Functional Overview
|
||||
-------------------
|
||||
|
||||
The following sections of this document cover the typical steps to configure and use the ETM module.
|
||||
|
||||
- :ref:`etm-channel-allocation` - describes how to install and uninstall ETM channel
|
||||
- :ref:`etm-event` - describes how to allocate a new ETM event handle or fetch an existing handle from various peripherals
|
||||
- :ref:`etm-task` - describes how to allocate a new ETM task handle or fetch an existing handle from various peripherals
|
||||
- :ref:`etm-channel-control` - describes common ETM channel control functions
|
||||
- :ref:`etm-thread-safety` - lists which APIs are guaranteed to be thread safe by the driver.
|
||||
- :ref:`etm-kconfig-options` - lists the supported Kconfig options that can be used to make a different effect on driver behavior
|
||||
|
||||
.. _etm-channel-allocation:
|
||||
|
||||
ETM Channel Allocation
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
There're many identical ETM channels in {IDF_TARGET_NAME} [1]_, each channel is represented by :cpp:type:`esp_etm_channel_handle_t` in the software. The ETM core driver manages all available hardware resources in a pool, so that you don't need to care about which channel is in use and which is not. The ETM core driver will allocate a channel for you when you call :cpp:func:`esp_etm_new_channel` and delete it when you call :cpp:func:`esp_etm_del_channel`. All requirements needed for allocating a channel are provided in :cpp:type:`esp_etm_channel_config_t`.
|
||||
|
||||
Before deleting an ETM channel, please disable it by :cpp:func:`esp_etm_channel_disable` in advance or make sure it has not been enabled yet by :cpp:func:`esp_etm_channel_enable`.
|
||||
|
||||
.. _etm-event:
|
||||
|
||||
ETM Event
|
||||
^^^^^^^^^
|
||||
|
||||
ETM Event abstracts the event source and is represented by :cpp:type:`esp_etm_event_handle_t` in the software. ETM event can be generated from a variety of peripherals, thus the way to get the event handle differs from peripherals. When an ETM event is no longer used, you should call :cpp:func:`esp_etm_channel_connect` with a ``NULL`` event handle to disconnect it and then call :cpp:func:`esp_etm_del_event` to free the event resource.
|
||||
|
||||
GPIO Events
|
||||
~~~~~~~~~~~
|
||||
|
||||
GPIO **edge** event is the most common event type, it can be generated by any GPIO pin. You can call :cpp:func:`gpio_new_etm_event` to create a GPIO event handle, with the configurations provided in :cpp:type:`gpio_etm_event_config_t`:
|
||||
|
||||
- :cpp:member:`gpio_etm_event_config_t::edge` decides which edge will trigger the event, supported edge types are listed in the :cpp:type:`gpio_etm_event_edge_t`.
|
||||
|
||||
You need to build a connection between the GPIO ETM event handle and the GPIO number. So you should call :cpp:func:`gpio_etm_event_bind_gpio` afterwards. Please note, only the ETM event handle that created by :cpp:func:`gpio_new_etm_event` can set a GPIO number. Calling this function with other kind of ETM event will return :c:macro:`ESP_ERR_INVALID_ARG` error. Needless to say, this function won't help do the GPIO initialization, you still need to call :cpp:func:`gpio_config` to set the property like direction, pull up/down mode separately.
|
||||
|
||||
Other Peripheral Events
|
||||
~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. list::
|
||||
|
||||
:SOC_SYSTIMER_SUPPORT_ETM: - You can call :cpp:func:`esp_systick_new_etm_alarm_event` to get the ETM event from RTOS Systick, one per CPU core.
|
||||
:SOC_SYSTIMER_SUPPORT_ETM: - Refer to :doc:`ESP Timer </api-reference/system/esp_timer>` for how to get the ETM event handle from esp_timer.
|
||||
:SOC_TIMER_SUPPORT_ETM: - Refer to :doc:`GPTimer </api-reference/peripherals/gptimer>` for how to get the ETM event handle from GPTimer.
|
||||
:SOC_GDMA_SUPPORT_ETM: - Refer to :doc:`Async Memory Copy </api-reference/system/async_memcpy>` for how to get the ETM event handle from async memcpy.
|
||||
|
||||
.. _etm-task:
|
||||
|
||||
ETM Task
|
||||
^^^^^^^^
|
||||
|
||||
ETM Task abstracts the task action and is represented by :cpp:type:`esp_etm_task_handle_t` in the software. ETM task can be assigned to a variety of peripherals, thus the way to get the task handle differs from peripherals. When an ETM task is no longer used, you should call :cpp:func:`esp_etm_channel_connect` with a ``NULL`` task handle to disconnect it and then call :cpp:func:`esp_etm_del_task` to free the task resource.
|
||||
|
||||
GPIO Tasks
|
||||
~~~~~~~~~~
|
||||
|
||||
GPIO task is the most common task type, one GPIO task can even manage multiple GPIOs. When tha task gets activated by the ETM channel, all managed GPIOs can set/clear/toggle at the same time. You can call :cpp:func:`gpio_new_etm_task` to create a GPIO task handle, with the configurations provided in :cpp:type:`gpio_etm_task_config_t`:
|
||||
|
||||
- :cpp:member:`gpio_etm_task_config_t::action` decides what the GPIO action would be taken by the ETM task. Supported actions are listed in the :cpp:type:`gpio_etm_task_action_t`.
|
||||
|
||||
To build a connection between the GPIO ETM task and the GPIO number, you should call :cpp:func:`gpio_etm_task_add_gpio`. You can call this function by several times if you want the task handle to manage more GPIOs. Please note, only the ETM task handle that created by :cpp:func:`gpio_new_etm_task` can manage a GPIO. Calling this function with other kind of ETM task will return :c:macro:`ESP_ERR_INVALID_ARG` error. Needless to say, this function won't help do the GPIO initialization, you still need to call :cpp:func:`gpio_config` to set the property like direction, pull up/down mode separately.
|
||||
|
||||
Before you call :cpp:func:`esp_etm_del_task` to delete the GPIO ETM task, make sure that all previously added GPIOs are removed by :cpp:func:`gpio_etm_task_rm_gpio` in advance.
|
||||
|
||||
Other Peripheral Tasks
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. list::
|
||||
|
||||
:SOC_TIMER_SUPPORT_ETM: - Refer to :doc:`GPTimer </api-reference/peripherals/gptimer>` for how to get the ETM task handle from GPTimer.
|
||||
|
||||
.. _etm-channel-control:
|
||||
|
||||
ETM Channel Control
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Connect Event and Task
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
An ETM event has no association with an ETM task, until they're connected to the same ETM channel by calling :cpp:func:`esp_etm_channel_connect`. Specially, calling the function with a ``NULL`` task/event handle, means to disconnect the channel from any task or event. Note that, this function can be called either before or after the channel is enabled. But calling this function at runtime to change the connection can be dangerous, because the channel may be in the middle of a cycle, and the new connection may not take effect immediately.
|
||||
|
||||
Enable and Disable Channel
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
You can call :cpp:func:`esp_etm_channel_enable` and :cpp:func:`esp_etm_channel_disable` to enable and disable the ETM channel from working.
|
||||
|
||||
ETM Channel Profiling
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
To check if the ETM channels are set with proper events and tasks, you can call :cpp:func:`esp_etm_dump` to dump all working ETM channels with their associated events and tasks. The dumping format is like:
|
||||
|
||||
::
|
||||
|
||||
===========ETM Dump Start==========
|
||||
channel 0: event 48 ==> task 17
|
||||
channel 1: event 48 ==> task 90
|
||||
channel 2: event 48 ==> task 94
|
||||
===========ETM Dump End============
|
||||
|
||||
The digital ID printed in the dump information is defined in the ``soc/soc_etm_source.h`` file.
|
||||
|
||||
.. _etm-thread-safety:
|
||||
|
||||
Thread Safety
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
The factory functions like :cpp:func:`esp_etm_new_channel` and :cpp:func:`gpio_new_etm_task` are guaranteed to be thread safe by the driver, which means, you can call it from different RTOS tasks without protection by extra locks.
|
||||
|
||||
No functions are allowed to run within ISR environment.
|
||||
|
||||
Other functions that take :cpp:type:`esp_etm_channel_handle_t`, :cpp:type:`esp_etm_task_handle_t` and :cpp:type:`esp_etm_event_handle_t` as the first positional parameter, are not treated as thread safe, which means you should avoid calling them from multiple tasks.
|
||||
|
||||
.. _etm-kconfig-options:
|
||||
|
||||
Kconfig Options
|
||||
^^^^^^^^^^^^^^^
|
||||
|
||||
- :ref:`CONFIG_ETM_ENABLE_DEBUG_LOG` is used to enabled the debug log output. Enable this option will increase the firmware binary size as well.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_etm.inc
|
||||
.. include-build-file:: inc/gpio_etm.inc
|
||||
.. include-build-file:: inc/esp_systick_etm.inc
|
||||
|
||||
.. [1]
|
||||
Different ESP chip series might have different numbers of ETM channels. For more details, please refer to *{IDF_TARGET_NAME} Technical Reference Manual* > Chapter *Event Task Matrix (ETM)* [`PDF <{IDF_TARGET_TRM_EN_URL}#evntaskmatrix>`__]. The driver will not forbid you from applying for more channels, but it will return error when all available hardware resources are used up. Please always check the return value when doing channel allocation (i.e. :cpp:func:`esp_etm_new_channel`).
|
||||
@ -17,16 +17,19 @@ Functional Overview
|
||||
|
||||
The following sections of this document cover the typical steps to install and operate a timer:
|
||||
|
||||
- :ref:`gptimer-resource-allocation` - covers which parameters should be set up to get a timer handle and how to recycle the resources when GPTimer finishes working.
|
||||
- :ref:`set-and-get-count-value` - covers how to force the timer counting from a start point and how to get the count value at anytime.
|
||||
- :ref:`set-up-alarm-action` - covers the parameters that should be set up to enable the alarm event.
|
||||
- :ref:`gptimer-register-event-callbacks` - covers how to hook user specific code to the alarm event callback function.
|
||||
- :ref:`enable-and-disable-timer` - covers how to enable and disable the timer.
|
||||
- :ref:`start-and-stop-timer` - shows some typical use cases that start the timer with different alarm behavior.
|
||||
- :ref:`gptimer-power-management` - describes how different source clock selections can affect power consumption.
|
||||
- :ref:`gptimer-iram-safe` - describes tips on how to make the timer interrupt and IO control functions work better along with a disabled cache.
|
||||
- :ref:`gptimer-thread-safety` - lists which APIs are guaranteed to be thread safe by the driver.
|
||||
- :ref:`gptimer-kconfig-options` - lists the supported Kconfig options that can be used to make a different effect on driver behavior.
|
||||
.. list::
|
||||
|
||||
- :ref:`gptimer-resource-allocation` - covers which parameters should be set up to get a timer handle and how to recycle the resources when GPTimer finishes working.
|
||||
- :ref:`set-and-get-count-value` - covers how to force the timer counting from a start point and how to get the count value at anytime.
|
||||
- :ref:`set-up-alarm-action` - covers the parameters that should be set up to enable the alarm event.
|
||||
- :ref:`gptimer-register-event-callbacks` - covers how to hook user specific code to the alarm event callback function.
|
||||
- :ref:`enable-and-disable-timer` - covers how to enable and disable the timer.
|
||||
- :ref:`start-and-stop-timer` - shows some typical use cases that start the timer with different alarm behavior.
|
||||
:SOC_TIMER_SUPPORT_ETM: - :ref:`gptimer-etm-event-and-task` - describes what the events and tasks can be connected to the ETM channel.
|
||||
- :ref:`gptimer-power-management` - describes how different source clock selections can affect power consumption.
|
||||
- :ref:`gptimer-iram-safe` - describes tips on how to make the timer interrupt and IO control functions work better along with a disabled cache.
|
||||
- :ref:`gptimer-thread-safety` - lists which APIs are guaranteed to be thread safe by the driver.
|
||||
- :ref:`gptimer-kconfig-options` - lists the supported Kconfig options that can be used to make a different effect on driver behavior.
|
||||
|
||||
.. _gptimer-resource-allocation:
|
||||
|
||||
@ -40,7 +43,6 @@ A GPTimer instance is represented by :cpp:type:`gptimer_handle_t`. The driver be
|
||||
To install a timer instance, there is a configuration structure that needs to be given in advance: :cpp:type:`gptimer_config_t`:
|
||||
|
||||
- :cpp:member:`gptimer_config_t::clk_src` selects the source clock for the timer. The available clocks are listed in :cpp:type:`gptimer_clock_source_t`, you can only pick one of them. For the effect on power consumption of different clock source, please refer to Section :ref:`gptimer-power-management`.
|
||||
|
||||
- :cpp:member:`gptimer_config_t::direction` sets the counting direction of the timer, supported directions are listed in :cpp:type:`gptimer_count_direction_t`, you can only pick one of them.
|
||||
|
||||
- :cpp:member:`gptimer_config_t::resolution_hz` sets the resolution of the internal counter. Each count step is equivalent to **1 / resolution_hz** seconds.
|
||||
@ -256,7 +258,23 @@ Alarm value can be updated dynamically inside the ISR handler callback, by chang
|
||||
ESP_ERROR_CHECK(gptimer_enable(gptimer));
|
||||
ESP_ERROR_CHECK(gptimer_start(gptimer, &alarm_config));
|
||||
|
||||
.. _gptimer-power-management:
|
||||
|
||||
.. only:: SOC_TIMER_SUPPORT_ETM
|
||||
|
||||
.. _gptimer-etm-event-and-task:
|
||||
|
||||
ETM Event and Task
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
GPTimer is able to generate various events that can interact with the :doc:`ETM </api-reference/peripherals/etm>` module. The supported events are listed in the :cpp:type:`gptimer_etm_event_type_t`. You can call :cpp:func:`gptimer_new_etm_event` to get the corresponding ETM event handle. Likewise, GPTimer exposes several tasks that can be triggered by other ETM events. The supported tasks are listed in the :cpp:type:`gptimer_etm_task_type_t`. You can call :cpp:func:`gptimer_new_etm_task` to get the corresponding ETM task handle.
|
||||
|
||||
For how to connect the event and task to an ETM channel, please refer to the :doc:`ETM </api-reference/peripherals/etm>` documentation.
|
||||
|
||||
.. _gptimer-power-management:
|
||||
|
||||
.. only:: not SOC_TIMER_SUPPORT_ETM
|
||||
|
||||
.. _gptimer-power-management:
|
||||
|
||||
Power Management
|
||||
^^^^^^^^^^^^^^^^
|
||||
@ -319,12 +337,17 @@ Kconfig Options
|
||||
Application Examples
|
||||
--------------------
|
||||
|
||||
* Typical use cases of GPTimer are listed in the example :example:`peripherals/timer_group/gptimer`.
|
||||
.. list::
|
||||
|
||||
- Typical use cases of GPTimer are listed in the example :example:`peripherals/timer_group/gptimer`.
|
||||
:SOC_TIMER_SUPPORT_ETM: - GPTimer capture external event's timestamp, with the help of ETM module: :example:`peripherals/timer_group/gptimer_capture_hc_sr04`.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/gptimer.inc
|
||||
.. include-build-file:: inc/gptimer_etm.inc
|
||||
.. include-build-file:: inc/gptimer_types.inc
|
||||
.. include-build-file:: inc/timer_types.inc
|
||||
|
||||
.. [1]
|
||||
|
||||
@ -11,6 +11,7 @@ Peripherals API
|
||||
:SOC_ADC_SUPPORTED: adc_calibration
|
||||
clk_tree
|
||||
:SOC_DAC_SUPPORTED: dac
|
||||
:SOC_ETM_SUPPORTED: etm
|
||||
gpio
|
||||
gptimer
|
||||
:SOC_DEDICATED_GPIO_SUPPORTED: dedic_gpio
|
||||
|
||||
@ -74,6 +74,15 @@ Uninstall driver (optional)
|
||||
|
||||
:cpp:func:`esp_async_memcpy_uninstall` is used to uninstall asynchronous memcpy driver. It's not necessary to uninstall the driver after each memcpy operation. If you know your application won't use this driver anymore, then this API can recycle the memory for you.
|
||||
|
||||
.. only:: SOC_GDMA_SUPPORT_ETM
|
||||
|
||||
ETM Event
|
||||
---------
|
||||
|
||||
Async memory copy is able to generate an event when one async memcpy operation is done. This event can be used to interact with the :doc:`ETM </api-reference/peripherals/etm>` module. You can call :cpp:func:`esp_async_memcpy_new_etm_event` to get the ETM event handle.
|
||||
|
||||
For how to connect the event to an ETM channel, please refer to the :doc:`ETM </api-reference/peripherals/etm>` documentation.
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
|
||||
@ -61,6 +61,15 @@ Callback functions
|
||||
Timer callbacks which are processed by ``ESP_TIMER_ISR`` method should not call the context switch call - ``portYIELD_FROM_ISR()``, instead of this you should use the :cpp:func:`esp_timer_isr_dispatch_need_yield` function.
|
||||
The context switch will be done after all ISR dispatch timers have been processed, if required by the system.
|
||||
|
||||
.. only:: SOC_SYSTIMER_SUPPORT_ETM
|
||||
|
||||
ETM Event
|
||||
---------
|
||||
|
||||
The esp_timer is constructed based on a hardware timer called *systimer*, which is able to generate the alarm event and interact with the :doc:`ETM </api-reference/peripherals/etm>` module. You can call :cpp:func:`esp_timer_new_etm_alarm_event` to get the corresponding ETM event handle.
|
||||
|
||||
For how to connect the event to an ETM channel, please refer to the :doc:`ETM </api-reference/peripherals/etm>` documentation.
|
||||
|
||||
esp_timer during the light sleep
|
||||
--------------------------------
|
||||
|
||||
|
||||
1
docs/zh_CN/api-reference/peripherals/etm.rst
Normal file
1
docs/zh_CN/api-reference/peripherals/etm.rst
Normal file
@ -0,0 +1 @@
|
||||
.. include:: ../../../en/api-reference/peripherals/etm.rst
|
||||
@ -17,16 +17,19 @@
|
||||
|
||||
下文介绍了配置和操作定时器的常规步骤：
|
||||
|
||||
- :ref:`gptimer-resource-allocation` - 获取定时器句柄应设置的参数，以及如何在通用定时器完成工作时回收资源。
|
||||
- :ref:`set-and-get-count-value` - 如何强制定时器从起点开始计数，以及如何随时获取计数值。
|
||||
- :ref:`set-up-alarm-action` - 启动警报事件应设置的参数。
|
||||
- :ref:`gptimer-register-event-callbacks` - 如何将用户的特定代码挂载到警报事件回调函数。
|
||||
- :ref:`enable-and-disable-timer` - 如何使能和禁用定时器。
|
||||
- :ref:`start-and-stop-timer` - 通过不同报警行为启动定时器的典型使用场景。
|
||||
- :ref:`gptimer-power-management` - 选择不同的时钟源将会如何影响功耗。
|
||||
- :ref:`gptimer-iram-safe` - 在 cache 禁用的情况下，如何更好地让定时器处理中断事务以及实现 IO 控制功能。
|
||||
- :ref:`gptimer-thread-safety` - 驱动程序保证哪些 API 线程安全。
|
||||
- :ref:`gptimer-kconfig-options` - 支持的 Kconfig 选项，这些选项会对驱动程序行为产生不同影响。
|
||||
.. list::
|
||||
|
||||
- :ref:`gptimer-resource-allocation` - 获取定时器句柄应设置的参数，以及如何在通用定时器完成工作时回收资源。
|
||||
- :ref:`set-and-get-count-value` - 如何强制定时器从起点开始计数，以及如何随时获取计数值。
|
||||
- :ref:`set-up-alarm-action` - 启动警报事件应设置的参数。
|
||||
- :ref:`gptimer-register-event-callbacks` - 如何将用户的特定代码挂载到警报事件回调函数。
|
||||
- :ref:`enable-and-disable-timer` - 如何使能和禁用定时器。
|
||||
- :ref:`start-and-stop-timer` - 通过不同报警行为启动定时器的典型使用场景。
|
||||
:SOC_TIMER_SUPPORT_ETM: - :ref:`gptimer-etm-event-and-task` - 定时器提供了哪些事件和任务可以连接到 ETM 通道上。
|
||||
- :ref:`gptimer-power-management` - 选择不同的时钟源将会如何影响功耗。
|
||||
- :ref:`gptimer-iram-safe` - 在 cache 禁用的情况下，如何更好地让定时器处理中断事务以及实现 IO 控制功能。
|
||||
- :ref:`gptimer-thread-safety` - 驱动程序保证哪些 API 线程安全。
|
||||
- :ref:`gptimer-kconfig-options` - 支持的 Kconfig 选项，这些选项会对驱动程序行为产生不同影响。
|
||||
|
||||
.. _gptimer-resource-allocation:
|
||||
|
||||
@ -256,7 +259,23 @@
|
||||
ESP_ERROR_CHECK(gptimer_enable(gptimer));
|
||||
ESP_ERROR_CHECK(gptimer_start(gptimer, &alarm_config));
|
||||
|
||||
.. _gptimer-power-management:
|
||||
|
||||
.. only:: SOC_TIMER_SUPPORT_ETM
|
||||
|
||||
.. _gptimer-etm-event-and-task:
|
||||
|
||||
ETM 事件与任务
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
定时器可以产生多种事件，这些事件可以连接到 :doc:`ETM </api-reference/peripherals/etm>` 模块。:cpp:type:`gptimer_etm_event_type_t` 中列出了定时器能够产生的事件类型。用户可以通过调用 :cpp:func:`gptimer_new_etm_event` 来获得相应事件的 ETM event 句柄。同样地，定时器还公开了一些可被其他事件触发然后自动执行的任务。:cpp:type:`gptimer_etm_task_type_t` 中列出了定时器能够支持的任务类型。 用户可以通过调用 :cpp:func:`gptimer_new_etm_task` 来获得相应任务的 ETM task 句柄。
|
||||
|
||||
关于如何将定时器事件和任务连接到 ETM 通道中，请参阅 :doc:`ETM </api-reference/peripherals/etm>` 文档。
|
||||
|
||||
.. _gptimer-power-management:
|
||||
|
||||
.. only:: not SOC_TIMER_SUPPORT_ETM
|
||||
|
||||
.. _gptimer-power-management:
|
||||
|
||||
电源管理
|
||||
^^^^^^^^^^^^^^^^^
|
||||
@ -319,12 +338,17 @@ Kconfig 选项
|
||||
应用示例
|
||||
------------------
|
||||
|
||||
* 示例 :example:`peripherals/timer_group/gptimer` 中列出了通用定时器的典型用例。
|
||||
.. list::
|
||||
|
||||
- 示例 :example:`peripherals/timer_group/gptimer` 中列出了通用定时器的典型用例。
|
||||
:SOC_TIMER_SUPPORT_ETM: - 示例 :example:`peripherals/timer_group/gptimer_capture_hc_sr04` 展示了如何在 ETM 模块的帮助下，用定时器捕获外部事件的时间戳。
|
||||
|
||||
API 参考
|
||||
-------------------
|
||||
|
||||
.. include-build-file:: inc/gptimer.inc
|
||||
.. include-build-file:: inc/gptimer_etm.inc
|
||||
.. include-build-file:: inc/gptimer_types.inc
|
||||
.. include-build-file:: inc/timer_types.inc
|
||||
|
||||
.. [1]
|
||||
|
||||
@ -11,6 +11,7 @@
|
||||
:SOC_ADC_SUPPORTED: adc_calibration
|
||||
clk_tree
|
||||
:SOC_DAC_SUPPORTED: dac
|
||||
:SOC_ETM_SUPPORTED: etm
|
||||
gpio
|
||||
gptimer
|
||||
:SOC_DEDICATED_GPIO_SUPPORTED: dedic_gpio
|
||||
|
||||
Loading…
Reference in New Issue
Block a user