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 f47f9c05aa097989788e08df443119c83cf4bcba Author: Michal Lenc <[email protected]> AuthorDate: Tue May 28 19:12:53 2024 +0200 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 <[email protected]> --- .../components/drivers/character/analog.rst | 55 -------- .../drivers/character/analog/adc/adc1242/index.rst | 11 ++ .../drivers/character/analog/adc/ads7828/index.rst | 9 ++ .../{hx711.rst => analog/adc/hx711/index.rst} | 7 +- .../drivers/character/analog/adc/index.rst | 142 +++++++++++++++++++++ .../character/analog/adc/ltc1867l/index.rst | 8 ++ .../character/analog/adc/max1161x/index.rst | 9 ++ .../drivers/character/analog/adc/pga11x/index.rst | 8 ++ .../drivers/character/analog/dac/dac7554/index.rst | 5 + .../drivers/character/analog/dac/dac7571/index.rst | 5 + .../drivers/character/analog/dac/index.rst | 75 +++++++++++ .../drivers/character/analog/dac/mcp48xx/index.rst | 8 ++ .../components/drivers/character/analog/index.rst | 29 +++++ .../components/drivers/character/index.rst | 3 +- Documentation/components/drivers/index.rst | 2 +- 15 files changed, 315 insertions(+), 61 deletions(-) diff --git a/Documentation/components/drivers/character/analog.rst b/Documentation/components/drivers/character/analog.rst deleted file mode 100644 index c8f8c75460..0000000000 --- a/Documentation/components/drivers/character/analog.rst +++ /dev/null @@ -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. diff --git a/Documentation/components/drivers/character/analog/adc/adc1242/index.rst b/Documentation/components/drivers/character/analog/adc/adc1242/index.rst new file mode 100644 index 0000000000..1eecf13d52 --- /dev/null +++ b/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. diff --git a/Documentation/components/drivers/character/analog/adc/ads7828/index.rst b/Documentation/components/drivers/character/analog/adc/ads7828/index.rst new file mode 100644 index 0000000000..812c5e89d9 --- /dev/null +++ b/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. diff --git a/Documentation/components/drivers/character/hx711.rst b/Documentation/components/drivers/character/analog/adc/hx711/index.rst similarity index 98% rename from Documentation/components/drivers/character/hx711.rst rename to Documentation/components/drivers/character/analog/adc/hx711/index.rst index 198e2713d1..648c4adf16 100644 --- a/Documentation/components/drivers/character/hx711.rst +++ b/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 + diff --git a/Documentation/components/drivers/character/analog/adc/index.rst b/Documentation/components/drivers/character/analog/adc/index.rst new file mode 100644 index 0000000000..c705cb1295 --- /dev/null +++ b/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: + + */* diff --git a/Documentation/components/drivers/character/analog/adc/ltc1867l/index.rst b/Documentation/components/drivers/character/analog/adc/ltc1867l/index.rst new file mode 100644 index 0000000000..8419d16241 --- /dev/null +++ b/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. diff --git a/Documentation/components/drivers/character/analog/adc/max1161x/index.rst b/Documentation/components/drivers/character/analog/adc/max1161x/index.rst new file mode 100644 index 0000000000..c8688247e8 --- /dev/null +++ b/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. diff --git a/Documentation/components/drivers/character/analog/adc/pga11x/index.rst b/Documentation/components/drivers/character/analog/adc/pga11x/index.rst new file mode 100644 index 0000000000..3557ac26f3 --- /dev/null +++ b/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. diff --git a/Documentation/components/drivers/character/analog/dac/dac7554/index.rst b/Documentation/components/drivers/character/analog/dac/dac7554/index.rst new file mode 100644 index 0000000000..30f327a736 --- /dev/null +++ b/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. diff --git a/Documentation/components/drivers/character/analog/dac/dac7571/index.rst b/Documentation/components/drivers/character/analog/dac/dac7571/index.rst new file mode 100644 index 0000000000..a277f48b53 --- /dev/null +++ b/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. diff --git a/Documentation/components/drivers/character/analog/dac/index.rst b/Documentation/components/drivers/character/analog/dac/index.rst new file mode 100644 index 0000000000..fc4c39c1f2 --- /dev/null +++ b/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: + + */* diff --git a/Documentation/components/drivers/character/analog/dac/mcp48xx/index.rst b/Documentation/components/drivers/character/analog/dac/mcp48xx/index.rst new file mode 100644 index 0000000000..91b32d595c --- /dev/null +++ b/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. diff --git a/Documentation/components/drivers/character/analog/index.rst b/Documentation/components/drivers/character/analog/index.rst new file mode 100644 index 0000000000..7d65b77372 --- /dev/null +++ b/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 + diff --git a/Documentation/components/drivers/character/index.rst b/Documentation/components/drivers/character/index.rst index 20ae908226..81639bcb90 100644 --- a/Documentation/components/drivers/character/index.rst +++ b/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 diff --git a/Documentation/components/drivers/index.rst b/Documentation/components/drivers/index.rst index 03bb7cc902..401f7336ca 100644 --- a/Documentation/components/drivers/index.rst +++ b/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
