stm32: quadspi overhaul documentation

Provide all doxygen framework boilerplate. Provide a very initial stub .c file to ensure that heirarchical headers are pulled in properly.
2021-01-29 12:59:55 +00:00 · 2021-01-29 12:59:55 +00:00 · ca479ad7d2
parent 2daef7c3ec
commit ca479ad7d2
6 changed files with 98 additions and 104 deletions
--- a/include/libopencm3/stm32/common/quadspi_common_v1.h
+++ b/include/libopencm3/stm32/common/quadspi_common_v1.h
@ -1,35 +1,56 @@
-/*
- * This file is part of the libopencm3 project.
- *
- * Copyright (C) 2016, Chuck McManis <cmcmanis@mcmanis.com>
- *
- * This library is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This library is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this library.  If not, see <http://www.gnu.org/licenses/>.
+/** @addtogroup quadspi_defines
+ * @author Chuck McManis <cmcmanis@mcmanis.com> 2016
+ * @copyright SPDX: LGPL-3.0-or-later
+ * @{
 */

-/* THIS FILE SHOULD NOT BE INCLUDED DIRECTLY, BUT ONLY VIA quadspi.h
-The order of header inclusion is important. quadspi.h includes the device
-specific memorymap.h header before including this header file.*/
+#pragma once

-/** @cond */
-#ifdef LIBOPENCM3_QUADSPI_H
-/** @endcond */
-#ifndef LIBOPENCM3_QUADSPI_COMMON_V1_H
-#define LIBOPENCM3_QUADSPI_COMMON_V1_H
-
-/* QUADSPI Control register */
+/** @addtogroup quadspi_registers QuadSPI Registers
+ * @{
+ */
+/** QUADSPI Control register */
 #define QUADSPI_CR      MMIO32(QUADSPI_BASE + 0x0U)

+/** QUADSPI Device Configuration */
+#define QUADSPI_DCR     MMIO32(QUADSPI_BASE + 0x4U)
+
+/** QUADSPI Status Register */
+#define QUADSPI_SR      MMIO32(QUADSPI_BASE + 0x8U)
+
+/** QUADSPI Flag Clear Register */
+#define QUADSPI_FCR     MMIO32(QUADSPI_BASE + 0xCU)
+
+/** QUADSPI Data Length Register */
+#define QUADSPI_DLR     MMIO32(QUADSPI_BASE + 0x10U)
+
+/** QUADSPI Communication Configuration Register */
+#define QUADSPI_CCR     MMIO32(QUADSPI_BASE + 0x14U)
+
+/** QUADSPI address register */
+#define QUADSPI_AR      MMIO32(QUADSPI_BASE + 0x18U)
+
+/** QUADSPI alternate bytes register */
+#define QUADSPI_ABR     MMIO32(QUADSPI_BASE + 0x1CU)
+
+/** QUADSPI data register */
+#define QUADSPI_DR      MMIO32(QUADSPI_BASE + 0x20U)
+/** BYTE addressable version for fetching bytes from the interface */
+#define QUADSPI_BYTE_DR     MMIO8(QUADSPI_BASE + 0x20U)
+
+/** QUADSPI polling status */
+#define QUADSPI_PSMKR     MMIO32(QUADSPI_BASE + 0x24U)
+
+/** QUADSPI polling status match */
+#define QUADSPI_PSMAR     MMIO32(QUADSPI_BASE + 0x28U)
+
+/** QUADSPI polling interval register */
+#define QUADSPI_PIR     MMIO32(QUADSPI_BASE + 0x2CU)
+
+/** QUADSPI low power timeout */
+#define QUADSPI_LPTR      MMIO32(QUADSPI_BASE + 0x30U
+/**@}*/
+
 #define QUADSPI_CR_PRESCALE_MASK  0xff
 #define QUADSPI_CR_PRESCALE_SHIFT 24
 #define QUADSPI_CR_PMM      (1 << 23)
@ -53,9 +74,6 @@ specific memorymap.h header before including this header file.*/
 #define QUADSPI_CR_ABORT    (1 << 1)
 #define QUADSPI_CR_EN     (1 << 0)

