From 88e190103c97c80775dcfde119593c58071b61f6 Mon Sep 17 00:00:00 2001 From: George Oikonomou Date: Sat, 14 Feb 2015 01:18:32 +0100 Subject: [PATCH 1/8] Fix doxygen warning in the CC2538 SPI driver --- cpu/cc2538/dev/spi.c | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/cpu/cc2538/dev/spi.c b/cpu/cc2538/dev/spi.c index 586c738bc..911b13a36 100644 --- a/cpu/cc2538/dev/spi.c +++ b/cpu/cc2538/dev/spi.c @@ -52,7 +52,7 @@ /** * \brief Initialize the SPI bus. * - * This SPI init() function uses the following #defines to set the pins: + * This SPI init() function uses the following defines to set the pins: * SPI_CLK_PORT SPI_CLK_PIN * SPI_MOSI_PORT SPI_MOSI_PIN * SPI_MISO_PORT SPI_MISO_PIN From 4100cbc9c04ade8983bcea54a9105b595503649f Mon Sep 17 00:00:00 2001 From: George Oikonomou Date: Sat, 14 Feb 2015 01:18:51 +0100 Subject: [PATCH 2/8] Fix doxygen warning in the CC2538 uDMA driver's header --- cpu/cc2538/dev/udma.h | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/cpu/cc2538/dev/udma.h b/cpu/cc2538/dev/udma.h index a6ddfc199..79cd58c20 100644 --- a/cpu/cc2538/dev/udma.h +++ b/cpu/cc2538/dev/udma.h @@ -560,12 +560,13 @@ void udma_init(void); /** * \brief Sets the channels source address * \param channel The channel as a value in [0 , UDMA_CONF_MAX_CHANNEL] - * \param + * \param src_end The source's end address */ void udma_set_channel_src(uint8_t channel, uint32_t src_end); /** - * \brief + * \brief Sets the channel's destination address + * \param dst_end The destination's end address * \param channel The channel as a value in [0 , UDMA_CONF_MAX_CHANNEL] */ void udma_set_channel_dst(uint8_t channel, uint32_t dst_end); From a34a2e5ad8b0a4f746353bac3354d8e002fe8769 Mon Sep 17 00:00:00 2001 From: George Oikonomou Date: Sat, 14 Feb 2015 01:19:38 +0100 Subject: [PATCH 3/8] Remove obsolete/unused doxygen group The group is defined within the cpu files themselves, so this definition simply resulted in a 2nd CC2538 group, which was empty --- doc/platform.txt | 5 ----- 1 file changed, 5 deletions(-) diff --git a/doc/platform.txt b/doc/platform.txt index 111e37e1b..49c255140 100644 --- a/doc/platform.txt +++ b/doc/platform.txt @@ -57,11 +57,6 @@ * \ingroup platform */ -/** - * \addtogroup cc2538dk CC2538 Development Kit - * \ingroup platform - */ - /** * \addtogroup cooja COOJA network simulator node * \ingroup platform From a93a8912c28ea2dbb4c09bd67d69cf51c8fa4e40 Mon Sep 17 00:00:00 2001 From: George Oikonomou Date: Sat, 14 Feb 2015 01:44:06 +0100 Subject: [PATCH 4/8] Clarify GPIO read and write macros --- cpu/cc2538/dev/gpio.h | 24 ++++++++++++++++++++++-- 1 file changed, 22 insertions(+), 2 deletions(-) diff --git a/cpu/cc2538/dev/gpio.h b/cpu/cc2538/dev/gpio.h index 8a61f668b..3f93633a1 100644 --- a/cpu/cc2538/dev/gpio.h +++ b/cpu/cc2538/dev/gpio.h @@ -117,6 +117,20 @@ typedef void (* gpio_callback_t)(uint8_t port, uint8_t pin); /** \brief Set pins with PIN_MASK of port with PORT_BASE to value. * \param PORT_BASE GPIO Port register offset * \param PIN_MASK Pin number mask. Pin 0: 0x01, Pin 1: 0x02 ... Pin 7: 0x80 + * \param value The new value to write to the register. Only pins specified + * by PIN_MASK will be set. + * + * \note The outcome of this macro invocation will be to write to the register + * a new value for multiple pins. For that reason, the value argument cannot be + * a simple 0 or 1. Instead, it must be the value corresponding to the pins that + * you wish to set. + * + * Thus, if you only want to set a single pin (e.g. pin 2), do \e not pass 1, + * but you must pass 0x04 instead (1 << 2). This may seem counter-intuitive at + * first glance, but it allows a single invocation of this macro to set + * multiple pins in one go if so desired. For example, you can set pins 3 and 1 + * and the same time clear pins 2 and 0. To do so, pass 0x0F as the PIN_MASK + * and then use 0x0A as the value ((1 << 3) | (1 << 1) for pins 3 and 1) */ #define GPIO_WRITE_PIN(PORT_BASE, PIN_MASK, value) \ do { REG(((PORT_BASE) | GPIO_DATA) + ((PIN_MASK) << 2)) = (value); } while(0) @@ -124,6 +138,12 @@ typedef void (* gpio_callback_t)(uint8_t port, uint8_t pin); /** \brief Read pins with PIN_MASK of port with PORT_BASE. * \param PORT_BASE GPIO Port register offset * \param PIN_MASK Pin number mask. Pin 0: 0x01, Pin 1: 0x02 ... Pin 7: 0x80 + * \return The value of the pins specified by PIN_MASK + * + * This macro will \e not return 0 or 1. Instead, it will return the values of + * the pins specified by PIN_MASK ORd together. Thus, if you pass 0xC3 + * (0x80 | 0x40 | 0x02 | 0x01) as the PIN_MASK and pins 7 and 0 are high, + * the macro will return 0x81. */ #define GPIO_READ_PIN(PORT_BASE, PIN_MASK) \ REG(((PORT_BASE) | GPIO_DATA) + ((PIN_MASK) << 2)) @@ -261,7 +281,7 @@ typedef void (* gpio_callback_t)(uint8_t port, uint8_t pin); /** * \brief Converts a pin number to a pin mask - * \param The pin number in the range [0..7] + * \param PIN The pin number in the range [0..7] * \return A pin mask which can be used as the PIN_MASK argument of the macros * in this category */ @@ -269,7 +289,7 @@ typedef void (* gpio_callback_t)(uint8_t port, uint8_t pin); /** * \brief Converts a port number to the port base address - * \param The port number in the range 0 - 3. Likely GPIO_X_NUM. + * \param PORT The port number in the range 0 - 3. Likely GPIO_X_NUM. * \return The base address for the registers corresponding to that port * number. */ From 8751e55c949a2763347ec55580da887582f86e0b Mon Sep 17 00:00:00 2001 From: George Oikonomou Date: Sat, 14 Feb 2015 01:44:30 +0100 Subject: [PATCH 5/8] Improve wording, fix warnigs in the SSI/SPI docs --- cpu/cc2538/dev/spi.c | 6 ++++-- platform/cc2538dk/dev/board.h | 14 +++++++------- 2 files changed, 11 insertions(+), 9 deletions(-) diff --git a/cpu/cc2538/dev/spi.c b/cpu/cc2538/dev/spi.c index 911b13a36..bff1783b5 100644 --- a/cpu/cc2538/dev/spi.c +++ b/cpu/cc2538/dev/spi.c @@ -31,7 +31,7 @@ * @{ * * \file - * Implementation of the cc2538 SPI peripheral + * Implementation of the cc2538 SPI peripheral driver */ #include "contiki.h" #include "reg.h" @@ -126,7 +126,9 @@ spi_disable(void) REG(SYS_CTRL_RCGCSSI) &= ~1; } /*---------------------------------------------------------------------------*/ -void spi_set_mode(uint32_t frame_format, uint32_t clock_polarity, uint32_t clock_phase, uint32_t data_size) +void +spi_set_mode(uint32_t frame_format, uint32_t clock_polarity, + uint32_t clock_phase, uint32_t data_size) { /* Disable the SSI peripheral to configure it */ REG(SSI0_BASE + SSI_CR1) = 0; diff --git a/platform/cc2538dk/dev/board.h b/platform/cc2538dk/dev/board.h index 729d703ab..c32941cd2 100644 --- a/platform/cc2538dk/dev/board.h +++ b/platform/cc2538dk/dev/board.h @@ -158,7 +158,7 @@ #define BUTTON_UP_VECTOR NVIC_INT_GPIO_PORT_C /** BUTTON_DOWN -> PC7 */ -#define BUTTON_DOWN_PORT GPIO_C_NUM +#define BUTTON_DOWN_PORT GPIO_C_NUM #define BUTTON_DOWN_PIN 7 #define BUTTON_DOWN_VECTOR NVIC_INT_GPIO_PORT_C @@ -186,12 +186,12 @@ * These values configure which CC2538 pins to use for the SPI lines. * @{ */ -#define SPI_CLK_PORT GPIO_A_NUM -#define SPI_CLK_PIN 2 -#define SPI_MOSI_PORT GPIO_A_NUM -#define SPI_MOSI_PIN 4 -#define SPI_MISO_PORT GPIO_A_NUM -#define SPI_MISO_PIN 5 +#define SPI_CLK_PORT GPIO_A_NUM /**< Clock port */ +#define SPI_CLK_PIN 2 /**< Clock pin */ +#define SPI_MOSI_PORT GPIO_A_NUM /**< MOSI port */ +#define SPI_MOSI_PIN 4 /**< MOSI pin */ +#define SPI_MISO_PORT GPIO_A_NUM /**< MISO port */ +#define SPI_MISO_PIN 5 /**< MISO pin */ /** @} */ /*---------------------------------------------------------------------------*/ /** From 72914369e801b4ecc388914bb8c9fe66a8a37cfb Mon Sep 17 00:00:00 2001 From: George Oikonomou Date: Sat, 14 Feb 2015 02:13:21 +0100 Subject: [PATCH 6/8] Re-structure CC2538 doxygen module hierarchy --- cpu/cc2538/cpu.h | 15 +++++++++++++-- cpu/cc2538/spi-arch.h | 12 ++++-------- examples/cc2538dk/cc2538-demo.c | 4 ++-- platform/cc2538dk/contiki-conf.h | 2 +- platform/cc2538dk/contiki-main.c | 4 ++-- platform/cc2538dk/dev/board.h | 3 ++- platform/cc2538dk/startup-gcc.c | 2 +- 7 files changed, 25 insertions(+), 17 deletions(-) diff --git a/cpu/cc2538/cpu.h b/cpu/cc2538/cpu.h index e8cd7e282..51ffa9075 100644 --- a/cpu/cc2538/cpu.h +++ b/cpu/cc2538/cpu.h @@ -29,12 +29,21 @@ * OF THE POSSIBILITY OF SUCH DAMAGE. */ /** - * \addtogroup cc2538 + * \addtogroup platform + * @{ + * + * \defgroup cc2538-platforms TI cc2538-powered platforms + * + * Documentation for all platforms powered by the TI cc2538 System-on-Chip + * @{ + * + * \defgroup cc2538 The TI cc2538 System-on-Chip + * CPU-Specific functionality - available to all cc2538-based platforms * @{ * * \defgroup cc2538-cpu cc2538 CPU * - * cc2538 CPU-specific functions for the cc2538 core + * CPU-specific functions for the cc2538 core * @{ * * \file @@ -60,6 +69,8 @@ unsigned long cpu_cpsie(void); #endif /* CPU_H_ */ /** + * @} + * @} * @} * @} */ diff --git a/cpu/cc2538/spi-arch.h b/cpu/cc2538/spi-arch.h index 53d7fe78d..46d8d3bf4 100644 --- a/cpu/cc2538/spi-arch.h +++ b/cpu/cc2538/spi-arch.h @@ -27,16 +27,13 @@ * SUCH DAMAGE. */ /** - * \addtogroup cc2538 + * \addtogroup cc2538-spi * @{ * - * Implementation of the low-level SPI primitives such as waiting for the TX - * FIFO to be ready, inserting into the TX FIFO, etc. - * @{ - */ -/** * \file - * Header file for the cc2538 SPI commands + * Header file for the cc2538 SPI driver, including macros for the + * implementation of the low-level SPI primitives such as waiting for the TX + * FIFO to be ready, inserting into the TX FIFO, etc. */ #ifndef SPI_ARCH_H_ #define SPI_ARCH_H_ @@ -121,6 +118,5 @@ void spi_set_mode(uint32_t frame_format, uint32_t clock_polarity, #endif /* SPI_ARCH_H_ */ /** - * @} * @} */ diff --git a/examples/cc2538dk/cc2538-demo.c b/examples/cc2538dk/cc2538-demo.c index d7fa056f2..9210968c2 100644 --- a/examples/cc2538dk/cc2538-demo.c +++ b/examples/cc2538dk/cc2538-demo.c @@ -29,10 +29,10 @@ * OF THE POSSIBILITY OF SUCH DAMAGE. */ /** - * \addtogroup cc2538 + * \addtogroup cc2538-platforms * @{ * - * \defgroup cc2538-examples cc2538dk Example Projects + * \defgroup cc2538-examples cc2538 Example Projects * @{ * * \defgroup cc2538-demo cc2538dk Demo Project diff --git a/platform/cc2538dk/contiki-conf.h b/platform/cc2538dk/contiki-conf.h index 84d78d9a1..354f042db 100644 --- a/platform/cc2538dk/contiki-conf.h +++ b/platform/cc2538dk/contiki-conf.h @@ -1,5 +1,5 @@ /** - * \addtogroup cc2538 + * \addtogroup cc2538dk * @{ * * \file diff --git a/platform/cc2538dk/contiki-main.c b/platform/cc2538dk/contiki-main.c index c66faed33..414d2aebb 100644 --- a/platform/cc2538dk/contiki-main.c +++ b/platform/cc2538dk/contiki-main.c @@ -29,10 +29,10 @@ * OF THE POSSIBILITY OF SUCH DAMAGE. */ /** - * \addtogroup platform + * \addtogroup cc2538-platforms * @{ * - * \defgroup cc2538 The cc2538 Development Kit platform + * \defgroup cc2538dk The cc2538 Development Kit platform * * The cc2538DK is the new platform by Texas Instruments, based on the * cc2530 SoC with an ARM Cortex-M3 core. diff --git a/platform/cc2538dk/dev/board.h b/platform/cc2538dk/dev/board.h index c32941cd2..d5514839d 100644 --- a/platform/cc2538dk/dev/board.h +++ b/platform/cc2538dk/dev/board.h @@ -28,7 +28,8 @@ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED * OF THE POSSIBILITY OF SUCH DAMAGE. */ -/** \addtogroup cc2538 +/** + * \addtogroup cc2538dk * @{ * * \defgroup cc2538-smartrf SmartRF06EB Peripherals diff --git a/platform/cc2538dk/startup-gcc.c b/platform/cc2538dk/startup-gcc.c index 8647fd638..ce3db6dde 100644 --- a/platform/cc2538dk/startup-gcc.c +++ b/platform/cc2538dk/startup-gcc.c @@ -30,7 +30,7 @@ * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. */ /** - * \addtogroup cc2538 + * \addtogroup cc2538dk * @{ * * \file From 6bd8bb05f64ed501557767ac7a8192c938cbac1b Mon Sep 17 00:00:00 2001 From: George Oikonomou Date: Sat, 14 Feb 2015 02:09:24 +0100 Subject: [PATCH 7/8] Improve wording --- cpu/cc2538/dbg.h | 2 +- cpu/cc2538/dev/ioc.h | 2 +- cpu/cc2538/dev/scb.h | 4 +++- cpu/cc2538/dev/sys-ctrl.h | 2 +- platform/cc2538dk/contiki-main.c | 4 ++-- 5 files changed, 8 insertions(+), 6 deletions(-) diff --git a/cpu/cc2538/dbg.h b/cpu/cc2538/dbg.h index d861cadd7..2e283c0b1 100644 --- a/cpu/cc2538/dbg.h +++ b/cpu/cc2538/dbg.h @@ -34,7 +34,7 @@ * * \defgroup cc2538-char-io cc2538 Character I/O * - * cc2538 CPU-specific functions for debugging and SLIP I/O + * CPU-specific functions for debugging and SLIP I/O * * On the cc2538, character I/O can be directed over USB or UART. This is * controlled by a series of configuration directives: diff --git a/cpu/cc2538/dev/ioc.h b/cpu/cc2538/dev/ioc.h index 34fcce809..7fad9d275 100644 --- a/cpu/cc2538/dev/ioc.h +++ b/cpu/cc2538/dev/ioc.h @@ -34,7 +34,7 @@ * * \defgroup cc2538-ioc cc2538 I/O Control * - * cc2538 I/O Control Module + * Driver for the cc2538 I/O Control Module * @{ * * \file diff --git a/cpu/cc2538/dev/scb.h b/cpu/cc2538/dev/scb.h index 53b1535e4..e91951ecb 100644 --- a/cpu/cc2538/dev/scb.h +++ b/cpu/cc2538/dev/scb.h @@ -32,7 +32,9 @@ * \addtogroup cc2538 * @{ * - * \defgroup cc2538-scb cc2538 System Control Block + * \defgroup cc2538-scb cc2538 System Control Block (SCB) + * + * Offsets and bit definitions for SCB registers * @{ * * \file diff --git a/cpu/cc2538/dev/sys-ctrl.h b/cpu/cc2538/dev/sys-ctrl.h index f63fd5a50..3c9885a89 100644 --- a/cpu/cc2538/dev/sys-ctrl.h +++ b/cpu/cc2538/dev/sys-ctrl.h @@ -32,7 +32,7 @@ * \addtogroup cc2538 * @{ * - * \defgroup cc2538-sys-ctrl cc2538 System Control + * \defgroup cc2538-sys-ctrl cc2538 System Control (SysCtrl) * * Driver for the cc2538 System Control Module * @{ diff --git a/platform/cc2538dk/contiki-main.c b/platform/cc2538dk/contiki-main.c index 414d2aebb..4487a07f2 100644 --- a/platform/cc2538dk/contiki-main.c +++ b/platform/cc2538dk/contiki-main.c @@ -34,8 +34,8 @@ * * \defgroup cc2538dk The cc2538 Development Kit platform * - * The cc2538DK is the new platform by Texas Instruments, based on the - * cc2530 SoC with an ARM Cortex-M3 core. + * The cc2538DK is a platform by Texas Instruments, based on the + * cc2538 SoC with an ARM Cortex-M3 core. * @{ * * \file From 65c1b667a5f8fd91f32c916d63c3c1fb98a94925 Mon Sep 17 00:00:00 2001 From: George Oikonomou Date: Sat, 14 Feb 2015 13:22:18 +0100 Subject: [PATCH 8/8] Adjust doxygen travis test error count --- regression-tests/00-doxygen/doxyerrors.cnt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/regression-tests/00-doxygen/doxyerrors.cnt b/regression-tests/00-doxygen/doxyerrors.cnt index 8641ad817..e01062f1f 100644 --- a/regression-tests/00-doxygen/doxyerrors.cnt +++ b/regression-tests/00-doxygen/doxyerrors.cnt @@ -1 +1 @@ -291 +282