This is an automated email from the ASF dual-hosted git repository.

acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git

commit 86917b47771548a28df30ff2d0cf33e1bce8cb3e
Author: Michal Lenc <michall...@seznam.cz>
AuthorDate: Thu Feb 20 10:52:20 2025 +0100

    drivers/pwm: add PWMIOC_FAULTS_FETCH_AND_CLEAR ioctl for fault clears
    
    This ioctl clears the active fault inputs. Some faults can be latched
    (still active even if the source is not active anymore), so they have
    to be cleared from the software. The argument is a pointer to unsigned
    long bitmask variable. This bitmask specifies which faults are to be
    cleared.
    
    The ioctl also can fetch the faults active prior to the clear. These
    faults are saved to the argument specifying which faults are to be
    cleared. Therefore passing zero bitmask means the driver will only return
    active faults and clear none. Passing NULL pointer means the driver
    will clear all active and return none.
    
    The implementation of this ioctl is per driver.
    
    Signed-off-by: Michal Lenc <michall...@seznam.cz>
---
 .../components/drivers/character/timers/pwm.rst       | 18 ++++++++++++++++++
 include/nuttx/timers/pwm.h                            | 19 +++++++++++++++----
 2 files changed, 33 insertions(+), 4 deletions(-)

diff --git a/Documentation/components/drivers/character/timers/pwm.rst 
b/Documentation/components/drivers/character/timers/pwm.rst
index 50483801ff..16190fa484 100644
--- a/Documentation/components/drivers/character/timers/pwm.rst
+++ b/Documentation/components/drivers/character/timers/pwm.rst
@@ -182,6 +182,24 @@ of PWM channels should be set before this operation.
 
 The ``PWMIOC_STOPS`` command stops the pulsed output.
 
+.. c:macro:: PWMIOC_FAULTS_FETCH_AND_CLEAR
+
+The ``PWMIOC_FAULTS_FETCH_AND_CLEAR`` command clears fault inputs. Some
+faults can be latched (remain active even if the source is not active
+anymore) and have to be cleared from the software. This provides an option
+to clear faults from the application and re-enable PWM output. It can be
+also used to fetch the current faults.
+
+The call takes a pointer to ``unsigned long`` variable as an argument, a
+bitmask defining which faults are to be cleared. The driver clears these
+faults and fills the argument with the active faults prior to this clear.
+Having the argument variable equal to zero will result in no faults cleared
+but the user will get the currently active faults. If NULL is passed as
+an argument, then all currently set faults are cleared and fetch is not
+performed.
+
+This may not be supported by all drivers.
+
 Application Example
 ~~~~~~~~~~~~~~~~~~~
 
diff --git a/include/nuttx/timers/pwm.h b/include/nuttx/timers/pwm.h
index 7a124c655c..bab35ef912 100644
--- a/include/nuttx/timers/pwm.h
+++ b/include/nuttx/timers/pwm.h
@@ -109,12 +109,23 @@
  *  and return immediately.
  *
  *  ioctl argument:  None
+ *
+ * PWMIOC_FAULTS_FETCH_AND_CLEAR - Fetch current faults and clear them.
+ *  This command will clear fault inputs and re-enable PWM output. It also
+ *  fetches the faults active before the clear operation.
+ *
+ *  ioctl argument:  A pointer to an unsigned long bitmask of fault inputs to
+ *  be cleared. The previously active faults are also saved into this
+ *  bitmask, therefore it ioctl is both input and output. Passing NULL
+ *  clears all active faults and does not read them back. Passing a pointer
+ *  to a bitmask full of zeros will read the current faults and clear none.
  */
 
-#define PWMIOC_SETCHARACTERISTICS _PWMIOC(1)
-#define PWMIOC_GETCHARACTERISTICS _PWMIOC(2)
-#define PWMIOC_START              _PWMIOC(3)
-#define PWMIOC_STOP               _PWMIOC(4)
+#define PWMIOC_SETCHARACTERISTICS      _PWMIOC(1)
+#define PWMIOC_GETCHARACTERISTICS      _PWMIOC(2)
+#define PWMIOC_START                   _PWMIOC(3)
+#define PWMIOC_STOP                    _PWMIOC(4)
+#define PWMIOC_FAULTS_FETCH_AND_CLEAR  _PWMIOC(5)
 
 /* PWM channel polarity *****************************************************/
 

Reply via email to