From 458a0553a86c4f843ad9252c8a07c7566aaef7be Mon Sep 17 00:00:00 2001 From: Karl Palsson Date: Wed, 3 Feb 2021 23:06:49 +0000 Subject: [PATCH] samd: overhaul doxygen --- include/libopencm3/sam/d/doc-samd.h | 8 ++ include/libopencm3/sam/d/port.h | 119 ++++++++++------------------ lib/sam/d/port.c | 32 +------- 3 files changed, 54 insertions(+), 105 deletions(-) create mode 100644 include/libopencm3/sam/d/doc-samd.h diff --git a/include/libopencm3/sam/d/doc-samd.h b/include/libopencm3/sam/d/doc-samd.h new file mode 100644 index 00000000..224f5bd7 --- /dev/null +++ b/include/libopencm3/sam/d/doc-samd.h @@ -0,0 +1,8 @@ +/** @defgroup peripheral_apis Peripheral APIs + * APIs for device peripherals + */ + +/** @defgroup SAMD_defines SAMD Defines + * Defined Constants and Types for the SAMD series. + * @copyright SPDX: LGPL-3.0-or-later + */ diff --git a/include/libopencm3/sam/d/port.h b/include/libopencm3/sam/d/port.h index 759f9e6e..860c63ee 100644 --- a/include/libopencm3/sam/d/port.h +++ b/include/libopencm3/sam/d/port.h @@ -1,29 +1,12 @@ -/** @defgroup gpio_defines +/** @defgroup port_defines IO Port Definitions * - * #ingroup SAMD_defines + * @ingroup SAMD_defines * - * @brief Defined Constants and Types for the SAMD Port controler + * @brief Defined Constants and Types for the SAMD Port controller * - * LGPL License Terms @ref lgpl_license - */ -/* - * This file is part of the libopencm3 project. - * - * Copyright (C) 2016 Karl Palsson - * Copyright (C) 2020 Gwenhael Goavec-Merou - * - * 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 . + * @copyright SPDX: LGPL-3.0-or-later + * @author 2016 Karl Palsson + * @author 2020 Gwenhael Goavec-Merou */ #pragma once @@ -40,7 +23,6 @@ /* GPIO number definitions (for convenience) */ /** @defgroup gpio_pin_id GPIO Pin Identifiers -@ingroup gpio_defines @{*/ #define GPIO0 (1 << 0) #define GPIO1 (1 << 1) @@ -79,7 +61,6 @@ /* GPIO mux definitions (for convenience) */ /** @defgroup gpio_mux GPIO mux configuration -@ingroup gpio_mux @{*/ enum port_mux { PORT_PMUX_FUN_A = 0, @@ -94,46 +75,48 @@ enum port_mux { }; /**@}*/ -/* --- PORT registers ----------------------------------------------------- */ - -/* Direction register */ +/** @defgroup port_registers PORT Registers + * @{ + */ +/** Direction register */ #define PORT_DIR(port) MMIO32((port) + 0x0000) -/* Direction clear register */ +/** Direction clear register */ #define PORT_DIRCLR(port) MMIO32((port) + 0x0004) -/* Direction set register */ +/** Direction set register */ #define PORT_DIRSET(port) MMIO32((port) + 0x0008) -/* Direction toggle register */ +/** Direction toggle register */ #define PORT_DIRTGL(port) MMIO32((port) + 0x000c) -/* output register */ +/** output register */ #define PORT_OUT(port) MMIO32((port) + 0x0010) -/* output clear register */ +/** output clear register */ #define PORT_OUTCLR(port) MMIO32((port) + 0x0014) -/* output set register */ +/** output set register */ #define PORT_OUTSET(port) MMIO32((port) + 0x0018) -/* output toggle register */ +/** output toggle register */ #define PORT_OUTTGL(port) MMIO32((port) + 0x001c) -/* input register */ +/** input register */ #define PORT_IN(port) MMIO32((port) + 0x0020) -/* Control register */ +/** Control register */ #define PORT_CTRL(port) MMIO32((port) + 0x0024) -/* Write configuration register */ +/** Write configuration register */ #define PORT_WRCONFIG(port) MMIO32((port) + 0x0028) -/* Peripheral multiplexing registers */ +/** Peripheral multiplexing registers */ #define PORT_PMUX(port, n) MMIO8((port) + 0x0030 + (n)) -/* Pin configuration registers */ +/** Pin configuration registers */ #define PORT_PINCFG(port, n) MMIO8((port) + 0x0040 + (n)) +/**@}*/ /* --- PORTx_DIR values ---------------------------------------------------- */ @@ -175,77 +158,66 @@ enum port_mux { /* PORTx_CTRL[31:0]: CTRLy[31:0]: Port input sampling mode [y=0..31] */ -/* --- PORTx_WRCONFIG values ----------------------------------------------- */ - -/* HWSEL: Half word select: 0 [15:0], 1 [31:16] */ +/**@defgroup port_wrconfig_values PortX WRCONFIG Values + * @{ + */ +/** HWSEL: Half word select: 0 [15:0], 1 [31:16] */ #define PORT_WRCONFIG_HWSEL (1 << 31) -/* WRPINCFG: Write PINCFG: 1 to update pins for selected by PINMASK */ +/** WRPINCFG: Write PINCFG: 1 to update pins for selected by PINMASK */ #define PORT_WRCONFIG_WRPINCFG (1 << 30) -/* Bit 29: Reserved */ - -/* WRPMUX: Write PMUX: 1 to update pins pmux for selected by PINMASK */ +/** WRPMUX: Write PMUX: 1 to update pins pmux for selected by PINMASK */ #define PORT_WRCONFIG_WRPMUX (1 << 28) -/* PMUX: Peripheral Multiplexing: determine pmux for pins selected by PINMASK */ +/** PMUX: Peripheral Multiplexing: determine pmux for pins selected by PINMASK */ #define PORT_WRCONFIG_PMUX(mux) ((0xf & (mux)) << 24) -/* Bit 23: Reserved */ - -/* DRVSTR: Output Driver Strength Selection: determine strength for pins in PINMASK */ +/** DRVSTR: Output Driver Strength Selection: determine strength for pins in PINMASK */ #define PORT_WRCONFIG_DRVSTR (1 << 22) -/* Bit [21:19]: Reserved */ - -/* PULLEN: Pull Enable: enable PINCFGy.PULLEN for pins in PINMASK */ +/** PULLEN: Pull Enable: enable PINCFGy.PULLEN for pins in PINMASK */ #define PORT_WRCONFIG_PULLEN (1 << 18) -/* INEN: Input Enable: enable PINCFGy.INEN for pins in PINMASK */ +/** INEN: Input Enable: enable PINCFGy.INEN for pins in PINMASK */ #define PORT_WRCONFIG_INEN (1 << 17) -/* PMUXEN: Peripheral Multiplexer Enable: enable PINCFGy.PMUXEN for pins in PINMASK */ +/** PMUXEN: Peripheral Multiplexer Enable: enable PINCFGy.PMUXEN for pins in PINMASK */ #define PORT_WRCONFIG_PMUXEN (1 << 16) -/* PINMASK: Pin Mask for Multiple Pin Configuration: select pins to be configured +/** PINMASK: Pin Mask for Multiple Pin Configuration: select pins to be configured * [31:16] if HWSET=1, [15:0] if HWSET=0 */ #define PORT_WRCONFIG_PINMASK(pins) ((0xffff & (pins)) << 0) +/**@}*/ /* --- PORTx_PMUX values --------------------------------------------------- */ -/* PMUXO: Peripheral Multiplexing for Odd-Numbered Pin: 2*x+1 pin multiplexing */ +/** PMUXO: Peripheral Multiplexing for Odd-Numbered Pin: 2*x+1 pin multiplexing */ #define PORT_PMUX_PMUXO(mux) ((0xf & (mux)) << 4) -/* PMUXE: Peripheral Multiplexing for Even-Numbered Pin: 2*x pin multiplexing */ +/** PMUXE: Peripheral Multiplexing for Even-Numbered Pin: 2*x pin multiplexing */ #define PORT_PMUX_PMUXE(mux) ((0xf & (mux)) << 0) /* --- PORTx_PINCFGy values ------------------------------------------------ */ /* Bit 7: Reserved */ -/* DRVSTR: Output Driver Strength Selection */ +/** DRVSTR: Output Driver Strength Selection */ #define PORT_PINCFG_DRVSTR (1 << 6) -/* Bit [5:3]: Reserved */ - -/* PULLEN: Pull Enable */ +/** PULLEN: Pull Enable */ #define PORT_PINCFG_PULLEN (1 << 2) -/* INEN: Input Enable */ +/** INEN: Input Enable */ #define PORT_PINCFG_INEN (1 << 1) -/* PMUXEN: Peripheral Multiplexer Enable */ +/** PMUXEN: Peripheral Multiplexer Enable */ #define PORT_PINCFG_PMUXEN (1 << 0) /* --- Convenience enums --------------------------------------------------- */ -/* GPIO mode definitions (for convenience) */ /** @defgroup gpio_direction GPIO Pin direction -@ingroup gpio_defines -@li Input -@li Output -@li InOut @{*/ #define GPIO_MODE_INPUT 0x00 #define GPIO_MODE_OUTPUT 0x01 @@ -253,7 +225,6 @@ enum port_mux { /**@}*/ /** @defgroup gpio_cnf GPIO mode configuration -@ingroup gpio_defines @li Float @li PullDown @li PullUp @@ -265,16 +236,10 @@ enum port_mux { #define GPIO_CNF_AF 0x03 /**@}*/ -/* --- Function prototypes ------------------------------------------------- */ - BEGIN_DECLS void gpio_mode_setup(uint32_t gpioport, uint8_t mode, uint8_t cnf, uint32_t gpios); void gpio_set_af(uint32_t gpioport, uint8_t af, uint32_t gpios); - -/** @ingroup gpio_control - * @{ */ - void gpio_set(uint32_t gpioport, uint32_t gpios); void gpio_clear(uint32_t gpioport, uint32_t gpios); uint32_t gpio_get(uint32_t gpioport, uint32_t gpios); diff --git a/lib/sam/d/port.c b/lib/sam/d/port.c index ac3a8faf..5a1ed449 100644 --- a/lib/sam/d/port.c +++ b/lib/sam/d/port.c @@ -1,32 +1,9 @@ -/** @defgroup gpio_defines - * - * @ingroup SAMD - * +/** @addtogroup port_file IO Port API + * @ingroup peripheral_apis * @brief Access functions for the SAMD I/O Controller - * * @date 10 April 2020 - * - * LGPL License Terms @ref lgpl_license - * - */ - -/* - * This file is part of the libopencm3 project. - * - * Copyright (C) 2020 Gwenhael Goavec-Merou - * - * 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 . + * @copyright SPDX: LGPL-3.0-or-later + * @author 2020 Gwenhael Goavec-Merou */ /**@{*/ @@ -43,7 +20,6 @@ * @param[in] gpios Any combinaison of pins may be * specified by OR'ing then together. */ - void gpio_mode_setup(uint32_t gpioport, uint8_t mode, uint8_t cnf, uint32_t gpios) { uint32_t reg = PORT_WRCONFIG_WRPINCFG;