documentation: add pulse width modulation API

Signed-off-by: Michal Lenc <michallenc@seznam.cz>

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

@@ -32,3 +32,182 @@ Files supporting PWM can be found in the following locations:
    in ``arch/<architecture>/src/<hardware>``
    directory for the specific processor ``<architecture>`` and for
    the specific ``<chip>`` PWM peripheral devices.
+
+Application Level Interface
+===========================
+
+The first necessary thing to be done in order to use the PWM driver in an
+application is to include the header file for the NuttX timer driver. It contains
+the Application Level Interface to the PWM driver. To do so, include:
+
+.. code-block:: c
+
+  #include <nuttx/timers/pwm.h>
+
+PWM driver is registered as a POSIX character device into ``/dev`` namespace.
+It is necessary to open the device to get a file descriptor for further
+operations.
+
+.. c:function:: int open(const char *pathname, int flags);
+
+  Opens a file. Files are required to be opened before any other file
+  operations are performed on it.
+
+  :param FAR const char * pathname: Relative path of the character device.
+  :param int flags: Does not have any affect.
+  :returns: Status of openning a file.
+  :retval OK (0): Success.
+  :retval < 0: Error.
+
+The PWM is accessed only through ``ioctl`` interface, functions ``read``
+and ``write`` does not have any affect. Following ``ioctl`` commands are
+available:
+
+ * :c:macro:`PWMIOC_SETCHARACTERISTICS`
+ * :c:macro:`PWMIOC_GETCHARACTERISTICS`
+ * :c:macro:`PWMIOC_START`
+ * :c:macro:`PWMIOC_STOP`
+
+.. c:macro:: PWMIOC_SETCHARACTERISTICS
+
+The ``PWMIOC_SETCHARACTERISTICS`` command sets PWM characteristics such as
+frequency, duty cycle, dead times and so on. These characteristics are
+set through ``pwm_info_s`` structure.
+
+.. c:struct:: pwm_info_s
+.. code-block:: c
+
+   struct pwm_info_s
+   {
+      /* Frequency of the pulse train */
+      uint32_t           frequency;
+   #ifdef CONFIG_PWM_MULTICHAN
+      /* Per-channel output state */
+      struct pwm_chan_s  channels[CONFIG_PWM_NCHANNELS];
+   #else
+      /* Duty of the pulse train, "1"-to-"0" duration.
+       * Maximum: 65535/65536 (0x0000ffff)
+       * Minimum:     1/65536 (0x00000001)
+       */
+      ub16_t             duty;
+   #ifdef CONFIG_PWM_DEADTIME
+      /* Dead time value for main output */
+      ub16_t             dead_time_a;
+      /* Dead time value for complementary output */
+      ub16_t             dead_time_b;
+   #endif
+   #ifdef CONFIG_PWM_PULSECOUNT
+      /* The number of pulse to generate.  0 means to
+       * generate an indefinite number of pulses
+       */
+      uint32_t           count;
+   #endif
+      /* Channel polarity */
+      uint8_t            cpol;
+      /* Disabled channel polarity */
+      uint8_t            dcpol;
+   #endif /* CONFIG_PWM_MULTICHAN */
+      /* User provided argument to be used in the lower half */
+      FAR void           *arg;
+   };
+
+Structure ``pwm_chan_s`` holds the representation of one PWM channel
+if multiple channels are used ( ``CONFIG_PWM_MULTICHAN`` is set).
+
+.. c:struct:: pwm_chan_s
+.. code-block:: c
+
+   struct pwm_chan_s
+   {
+      /* Duty of the pulse train, "1"-to-"0" duration.
+       * Maximum: 65535/65536 (0x0000ffff)
+       * Minimum:     1/65536 (0x00000001)
+       */
+      ub16_t duty;
+   #ifdef CONFIG_PWM_OVERWRITE
+      /* Channel overwrite */
+      bool ch_outp_ovrwr;
+      /* Channel overwrite value */
+      bool ch_outp_ovrwr_val;
+   #endif
+   #ifdef CONFIG_PWM_DEADTIME
+      /* Dead time value for main output */
+      ub16_t dead_time_a;
+      /* Dead time value for complementary output */
+      ub16_t dead_time_b;
+   #endif
+      /* Channel polarity */
+      uint8_t cpol;
+      /* Disabled channel polarity */
+      uint8_t dcpol;
+      /* Channel number */
+      int8_t channel;
+   };
+
+Apart from duty cycle and frequency, the ``ioctl`` command allows to
+set many other PWM characteristics. These functionalities might not be
+supported by all PWM controllers and user should always refer to target
+documentation in this case.
+
+If ``CONFIG_PWM_OVERWRITE`` is set and ``ch_outp_ovrwr`` is true, it is
+possible to overwrite channel output with value set in ``ch_outp_ovrwr_val``.
+Configuration option ``CONFIG_PWM_DEADTIME`` and fields ``dead_time_a``
+and ``dead_time_b`` provides an option to set dead time between complementary
+outputs. This instructs the driver to automatically insert output activation
+delay for complementary PWM outputs and is useful for H-bridge motor control
+for example.
+
+User may also set default channel polarity ``cpol`` and disabled channel
+polarity ``dcpol``. If set to zero, default controller values (or values
+determined in the configuration) are used. Following defines can be used
+to set the polarities:
+
+.. code-block:: c
+
+   /* Not defined, the default output state is arch dependant */
+   #define PWM_CPOL_NDEF             0
+   /* Logical zero */
+   #define PWM_CPOL_LOW              1
+   /* Logical one */
+   #define PWM_CPOL_HIGH             2
+
+   /* Not defined, the default output state is arch dependant */
+   #define PWM_DCPOL_NDEF            0
+    /* Logical zero */
+   #define PWM_DCPOL_LOW             1
+    /* Logical one  */
+   #define PWM_DCPOL_HIGH            2
+
+.. c:macro:: PWMIOC_GETCHARACTERISTICS
+
+Command ``PWMIOC_GETCHARACTERISTICS`` operates the same way as
+``PWMIOC_SETCHARACTERISTICS`` but it obtains currently set values
+instead of setting them.
+
+.. c:macro:: PWMIOC_START
+
+The ``PWMIOC_START`` command starts the pulsed output. Characteristics
+of PWM channels should be set before this operation.
+
+.. c:macro:: PWMIOC_STOPS
+
+The ``PWMIOC_STOPS`` command stops the pulsed output.
+
+Configuration
+=============
+
+This section describes common PWM configuration in ``Kconfig``. The reader
+should refer to target documentation for target specific configuration.
+
+PWM is enabled by ``CONFIG_PWM`` configuration option. Option
+``CONFIG_PWM_MULTICHAN`` selects support for multiple channels for one PWM
+instance. If multiple channels are used, configuration option
+``CONFIG_PWM_NCHANNELS`` defines the maximum number of channels per instance.
+Each timer/controller may support fewer output channels than this value.
+
+Generation of pin overwrite is enabled by ``CONFIG_PWM_OVERWRITE`` option.
+This supports generation of a pin overwrite with 0 or 1 without the need to
+wait for an end of cycle.
+
+The ``CONFIG_PWM_DEADTIME`` option brings the possibility to introduce
+dead time values between complementary PWM outputs.