From a3e9966359c432405c8ab1eb49a27133e5271ba2 Mon Sep 17 00:00:00 2001 From: Giovanni Di Sirio Date: Mon, 21 Jan 2019 19:42:49 +0000 Subject: More renaming for consistency. git-svn-id: svn://svn.code.sf.net/p/chibios/svn/trunk@12571 110e8d01-0319-4d1e-a829-52ad28d1bb01 --- os/hal/dox/hal_adc.dox | 141 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 os/hal/dox/hal_adc.dox (limited to 'os/hal/dox/hal_adc.dox') diff --git a/os/hal/dox/hal_adc.dox b/os/hal/dox/hal_adc.dox new file mode 100644 index 000000000..c80a0b495 --- /dev/null +++ b/os/hal/dox/hal_adc.dox @@ -0,0 +1,141 @@ +/* + ChibiOS - Copyright (C) 2006..2018 Giovanni Di Sirio + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. +*/ + +/** + * @defgroup ADC ADC Driver + * @brief Generic ADC Driver. + * @details This module implements a generic ADC (Analog to Digital Converter) + * driver supporting a variety of buffer and conversion modes. + * @pre In order to use the ADC driver the @p HAL_USE_ADC option + * must be enabled in @p halconf.h. + * + * @section adc_1 Driver State Machine + * The driver implements a state machine internally, not all the driver + * functionalities can be used in any moment, any transition not explicitly + * shown in the following diagram has to be considered an error and shall + * be captured by an assertion (if enabled). + * @if LATEX_PDF + * @dot + digraph example { + rankdir="LR"; + size="5, 7"; + + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + stop [label="ADC_STOP\nLow Power"]; + uninit [label="ADC_UNINIT", style="bold"]; + ready [label="ADC_READY\nClock Enabled"]; + active [label="ADC_ACTIVE\nConverting"]; + error [label="ADC_ERROR\nError"]; + complete [label="ADC_COMPLETE\nComplete"]; + + uninit -> stop [label="\n adcInit()", constraint=false]; + stop -> ready [label="\nadcStart()"]; + ready -> ready [label="\nadcStart()\nadcStopConversion()"]; + ready -> stop [label="\nadcStop()"]; + stop -> stop [label="\nadcStop()"]; + ready -> active [label="\nadcStartConversion() (async)\nadcConvert() (sync)"]; + active -> ready [label="\nadcStopConversion()\nsync return"]; + active -> active [label="\nasync callback (half buffer, circular)\nasync callback (full buffer)\n>acg_endcb<"]; + active -> complete [label="\n\nasync callback (full buffer)\n>end_cb<"]; + active -> error [label="\n\nasync callback (error)\n>error_cb<"]; + complete -> active [label="\nadcStartConversionI()\nthen\ncallback return"]; + complete -> ready [label="\ncallback return"]; + error -> active [label="\nadcStartConversionI()\nthen\ncallback return"]; + error -> ready [label="\ncallback return"]; + } + * @enddot + * @else + * @dot + digraph example { + rankdir="LR"; + + node [shape=circle, fontname=Helvetica, fontsize=8, fixedsize="true", width="0.9", height="0.9"]; + edge [fontname=Helvetica, fontsize=8]; + + stop [label="ADC_STOP\nLow Power"]; + uninit [label="ADC_UNINIT", style="bold"]; + ready [label="ADC_READY\nClock Enabled"]; + active [label="ADC_ACTIVE\nConverting"]; + error [label="ADC_ERROR\nError"]; + complete [label="ADC_COMPLETE\nComplete"]; + + uninit -> stop [label="\n adcInit()", constraint=false]; + stop -> ready [label="\nadcStart()"]; + ready -> ready [label="\nadcStart()\nadcStopConversion()"]; + ready -> stop [label="\nadcStop()"]; + stop -> stop [label="\nadcStop()"]; + ready -> active [label="\nadcStartConversion() (async)\nadcConvert() (sync)"]; + active -> ready [label="\nadcStopConversion()\nsync return"]; + active -> active [label="\nasync callback (half buffer, circular)\nasync callback (full buffer)\n>acg_endcb<"]; + active -> complete [label="\n\nasync callback (full buffer)\n>end_cb<"]; + active -> error [label="\n\nasync callback (error)\n>error_cb<"]; + complete -> active [label="\nadcStartConversionI()\nthen\ncallback return"]; + complete -> ready [label="\ncallback return"]; + error -> active [label="\nadcStartConversionI()\nthen\ncallback return"]; + error -> ready [label="\ncallback return"]; + } + * @enddot + * @endif + * + * @section adc_2 ADC Operations + * The ADC driver is quite complex, an explanation of the terminology and of + * the operational details follows. + * + * @subsection adc_2_1 ADC Conversion Groups + * The @p ADCConversionGroup is the objects that specifies a physical + * conversion operation. This structure contains some standard fields and + * several implementation-dependent fields.
+ * The standard fields define the CG mode, the number of channels belonging + * to the CG and the optional callbacks.
+ * The implementation-dependent fields specify the physical ADC operation + * mode, the analog channels belonging to the group and any other + * implementation-specific setting. Usually the extra fields just mirror + * the physical ADC registers, please refer to the vendor's MCU Reference + * Manual for details about the available settings. Details are also available + * into the documentation of the ADC low level drivers and in the various + * sample applications. + * + * @subsection adc_2_2 ADC Conversion Modes + * The driver supports several conversion modes: + * - One Shot, the driver performs a single group conversion then stops. + * - Linear Buffer, the driver performs a series of group conversions + * then stops. This mode is like a one shot conversion repeated N times, + * the buffer pointer increases after each conversion. The buffer is + * organized as an S(CG)*N samples matrix, when S(CG) is the conversion + * group size (number of channels) and N is the buffer depth (number of + * repeated conversions). + * - Circular Buffer, much like the linear mode but the operation does + * not stop when the buffer is filled, it is automatically restarted + * with the buffer pointer wrapping back to the buffer base. + * . + * @subsection adc_2_3 ADC Callbacks + * The driver is able to invoke callbacks during the conversion process. A + * callback is invoked when the operation has been completed or, in circular + * mode, when the buffer has been filled and the operation is restarted. In + * circular mode a callback is also invoked when the buffer is half filled.
+ * The "half filled" and "filled" callbacks in circular mode allow to + * implement "streaming processing" of the sampled data, while the driver is + * busy filling one half of the buffer the application can process the + * other half, this allows for continuous interleaved operations. + * + * The driver is not thread safe for performance reasons, if you need to access + * the ADC bus from multiple threads then use the @p adcAcquireBus() and + * @p adcReleaseBus() APIs in order to gain exclusive access. + * + * @ingroup HAL_NORMAL_DRIVERS + */ -- cgit v1.2.3