docs(h743zi/capture): add capture driver docs
Add documentation for changes made in #16809. Add an example defconfig for a nsh build with the capture example. Replace the STM32H7_CAP option with just CAPTURE as the guard for the lower half driver. Signed-off-by: Côme VINCENT <44554692+comejv@users.noreply.github.com>
This commit is contained in:
Côme VINCENT
Xiang Xiao
parent
7ea3f8e333
commit
bebcfa0f46
5 changed files with 194 additions and 23 deletions
138
Documentation/components/drivers/character/timers/capture.rst
Normal file
138
Documentation/components/drivers/character/timers/capture.rst
Normal file
|
|
@ -0,0 +1,138 @@
|
|||
=======
|
||||
Capture
|
||||
=======
|
||||
|
||||
The **capture driver** is a character device driver that allows capturing
|
||||
timer values on specific events. This is useful for tasks such as
|
||||
measuring the frequency, duty cycle, or pulse count of an input signal.
|
||||
|
||||
This documentation is based on the STM32H7 timer capture driver.
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
The capture driver is accessed via a device file (e.g., ``/dev/capture0``).
|
||||
You can use standard file operations along with ``ioctl()`` calls to
|
||||
retrieve captured values or configure the driver.
|
||||
|
||||
Supported ``ioctl`` Commands
|
||||
----------------------------
|
||||
|
||||
.. c:macro:: CAPIOC_DUTYCYCLE
|
||||
|
||||
Get the PWM duty cycle from the capture unit.
|
||||
|
||||
**Argument:** ``int8_t *`` (pointer to duty cycle percentage).
|
||||
|
||||
.. c:macro:: CAPIOC_FREQUENCE
|
||||
|
||||
Get the pulse frequency from the capture unit.
|
||||
|
||||
**Argument:** ``int32_t *`` (pointer to frequency in Hz).
|
||||
|
||||
.. c:macro:: CAPIOC_EDGES
|
||||
|
||||
Get the number of PWM edges detected.
|
||||
|
||||
**Argument:** ``int32_t *`` (pointer to edge count).
|
||||
|
||||
.. c:macro:: CAPIOC_ALL
|
||||
|
||||
Get duty cycle, pulse frequency, and edge count in a single call.
|
||||
|
||||
**Argument:** ``struct cap_all_s *`` (structure containing all values).
|
||||
|
||||
.. c:macro:: CAPIOC_PULSES
|
||||
|
||||
Read the current pulse count value.
|
||||
|
||||
**Argument:** ``int *`` (pointer to pulse count).
|
||||
|
||||
.. c:macro:: CAPIOC_CLR_CNT
|
||||
|
||||
Clear the pulse count value.
|
||||
|
||||
**Argument:** None.
|
||||
|
||||
.. c:macro:: CAPIOC_FILTER
|
||||
|
||||
Configure the glitch filter.
|
||||
|
||||
**Argument:** ``uint32_t`` (filter value in nanoseconds, ``0`` to disable).
|
||||
|
||||
.. c:macro:: CAPIOC_HANDLER
|
||||
|
||||
Set a user callback function for capture events.
|
||||
|
||||
**Argument:** ``xcpt_t`` (function pointer, ``NULL`` to disable).
|
||||
|
||||
.. c:macro:: CAPIOC_ADD_WP
|
||||
|
||||
Add a watchpoint to the capture unit.
|
||||
|
||||
**Argument:** ``int`` (value to watch for).
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
To enable the capture driver, enable the following configuration options:
|
||||
|
||||
* ``CONFIG_CAPTURE``
|
||||
* ``CONFIG_STM32H7_TIM4_CAP`` (for STM32H7 Timer 4)
|
||||
|
||||
The ``CONFIG_CAPTURE`` option enables the lower-half driver and registers
|
||||
the ``/dev/capture`` device.
|
||||
|
||||
Without it, capture is still possible manually by including the appropriate
|
||||
header (e.g., ``arch/arm/src/stm32h7/stm32_capture.h``) and performing a
|
||||
manual initialization.
|
||||
|
||||
Example
|
||||
-------
|
||||
|
||||
Here is a simple example of using the capture driver to read a signal's
|
||||
frequency:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include <stdio.h>
|
||||
#include <fcntl.h>
|
||||
#include <sys/ioctl.h>
|
||||
#include <nuttx/timers/capture.h>
|
||||
|
||||
int main(int argc, char *argv[])
|
||||
{
|
||||
int fd;
|
||||
uint32_t frequency;
|
||||
|
||||
fd = open("/dev/capture0", O_RDONLY);
|
||||
if (fd < 0)
|
||||
{
|
||||
perror("Failed to open capture device");
|
||||
return 1;
|
||||
}
|
||||
|
||||
if (ioctl(fd, CAPIOC_FREQUENCE, (unsigned long)&frequency) < 0)
|
||||
{
|
||||
perror("Failed to get frequency");
|
||||
close(fd);
|
||||
return 1;
|
||||
}
|
||||
|
||||
printf("Frequency: %u Hz\n", frequency);
|
||||
|
||||
close(fd);
|
||||
return 0;
|
||||
}
|
||||
|
||||
Notes
|
||||
-----
|
||||
|
||||
* The actual set of supported ``ioctl`` commands may vary depending on
|
||||
the hardware and driver implementation.
|
||||
* The ``CAPIOC_FREQUENCE`` macro name is preserved for compatibility,
|
||||
even though "frequency" is the correct English spelling.
|
||||
* Always check return values from ``ioctl()`` calls for error handling.
|
||||
* **Important:** In debug builds of NuttX, calling an unsupported
|
||||
``ioctl`` command will trigger a ``DEBUGASSERT`` in the driver,
|
||||
which will halt or crash the system.
|
||||
|
|
@ -9,4 +9,5 @@ Timers Drivers
|
|||
pwm.rst
|
||||
watchdog.rst
|
||||
rtc.rst
|
||||
capture.rst
|
||||
|
||||
|
|
|
|||
|
|
@ -4584,15 +4584,10 @@ config STM32H7_ADC3_TIMTRIG
|
|||
---help---
|
||||
Values 0:CC1 1:CC2 2:CC3 3:CC4 4:TRGO
|
||||
|
||||
config STM32H7_CAP
|
||||
bool
|
||||
default n
|
||||
|
||||
config STM32H7_TIM1_CAP
|
||||
bool "TIM1 Capture"
|
||||
default n
|
||||
depends on STM32H7_TIM1
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve timer 1 for use by the capture driver.
|
||||
|
||||
|
|
@ -4617,7 +4612,6 @@ config STM32H7_TIM8_CAP
|
|||
bool "TIM8 Capture"
|
||||
default n
|
||||
depends on STM32H7_TIM8
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve timer 8 for use by the capture driver.
|
||||
|
||||
|
|
@ -4646,7 +4640,6 @@ config STM32H7_TIM2_CAP
|
|||
bool "TIM2 Capture"
|
||||
default n
|
||||
depends on STM32H7_TIM2
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve timer 2 for use by the capture driver.
|
||||
|
||||
|
|
@ -4671,7 +4664,6 @@ config STM32H7_TIM3_CAP
|
|||
bool "TIM3 Capture"
|
||||
default n
|
||||
depends on STM32H7_TIM3
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve timer 3 for use by the capture driver.
|
||||
|
||||
|
|
@ -4696,7 +4688,6 @@ config STM32H7_TIM4_CAP
|
|||
bool "TIM4 Capture"
|
||||
default n
|
||||
depends on STM32H7_TIM4
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve timer 4 for use by the capture driver.
|
||||
|
||||
|
|
@ -4721,7 +4712,6 @@ config STM32H7_TIM5_CAP
|
|||
bool "TIM5 Capture"
|
||||
default n
|
||||
depends on STM32H7_TIM5
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve timer 5 for use by the capture driver.
|
||||
|
||||
|
|
@ -4750,7 +4740,6 @@ config STM32H7_TIM12_CAP
|
|||
bool "TIM12 Capture"
|
||||
default n
|
||||
depends on STM32H7_TIM12
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve timer 12 for use by the capture driver.
|
||||
|
||||
|
|
@ -4775,7 +4764,6 @@ config STM32H7_TIM15_CAP
|
|||
bool "TIM15 Capture"
|
||||
default n
|
||||
depends on STM32H7_TIM15
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve timer 15 for use by the capture driver.
|
||||
|
||||
|
|
@ -4804,7 +4792,6 @@ config STM32H7_TIM13_CAP
|
|||
bool "TIM13 Capture"
|
||||
default n
|
||||
depends on STM32H7_TIM13
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve timer 13 for use by the capture driver.
|
||||
|
||||
|
|
@ -4829,7 +4816,6 @@ config STM32H7_TIM14_CAP
|
|||
bool "TIM14 Capture"
|
||||
default n
|
||||
depends on STM32H7_TIM14
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve timer 14 for use by the capture driver.
|
||||
|
||||
|
|
@ -4854,7 +4840,6 @@ config STM32H7_TIM16_CAP
|
|||
bool "TIM16 Capture"
|
||||
default n
|
||||
depends on STM32H7_TIM16
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve timer 16 for use by the capture driver.
|
||||
|
||||
|
|
@ -4879,7 +4864,6 @@ config STM32H7_TIM17_CAP
|
|||
bool "TIM17 Capture"
|
||||
default n
|
||||
depends on STM32H7_TIM17
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve timer 17 for use by the capture driver.
|
||||
|
||||
|
|
@ -4908,7 +4892,6 @@ config STM32H7_LPTIM1_CAP
|
|||
bool "LPTIM1 Capture"
|
||||
default n
|
||||
depends on STM32H7_LPTIM1
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve low-power timer 1 for use by the capture driver.
|
||||
|
||||
|
|
@ -4933,7 +4916,6 @@ config STM32H7_LPTIM2_CAP
|
|||
bool "LPTIM2 Capture"
|
||||
default n
|
||||
depends on STM32H7_LPTIM2
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve low-power timer 2 for use by the capture driver.
|
||||
|
||||
|
|
@ -4958,7 +4940,6 @@ config STM32H7_LPTIM3_CAP
|
|||
bool "LPTIM3 Capture"
|
||||
default n
|
||||
depends on STM32H7_LPTIM3
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve low-power timer 3 for use by the capture driver.
|
||||
|
||||
|
|
@ -4983,7 +4964,6 @@ config STM32H7_LPTIM4_CAP
|
|||
bool "LPTIM4 Capture"
|
||||
default n
|
||||
depends on STM32H7_LPTIM4
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve low-power timer 4 for use by the capture driver.
|
||||
|
||||
|
|
@ -5008,7 +4988,6 @@ config STM32H7_LPTIM5_CAP
|
|||
bool "LPTIM5 Capture"
|
||||
default n
|
||||
depends on STM32H7_LPTIM5
|
||||
select STM32H7_CAP
|
||||
---help---
|
||||
Reserve low-power timer 5 for use by the capture driver.
|
||||
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@
|
|||
|
||||
#include "stm32_capture.h"
|
||||
|
||||
#if defined(CONFIG_STM32H7_CAP)
|
||||
#if defined(CONFIG_CAPTURE)
|
||||
|
||||
/****************************************************************************
|
||||
* Pre-processor Definitions
|
||||
|
|
@ -587,4 +587,4 @@ errout:
|
|||
return (struct cap_lowerhalf_s *)lower;
|
||||
}
|
||||
|
||||
#endif /* CONFIG_STM32H7_CAP */
|
||||
#endif /* CONFIG_CAPTURE */
|
||||
|
|
|
|||
53
boards/arm/stm32h7/nucleo-h743zi/configs/capture/defconfig
Normal file
53
boards/arm/stm32h7/nucleo-h743zi/configs/capture/defconfig
Normal file
|
|
@ -0,0 +1,53 @@
|
|||
#
|
||||
# This file is autogenerated: PLEASE DO NOT EDIT IT.
|
||||
#
|
||||
# You can use "make menuconfig" to make any modifications to the installed .config file.
|
||||
# You can then do "make savedefconfig" to generate a new defconfig file that includes your
|
||||
# modifications.
|
||||
#
|
||||
# CONFIG_ARCH_LEDS is not set
|
||||
# CONFIG_STANDARD_SERIAL is not set
|
||||
# CONFIG_STM32H7_USE_LEGACY_PINMAP is not set
|
||||
CONFIG_ARCH="arm"
|
||||
CONFIG_ARCH_BOARD="nucleo-h743zi"
|
||||
CONFIG_ARCH_BOARD_NUCLEO_H743ZI=y
|
||||
CONFIG_ARCH_BUTTONS=y
|
||||
CONFIG_ARCH_CHIP="stm32h7"
|
||||
CONFIG_ARCH_CHIP_STM32H743ZI=y
|
||||
CONFIG_ARCH_CHIP_STM32H7=y
|
||||
CONFIG_ARCH_CHIP_STM32H7_CORTEXM7=y
|
||||
CONFIG_ARCH_STACKDUMP=y
|
||||
CONFIG_ARMV7M_DCACHE=y
|
||||
CONFIG_ARMV7M_DCACHE_WRITETHROUGH=y
|
||||
CONFIG_ARMV7M_DTCM=y
|
||||
CONFIG_ARMV7M_ICACHE=y
|
||||
CONFIG_BOARD_LATE_INITIALIZE=y
|
||||
CONFIG_BOARD_LOOPSPERMSEC=43103
|
||||
CONFIG_BUILTIN=y
|
||||
CONFIG_CAPTURE=y
|
||||
CONFIG_DEBUG_SYMBOLS=y
|
||||
CONFIG_EXAMPLES_CAPTURE=y
|
||||
CONFIG_EXPERIMENTAL=y
|
||||
CONFIG_HAVE_CXX=y
|
||||
CONFIG_HAVE_CXXINITIALIZE=y
|
||||
CONFIG_INIT_ENTRYPOINT="nsh_main"
|
||||
CONFIG_INTELHEX_BINARY=y
|
||||
CONFIG_LINE_MAX=64
|
||||
CONFIG_MM_REGIONS=4
|
||||
CONFIG_NSH_BUILTIN_APPS=y
|
||||
CONFIG_PREALLOC_TIMERS=4
|
||||
CONFIG_RAM_SIZE=245760
|
||||
CONFIG_RAM_START=0x20010000
|
||||
CONFIG_RAW_BINARY=y
|
||||
CONFIG_RR_INTERVAL=200
|
||||
CONFIG_SCHED_WAITPID=y
|
||||
CONFIG_SPI=y
|
||||
CONFIG_START_DAY=6
|
||||
CONFIG_START_MONTH=12
|
||||
CONFIG_START_YEAR=2011
|
||||
CONFIG_STM32H7_TIM4=y
|
||||
CONFIG_STM32H7_TIM4_CAP=y
|
||||
CONFIG_STM32H7_USART3=y
|
||||
CONFIG_SYSTEM_NSH=y
|
||||
CONFIG_TIMER=y
|
||||
CONFIG_USART3_SERIAL_CONSOLE=y
|
||||
Loading…
Add table
Reference in a new issue