From bebcfa0f46a1e24d77ed48ee73020f9f90ea4dd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?C=C3=B4me=20VINCENT?= <44554692+comejv@users.noreply.github.com> Date: Mon, 11 Aug 2025 16:17:32 -0400 Subject: [PATCH] docs(h743zi/capture): add capture driver docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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> --- .../drivers/character/timers/capture.rst | 138 ++++++++++++++++++ .../drivers/character/timers/index.rst | 1 + arch/arm/src/stm32h7/Kconfig | 21 --- .../arm/src/stm32h7/stm32_capture_lowerhalf.c | 4 +- .../nucleo-h743zi/configs/capture/defconfig | 53 +++++++ 5 files changed, 194 insertions(+), 23 deletions(-) create mode 100644 Documentation/components/drivers/character/timers/capture.rst create mode 100644 boards/arm/stm32h7/nucleo-h743zi/configs/capture/defconfig diff --git a/Documentation/components/drivers/character/timers/capture.rst b/Documentation/components/drivers/character/timers/capture.rst new file mode 100644 index 0000000000..03b492146f --- /dev/null +++ b/Documentation/components/drivers/character/timers/capture.rst @@ -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 + #include + #include + #include + + 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. diff --git a/Documentation/components/drivers/character/timers/index.rst b/Documentation/components/drivers/character/timers/index.rst index 3ebe20aa3e..ceffa6bdca 100644 --- a/Documentation/components/drivers/character/timers/index.rst +++ b/Documentation/components/drivers/character/timers/index.rst @@ -9,4 +9,5 @@ Timers Drivers pwm.rst watchdog.rst rtc.rst + capture.rst diff --git a/arch/arm/src/stm32h7/Kconfig b/arch/arm/src/stm32h7/Kconfig index 12bf79aa1c..a91f8f1d9e 100644 --- a/arch/arm/src/stm32h7/Kconfig +++ b/arch/arm/src/stm32h7/Kconfig @@ -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. diff --git a/arch/arm/src/stm32h7/stm32_capture_lowerhalf.c b/arch/arm/src/stm32h7/stm32_capture_lowerhalf.c index 11b855dd4f..6bdf846cfb 100644 --- a/arch/arm/src/stm32h7/stm32_capture_lowerhalf.c +++ b/arch/arm/src/stm32h7/stm32_capture_lowerhalf.c @@ -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 */ diff --git a/boards/arm/stm32h7/nucleo-h743zi/configs/capture/defconfig b/boards/arm/stm32h7/nucleo-h743zi/configs/capture/defconfig new file mode 100644 index 0000000000..dceb47307f --- /dev/null +++ b/boards/arm/stm32h7/nucleo-h743zi/configs/capture/defconfig @@ -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