Update doxygen documentation for cirbuf

linux-elphel.Doxyfile

@@ -101,7 +101,7 @@ WARN_LOGFILE =
 #---------------------------------------------------------------------------
 INPUT = linux/source/drivers/elphel linux/source/drivers/ata/ahci_elphel.c linux/source/drivers/clk/clk-si5338.c linux/source/drivers/misc/ltc3589.c linux/source/drivers/misc/vsc330x.c linux/source/drivers/mmc/host/sdhci.c linux/source/drivers/mmc/host/sdhci.h linux/source/drivers/mtd/nand/nand_base.c linux/source/drivers/mtd/nand/nand.h linux/source/drivers/mtd/nand/nandchip-micron.c linux/source/drivers/mtd/nand/pl35x-nand.c linux/source/include/elphel linux/source/include/linux/i2c/ltc3589.h
 INPUT_ENCODING = UTF-8
-FILE_PATTERNS = *.h *.cpp *.md
+FILE_PATTERNS = *.h *.c *.cpp *.md
 RECURSIVE = YES
 EXCLUDE = src/logos.cpp src/lodepng.cpp
 EXCLUDE_SYMLINKS = NO

src/drivers/elphel/circbuf.h

-// FILE NAME  : cxsdma.h
-// read/write image and FPN buffers from SDRAM
+/** @file circbuf.h
+ *
+ * @brief Drivers to manipulate large circular buffer that holds compressed
+ * images/video. Buffer frame data is filled in by the FPGA, frame pointers and
+ * essential frames metadata filled during servicing of the interrupts.
+ *
+ * @copyright Copyright (C) 2016 Elphel, Inc
+ *
+ * @par <b>License</b>
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU 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 General Public License for more details.
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
 
 #ifndef _CIRCBUF_H
 #define _CIRCBUF_H
 
 #include <linux/poll.h>
 
-int          circbuf_all_open  (struct inode *inode,  struct file *filp); // set filesize
+/** @brief Circular buffer private data */
+struct circbuf_priv_t {
+	int                 minor;                             ///< device file minor number
+	unsigned long       *buf_ptr;                          ///< pointer to circular buffer memory region
+	dma_addr_t          phys_addr;                         ///< physical address of memory region reported by memory driver
+};
+extern struct circbuf_priv_t *circbuf_priv_ptr;
+extern wait_queue_head_t circbuf_wait_queue;
+
+int          circbuf_all_open  (struct inode *inode,  struct file *filp); // set file size
 int          circbuf_all_release(struct inode *inode, struct file *filp);
 loff_t       circbuf_all_lseek (struct file * file,   loff_t offset, int orig);
 ssize_t      circbuf_all_write (struct file * file,   const char * buf, size_t count, loff_t *off);
 ssize_t      circbuf_all_read  (struct file * file,   char * buf, size_t count, loff_t *off);
 int          circbuf_all_mmap  (struct file *file,    struct vm_area_struct *vma);
 unsigned int circbuf_all_poll  (struct file *file,    poll_table *wait);
-//!just to notify it is not implemented
-int          circbuf_all_ioctl(struct inode *inode, struct file *filp, unsigned int cmd, unsigned long arg);
-
-
 
-int          circbuf_open  (struct inode *inode, struct file *filp); // set filesize
+int          circbuf_open  (struct inode *inode, struct file *filp);      // set file size
 loff_t       circbuf_lseek (struct file * file, loff_t offset, int orig);
 ssize_t      circbuf_write (struct file * file, const char * buf, size_t count, loff_t *off);
 ssize_t      circbuf_read  (struct file * file, char * buf, size_t count, loff_t *off);
 int          circbuf_mmap  (struct file *file, struct vm_area_struct *vma);
 unsigned int circbuf_poll  (struct file *file,    poll_table *wait);
 
-//int init_ccam_dma_buf_ptr(void);
-/*!======================================================================================
- *! Wait queue for the processes waiting for a new frame to appear in the circular buffer
- *!======================================================================================*/
-extern wait_queue_head_t circbuf_wait_queue;
-
-// private data
-struct circbuf_priv_t {
-	int                 minor;
-	unsigned long       *buf_ptr;
-	dma_addr_t          phys_addr;
-};
-extern struct circbuf_priv_t *circbuf_priv_ptr;
-
 /* debug code follows */
 extern unsigned short circbuf_quality;
 extern unsigned short circbuf_height;

src/drivers/elphel/x393_helpers.c

@@ -2,22 +2,20 @@
  *
  * @brief Helper functions for various routines form x393.h which require several actions to get
  * reliable result.
