docs: add API description for ADC/DAC peripherals

This adds basic API description for ADC and DAC peripherals. External
ADC/DAC controllers are listed as well.

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

Documentation/components/drivers/character/analog.rst

@@ -1,55 +0,0 @@
-========================
-Analog (ADC/DAC) Drivers
-========================
-
-The NuttX analog drivers are split into two parts:
-
-#. An "upper half", generic driver that provides the common analog
-   interface to application level code, and
-#. A "lower half", platform-specific driver that implements the
-   low-level controls to implement the analog functionality.
-
--  General header files for the NuttX analog drivers reside in
-   ``include/nuttx/analog/``. These header files includes both the
-   application level interface to the analog driver as well as the
-   interface between the "upper half" and "lower half" drivers.
--  Common analog logic and share-able analog drivers reside in the
-   ``drivers/analog/``.
--  Platform-specific drivers reside in
-   ``arch/<architecture>/src/<hardware>`` directory
-   for the specific processor ``<architecture>`` and for the
-   specific ``<chip>`` analog peripheral devices.
-
-ADC Drivers
------------
-
--  ``include/nuttx/analog/adc.h``. All structures and APIs needed
-   to work with ADC drivers are provided in this header file. This
-   header file includes:
-
-   #. Structures and interface descriptions needed to develop a
-      low-level, architecture-specific, ADC driver.
-   #. To register the ADC driver with a common ADC character
-      driver.
-   #. Interfaces needed for interfacing user programs with the
-      common ADC character driver.
-
--  ``drivers/analog/adc.c``. The implementation of the common ADC
-   character driver.
-
-DAC Drivers
------------
-
--  ``include/nuttx/analog/dac.h``. All structures and APIs needed
-   to work with DAC drivers are provided in this header file. This
-   header file includes:
-
-   #. Structures and interface descriptions needed to develop a
-      low-level, architecture-specific, DAC driver.
-   #. To register the DAC driver with a common DAC character
-      driver.
-   #. Interfaces needed for interfacing user programs with the
-      common DAC character driver.
-
--  ``drivers/analog/dac.c``. The implementation of the common DAC
-   character driver.

Documentation/components/drivers/character/analog/adc/adc1242/index.rst

@@ -0,0 +1,11 @@
+==========
+TI ADS1242
+==========
+
+ADS1242 24-Bit SPI powered ADC. This driver supports reading the ADC
+conversionresult as well as configuring the ADC, setting the input channel,
+etc. is implemented via ioctl calls. However, it does not yet implement
+the standard ADC interface.
+
+-  ``include/nuttx/analog/ads1242.h``. All structures and APIs needed
+   to work with DAtC drivers are provided in this header file.

Documentation/components/drivers/character/analog/adc/ads7828/index.rst

@@ -0,0 +1,9 @@
+==========
+TI ADS7828
+==========
+
+ADS7828 12-Bit I2C powered ADC. This driver supports reading single or
+multiple ADC conversion result as well as onfiguring the ADC, via ioctl calls.
+
+-  ``include/nuttx/analog/ads7828.h``. All structures and APIs needed
+   to work with DAtC drivers are provided in this header file.

Documentation/components/drivers/character/analog/adc/hx711/index.rst

@@ -1,6 +1,6 @@
-=============================
-HX711 ADC DESIGNED FOR SCALES
-=============================
+========================
+Avia Semiconductor HX711
+========================
 
 Driver contributed by Michał Łyszczek.
 
@@ -218,3 +218,4 @@ from the shell, as it can dump readings and set all options.
 
    Set value per unit, to get output in grams, and then tare with 10g precision
         hx711 -v 813 -t 10
+

Documentation/components/drivers/character/analog/adc/index.rst

