docs: add API description for qencoder peripheral

This adds basic API description for quadrature encoder peripheral.

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

Documentation/components/drivers/character/quadrature.rst

@@ -28,3 +28,99 @@ following locations:
    for the specific processor ``<architecture>`` and for the
    specific ``<chip>`` Quadrature Encoder peripheral devices.
 
+Application Programming Interface
+=================================
+
+The first thing to be done in order to use the quadrature encoder driver
+from an application is to include the correct header filer. It contains the
+Application Programming Interface to the driver. To do so, include
+
+.. code-block:: c
+
+  #include <nuttx/sensors/qencoder.h>
+
+Quadrature encoder driver is registered as a POSIX character device file
+into ``/dev`` namespace. It is necessary to open the device to get a file
+descriptor for further operations. This can be done with standard POSIX
+``open()`` call.
+
+The driver is accessed only through ``ioctl`` interface, functions ``read``
+and ``write`` does not have any affect. Following ``ioctl`` commands are
+available:
+
+ * :c:macro:`QEIOC_POSITION`
+ * :c:macro:`QEIOC_RESET`
+ * :c:macro:`QEIOC_SETPOSMAX`
+ * :c:macro:`QEIOC_SETINDEX`
+ * :c:macro:`QEIOC_GETINDEX`
+
+.. c:macro:: QEIOC_POSITION
+
+This call gets the current position from the encoder driver. Argument
+of the call is a pointer to ``int32_t`` variable.
+
+.. c:macro:: QEIOC_RESET
+
+This command resets the current encoder positition to zero.
+
+.. c:macro:: QEIOC_SETPOSMAX
+
+The ``QEIOC_SETPOSMAX`` call sets the maximum position for the encoder.
+An argument is an ``uint32_t`` variable with the maximum position value.
+
+.. c:macro:: QEIOC_SETINDEX
+
+This ioctl sets the index position of the encoder. An argument is an
+``uint32_t`` variable with the maximum position value.
+
+.. c:macro:: QEIOC_GETINDEX
+
+This ioctl gets the index position of the encoder. An argument is a
+pointer to ``qe_index_s`` structure.
+
+.. c:struct:: qe_index_s
+.. code-block:: c
+
+   struct qe_index_s
+   {
+      /* Qencoder actual position */
+      int32_t qenc_pos;
+      /* Index last position */
+      int32_t indx_pos;
+      /* Number of index occurances */
+      int16_t indx_cnt;
+   };
+
+The pointer to this structure is used as an argument to ``QEIOC_GETINDEX``
+ioctl command. It gets the current encoder position, the last position of
+index and the number of index occurances.
+
+Application Example
+~~~~~~~~~~~~~~~~~~~
+
+An example application can be found in ``nuttx-apps`` repository under
+path ``examples/qencoder``. It demonstrates the basic data read
+from an encoder device.
+
+.. code-block:: console
+
+    nsh> qe
+    1.  0
+    2.  0
+    3.  0
+    4.  1
+    5.  1
+    6.  1
+    7.  2
+    8.  2
+    9.  3
+
+Configuration
+=============
+
+This section describes qencoder driver configuration in ``Kconfig``. The
+reader should refer to target documentation for target specific configuration.
+
+The ``CONFIG_SENSORS`` option has to be enabled in order to use the qencoder
+peripheral. The peripheral itself is enabled by ``CONFIG_SENSORS_QENCODER``
+option.