shared vmeUniverse: Improve Doxygen

2014-01-05 22:43:54 +01:00
parent d496095366
commit e87b300635
22 changed files with 311 additions and 60 deletions
--- a/c/src/lib/libbsp/shared/doxygen.h
+++ b/c/src/lib/libbsp/shared/doxygen.h
@@ -1,13 +1,15 @@
- /**
-  *  @defgroup bsp_kit Board Support Packages
-  *
-  *  @brief Board Support Packages
-  */
+/**
+ *  @defgroup bsp_shared SHARED
+ *
+ *  @ingroup bsp_kit
+ *
+ *  @brief SHARED Board Support Packages
+ */

- /**
-  *  @defgroup bsp_shared Shared Modules
-  *
-  *  @ingroup bsp_kit
-  *
-  *  @brief BSP Shared Modules
-  */
+/**
+ *  @defgroup shared_tod SHARED TOD Modules
+ *
+ *  @ingroup bsp_shared
+ *
+ *  @brief SHARED TOD Modules
+ */
--- a/c/src/lib/libbsp/shared/include/coverhd.h
+++ b/c/src/lib/libbsp/shared/include/coverhd.h
@@ -1,7 +1,13 @@
-/* coverhd.h
+/**
+ *  @file
 *
- *  This include file has defines to represent the overhead associated
+ *  @ingroup shared_coverhd
+ *
+ *  @brief This include file has defines to represent the overhead associated
 *  with calling a particular directive from C on this target.
+ */
+
+/* coverhd.h
 *
 *  COPYRIGHT (c) 1989-1999.
 *  On-Line Applications Research Corporation (OAR).
--- a/c/src/lib/libbsp/shared/include/default-initial-extension.h
+++ b/c/src/lib/libbsp/shared/include/default-initial-extension.h
@@ -1,3 +1,11 @@
+/**
+ *  @file
+ *
+ *  @ingroup shared_defaultinitialextension
+ *
+ *  @brief DEFAULT_INITIAL_EXTENSION Support
+ */
+
 /*
 * Copyright (c) 2012 embedded brains GmbH.  All rights reserved.
 *
@@ -21,6 +29,14 @@
 extern "C" {
 #endif /* __cplusplus */

