Partial documentation of the communications module.

comm/Makefile

@@ -12,6 +12,8 @@ COMPILE_OPTS_M3 = -mfloat-abi=softfp -mcpu=cortex-m3
 
 INCLUDE_DIRS = -I./include/ -I../utils/include
 
+DOC_DIR = ./doc
+
 TCHAIN_PREFIX=arm-none-eabi-
 
 CC = $(TCHAIN_PREFIX)gcc
@@ -71,6 +73,9 @@ $(COMM_OUT_M3): mkdir_build $(COMM_M3_OBJS)
 	mkdir -p lib
 	$(AR) $(ARFLAGS) $@ $(COMM_M3_OBJS)
 
+doc: 
+	doxygen $(DOC_DIR)/doxygen.conf 
+
 clean:
 	rm -f $(COMM_M4_FPU_OBJS)
 	rm -f $(COMM_M0_OBJS)
@@ -78,3 +83,6 @@ clean:
 	rm -f $(COMM_M3_OBJS)
 	rm -rf lib
 	rm -rf build
+	rm -rf doc/html
+
+.PHONY: all clean doc

comm/doc/doxygen_project_name.conf

+PROJECT_NAME = "Communication abstraction module"

comm/doc/index.html

+<META HTTP-EQUIV="Refresh" CONTENT="0; URL=html/index.html">

comm/doc/main.dox

+/*! \mainpage Communication abstraction module 
+
+  \section Installation
+
+  \subsection Pre-Requisites
+
+  This package requires of the following libraries and packages
+         - STM32 HAL library.
+         - Util library.
+	 .
+
+  \subsection Compilation
+
+  Just download this package, uncompress it, and execute
+   - make 
+   .
+  to obtain the static libraries for all processor families (in this case called 
+  <em>utils_m0.a</em> <em>utils_m0plus.a</em> <em>utils_m3.a</em> 
+  <em>utils_m4_fpu.a</em>).
+
+  To generate this documentation type
+       - make doc
+       .
+
+  The files in the <em>build</em> directory are genetated by <em>make</em> and 
+  can be safely removed. 
+
+  \section License
+
+  This package is licensed under a
+  <a href="http://www.gnu.org/licenses/lgpl.html">
+    LGPL 3.0 License</a>.
+
+  \section Disclaimer
+
+   This 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 program 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 program.  If not, see <http://www.gnu.org/licenses/>.
+
+ */

comm/include/comm.h

+/** @file */
+
 #ifndef _COMM_H
 #define _COMM_H
 
 #include "buffer.h"
 #include "stm32_time.h"
 
-typedef enum {COMM_SUCCESS=0x00,
-              COMM_BUSY=0x01,
-              COMM_ERROR=0x02,
-              COMM_TIMEOUT=0x03,
-              COMM_FULL=0x04} comm_error;
+/** 
+ * \brief Possible communication states
+ * 
+ */
+typedef enum {COMM_SUCCESS=0x00,/*!< The communication module has ended successfully */
+              COMM_BUSY=0x01,/*!< The communication module is busy */
+              COMM_ERROR=0x02,/*!< The communication module has ended with an error */
+              COMM_TIMEOUT=0x03,/*!< The communication module waited too long for data */
+              COMM_FULL=0x04/*!< The communication data buffer is full */
+             } comm_error;
 