@@ -0,0 +1,142 @@
+===========
+ADC Drivers
+===========
+
+-  ``include/nuttx/analog/adc.h``. All structures and APIs needed
+   to work with ADC drivers are provided in this header file. This
+   header file includes:
+
+   #. Structures and interface descriptions needed to develop a
+      low-level, architecture-specific, ADC driver.
+   #. To register the ADC driver with a common ADC character
+      driver.
+   #. Interfaces needed for interfacing user programs with the
+      common ADC character driver.
+
+-  ``drivers/analog/adc.c``. The implementation of the common ADC
+   character driver.
+
+Application Programming Interface
+=================================
+
+The first necessary thing to be done in order to use the ADC driver from an
+application is to include the correct header filer. It contains the
+Application Programming Interface to the ADC driver. To do so, include:
+
+
+.. code-block:: c
+
+  #include <nuttx/analog/adc.h>
+
+ADC 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.
+
+Standard POSIX ``read()`` operation may be used to read the measured data from
+the controller. The driver utilizes FIFO queue for received measurements
+and ``read()`` operation gets data from this queue. Structure ``adc_msg_s``
+(or array of these structures) should be passed to buffer parameter of
+``read()`` call. This structure represents one ADC measurement.
+
+.. c:struct:: adc_msg_s
+.. code-block:: c
+
+  begin_packed_struct struct adc_msg_s
+  {
+    /* The 8-bit ADC Channel */
+    uint8_t      am_channel;
+    /* ADC convert result (4 bytes) */
+    int32_t      am_data;
+  } end_packed_struct;
+
+User may perform polling operation on the driver with ``poll()`` call.
+The controller also may be configured/controlled at run time with numerous
+``ioctl()`` calls. Following commands are supported:
+
+ * :c:macro:`ANIOC_TRIGGER`
+ * :c:macro:`ANIOC_WDOG_UPPER`
+ * :c:macro:`ANIOC_WDOG_LOWER`
+ * :c:macro:`ANIOC_GET_NCHANNELS`
+ * :c:macro:`ANIOC_RESET_FIFO`
+ * :c:macro:`ANIOC_SAMPLES_ON_READ`
+
+.. c:macro:: ANIOC_TRIGGER
+
+The ``ANIOC_TRIGGER`` command triggers one conversion. This call is used
+when software trigger conversion is configured. The opposite to software
+trigger is a hardware trigger. This may be some timer driver for example.
+
+.. c:macro:: ANIOC_WDOG_UPPER
+
+This command is used to set the upper threshold for the watchdog.
+
+.. c:macro:: ANIOC_WDOG_LOWER
+
+This command is used to set the lower threshold for the watchdog.
+
+.. c:macro:: ANIOC_GET_NCHANNELS
+
+The ``ANIOC_GET_NCHANNELS`` gets the number of used/configured channels
+for given opened instance. This is the only portable way how to get
+the number of channels from the driver.
+
+.. c:macro:: ANIOC_RESET_FIFO
+
+This ``ioctl`` command clears the FIFO queue in which measured data are stored.
+
+.. c:macro:: ANIOC_SAMPLES_ON_READ
+
+The ``ANIOC_SAMPLES_ON_READ`` returns number of samples/measured data waiting
+in the FIFO queue to be read.
+
+It is possible for a controller to support its specific ioctl commands. These
+should be described in controller specific documentation.
+
+Application Example
+~~~~~~~~~~~~~~~~~~~
+
+An example application can be found in ``nuttx-apps`` repository under
+path ``examples/adc``. It is an example application that reads the data
+from the defined number of channels.
+
+.. code-block :: bash
+
+   nsh> adc
+   Sample:
+   1: channel: 0 value 951
+   2: channel: 1 value 1879
+   Sample:
+   1: channel: 0 value 952
+   2: channel: 1 value 1880
+   Sample:
+   1: channel: 0 value 942
+   2: channel: 1 value 1800
+
+Configuration
+=============
+
+This section describes ADC driver configuration in ``Kconfig``. The reader
+should refer to target documentation for target specific configuration.
+
+ADC peripheral is enabled by ``CONFIG_ANALOG`` and ``CONFIG_ADC`` options,
+respectively. The user can configure FIFO queue size with configuration
+option ``CONFIG_ADC_FIFOSIZE``. This variable defines the size of the
+ADC ring buffer that is used to queue received ADC data until they can be
+retrieved by the  application by reading from the ADC character device. Since
+this is a ring buffer, the actual number of bytes that can be
+retained in buffer is (``CONFIG_ADC_FIFOSIZE - 1``).
+
+Configuration option ``CONFIG_ADC_NPOLLWAITERS`` defines number of
+threads that can be waiting on poll.
+
+External Devices
+================
+
+NuttX also provides support for various external ADC devices. These usually
+communicates with MCU with I2C or SPI peripherals.
+
+.. toctree::
+  :maxdepth: 1
+  :glob:
+
+  */*

Documentation/components/drivers/character/analog/adc/ltc1867l/index.rst

@@ -0,0 +1,8 @@
+===============
+LTC 1863L/1867L
+===============
+
+LTC 1863L (12 bit) and LTC 1867L (16 bit) SPI powered ADC.
+
+-  ``include/nuttx/analog/ltc1867l.h``. All structures and APIs needed
+   to work with DAtC drivers are provided in this header file.

Documentation/components/drivers/character/analog/adc/max1161x/index.rst

@@ -0,0 +1,9 @@
+====================
+Maxim MAX11612-11617
+====================
+
+MAX1161X 12-Bit I2C powered ADC Family. This driver supports reading single or
+multiple ADC conversion result as well as configuring the ADC, via ioctl calls.
+
+-  ``include/nuttx/analog/max1161x.h``. All structures and APIs needed
+   to work with DAtC drivers are provided in this header file.

Documentation/components/drivers/character/analog/adc/pga11x/index.rst

@@ -0,0 +1,8 @@
+===============
+TI PGA112/3/6/7
+===============
+
+PGA112, PGA113, PGA116, PGA117 Zero-Drift PROGRAMMABLE GAIN AMPLIFIER with MUX.
+
+-  ``include/nuttx/analog/pga11x.h``. All structures and APIs needed
+   to work with DAtC drivers are provided in this header file.

Documentation/components/drivers/character/analog/dac/dac7554/index.rst

@@ -0,0 +1,5 @@
+=========================
+Texas Instruments DAC7554
+=========================
+
+Texas Instruments DAC7554 DAC. This controller does not have API.

Documentation/components/drivers/character/analog/dac/dac7571/index.rst

@@ -0,0 +1,5 @@
+=========================
+Texas Instruments DAC7571
+=========================
+
+Texas Instruments DAC7571 DAC. This controller does not have API.

Documentation/components/drivers/character/analog/dac/index.rst

@@ -0,0 +1,75 @@
+===========
+DAC Drivers
+===========
+
+-  ``include/nuttx/analog/dac.h``. All structures and APIs needed
+   to work with DAtC drivers are provided in this header file. This
+   header file includes:
+
+   #. Structures and inerface descriptions needed to develop a
+      low-level, architecture-specific, DAC driver.
+   #. To register the DAC driver with a common DAC character
+      driver.
+   #. Interfaces needed for interfacing user programs with the
+      common DAC character driver.
+
+-  ``drivers/analog/dac.c``. The implementation of the common DAC
+   character driver.
+
+Application Programming Interface
+=================================
+
+The first necessary thing to be done in order to use the DAC driver from an
+application is to include the correct header filer. It contains the
+Application Programming Interface to the PWM driver. To do so, include
+
+.. code-block:: c
+
+  #include <nuttx/analog/dac.h>
+
+DAC driver is registered as a POSIX character device driver 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.
+
+Standard POSIX ``write()`` call is used to send data from an application to
+a controller. Structure  ``dac_msg_s`` is used to pass the data/samples.
+
+.. c:struct:: dac_msg_s
+.. code-block:: c
+
+  begin_packed_struct struct dac_msg_s
+  {
+    /* The 8-bit DAC Channel */
+    uint8_t      am_channel;
+    /* DAC convert result (4 bytes) */
+    int32_t      am_data;
+  } end_packed_struct;
+
+Application Example
+~~~~~~~~~~~~~~~~~~~
+
+An example application can be found in ``nuttx-apps`` repository under
+path ``examples/dac``. It provides command line interface to write data
+to DAC channels.s
+
+Configuration
+=============
+
+This section describes DAC driver configuration in ``Kconfig``. The reader
+should refer to target documentation for target specific configuration.
+
+The peripheral is enabled by ``CONFIG_ANALOG``  and ``CONFIG_DAC`` options,
+respectively. The FIFO queue size is configurable with ``CONFIG_DAC_FIFOSIZE``.
+This size is limited to ``255`` to fit into ``uint8_t``.
+
+External Devices
+================
+
+NuttX also provides support for various external DAC devices. These usually
+communicates with MCU with I2C or SPI peripherals.
+
+.. toctree::
+  :maxdepth: 1
+  :glob:
+
+  */*

Documentation/components/drivers/character/analog/dac/mcp48xx/index.rst

@@ -0,0 +1,8 @@
+===========================
+Microchip MCP4802/4812/4822
+===========================
+
+Microchip MCP4802/4812/4822 DAC.
+
+-  ``include/nuttx/analog/mcp48xx.h``. All structures and APIs needed
+   to work with DAtC drivers are provided in this header file.

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

@@ -0,0 +1,29 @@
+========================
+Analog (ADC/DAC) Drivers
+========================
+
+The NuttX analog drivers are split into two parts:
+
+#. An "upper half", generic driver that provides the common analog
+   interface to application level code, and
+#. A "lower half", platform-specific driver that implements the
+   low-level controls to implement the analog functionality.
+
+-  General header files for the NuttX analog drivers reside in
+   ``include/nuttx/analog/``. These header files includes both the
+   application level interface to the analog driver as well as the
+   interface between the "upper half" and "lower half" drivers.
+-  Common analog logic and share-able analog drivers reside in the
+   ``drivers/analog/``.
+-  Platform-specific drivers reside in
+   ``arch/<architecture>/src/<hardware>`` directory
+   for the specific processor ``<architecture>`` and for the
+   specific ``<chip>`` analog peripheral devices.
+
+.. toctree::
+  :caption: Supported Drivers
+  :maxdepth: 1
+
+  adc/index.rst
+  dac/index.rst
+

Documentation/components/drivers/character/index.rst

@@ -55,13 +55,12 @@ Character device drivers have these properties:
   :maxdepth: 2
 
   1wire.rst
-  analog.rst
+  analog/index.rst
   bch.rst
   can.rst
   contactless.rst
   crypto/index.rst
   efuse.rst
-  hx711.rst
   i2s.rst
   input/index.rst
   ipcc.rst

Documentation/components/drivers/index.rst

@@ -37,7 +37,7 @@ Subdirectories of ``nuttx/drivers``
 
   1wire device drivers.
 
-* ``analog/`` :doc:`character/analog`
+* ``analog/`` :doc:`character/analog/index`
 
   This directory holds implementations of analog device drivers.
   This includes drivers for Analog to Digital Conversion (ADC) as