diff options
| -rw-r--r-- | source/libmaple/api/adc.rst | 360 |
1 files changed, 188 insertions, 172 deletions
diff --git a/source/libmaple/api/adc.rst b/source/libmaple/api/adc.rst index fecaece..2f06926 100644 --- a/source/libmaple/api/adc.rst +++ b/source/libmaple/api/adc.rst @@ -1,24 +1,31 @@ .. highlight:: c .. _libmaple-adc: -``adc.h`` -========= +``<libmaple/adc.h>`` +==================== :ref:`Analog to Digital Conversion <adc>` (ADC) support. +A common API for basic ADC functionality is available, but the +characteristics of the ADC peripherals vary slightly across +targets. To manage this, each target defines a small set of datatypes +expressing its capabilities (namely :ref:`adc_extsel_event +<adc-adc_extsel_event>`, :ref:`adc_smp_rate <adc-adc_smp_rate>`, and +:ref:`adc_prescaler <adc-adc_prescaler>`). + .. contents:: Contents :local: + :depth: 2 -Types ------ +Devices +------- + +The individual ADC peripherals have the following device struct. .. doxygenstruct:: adc_dev -.. doxygenstruct:: adc_reg_map -.. doxygenenum:: adc_extsel_event -.. doxygenenum:: adc_smp_rate -Devices -------- +The available ADC peripherals vary by target. The complete list is +``ADC1``, ``ADC2``, and ``ADC3``. .. doxygenvariable:: ADC1 .. doxygenvariable:: ADC2 @@ -27,189 +34,198 @@ Devices Functions --------- +Activation and Deactivation +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +``adc_enable_single_swstart()`` is simple, portable function, which +enables an ADC and sets it up for its basic usage: performing single +conversions using :ref:`adc_read() <adc-adc_read>`. + +.. _adc-adc_enable_single_swstart: +.. doxygenfunction:: adc_enable_single_swstart + +The precise software sequence used varies by target, so this is a good +function to use if your program needs to support multiple MCUs. By +default, Wirish calls ``adc_enable_single_swstart()`` on all available +ADCs at ``init()`` time, so Wirish users don't have to call this +function. + +There are several other lower-level routines used for activating and +deactivating ADCs: + +.. _adc-adc_init: .. doxygenfunction:: adc_init -.. doxygenfunction:: adc_calibrate -.. doxygenfunction:: adc_set_extsel +.. _adc-adc_enable: .. doxygenfunction:: adc_enable +.. _adc-adc_disable: .. doxygenfunction:: adc_disable +.. _adc-adc_disable_all: .. doxygenfunction:: adc_disable_all -.. doxygenfunction:: adc_foreach -.. doxygenfunction:: adc_set_sample_rate + +ADC Conversion +~~~~~~~~~~~~~~ + +``adc_read()`` is a simple function which starts conversion on a +single ADC channel, blocks until it has completed, and returns the +converted result. Don't use the ADC device for any other purpose while +it's running. + +.. _adc-adc_read: .. doxygenfunction:: adc_read + +To use ``adc_read()``, the device must be configured appropriately. +You can do this with :ref:`adc_enable_single_swstart() +<adc-adc_enable_single_swstart>`. + +Note that for an ADC device to perform conversion on a GPIO input +(which is the usual case; the notable exception being taking +temperature reading), the pin must be configured for analog +conversion. Do this with :ref:`adc_config_gpio() +<adc-adc_config_gpio>`. + +Other routines helpful for ADC conversion: + +.. _adc-adc_set_reg_seqlen: .. doxygenfunction:: adc_set_reg_seqlen -.. doxygenfunction:: adc_set_exttrig +.. _adc-adc_set_extsel: +.. doxygenfunction:: adc_set_extsel -Register Map Base Pointers --------------------------- +.. _adc-adc_extsel_event: -.. doxygendefine:: ADC1_BASE -.. doxygendefine:: ADC2_BASE -.. doxygendefine:: ADC3_BASE +The last of these, :ref:`adc_set_extsel() <adc-adc_set_extsel>`, takes +a target-dependent ``adc_extsel_event`` argument. -Register Bit Definitions ------------------------- +STM32F1 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f1::adc_extsel_event + +STM32F2 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f2::adc_extsel_event + +ADC Clock Prescaler +~~~~~~~~~~~~~~~~~~~ + +``adc_set_prescaler()`` is available for setting the prescaler which +determines the common ADC clock rate. (Wirish sets a sensible default +for this, so Wirish users ordinarily don't need to call this +function.) + +.. warning:: Increasing the ADC clock rate does speed conversion time, + but the ADC peripherals have a maximum clock rate which must not be + exceeded. Make sure to configure your system and ADC clocks to + respect your device's maximum rate. + +.. _adc_adc_set_prescaler: +.. doxygenfunction:: adc_set_prescaler -Status register +.. _adc-adc_prescaler: + +ADC prescaler values are target-dependent. + +STM32F1 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f1::adc_prescaler + +STM32F2 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f2::adc_prescaler + +.. _adc-adc_set_sample_rate: + +ADC Sample Time ~~~~~~~~~~~~~~~ -.. doxygendefine:: ADC_SR_AWD_BIT -.. doxygendefine:: ADC_SR_EOC_BIT -.. doxygendefine:: ADC_SR_JEOC_BIT -.. doxygendefine:: ADC_SR_JSTRT_BIT -.. doxygendefine:: ADC_SR_STRT_BIT - -.. doxygendefine:: ADC_SR_AWD -.. doxygendefine:: ADC_SR_EOC -.. doxygendefine:: ADC_SR_JEOC -.. doxygendefine:: ADC_SR_JSTRT -.. doxygendefine:: ADC_SR_STRT - -Control register 1 -~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: ADC_CR1_EOCIE_BIT -.. doxygendefine:: ADC_CR1_AWDIE_BIT -.. doxygendefine:: ADC_CR1_JEOCIE_BIT -.. doxygendefine:: ADC_CR1_SCAN_BIT -.. doxygendefine:: ADC_CR1_AWDSGL_BIT -.. doxygendefine:: ADC_CR1_JAUTO_BIT -.. doxygendefine:: ADC_CR1_DISCEN_BIT -.. doxygendefine:: ADC_CR1_JDISCEN_BIT -.. doxygendefine:: ADC_CR1_JAWDEN_BIT -.. doxygendefine:: ADC_CR1_AWDEN_BIT - -.. doxygendefine:: ADC_CR1_AWDCH -.. doxygendefine:: ADC_CR1_EOCIE -.. doxygendefine:: ADC_CR1_AWDIE -.. doxygendefine:: ADC_CR1_JEOCIE -.. doxygendefine:: ADC_CR1_SCAN -.. doxygendefine:: ADC_CR1_AWDSGL -.. doxygendefine:: ADC_CR1_JAUTO -.. doxygendefine:: ADC_CR1_DISCEN -.. doxygendefine:: ADC_CR1_JDISCEN -.. doxygendefine:: ADC_CR1_DISCNUM -.. doxygendefine:: ADC_CR1_JAWDEN -.. doxygendefine:: ADC_CR1_AWDEN - -Control register 2 -~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: ADC_CR2_ADON_BIT -.. doxygendefine:: ADC_CR2_CONT_BIT -.. doxygendefine:: ADC_CR2_CAL_BIT -.. doxygendefine:: ADC_CR2_RSTCAL_BIT -.. doxygendefine:: ADC_CR2_DMA_BIT -.. doxygendefine:: ADC_CR2_ALIGN_BIT -.. doxygendefine:: ADC_CR2_JEXTTRIG_BIT -.. doxygendefine:: ADC_CR2_EXTTRIG_BIT -.. doxygendefine:: ADC_CR2_JSWSTART_BIT -.. doxygendefine:: ADC_CR2_SWSTART_BIT -.. doxygendefine:: ADC_CR2_TSEREFE_BIT - -.. doxygendefine:: ADC_CR2_ADON -.. doxygendefine:: ADC_CR2_CONT -.. doxygendefine:: ADC_CR2_CAL -.. doxygendefine:: ADC_CR2_RSTCAL -.. doxygendefine:: ADC_CR2_DMA -.. doxygendefine:: ADC_CR2_ALIGN -.. doxygendefine:: ADC_CR2_JEXTSEL -.. doxygendefine:: ADC_CR2_JEXTTRIG -.. doxygendefine:: ADC_CR2_EXTSEL -.. doxygendefine:: ADC_CR2_EXTTRIG -.. doxygendefine:: ADC_CR2_JSWSTART -.. doxygendefine:: ADC_CR2_SWSTART -.. doxygendefine:: ADC_CR2_TSEREFE - -Sample time register 1 -~~~~~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: ADC_SMPR1_SMP17 -.. doxygendefine:: ADC_SMPR1_SMP16 -.. doxygendefine:: ADC_SMPR1_SMP15 -.. doxygendefine:: ADC_SMPR1_SMP14 -.. doxygendefine:: ADC_SMPR1_SMP13 -.. doxygendefine:: ADC_SMPR1_SMP12 -.. doxygendefine:: ADC_SMPR1_SMP11 -.. doxygendefine:: ADC_SMPR1_SMP10 - -Sample time register 2 -~~~~~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: ADC_SMPR2_SMP9 -.. doxygendefine:: ADC_SMPR2_SMP8 -.. doxygendefine:: ADC_SMPR2_SMP7 -.. doxygendefine:: ADC_SMPR2_SMP6 -.. doxygendefine:: ADC_SMPR2_SMP5 -.. doxygendefine:: ADC_SMPR2_SMP4 -.. doxygendefine:: ADC_SMPR2_SMP3 -.. doxygendefine:: ADC_SMPR2_SMP2 -.. doxygendefine:: ADC_SMPR2_SMP1 -.. doxygendefine:: ADC_SMPR2_SMP0 - -Injected channel data offset register -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: ADC_JOFR_JOFFSET - -Watchdog high threshold register -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: ADC_HTR_HT - -Watchdog low threshold register -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. doxygendefine:: ADC_LTR_LT - -Regular sequence register 1 -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +You can control the sampling time (in ADC cycles) for an entire ADC +device using ``adc_set_sample_rate()`` [#fchansamp]_. This function +**only controls the sample rate**; the total conversion time is equal +to the sample time plus an additional number of ADC cycles. Consult +the reference manual for your chip for more details. -.. doxygendefine:: ADC_SQR1_L -.. doxygendefine:: ADC_SQR1_SQ16 -.. doxygendefine:: ADC_SQR1_SQ15 -.. doxygendefine:: ADC_SQR1_SQ14 -.. doxygendefine:: ADC_SQR1_SQ13 +.. warning:: Decreasing ADC sample time speeds conversion, but it also + decreases the maximum allowable impedance of the voltage source you + are measuring. If your voltage source has a high impedance + (e.g. you're measuring Vcc through a potentiometer), and your + sample time is too low, you will get inaccurate results. Consult + the datasheet for your target for more details. -Regular sequence register 2 -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. note:: Wirish sets a sensible default sample rate to allow for + high-impedance inputs at ``init()`` time, but Wirish users who know + what they're doing may want to call this function to speed up ADC + conversion. -.. doxygendefine:: ADC_SQR2_SQ12 -.. doxygendefine:: ADC_SQR2_SQ11 -.. doxygendefine:: ADC_SQR2_SQ10 -.. doxygendefine:: ADC_SQR2_SQ9 -.. doxygendefine:: ADC_SQR2_SQ8 -.. doxygendefine:: ADC_SQR2_SQ7 +.. doxygenfunction:: adc_set_sample_rate -Regular sequence register 3 -~~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _adc-adc_smp_rate: + +The ``adc_smp_rate`` argument to :ref:`adc_set_sample_rate() +<adc-adc_set_sample_rate>` is target-dependent. + +STM32F1 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f1::adc_smp_rate + +STM32F2 Targets ++++++++++++++++ + +.. doxygenenum:: stm32f2::adc_smp_rate + +Miscellaneous +~~~~~~~~~~~~~ -.. doxygendefine:: ADC_SQR3_SQ6 -.. doxygendefine:: ADC_SQR3_SQ5 -.. doxygendefine:: ADC_SQR3_SQ4 -.. doxygendefine:: ADC_SQR3_SQ3 -.. doxygendefine:: ADC_SQR3_SQ2 -.. doxygendefine:: ADC_SQR3_SQ1 +.. FIXME [0.0.13] why don't adc_config_gpio()'s docs show up? -Injected sequence register -~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _adc-adc_foreach: +.. doxygenfunction:: adc_foreach + +.. _adc-adc_config_gpio: +.. doxygenfunction:: adc_config_gpio + +STM32F1 only +~~~~~~~~~~~~ + +The following routines are available only on STM32F1 targets. + +.. _adc-adc_set_exttrig: +.. doxygenfunction:: adc_set_exttrig + +``adc_calibrate()`` performs calibration necessary on STM32F1 before +using an ADC. Note that on STM32F1 targets, +:ref:`adc_enable_single_swstart() <adc-adc_enable_single_swstart>` +calls ``adc_calibrate()``, so there's no need to do it separately. + +.. _adc-adc_calibrate: +.. doxygenfunction:: adc_calibrate -.. doxygendefine:: ADC_JSQR_JL -.. doxygendefine:: ADC_JSQR_JL_1CONV -.. doxygendefine:: ADC_JSQR_JL_2CONV -.. doxygendefine:: ADC_JSQR_JL_3CONV -.. doxygendefine:: ADC_JSQR_JL_4CONV -.. doxygendefine:: ADC_JSQR_JSQ4 -.. doxygendefine:: ADC_JSQR_JSQ3 -.. doxygendefine:: ADC_JSQR_JSQ2 -.. doxygendefine:: ADC_JSQR_JSQ1 +Register Maps +------------- + +Individual ADC peripherals have the following register map. The base +pointers are ``ADC1_BASE``, ``ADC2_BASE``, and ``ADC3_BASE``. + +.. _adc-adc_reg_map: +.. doxygenstruct:: adc_reg_map + +On **STM32F2 targets**, there is an additional common set of registers +shared by all ADC peripherals. Its base pointer is +``ADC_COMMON_BASE``. + +.. _adc-adc_common_reg_map: +.. doxygenstruct:: stm32f2::adc_common_reg_map + +Register Bit Definitions +------------------------ -Injected data registers -~~~~~~~~~~~~~~~~~~~~~~~ +.. TODO [0.0.13] -.. doxygendefine:: ADC_JDR_JDATA +TODO -Regular data register -~~~~~~~~~~~~~~~~~~~~~ +.. rubric:: Footnotes -.. doxygendefine:: ADC_DR_ADC2DATA -.. doxygendefine:: ADC_DR_DATA +.. [#fchansamp] Per-channel sample time configuration is possible, + but currently unsupported. |