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>

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

Documentation/components/drivers/character/timers/index.rst

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

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.
 

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 */

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