luchianmihai/walnux
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs(h743zi/capture): add capture driver docs

Browse source 
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 2025-08-11 16:17:32 -04:00 • committed by Xiang Xiao
parent 7ea3f8e333
commit bebcfa0f46
5 changed files with 194 additions and 23 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

138
Documentation/components/drivers/character/timers/capture.rst Normal file
View 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.

1
Documentation/components/drivers/character/timers/index.rst
View file

@ -9,4 +9,5 @@ Timers Drivers
pwm.rst
watchdog.rst
rtc.rst
capture.rst

21
arch/arm/src/stm32h7/Kconfig
View file

@ -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.

4
arch/arm/src/stm32h7/stm32_capture_lowerhalf.c
View file

@ -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
View 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