-/* QUADSPI Device Configuration */
-#define QUADSPI_DCR     MMIO32(QUADSPI_BASE + 0x4U)
-
 /* bits 31:21 reserved */
 #define QUADSPI_DCR_FSIZE_MASK    0x1f
 #define QUADSPI_DCR_FSIZE_SHIFT   16
@ -65,9 +83,6 @@ specific memorymap.h header before including this header file.*/
 /* bits 7:1 reserved */
 #define QUADSPI_DCR_CKMODE    (1 << 0)

-/* QUADSPI Status Register */
-#define QUADSPI_SR      MMIO32(QUADSPI_BASE + 0x8U)
-
 /* bits 31:14 reserved */
 #define QUADSPI_SR_FLEVEL_MASK    0x3f
 #define QUADSPI_SR_FLEVEL_SHIFT   8
@ -80,9 +95,6 @@ specific memorymap.h header before including this header file.*/
 #define QUADSPI_SR_TCF      (1 << 1)
 #define QUADSPI_SR_TEF      (1 << 0)

-/* QUADSPI Flag Clear Register */
-#define QUADSPI_FCR     MMIO32(QUADSPI_BASE + 0xCU)
-
 /* bits 31:5 reserved */
 #define QUADSPI_FCR_CTOF    (1 << 4)
 #define QUADSPI_FCR_CSMF    (1 << 3)
@ -90,12 +102,6 @@ specific memorymap.h header before including this header file.*/
 #define QUADSPI_FCR_CTCF    (1 << 1)
 #define QUADSPI_FCR_CTEF    (1 << 0)

-/* QUADSPI Data Length Register */
-#define QUADSPI_DLR     MMIO32(QUADSPI_BASE + 0x10U)
-
-/* QUADSPI Communication Configuration Register */
-#define QUADSPI_CCR     MMIO32(QUADSPI_BASE + 0x14U)
-
 #define QUADSPI_CCR_DDRM    (1 << 31)
 #define QUADSPI_CCR_DHHC    (1 << 30)
 /* bit 29 reserved on F4, FRCM on H7 */
@ -138,33 +144,32 @@ specific memorymap.h header before including this header file.*/
 #define QUADSPI_CCR_FMODE_APOLL   2
 #define QUADSPI_CCR_FMODE_MEMMAP  3

+/**@}*/

-/* QUADSPI address register */
-#define QUADSPI_AR      MMIO32(QUADSPI_BASE + 0x18U)

-/* QUADSPI alternate bytes register */
-#define QUADSPI_ABR     MMIO32(QUADSPI_BASE + 0x1CU)
+/**
+ * @defgroup quadspi_file QuadSPI peripheral API
+ * @brief APIs for the specialized SPI Flash peripheral
+ * @ingroup peripheral_apis
+ * @copyright SPDX: LGPL-3.0-or-later
+ *
+ * The QUADSPI is a specialized communication interface targeting single,
+ * dual or quad SPI Flash memories
+ * @{
+ */

-/* QUADSPI data register */
-#define QUADSPI_DR      MMIO32(QUADSPI_BASE + 0x20U)
-/* BYTE addressable version for fetching bytes from the interface */
-#define QUADSPI_BYTE_DR     MMIO8(QUADSPI_BASE + 0x20U)
+BEGIN_DECLS

-/* QUADSPI polling status */
-#define QUADSPI_PSMKR     MMIO32(QUADSPI_BASE + 0x24U)
+/**
+ * Enable the quadspi peripheral.
+ */
+void quadspi_enable(void);

-/* QUADSPI polling status match */
-#define QUADSPI_PSMAR     MMIO32(QUADSPI_BASE + 0x28U)
+/**
+ * Disable the quadspi peripheral.
+ */
+void quadspi_disable(void);

-/* QUADSPI polling interval register */
-#define QUADSPI_PIR     MMIO32(QUADSPI_BASE + 0x2CU)
+END_DECLS

