Update <libmaple/fsmc.h> page.

No API changes (new stuff was ported as-is to STM32F2), but more
explanatory text.

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

1 files changed, 197 insertions, 151 deletions

diff --git a/source/libmaple/api/fsmc.rst b/source/libmaple/api/fsmc.rst
index 3b356cc..e2bf87a 100644
--- a/source/libmaple/api/fsmc.rst
+++ b/source/libmaple/api/fsmc.rst
@@ -1,19 +1,43 @@
 .. highlight:: c
 .. _libmaple-fsmc:
 
-``fsmc.h``
-==========
+``<libmaple/fsmc.h>``
+=====================
 
-Flexible Static Memory Controller (FSMC) support.
+Flexible Static Memory Controller (FSMC) support. The FSMC peripheral
+is only available on some targets.  Including this header on a target
+without an FSMC will cause a compilation error.  Check your target's
+documentation to determine if it's available.  You can also use
+:ref:`STM32_HAVE_FSMC <libmaple-stm32-STM32_HAVE_FSMC>` from
+``<libmaple/stm32.h>`` to determine whether your target has an FSMC at
+build time.
+
+All functionality documented here is portable.
 
 .. contents:: Contents
    :local:
 
-Types
------
+Usage Note
+----------
 
-.. doxygenstruct:: fsmc_reg_map
-.. doxygenstruct:: fsmc_nor_psram_reg_map
+FSMC support is fairly limited at this time. Current Leaflabs boards
+only use the FSMC to interface with external SRAM chips, so that's
+what there's the most support for (:ref:`patches welcome!
+<libmaple-contributing>`). Even for use with SRAM, you will still need
+to program some registers directly.
+
+To use the FSMC with an SRAM chip, first call
+:ref:`fsmc_sram_init_gpios() <libmaple-fsmc-fsmc_sram_init_gpios>` to
+configure its data, address, and control lines.  Then, turn on the
+FSMC clock (by calling :ref:`rcc_clk_enable(RCC_FSMC)
+<libmaple-rcc-rcc_clk_enable>`). You can then configure the relevant
+:ref:`fsmc_nor_psram_reg_map <libmaple-fsmc-fsmc_nor_psram_reg_map>`
+``BCR`` register yourself for the SRAM chip you are using.
+
+You can additionally use :ref:`fsmc_nor_psram_set_datast()
+<libmaple-fsmc-fsmc_nor_psram_set_datast>` and
+:ref:`fsmc_nor_psram_set_datast() <libmaple-fsmc-fsmc_nor_psram_set_datast>`
+to control read/write timing.
 
 Devices
 -------
@@ -23,13 +47,49 @@ None at this time.
 Functions
 ---------
 
+.. _libmaple-fsmc-fsmc_sram_init_gpios:
 .. doxygenfunction:: fsmc_sram_init_gpios
+.. _libmaple-fsmc-fsmc_nor_psram_set_datast:
 .. doxygenfunction:: fsmc_nor_psram_set_datast
+.. _libmaple-fsmc-fsmc_nor_psram_set_addset:
 .. doxygenfunction:: fsmc_nor_psram_set_addset
 
+Register Maps
+-------------
+
+The general purpose register map type is ``fsmc_reg_map``; its base
+pointer is ``FSMC_BASE``.  The ``fsmc_nor_psram_reg_map`` type is for
+use configuring the registers for an individual NOR/PSRAM region
+(``FSMC_BCRx``, ``FSMC_BTRx``, and ``FSMC_BWTRx``); the relevant base
+pointers are ``FSMC_NOR_PSRAM_REGION1`` through
+``FSMC_NOR_PSRAM_REGION4``.
+
+.. doxygendefine:: FSMC_BASE
+
+.. doxygendefine:: FSMC_NOR_PSRAM1_BASE
+.. doxygendefine:: FSMC_NOR_PSRAM2_BASE
+.. doxygendefine:: FSMC_NOR_PSRAM3_BASE
+.. doxygendefine:: FSMC_NOR_PSRAM4_BASE
+
+.. doxygenstruct:: fsmc_reg_map
+.. _libmaple-fsmc-fsmc_nor_psram_reg_map:
+.. doxygenstruct:: fsmc_nor_psram_reg_map
+
 Memory Bank Boundary Addresses
 ------------------------------
 
+Reading and writing data on an external memory chip using FSMC is done
+by reading and writing from addresses in special memory-mapped
+sections of the address space called *memory banks*.
+
+This is convenient, since it implies that the usual load and store
+instructions used for I/O with the internal SRAM are also used to
+perform bus transactions with the external memory chip.  (Which means
+you can use ``memcpy()`` etc. on external memory.)
+
+Pointers to the memory banks' base addresses are given by the
+following macros.
+
 .. doxygendefine:: FSMC_BANK1
 .. doxygendefine:: FSMC_BANK2
 .. doxygendefine:: FSMC_BANK3
@@ -40,150 +100,136 @@ Memory Bank Boundary Addresses
 .. doxygendefine:: FSMC_NOR_PSRAM_REGION3
 .. doxygendefine:: FSMC_NOR_PSRAM_REGION4
 
-Register Map Base Pointers
---------------------------
-
-.. doxygendefine:: FSMC_BASE
-
-.. doxygendefine:: FSMC_NOR_PSRAM1_BASE
-.. doxygendefine:: FSMC_NOR_PSRAM2_BASE
-.. doxygendefine:: FSMC_NOR_PSRAM3_BASE
-.. doxygendefine:: FSMC_NOR_PSRAM4_BASE
-
 Register Bit Definitions
 ------------------------
 
-NOR/PSRAM Chip-Select Control Registers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. doxygendefine:: FSMC_BCR_CBURSTRW_BIT
-.. doxygendefine:: FSMC_BCR_ASYNCWAIT_BIT
-.. doxygendefine:: FSMC_BCR_EXTMOD_BIT
-.. doxygendefine:: FSMC_BCR_WAITEN_BIT
-.. doxygendefine:: FSMC_BCR_WREN_BIT
-.. doxygendefine:: FSMC_BCR_WAITCFG_BIT
-.. doxygendefine:: FSMC_BCR_WRAPMOD_BIT
-.. doxygendefine:: FSMC_BCR_WAITPOL_BIT
-.. doxygendefine:: FSMC_BCR_BURSTEN_BIT
-.. doxygendefine:: FSMC_BCR_FACCEN_BIT
-.. doxygendefine:: FSMC_BCR_MUXEN_BIT
-.. doxygendefine:: FSMC_BCR_MBKEN_BIT
-
-.. doxygendefine:: FSMC_BCR_CBURSTRW
-.. doxygendefine:: FSMC_BCR_ASYNCWAIT
-.. doxygendefine:: FSMC_BCR_EXTMOD
-.. doxygendefine:: FSMC_BCR_WAITEN
-.. doxygendefine:: FSMC_BCR_WREN
-.. doxygendefine:: FSMC_BCR_WAITCFG
-.. doxygendefine:: FSMC_BCR_WRAPMOD
-.. doxygendefine:: FSMC_BCR_WAITPOL
-.. doxygendefine:: FSMC_BCR_BURSTEN
-.. doxygendefine:: FSMC_BCR_FACCEN
-.. doxygendefine:: FSMC_BCR_MWID
-.. doxygendefine:: FSMC_BCR_MWID_8BITS
-.. doxygendefine:: FSMC_BCR_MWID_16BITS
-.. doxygendefine:: FSMC_BCR_MTYP
-.. doxygendefine:: FSMC_BCR_MTYP_SRAM
-.. doxygendefine:: FSMC_BCR_MTYP_PSRAM
-.. doxygendefine:: FSMC_BCR_MTYP_NOR_FLASH
-.. doxygendefine:: FSMC_BCR_MUXEN
-.. doxygendefine:: FSMC_BCR_MBKEN
-
-SRAM/NOR-Flash Chip-Select Timing Registers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. doxygendefine:: FSMC_BTR_ACCMOD
-.. doxygendefine:: FSMC_BTR_ACCMOD_A
-.. doxygendefine:: FSMC_BTR_ACCMOD_B
-.. doxygendefine:: FSMC_BTR_ACCMOD_C
-.. doxygendefine:: FSMC_BTR_ACCMOD_D
-.. doxygendefine:: FSMC_BTR_DATLAT
-.. doxygendefine:: FSMC_BTR_CLKDIV
-.. doxygendefine:: FSMC_BTR_BUSTURN
-.. doxygendefine:: FSMC_BTR_DATAST
-.. doxygendefine:: FSMC_BTR_ADDHLD
-.. doxygendefine:: FSMC_BTR_ADDSET
-
-SRAM/NOR-Flash Write Timing Registers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. doxygendefine:: FSMC_BWTR_ACCMOD
-.. doxygendefine:: FSMC_BWTR_ACCMOD_A
-.. doxygendefine:: FSMC_BWTR_ACCMOD_B
-.. doxygendefine:: FSMC_BWTR_ACCMOD_C
-.. doxygendefine:: FSMC_BWTR_ACCMOD_D
-.. doxygendefine:: FSMC_BWTR_DATLAT
-.. doxygendefine:: FSMC_BWTR_CLKDIV
-.. doxygendefine:: FSMC_BWTR_DATAST
-.. doxygendefine:: FSMC_BWTR_ADDHLD
-.. doxygendefine:: FSMC_BWTR_ADDSET
-
-NAND Flash/PC Card Controller Registers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. doxygendefine:: FSMC_PCR_ECCEN_BIT
-.. doxygendefine:: FSMC_PCR_PTYP_BIT
-.. doxygendefine:: FSMC_PCR_PBKEN_BIT
-.. doxygendefine:: FSMC_PCR_PWAITEN_BIT
-
-.. doxygendefine:: FSMC_PCR_ECCPS
-.. doxygendefine:: FSMC_PCR_ECCPS_256B
-.. doxygendefine:: FSMC_PCR_ECCPS_512B
-.. doxygendefine:: FSMC_PCR_ECCPS_1024B
-.. doxygendefine:: FSMC_PCR_ECCPS_2048B
-.. doxygendefine:: FSMC_PCR_ECCPS_4096B
-.. doxygendefine:: FSMC_PCR_ECCPS_8192B
-.. doxygendefine:: FSMC_PCR_TAR
-.. doxygendefine:: FSMC_PCR_TCLR
-.. doxygendefine:: FSMC_PCR_ECCEN
-.. doxygendefine:: FSMC_PCR_PWID
-.. doxygendefine:: FSMC_PCR_PWID_8BITS
-.. doxygendefine:: FSMC_PCR_PWID_16BITS
-.. doxygendefine:: FSMC_PCR_PTYP
-.. doxygendefine:: FSMC_PCR_PTYP_PC_CF_PCMCIA
-.. doxygendefine:: FSMC_PCR_PTYP_NAND
-.. doxygendefine:: FSMC_PCR_PBKEN
-.. doxygendefine:: FSMC_PCR_PWAITEN
-
-FIFO Status And Interrupt Registers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. doxygendefine:: FSMC_SR_FEMPT_BIT
-.. doxygendefine:: FSMC_SR_IFEN_BIT
-.. doxygendefine:: FSMC_SR_ILEN_BIT
-.. doxygendefine:: FSMC_SR_IREN_BIT
-.. doxygendefine:: FSMC_SR_IFS_BIT
-.. doxygendefine:: FSMC_SR_ILS_BIT
-.. doxygendefine:: FSMC_SR_IRS_BIT
-
-.. doxygendefine:: FSMC_SR_FEMPT
-.. doxygendefine:: FSMC_SR_IFEN
-.. doxygendefine:: FSMC_SR_ILEN
-.. doxygendefine:: FSMC_SR_IREN
-.. doxygendefine:: FSMC_SR_IFS
-.. doxygendefine:: FSMC_SR_ILS
-.. doxygendefine:: FSMC_SR_IRS
-
-Common Memory Space Timing Registers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. doxygendefine:: FSMC_PMEM_MEMHIZ
-.. doxygendefine:: FSMC_PMEM_MEMHOLD
-.. doxygendefine:: FSMC_PMEM_MEMWAIT
-.. doxygendefine:: FSMC_PMEM_MEMSET
-
-Attribute Memory Space Timing Registers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. doxygendefine:: FSMC_PATT_ATTHIZ
-.. doxygendefine:: FSMC_PATT_ATTHOLD
-.. doxygendefine:: FSMC_PATT_ATTWAIT
-.. doxygendefine:: FSMC_PATT_ATTSET
-
-I/O Space Timing Register 4
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-.. doxygendefine:: FSMC_PIO_IOHIZ
-.. doxygendefine:: FSMC_PIO_IOHOLD
-.. doxygendefine:: FSMC_PIO_IOWAIT
-.. doxygendefine:: FSMC_PIO_IOSET
+These are given as source code.
+
+::
+
+    /* NOR/PSRAM chip-select control registers */
+
+    #define FSMC_BCR_CBURSTRW_BIT           19
+    #define FSMC_BCR_ASYNCWAIT_BIT          15
+    #define FSMC_BCR_EXTMOD_BIT             14
+    #define FSMC_BCR_WAITEN_BIT             13
+    #define FSMC_BCR_WREN_BIT               12
+    #define FSMC_BCR_WAITCFG_BIT            11
+    #define FSMC_BCR_WRAPMOD_BIT            10
+    #define FSMC_BCR_WAITPOL_BIT            9
+    #define FSMC_BCR_BURSTEN_BIT            8
+    #define FSMC_BCR_FACCEN_BIT             6
+    #define FSMC_BCR_MUXEN_BIT              1
+    #define FSMC_BCR_MBKEN_BIT              0
+
+    #define FSMC_BCR_CBURSTRW               (1U << FSMC_BCR_CBURSTRW_BIT)
+    #define FSMC_BCR_ASYNCWAIT              (1U << FSMC_BCR_ASYNCWAIT_BIT)
+    #define FSMC_BCR_EXTMOD                 (1U << FSMC_BCR_EXTMOD_BIT)
+    #define FSMC_BCR_WAITEN                 (1U << FSMC_BCR_WAITEN_BIT)
+    #define FSMC_BCR_WREN                   (1U << FSMC_BCR_WREN_BIT)
+    #define FSMC_BCR_WAITCFG                (1U << FSMC_BCR_WAITCFG_BIT)
+    #define FSMC_BCR_WRAPMOD                (1U << FSMC_BCR_WRAPMOD_BIT)
+    #define FSMC_BCR_WAITPOL                (1U << FSMC_BCR_WAITPOL_BIT)
+    #define FSMC_BCR_BURSTEN                (1U << FSMC_BCR_BURSTEN_BIT)
+    #define FSMC_BCR_FACCEN                 (1U << FSMC_BCR_FACCEN_BIT)
+    #define FSMC_BCR_MWID                   (0x3 << 4)
+    #define FSMC_BCR_MWID_8BITS             (0x0 << 4)
+    #define FSMC_BCR_MWID_16BITS            (0x1 << 4)
+    #define FSMC_BCR_MTYP                   (0x3 << 2)
+    #define FSMC_BCR_MTYP_SRAM              (0x0 << 2)
+    #define FSMC_BCR_MTYP_PSRAM             (0x1 << 2)
+    #define FSMC_BCR_MTYP_NOR_FLASH         (0x2 << 2)
+    #define FSMC_BCR_MUXEN                  (1U << FSMC_BCR_MUXEN_BIT)
+    #define FSMC_BCR_MBKEN                  (1U << FSMC_BCR_MBKEN_BIT)
+
+    /* SRAM/NOR-Flash chip-select timing registers */
+
+    #define FSMC_BTR_ACCMOD                 (0x3 << 28)
+    #define FSMC_BTR_ACCMOD_A               (0x0 << 28)
+    #define FSMC_BTR_ACCMOD_B               (0x1 << 28)
+    #define FSMC_BTR_ACCMOD_C               (0x2 << 28)
+    #define FSMC_BTR_ACCMOD_D               (0x3 << 28)
+    #define FSMC_BTR_DATLAT                 (0xF << 24)
+    #define FSMC_BTR_CLKDIV                 (0xF << 20)
+    #define FSMC_BTR_BUSTURN                (0xF << 16)
+    #define FSMC_BTR_DATAST                 (0xFF << 8)
+    #define FSMC_BTR_ADDHLD                 (0xF << 4)
+    #define FSMC_BTR_ADDSET                 0xF
+
+    /* SRAM/NOR-Flash write timing registers */
+
+    #define FSMC_BWTR_ACCMOD                 (0x3 << 28)
+    #define FSMC_BWTR_ACCMOD_A               (0x0 << 28)
+    #define FSMC_BWTR_ACCMOD_B               (0x1 << 28)
+    #define FSMC_BWTR_ACCMOD_C               (0x2 << 28)
+    #define FSMC_BWTR_ACCMOD_D               (0x3 << 28)
+    #define FSMC_BWTR_DATLAT                 (0xF << 24)
+    #define FSMC_BWTR_CLKDIV                 (0xF << 20)
+    #define FSMC_BWTR_DATAST                 (0xFF << 8)
+    #define FSMC_BWTR_ADDHLD                 (0xF << 4)
+    #define FSMC_BWTR_ADDSET                 0xF
+
+    /* NAND Flash/PC Card controller registers */
+
+    #define FSMC_PCR_ECCEN_BIT               6
+    #define FSMC_PCR_PTYP_BIT                3
+    #define FSMC_PCR_PBKEN_BIT               2
+    #define FSMC_PCR_PWAITEN_BIT             1
+
+    #define FSMC_PCR_ECCPS                   (0x7 << 17)
+    #define FSMC_PCR_ECCPS_256B              (0x0 << 17)
+    #define FSMC_PCR_ECCPS_512B              (0x1 << 17)
+    #define FSMC_PCR_ECCPS_1024B             (0x2 << 17)
+    #define FSMC_PCR_ECCPS_2048B             (0x3 << 17)
+    #define FSMC_PCR_ECCPS_4096B             (0x4 << 17)
+    #define FSMC_PCR_ECCPS_8192B             (0x5 << 17)
+    #define FSMC_PCR_TAR                     (0xF << 13)
+    #define FSMC_PCR_TCLR                    (0xF << 9)
+    #define FSMC_PCR_ECCEN                   (1U << FSMC_PCR_ECCEN_BIT)
+    #define FSMC_PCR_PWID                    (0x3 << 4)
+    #define FSMC_PCR_PWID_8BITS              (0x0 << 4)
+    #define FSMC_PCR_PWID_16BITS             (0x1 << 4)
+    #define FSMC_PCR_PTYP                    (1U << FSMC_PCR_PTYP_BIT)
+    #define FSMC_PCR_PTYP_PC_CF_PCMCIA       (0x0 << FSMC_PCR_PTYP_BIT)
+    #define FSMC_PCR_PTYP_NAND               (0x1 << FSMC_PCR_PTYP_BIT)
+    #define FSMC_PCR_PBKEN                   (1U << FSMC_PCR_PBKEN_BIT)
+    #define FSMC_PCR_PWAITEN                 (1U << FSMC_PCR_PWAITEN_BIT)
+
+    /* FIFO status and interrupt registers */
+
+    #define FSMC_SR_FEMPT_BIT                6
+    #define FSMC_SR_IFEN_BIT                 5
+    #define FSMC_SR_ILEN_BIT                 4
+    #define FSMC_SR_IREN_BIT                 3
+    #define FSMC_SR_IFS_BIT                  2
+    #define FSMC_SR_ILS_BIT                  1
+    #define FSMC_SR_IRS_BIT                  0
+
+    #define FSMC_SR_FEMPT                    (1U << FSMC_SR_FEMPT_BIT)
+    #define FSMC_SR_IFEN                     (1U << FSMC_SR_IFEN_BIT)
+    #define FSMC_SR_ILEN                     (1U << FSMC_SR_ILEN_BIT)
+    #define FSMC_SR_IREN                     (1U << FSMC_SR_IREN_BIT)
+    #define FSMC_SR_IFS                      (1U << FSMC_SR_IFS_BIT)
+    #define FSMC_SR_ILS                      (1U << FSMC_SR_ILS_BIT)
+    #define FSMC_SR_IRS                      (1U << FSMC_SR_IRS_BIT)
+
+    /* Common memory space timing registers */
+
+    #define FSMC_PMEM_MEMHIZ                 (0xFF << 24)
+    #define FSMC_PMEM_MEMHOLD                (0xFF << 16)
+    #define FSMC_PMEM_MEMWAIT                (0xFF << 8)
+    #define FSMC_PMEM_MEMSET                 0xFF
+
+    /* Attribute memory space timing registers */
+
+    #define FSMC_PATT_ATTHIZ                 (0xFF << 24)
+    #define FSMC_PATT_ATTHOLD                (0xFF << 16)
+    #define FSMC_PATT_ATTWAIT                (0xFF << 8)
+    #define FSMC_PATT_ATTSET                 0xFF
+
+    /* I/O space timing register 4 */
+
+    #define FSMC_PIO_IOHIZ                  (0xFF << 24)
+    #define FSMC_PIO_IOHOLD                 (0xFF << 16)
+    #define FSMC_PIO_IOWAIT                 (0xFF << 8)
+    #define FSMC_PIO_IOSET                  0xF