(Mostly) update <libmaple/adc.h> page.

Still undone:

- resolve Breathe/Doxygen/whatever bug that keeps adc_config_gpio()
  docs from showing up

- add register bit definitions

Signed-off-by: Marti Bolivar <mbolivar@leaflabs.com>

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.