-/* QUADSPI low power timeout */
-#define QUADSPI_LPTR      MMIO32(QUADSPI_BASE + 0x30U
-
-#endif
-/** @cond */
-#else
-#warning "quadspi_common_v1.h should not be included directly, only via quadspi.h"
-#endif
-/** @endcond */
+/**@}*/
--- a/include/libopencm3/stm32/f4/quadspi.h
+++ b/include/libopencm3/stm32/f4/quadspi.h
@ -1,29 +1,15 @@
-/*
- * STM32F4 Quad SPI defines
- *
- * This file is part of the libopencm3 project.
- *
- * This library is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This library is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this library.  If not, see <http://www.gnu.org/licenses/>.
- *
+/** @defgroup quadspi_defines QuadSPI Defines
+ * @brief Defined constants and types for the STM32F4 QuadSPI peripheral
+ * @ingroup STM32F4xx_defines
+ * @copyright SPDX: LGPL-3.0-or-later
+ * @{
 */

-#ifndef LIBOPENCM3_QUADSPI_H
-#define LIBOPENCM3_QUADSPI_H
+#pragma once

 #include <libopencm3/stm32/memorymap.h>
 #include <libopencm3/stm32/common/quadspi_common_v1.h>

 #define QUADSPI_CR_DMAEN    (1 << 2)

-#endif  /* LIBOPENCM3_QUADSPI_H */
+/**@}*/
--- a/include/libopencm3/stm32/h7/quadspi.h
+++ b/include/libopencm3/stm32/h7/quadspi.h
@ -1,22 +1,11 @@
-/*
- * This file is part of the libopencm3 project.
- *
- * This library is free software: you can redistribute it and/or modify
- * it under the terms of the GNU Lesser General Public License as published by
- * the Free Software Foundation, either version 3 of the License, or
- * (at your option) any later version.
- *
- * This library is distributed in the hope that it will be useful,
- * but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- * GNU Lesser General Public License for more details.
- *
- * You should have received a copy of the GNU Lesser General Public License
- * along with this library.  If not, see <http://www.gnu.org/licenses/>.
+/** @defgroup quadspi_defines QuadSPI Defines
+ * @brief Defined constants and types for the STM32H7 QuadSPI peripheral
+ * @ingroup STM32H7xx_defines
+ * @copyright SPDX: LGPL-3.0-or-later
+ * @{
 */

-#ifndef LIBOPENCM3_QUADSPI_H
-#define LIBOPENCM3_QUADSPI_H
+#pragma once

 #include <libopencm3/stm32/memorymap.h>
 #include <libopencm3/stm32/common/quadspi_common_v1.h>
@ -24,4 +13,4 @@
 /** Enable free running clock mode, for testing */
 #define QUADSPI_CCR_FRCM    (1 << 29)

-#endif  /* LIBOPENCM3_QUADSPI_H */
+/**@}*/
--- a/lib/stm32/common/quadspi_common_v1.c
+++ b/lib/stm32/common/quadspi_common_v1.c
@ -0,0 +1,12 @@
+
+#include <libopencm3/stm32/quadspi.h>
+
+void quadspi_enable(void)
+{
+	QUADSPI_CR |= QUADSPI_CR_EN;
+}
+
+void quadspi_disable(void)
+{
+	QUADSPI_CR &= ~QUADSPI_CR_EN;
+}
--- a/lib/stm32/f4/Makefile
+++ b/lib/stm32/f4/Makefile
@ -64,6 +64,7 @@ OBJS += rtc_common_l1f024.o rtc.o
 OBJS += spi_common_all.o spi_common_v1.o spi_common_v1_frf.o
 OBJS += timer_common_all.o timer_common_f0234.o timer_common_f24.o
 OBJS += usart_common_all.o usart_common_f124.o
+OBJS += quadspi_common_v1.o

 OBJS += usb.o usb_standard.o usb_control.o usb_msc.o
 OBJS += usb_hid.o
--- a/lib/stm32/h7/Makefile
+++ b/lib/stm32/h7/Makefile
@ -48,6 +48,7 @@ OBJS += rng_common_v1.o
 OBJS += spi_common_all.o spi_common_v2.o
 OBJS += timer_common_all.o
 OBJS += usart_common_v2.o usart_common_fifos.o
+OBJS += quadspi_common_v1.o

 VPATH += ../../usb:../:../../cm3:../common