- */
-
-/* Copyright (C) 2016 Elphel, Inc
- *
- *  This program is free software: you can redistribute it and/or modify
- *  it under the terms of the GNU 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 General Public License for more details.
+ * @copyright Copyright (C) 2016 Elphel, Inc
  *
- *  You should have received a copy of the GNU General Public License
- *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * @par <b>License</b>
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU 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 General Public License for more details.
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
 #include <stddef.h>

src/drivers/elphel/x393_helpers.h

@@ -2,22 +2,20 @@
  *
  * @brief Helper functions for various routines form x393.h which require several actions to get
  * reliable result.
- */
-
-/* Copyright (C) 2016 Elphel, Inc
- *
- *  This program is free software: you can redistribute it and/or modify
- *  it under the terms of the GNU 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 General Public License for more details.
+ * @copyright Copyright (C) 2016 Elphel, Inc
  *
- *  You should have received a copy of the GNU General Public License
- *  along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * @par <b>License</b>
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU 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 General Public License for more details.
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
 #ifndef _X393_HELPERS_H
@@ -26,7 +24,7 @@
 #include <asm/types.h>
 #include "x393.h"
 
-/** @brief Number of times to repeat register read sequence while waiting for
+/** @brief The number of times to repeat register read sequence while waiting for
  * sequence number specified.
  */
 #define REPEAT_READ               10

src/drivers/elphel/x393_macro.h

 /**
  * @file x393_macro.h
  * @brief This file contains various macros used in multiple files.
+ * @copyright Copyright (C) 2016 Elphel, Inc
+ *
+ * @par <b>License</b>
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU 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 General Public License for more details.
+ * You should have received a copy of the GNU General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
+
 #ifndef _X393_MACRO
 #define _X393_MACRO
 
@@ -9,39 +23,46 @@
 
 /** @brief Resolution of current/OEF pointer in bits */
 #define OFFSET256_CNTR_RES   26
-
+/** @brief The size of data transfer in bytes */
 #define CHUNK_SIZE           32
 
 /** @brief The size of #interframe_params_t structure in double words */
 #define INTERFRAME_PARAMS_SZ 8
-
+/** @brief Marker field in frame length double word value */
 #define MARKER_FF            0xff000000
-
+/** @brief #interframe_params_t has a guard field and its value must be equal to MARKER_FFFF, otherwise
+ * it has been overwritten, as JPEG can not have two subsequent 0xFF */
 #define MARKER_FFFF          0xffff
-
+/** @brief Mask for frame length extraction from double word value */
 #define FRAME_LENGTH_MASK    0xffffff
 
+/** @brief No operations with compressor interrupt control register */
 #define IRQ_NOP              0
+/** @brief Clear compressor interrupt status */
 #define IRQ_CLEAR            1
+/** @brief Disable compressor interrupt */
 #define IRQ_DISABLE          2
+/** @brief Enable compressor interrupt */
 #define IRQ_ENABLE           3
-
+/** @brief Convert size in bytes to size in double words */
 #define BYTE2DW(x)           ((x) >> 2)
+/** @brief Convert size in double words to size in bytes */
 #define DW2BYTE(x)           ((x) << 2)
-
-// 4 bytes offset, this one comes from python code x393_cmprs_afi.py
+/** @brief 4 bytes offset, this one comes from Python code x393_cmprs_afi.py */
 #define ADJUSTMENT           4
 #define INSERTED_BYTES(x)    (((CHUNK_SIZE - ((((x) % CHUNK_SIZE) + CCAM_MMAP_META) % CHUNK_SIZE) - ADJUSTMENT) % CHUNK_SIZE ) + ADJUSTMENT)
 
-/* These macro were removed from sensor_common.h*/
 #define X313_LENGTH_MASK      0xff000000
+/** @brief Subtract two offsets considering that the resulting offset can roll over the start of circular buffer */
 #define X393_BUFFSUB(x, y) (((x) >= (y)) ? ((x)-(y)) : ((x) + (CCAM_DMA_SIZE -(y))))
+/** @brief Add two offsets considering that the resulting offset car roll over the end of circular buffer */
 #define X393_BUFFADD(x, y) ((((x) + (y)) <= CCAM_DMA_SIZE) ? ((x) + (y)) : ((x) - (CCAM_DMA_SIZE -(y))))
 
 #define TABLE_TYPE_QUANT     0
 #define TABLE_TYPE_CORING    1
 #define TABLE_TYPE_FOCUS     2
 #define TABLE_TYPE_HUFFMAN   3
+
 /**
  * @brief Converts file minor number to image compressor channel.
  *
@@ -49,7 +70,7 @@
  * next nibble contains device type. Channel numbers and device type are defined in #driver_numbers.h
  * @param[in]   minor     file minor number
  * @param[out]  dev_type  pointer to a variable which will hold device type or NULL if this value is not needed
- * @return      compressor channel number in the range [0..#IMAGE_CHN_NUM)
+ * @return      compressor channel number in the range [0..#SENSOR_PORTS)
  */
 static inline unsigned int minor_to_chn(unsigned int minor, unsigned int *dev_type)
 {