Merge pull request #959 from g-oikonomou/cc2538-doc

Improve CC2538 documentation

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_ */
 
 /**
+ * @}
+ * @}
  * @}
  * @}
  */

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:

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.
  */

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

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

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"
@@ -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
@@ -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;

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
  * @{

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);

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_ */
 
 /**
- * @}
  * @}
  */

doc/platform.txt

@@ -57,11 +57,6 @@
  * \ingroup platform
  */
 
-/**
- * \addtogroup cc2538dk CC2538 Development Kit
- * \ingroup platform
- */
-
 /**
  * \addtogroup cooja COOJA network simulator node
  * \ingroup platform

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

platform/cc2538dk/contiki-conf.h

@@ -1,5 +1,5 @@
 /**
- * \addtogroup cc2538
+ * \addtogroup cc2538dk
  * @{
  *
  * \file

platform/cc2538dk/contiki-main.c

@@ -29,13 +29,13 @@
  * 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
+ * The cc2538DK is a platform by Texas Instruments, based on the
- * cc2530 SoC with an ARM Cortex-M3 core.
+ * cc2538 SoC with an ARM Cortex-M3 core.
  * @{
  *
  * \file

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
@@ -158,7 +159,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 +187,12 @@
  * These values configure which CC2538 pins to use for the SPI lines.
  * @{
  */
-#define SPI_CLK_PORT             GPIO_A_NUM
+#define SPI_CLK_PORT             GPIO_A_NUM /**< Clock port */
-#define SPI_CLK_PIN              2
+#define SPI_CLK_PIN              2          /**< Clock pin */
-#define SPI_MOSI_PORT            GPIO_A_NUM
+#define SPI_MOSI_PORT            GPIO_A_NUM /**< MOSI port */
-#define SPI_MOSI_PIN             4
+#define SPI_MOSI_PIN             4          /**< MOSI pin */
-#define SPI_MISO_PORT            GPIO_A_NUM
+#define SPI_MISO_PORT            GPIO_A_NUM /**< MISO port */
-#define SPI_MISO_PIN             5
+#define SPI_MISO_PIN             5          /**< MISO pin */
 /** @} */
 /*---------------------------------------------------------------------------*/
 /**

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

regression-tests/00-doxygen/doxyerrors.cnt

@@ -1 +1 @@
-291
+282