+/**
+ *  @defgroup shared_defaultinitialextension DEFAULT_INITIAL_EXTENSION Support
+ *
+ *  @ingroup shared_include
+ *
+ *  @brief DEFAULT_INITIAL_EXTENSION Support Package
+ */
+
 void bsp_fatal_extension(
  rtems_fatal_source source,
  bool is_internal,
--- a/c/src/lib/libbsp/shared/include/doxygen.h
+++ b/c/src/lib/libbsp/shared/include/doxygen.h
@@ -0,0 +1,7 @@
+/**
+ *  @defgroup shared_include SHARED INCLUDE Modules
+ *
+ *  @ingroup bsp_shared
+ *
+ *  @brief SHARED INCLUDE Modules
+ */
--- a/c/src/lib/libbsp/shared/include/mm.h
+++ b/c/src/lib/libbsp/shared/include/mm.h
@@ -1,3 +1,11 @@
+/**
+ *  @file
+ *
+ *  @ingroup shared_mm
+ *
+ *  @brief MM Support
+ */
+
 /*
 * Copyright (c) 2013 Hesham AL-Matary.
 * Copyright (c) 2013 Gedare Bloom.
@@ -17,6 +25,14 @@
 extern "C" {
 #endif

+/**
+ *  @defgroup shared_mm MM Support
+ *
+ *  @ingroup shared_include
+ *
+ *  @brief MM Support Package
+ */
+
 void bsp_memory_management_initialize(void);

 #ifdef __cplusplus
--- a/c/src/lib/libbsp/shared/include/tm27.h
+++ b/c/src/lib/libbsp/shared/include/tm27.h
@@ -1,6 +1,12 @@
-/*
- *  Empty stub for tm27.h
+/**
+ *  @file
 *
+ *  @ingroup shared_tm27
+ *
+ *  @brief Empty stub for tm27.h
+ */
+
+/*
 *  The license and distribution terms for this file may be
 *  found in the file LICENSE in this distribution or at
 *  http://www.rtems.com/license/LICENSE.
@@ -13,8 +19,12 @@
 #ifndef __tm27_h
 #define __tm27_h

-/*
- *  Stuff for Time Test 27
+/**
+ *  @defgroup shared_tm27 Time Test 27
+ *
+ *  @ingroup shared_include
+ *
+ *  @brief Stuff for Time Test 27
 */

 #define MUST_WAIT_FOR_INTERRUPT 0
--- a/c/src/lib/libbsp/shared/include/u-boot.h
+++ b/c/src/lib/libbsp/shared/include/u-boot.h
@@ -1,3 +1,11 @@
+/**
+ *  @file
+ *
+ *  @ingroup shared_uboot
+ *
+ *  @brief U_BOOT Support
+ */
+
 /*
 * Copyright (c) 2010 embedded brains GmbH.  All rights reserved.
 *
@@ -27,6 +35,14 @@ extern "C" {

 extern bd_t bsp_uboot_board_info;

+/**
+ *  @defgroup shared_uboot U_BOOT Support
+ *
+ *  @ingroup shared_include
+ *
+ *  @brief U_BOOT Support Package
+ */
+
 void bsp_uboot_copy_board_info(const bd_t *src);

 #ifdef __cplusplus
--- a/c/src/lib/libbsp/shared/tod.h
+++ b/c/src/lib/libbsp/shared/tod.h
@@ -1,5 +1,12 @@
+/**
+ *  @file
+ *
+ *  @ingroup shared_tod
+ *
+ *  @brief Real Time Clock (MK48T08) for RTEMS on Score603e
+ */
+
 /*
- * Real Time Clock (MK48T08) for RTEMS on Score603e
 *
 *  Based on MVME162 TOD by:
 *    COPYRIGHT (C) 1997
@@ -18,8 +25,12 @@
 extern "C" {
 #endif

-/*
- *  Set the RTC.
+/**
+ *  @defgroup shared_tod RTC
+ *
+ *  @ingroup bsp_shared
+ *
+ *  @brief Set the RTC
 */

 int setRealTime(
--- a/c/src/lib/libbsp/shared/umon/cli.h
+++ b/c/src/lib/libbsp/shared/umon/cli.h
@@ -1,7 +1,12 @@
-/*
- *  cli.h - Header file for Command Line Interface related stuff
+/**
+ *  @file
 *
- *  Based upon code from MicroMonitor 1.17 from http://www.umonfw.com/
+ *  @ingroup shared_cli
+ *
+ *  @brief Header file for Command Line Interface related stuff
+ */
+
+/*  Based upon code from MicroMonitor 1.17 from http://www.umonfw.com/
 *  which includes this notice:
 *
 **************************************************************************
@@ -38,8 +43,14 @@
 extern "C" {
 #endif

-/* Command table structure used by the monitor:
+/**
+ *  @defgroup shared_cli Command table structure
+ *
+ *  @ingroup shared_umon
+ *
+ *  @brief Command table structure used by the monitor:
 */
+
 struct	monCommand {
    char    *name;					/* Name of command seen by user. */
    int	    (*func)(int,char **);	/* Called when command is invoked. */
--- a/c/src/lib/libbsp/shared/umon/doxygen.h
+++ b/c/src/lib/libbsp/shared/umon/doxygen.h
@@ -0,0 +1,7 @@
+/**
+ *  @defgroup shared_umon SHARED UMON Modules
+ *
+ *  @ingroup bsp_shared
+ *
+ *  @brief SHARED UMON Modules
+ */
--- a/c/src/lib/libbsp/shared/umon/monlib.h
+++ b/c/src/lib/libbsp/shared/umon/monlib.h
@@ -1,8 +1,13 @@
-/*
- *  monlib.h - Used by both the monitor and the application that
- *             may reside on top of the monitor
+/**
+ *  @file
 *
- *  Based upon code from MicroMonitor 1.17 from http://www.umonfw.com/
+ *  @ingroup shared_monlib
+ *
+ *  @brief Used by both the monitor and the application that
+ *  may reside on top of the monitor
+ */
+
+/*  Based upon code from MicroMonitor 1.17 from http://www.umonfw.com/
 *  which includes this notice:
 *
 **************************************************************************
@@ -42,6 +47,14 @@
 extern "C" {
 #endif

+/**
+ *  @defgroup shared_monlib MONLIB Support
+ *
+ *  @ingroup shared_umon
+ *
+ *  @brief MONLIB Support Package
+ */
+
 extern int monConnect(int (*monptr)(int,void *,void *,void *),
 		void (*lock)(void),void (*unlock)(void));
 extern void mon_getargv(int *argc,char ***argv);
--- a/c/src/lib/libbsp/shared/umon/tfs.h
+++ b/c/src/lib/libbsp/shared/umon/tfs.h
@@ -1,8 +1,13 @@
-/*
- *  tfs.h - Header file for TFS transactions, used by both application and
- *  monnitor.
+/**
+ *  @file
 *
- *  Based upon code from MicroMonitor 1.17 from http://www.umonfw.com/
+ *  @ingroup shared_tfs
+ *
+ *  @brief Header file for TFS transactions, used by both application and
+ *  monnitor.
+ */
+
+/*  Based upon code from MicroMonitor 1.17 from http://www.umonfw.com/
 *  which includes this notice:
 *
 **************************************************************************
@@ -35,6 +40,14 @@
 #ifndef _tfs_h
 #define _tfs_h

+/**
+ *  @defgroup shared_tfs TFS Support
+ *
+ *  @ingroup shared_umon
+ *
+ *  @brief TFS Support Package
+ */
+
 #define TFSINFOSIZE		23		/* Max size of info string (mod4-1). */

 #ifndef TFSNAMESIZE				/* This specifies the maximum size of a file */
--- a/c/src/lib/libbsp/shared/vmeUniverse/VME.h
+++ b/c/src/lib/libbsp/shared/vmeUniverse/VME.h
@@ -1,8 +1,14 @@
+/**
+ *  @file
+ *
+ *  @ingroup shared_vme
+ *
+ *  @brief SVGM et al. BSP's VME support
+ */
+
 #ifndef RTEMS_BSP_VME_API_H
 #define RTEMS_BSP_VME_API_H

-/* SVGM et al. BSP's VME support */
-
 /*
 * Authorship
 * ----------
@@ -57,12 +63,15 @@
 extern "C" {
 #endif

-/* VME related declarations */
-
-/*
- * BSP-specific configuration routine; sets up
+/**
+ *  @defgroup shared_vme VME related declarations
+ *
+ *  @ingroup shared_vmeuniverse
+ *
+ *  @brief BSP-specific configuration routine; sets up
 * VME windows and installs the VME interrupt manager.
 */
+
 void BSP_vme_config();

 /* translate through host bridge and vme master window of vme bridge */
--- a/c/src/lib/libbsp/shared/vmeUniverse/VMEDMA.h
+++ b/c/src/lib/libbsp/shared/vmeUniverse/VMEDMA.h
@@ -1,8 +1,14 @@
+/**
+ *  @file
+ *
+ *  @ingroup shared_vmedma
+ *
+ *  @brief Public interface of DMA routines
+ */
+
 #ifndef BSP_VME_DMA_H
 #define BSP_VME_DMA_H

-/* Public interface of DMA routines */
-
 /*
 * Authorship
 * ----------
@@ -54,6 +60,14 @@
 extern "C" {
 #endif

+/**
+ *  @defgroup shared_vmedma VMEDMA Support
+ *
+ *  @ingroup shared_vmeuniverse
+ *
+ *  @brief VMEDMA Support Package
+ */
+

 /* NOTE: Access to DMA Channels is *not* protected / thread-safe.
 *       It is the responsability of the user to provide appropriate
--- a/c/src/lib/libbsp/shared/vmeUniverse/bspVmeDmaList.h
+++ b/c/src/lib/libbsp/shared/vmeUniverse/bspVmeDmaList.h
@@ -1,9 +1,19 @@
+/**
+ *  @file
+ *
+ *  @ingroup shared_bspvmedmalist
+ *
+ *  @brief This header should only be used inside a BSP
+ * chosing to use bspVmeDmaList for implementing VMEDMA.h
+ */
+
 #ifndef BSP_VME_DMA_LIST_H
 #define BSP_VME_DMA_LIST_H



-/* The bspVmeDmaList utility implements part of the API defined by
+/*
+ * The bspVmeDmaList utility implements part of the API defined by
 * 'VMEDMA.h' namely all 'VMEDmaListDescriptor' related entry points:
 *
 * BSP_VMEDmaListDescriptorDestroy(),
@@ -31,9 +41,6 @@
 * and
 *
 * BSP_VMEDmaListDescriptorStartTool()
- *
- * This header should only be used inside a BSP
- * chosing to use bspVmeDmaList for implementing VMEDMA.h
 */

 /*
@@ -92,8 +99,12 @@ typedef struct VMEDmaListNodeRec_    *VMEDmaListNode;

 typedef struct VMEDmaListClassRec_   *VMEDmaListClass;

-/* Create and setup a new descriptor.
- * The BSP must supply the appropriate controller class.
+/**
+ *  @defgroup shared_bspvmedmalist Create and setup a new descriptor.
+ *
+ *  @ingroup shared_vmeuniverse
+ *
+ *  @brief The BSP must supply the appropriate controller class.
 */

 VMEDmaListNode
--- a/c/src/lib/libbsp/shared/vmeUniverse/bspVmeDmaListP.h
+++ b/c/src/lib/libbsp/shared/vmeUniverse/bspVmeDmaListP.h
@@ -1,10 +1,17 @@
+/**
+ *  @file
+ *
+ *  @ingroup shared_bspvmedmalistp
+ *
+ *  @brief Private Interface to the bspVmeDmaList facility
+ */
+
 #ifndef BSP_VME_DMA_LIST_P_H
 #define BSP_VME_DMA_LIST_P_H

 #include <bsp/bspVmeDmaList.h>

-/* Private Interface to the bspVmeDmaList facility
- *
+/*
 * This is used by chip drivers to implement the
 * 'class' members so that 'bspVmeDmaList' can access
 * the device in an abstract manner.
@@ -60,7 +67,13 @@ extern "C" {

 typedef void           *DmaDescriptor;

-/* Member functions to be implemented by chip drivers */
+/**
+ *  @defgroup shared_bspvmedmalistp member functions
+ *
+ *  @ingroup shared_vmeuniverse
+ *
+ *  @brief Member functions to be implemented by chip drivers
+ */

 typedef DmaDescriptor (*DmaDescriptorAlloc)(void);
 typedef void          (*DmaDescriptorFree) (DmaDescriptor d);
--- a/c/src/lib/libbsp/shared/vmeUniverse/doxygen.h
+++ b/c/src/lib/libbsp/shared/vmeUniverse/doxygen.h
@@ -0,0 +1,7 @@
+/**
+ *  @defgroup shared_vmeuniverse SHARED VMEUNIVERSE Modules
+ *
+ *  @ingroup bsp_shared
+ *
+ *  @brief SHARED VMEUNIVERSE Modules
+ */
--- a/c/src/lib/libbsp/shared/vmeUniverse/vmeTsi148.h
+++ b/c/src/lib/libbsp/shared/vmeUniverse/vmeTsi148.h
@@ -1,8 +1,14 @@
+/**
+ *  @file
+ *
+ *  @ingroup shared_vmetsi148
+ *
+ *  @brief Driver for the Tundra Tsi148 pci-vme bridge
+ */
+
 #ifndef VME_TSI148_DRIVER_H
 #define VME_TSI148_DRIVER_H

-/* Driver for the Tundra Tsi148 pci-vme bridge */
-
 /*
 * Authorship
 * ----------
@@ -52,6 +58,14 @@
 #include <bsp/vme_am_defs.h>


+/**
+ *  @defgroup shared_vmetsi148 VMETSI148 Support
+ *
+ *  @ingroup shared_vmeuniverse
+ *
+ *  @brief VMETSI148 Support Package
+ */
+
 /* NOTE: A64 currently not implemented */

 /* These can be ored with the AM */
--- a/c/src/lib/libbsp/shared/vmeUniverse/vmeTsi148DMA.h
+++ b/c/src/lib/libbsp/shared/vmeUniverse/vmeTsi148DMA.h
@@ -1,3 +1,11 @@
+/**
+ *  @file
+ *
+ *  @ingroup shared_vmetsi148dma
+ *
+ *  @brief vmeTsi148DMA Support
+ */
+
 #ifndef VME_TSI148_DMA_H
 #define VME_TSI148_DMA_H

@@ -51,7 +59,14 @@
 extern "C" {
 #endif

-/* DMA List access functions for use by bspVmeDmaList */
+/**
+ *  @defgroup shared_vmetsi148dma DMA List
+ *
+ *  @ingroup shared_vmeuniverse
+ *
+ *  @brief DMA List access functions for use by bspVmeDmaList
+ */
+
 extern struct VMEDmaListClassRec_ vmeTsi148DmaListClass;

 typedef struct VmeTsi148DmaListDescriptorRec_ *VmeTsi148DmaListDescriptor;
--- a/c/src/lib/libbsp/shared/vmeUniverse/vmeUniverse.h
+++ b/c/src/lib/libbsp/shared/vmeUniverse/vmeUniverse.h
@@ -1,8 +1,14 @@
+/**
+ *  @file
+ *
+ *  @ingroup shared_vmeuniverse
+ *
+ *  @brief Driver for the Tundra Universe II pci-vme bridge
+ */
+
 #ifndef VME_UNIVERSE_UTIL_H
 #define VME_UNIVERSE_UTIL_H

-/* Driver for the Tundra Universe II pci-vme bridge */
-
 /*
 * Authorship
 * ----------
@@ -48,8 +54,13 @@
 * ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03
 */

-/* Register definitions */
-/* NOTE: all registers contents in PCI space are LITTLE ENDIAN */
+/**
+ *  @defgroup shared_vmeuniverse Register definitions
+ *
+ *  @ingroup bsp_shared
+ *
+ *  @brief all registers contents in PCI space are LITTLE ENDIAN
+ */

 #ifdef __vxworks
 #include <vme.h>
--- a/c/src/lib/libbsp/shared/vmeUniverse/vmeUniverseDMA.h
+++ b/c/src/lib/libbsp/shared/vmeUniverse/vmeUniverseDMA.h
@@ -1,3 +1,11 @@
+/**
+ *  @file
+ *
+ *  @ingroup shared_vmeuniversedma
+ *
+ *  @brief vmeUniverseDMA Support
+ */
+
 #ifndef VME_UNIVERSE_DMA_H
 #define VME_UNIVERSE_DMA_H

@@ -52,6 +60,14 @@
 extern "C" {
 #endif

+/**
+ *  @defgroup shared_vmeuniversedma vmeUniverseDMA Support
+ *
+ *  @ingroup shared_vmeuniverse
+ *
+ *  @brief vmeUniverseDMA Support Package
+ */
+
 extern struct VMEDmaListClassRec_ vmeUniverseDmaListClass;

 int
--- a/c/src/lib/libbsp/shared/vmeUniverse/vme_am_defs.h
+++ b/c/src/lib/libbsp/shared/vmeUniverse/vme_am_defs.h
@@ -1,8 +1,14 @@
+/**
+ *  @file
+ *
+ *  @ingroup shared_vmeamdefs
+ *
+ *  @brief vxworks compatible addressing modes
+ */
+
 #ifndef VME_AM_DEFINITIONS_H
 #define VME_AM_DEFINITIONS_H

-/* vxworks compatible addressing modes */
-
 /*
 * Authorship
 * ----------
@@ -47,7 +53,14 @@
 *
 * ------------------ SLAC Software Notices, Set 4 OTT.002a, 2004 FEB 03
 */
-/* NOTE: 64-bit *addresses* are not supported [data are]. */
+
+/**
+ *  @defgroup shared_vmeamdefs VME_AM_DEFS
+ *
+ *  @ingroup shared_vmeuniverse
+ *
+ *  @brief 64-bit *addresses* are not supported [data are].
+ */

 #ifndef VME_AM_STD_SUP_BLT
 #define	VME_AM_STD_SUP_BLT			0x3f