+/** 
+ * \brief
+ * 
+ */
 typedef struct
 {
   /* private data */
+  /** 
+   * \brief Transmission data buffer
+   * 
+   * This parameter holds the data to be transmitted until they can be actually sent.
+   */
   TBuffer tx_buffer;
+  /** 
+   * \brief Active transmission using IRQ flag
+   * 
+   * This parameter is used to indicate if there is an acive transmission of data
+   * using interrupts to handle it. This flag is set when a transmission starts and 
+   * it is cleared when it ends.
+   */
   volatile unsigned char irq_sending;
+  /** 
+   * \brief Active transmission using DMA flag
+   * 
+   * This parameter is used to indicate if there is an acive transmission of data
+   * using DMA to handle it. This flag is set when a transmission starts and it is
+   * cleared when it ends.
+   */
   volatile unsigned char dma_sending;
+  /** 
+   * \brief Number of bytes pending to be sent
+   *
+   * This parameter holds the number of bytes pending to be sent in the current 
+   * transaction. This parameter is initialized when the transmission starts, and 
+   * is decremented after the transmission of each byte.
+   */
   unsigned short int tx_length;
+  /** 
+   * \brief Reception data buffer
+   * 
+   * This parameter holds the data to be transmitted until they can be actually sent.
+   */
   TBuffer rx_buffer;
+  /** 
+   * \brief Active reception using IRQ flag
+   * 
+   * This parameter is used to indicate if there is an acive reception of data
+   * using interrupts to handle it. This flag is set when a reception starts and 
+   * it is cleared when it ends.
+   */
   volatile unsigned char irq_receiving;
+  /** 
+   * \brief Active reception using DMA flag
+   * 
+   * This parameter is used to indicate if there is an acive reception of data
+   * using DMA to handle it. This flag is set when a reception starts and it is
+   * cleared when it ends.
+   */
   volatile unsigned char dma_receiving;
+  /** 
+   * \brief Number of bytes pending to be received
+   * 
+   * This parameter holds the number of bytes pending to be recevied in the current 
+   * transaction. This parameter is initialized when the reception starts, and 
+   * is decremented after the reception of each byte.
+   */
   unsigned short int rx_length;
+  /** 
+   * \brief Use DMA flag
+   * 
+   * This parameter indicates if the communication module uses DMA or not to
+   * complete any transmission and reception.
+   */
   unsigned char use_dma;
+  /** 
+   * \brief
+   * 
+   */
   unsigned char dma_waiting_buffer_empty;
+  /** 
+   * \brief Last communication error
+   * 
+   * This parameter holds the error of the last communication transaction (either
+   * transmission or reception). 
+   */
   unsigned char error;
+  /** 
+   * \brief
+   * 
+   */
   TTime *time;
+  /** 
+   * \brief
+   * 
+   */
   void *data;
   /* IRQ functions */
+  /** 
+   * \brief
+   * 
+   */
   unsigned char (*send_irq)(unsigned char first_byte);
+  /** 
+   * \brief
+   * 
+   */
   unsigned char (*enable_tx_irq)(void);
+  /** 
+   * \brief
+   * 
+   */
   unsigned char (*receive_irq)(void);
+  /** 
+   * \brief
+   * 
+   */
   unsigned char (*cancel_receive_irq)(void);
   /* DMA functions */
+  /** 
+   * \brief
+   * 
+   */
   unsigned char (*send_dma)(unsigned char *data,unsigned short int length);
+  /** 
+   * \brief
+   * 
+   */
   unsigned char (*receive_dma)(unsigned char *data,unsigned short int length);
+  /** 
+   * \brief
+   * 
+   */
   unsigned char (*cancel_receive_dma)(void);
   /* irq callbacks */
+  /** 
+   * \brief
+   * 
+   */
   unsigned char (*irq_send_cb)(void *data,unsigned char *byte);
+  /** 
+   * \brief
+   * 
+   */
   unsigned char (*irq_receive_cb)(void *data,unsigned char byte);
   /* dma callbacks */
+  /** 
+   * \brief
+   * 
+   */
   unsigned char (*dma_send_cb)(void *data);
+  /** 
+   * \brief
+   * 
+   */
   unsigned char (*dma_receive_cb)(void *data);
 }TComm;
 
 /* public functions */
+/** 
+ * \brief
+ * 
+ */
 void comm_init(TComm *dev,unsigned char use_dma,TTime *time);
+/** 
+ * \brief
+ * 
+ */
 comm_error comm_send(TComm *dev,unsigned char *data,unsigned short int length);
+/** 
+ * \brief
+ * 
+ */
 comm_error comm_receive(TComm *dev,unsigned char *data,unsigned short int *length,unsigned long int timeout);
 /* IRQ functions */
+/** 
+ * \brief
+ * 
+ */
 comm_error comm_send_irq(TComm *dev,unsigned char *data,unsigned short int length);
+/** 
+ * \brief
+ * 
+ */
 unsigned char comm_do_irq_send(TComm *dev,unsigned char *byte);
+/** 
+ * \brief
+ * 
+ */
 comm_error comm_receive_irq(TComm *dev,unsigned short int length);
+/** 
+ * \brief
+ * 
+ */
 unsigned char comm_do_irq_receive(TComm *dev,unsigned char byte);
+/** 
+ * \brief
+ * 
+ */
 comm_error comm_get_received_data(TComm *dev,unsigned char *data,unsigned short int *length);
+/** 
+ * \brief
+ * 
+ */
 void comm_cancel_irq_receive(TComm *dev);
 /* DMA functions */
+/** 
+ * \brief
+ * 
+ */
 comm_error comm_send_dma(TComm *dev,unsigned char *data,unsigned short int length);
+/** 
+ * \brief
+ * 
+ */
 void comm_do_dma_send(TComm *dev);
+/** 
+ * \brief
+ * 
+ */
 comm_error comm_receive_dma(TComm *dev,unsigned char *data,unsigned short int length);
+/** 
+ * \brief
+ * 
+ */
 void comm_do_dma_receive(TComm *dev);
+/** 
+ * \brief
+ * 
+ */
 void comm_cancel_dma_receive(TComm *dev);
 /* common functions */
+/** 
+ * \brief
+ * 
+ */
 comm_error comm_is_send_done(TComm *dev);
+/** 
+ * \brief
+ * 
+ */
 comm_error comm_is_receive_done(TComm *dev);
+/** 
+ * \brief
+ * 
+ */
 inline unsigned char comm_get_error(TComm *dev);
+/** 
+ * \brief
+ * 
+ */
 inline void comm_set_error(TComm *dev, unsigned char error);
+/** 
+ * \brief
+ * 
+ */
 
 #endif