libmaple/api/stm32.rst: Updates for new APIs.

Updates from changes since last release.

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

1 files changed, 103 insertions, 15 deletions

diff --git a/source/libmaple/api/stm32.rst b/source/libmaple/api/stm32.rst
index 0e45990..4a4ee6c 100644
--- a/source/libmaple/api/stm32.rst
+++ b/source/libmaple/api/stm32.rst
@@ -1,29 +1,117 @@
 .. highlight:: c
 .. _libmaple-stm32:
 
-``stm32.h``
-===========
+``<libmaple/stm32.h>``
+======================
 
-General STM32-specific definitions.  This file is currently somewhat
-incomplete, but it will form the future basis for MCU-specific (rather
-than board-specific, which belongs in :ref:`Wirish
-<libmaple-vs-wirish>`) configuration.
+STM32 chip header. This header supplies various series-specific and
+chip-specific macros for the current build target.  It's useful both
+to abstract away hardware details (e.g. through use of
+:ref:`STM32_NR_INTERRUPTS <libmaple-stm32-STM32_NR_INTERRUPTS>`) and
+to decide what to do when you want something nonportable (e.g. by
+checking :ref:`STM32_MCU_SERIES <libmaple-stm32-STM32_MCU_SERIES>`).
 
-Defines
--------
+.. contents:: Contents
+   :local:
+
+Determining the Target Series
+-----------------------------
+
+The STM32 series (e.g. STM32F1, STM32F2, etc.) of the current target
+can be inspected with ``STM32_MCU_SERIES``.
+
+.. _libmaple-stm32-STM32_MCU_SERIES:
+.. doxygendefine:: STM32_MCU_SERIES
+
+Allowed values for ``STM32_MCU_SERIES`` are the following. This set is
+expected to grow over time.
+
+.. doxygendefine:: STM32_SERIES_F1
+.. doxygendefine:: STM32_SERIES_F2
+.. doxygendefine:: STM32_SERIES_L1
+.. doxygendefine:: STM32_SERIES_F4
+
+Series-Specific Characteristics
+-------------------------------
+
+The macros in this section are only available on some STM32 series.
+
+STM32F1
+~~~~~~~
+
+.. note:: These macros are only available when the current target is
+          an STM32F1 series MCU (i.e., when :ref:`STM32_MCU_SERIES
+          <libmaple-stm32-STM32_MCU_SERIES>` is ``STM32_SERIES_F1``).
+
+The STM32F1 series is further subdivided into :ref:`lines
+<stm32-series-f1-lines>`. The line of the current target can be
+inspected with ``STM32_F1_LINE``.
+
+.. doxygendefine:: STM32_F1_LINE
+
+There are five STM32F1 lines. The corresponding values
+``STM32_F1_LINE`` can take are the following, though libmaple doesn't
+currently support all of them.
+
+.. doxygendefine:: STM32_F1_LINE_VALUE
+.. doxygendefine:: STM32_F1_LINE_ACCESS
+.. doxygendefine:: STM32_F1_LINE_USB_ACCESS
+.. doxygendefine:: STM32_F1_LINE_PERFORMANCE
+.. doxygendefine:: STM32_F1_LINE_CONNECTIVITY
+
+MCU Feature Tests
+-----------------
+
+The following defines can be used to determine if the target MCU has
+a particular feature.
+
+.. doxygendefine:: STM32_HAVE_FSMC
+.. doxygendefine:: STM32_HAVE_USB
+
+MCU Characteristics
+-------------------
+
+The following defines give salient characteristics of the target MCU.
+
+.. doxygendefine:: STM32_NR_GPIO_PORTS
+.. _libmaple-stm32-STM32_NR_INTERRUPTS:
+.. doxygendefine:: STM32_NR_INTERRUPTS
+.. doxygendefine:: STM32_SRAM_END
+
+Clock Speeds
+------------
+
+The macros in this section are related to clock rates.  As such, they
+are really part of the configuration of the MCU, rather than inherent
+characteristics of the MCU itself.  For instance, it's possible to
+change the PCLK1 and PCLK2 clock rates by reconfiguring the :ref:`RCC
+<libmaple-rcc>`. libmaple proper never changes any clock rates, but it
+does have APIs for doing so (such as :ref:`rcc_configure_pll()
+<libmaple-rcc-rcc_configure_pll>`). Because of this, be careful when
+using the macros in this section, as they assume that some values are
+constant which in fact may be changed.
+
+The values these macros actually take are typically the maximum values
+supported by the MCU. Since these are their actual values in practice
+(at least in LeafLabs' current use cases, which have the chips running
+as fast as possible), they're still considered useful.
 
 .. doxygendefine:: STM32_PCLK1
 .. doxygendefine:: STM32_PCLK2
-.. doxygendefine:: STM32_NR_INTERRUPTS
-.. doxygendefine:: STM32_NR_GPIO_PORTS
+
+The following macro, ``STM32_DELAY_US_MULT``, is a libmaple
+implementation detail. It was included in this public API page in a
+previous release by mistake, and is not deprecated, but using it in
+your own code is a bad idea.
+
 .. doxygendefine:: STM32_DELAY_US_MULT
-.. doxygendefine:: STM32_SRAM_END
 
-.. _libmaple-stm32-STM32_MCU_SERIES:
-.. doxygendefine:: STM32_MCU_SERIES
+Deprecated Macros
+-----------------
 
-Deprecated Defines
-------------------
+.. warning:: The macros in this section are deprecated, and are
+             available for backwards compatibility only. Do not use
+             them in new code.
 
 .. doxygendefine:: PCLK1
 .. doxygendefine:: PCLK2