shared vmeUniverse: Improve Doxygen

22 files changed, 311 insertions, 60 deletions

diff --git a/c/src/lib/libbsp/shared/doxygen.h b/c/src/lib/libbsp/shared/doxygen.h
index a552b25f86..bbc7bb972f 100644
--- 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
+ */
\ No newline at end of file
diff --git a/c/src/lib/libbsp/shared/include/coverhd.h b/c/src/lib/libbsp/shared/include/coverhd.h
index 67fc5305f3..833bad2530 100644
--- 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
+ *
+ *  @ingroup shared_coverhd
  *
- *  This include file has defines to represent the overhead associated
+ *  @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).
diff --git a/c/src/lib/libbsp/shared/include/default-initial-extension.h b/c/src/lib/libbsp/shared/include/default-initial-extension.h
index 44938c8de3..c5655cfeda 100644
--- 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,
diff --git a/c/src/lib/libbsp/shared/include/doxygen.h b/c/src/lib/libbsp/shared/include/doxygen.h
new file mode 100644
index 0000000000..3069a1fe6a
--- /dev/null
+++ 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
+ */
\ No newline at end of file
diff --git a/c/src/lib/libbsp/shared/include/mm.h b/c/src/lib/libbsp/shared/include/mm.h
index 1a1eb7ffa2..3d904cba2a 100644
--- 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
diff --git a/c/src/lib/libbsp/shared/include/tm27.h b/c/src/lib/libbsp/shared/include/tm27.h
index b01c2beb0f..d1106757d3 100644
--- 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
diff --git a/c/src/lib/libbsp/shared/include/u-boot.h b/c/src/lib/libbsp/shared/include/u-boot.h
index b2427dcfc1..68df5babe4 100644
--- 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
diff --git a/c/src/lib/libbsp/shared/tod.h b/c/src/lib/libbsp/shared/tod.h
index f8b33855f9..411d36917a 100644
--- 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(
diff --git a/c/src/lib/libbsp/shared/umon/cli.h b/c/src/lib/libbsp/shared/umon/cli.h
index 0cf2bb1833..0e1689db26 100644
--- 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. */
diff --git a/c/src/lib/libbsp/shared/umon/doxygen.h b/c/src/lib/libbsp/shared/umon/doxygen.h
new file mode 100644
index 0000000000..a74d3c3e8b
--- /dev/null
+++ 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
+ */
\ No newline at end of file
diff --git a/c/src/lib/libbsp/shared/umon/monlib.h b/c/src/lib/libbsp/shared/umon/monlib.h
index bc87c20815..efbfc93d59 100644
--- 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);
diff --git a/c/src/lib/libbsp/shared/umon/tfs.h b/c/src/lib/libbsp/shared/umon/tfs.h
index d84f859a66..258288bd14 100644
--- 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
+ *
+ *  @ingroup shared_tfs
  *
- *  Based upon code from MicroMonitor 1.17 from http://www.umonfw.com/
+ *  @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 */
diff --git a/c/src/lib/libbsp/shared/vmeUniverse/VME.h b/c/src/lib/libbsp/shared/vmeUniverse/VME.h
index 6135ae798a..bdaa45870e 100644
--- 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 */
diff --git a/c/src/lib/libbsp/shared/vmeUniverse/VMEDMA.h b/c/src/lib/libbsp/shared/vmeUniverse/VMEDMA.h
index 85f6ad7d75..6b53b127d6 100644
--- 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
diff --git a/c/src/lib/libbsp/shared/vmeUniverse/bspVmeDmaList.h b/c/src/lib/libbsp/shared/vmeUniverse/bspVmeDmaList.h
index 37d7f8bb1c..414afab5c9 100644
--- 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
diff --git a/c/src/lib/libbsp/shared/vmeUniverse/bspVmeDmaListP.h b/c/src/lib/libbsp/shared/vmeUniverse/bspVmeDmaListP.h
index 579d48e274..1a1f97b9ad 100644
--- 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);
diff --git a/c/src/lib/libbsp/shared/vmeUniverse/doxygen.h b/c/src/lib/libbsp/shared/vmeUniverse/doxygen.h
new file mode 100644
index 0000000000..88ded941ac
--- /dev/null
+++ 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
+ */
\ No newline at end of file
diff --git a/c/src/lib/libbsp/shared/vmeUniverse/vmeTsi148.h b/c/src/lib/libbsp/shared/vmeUniverse/vmeTsi148.h
index b2df80001d..6183940a2d 100644
--- 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 */
diff --git a/c/src/lib/libbsp/shared/vmeUniverse/vmeTsi148DMA.h b/c/src/lib/libbsp/shared/vmeUniverse/vmeTsi148DMA.h
index 21eeea2dbd..da7c99302b 100644
--- 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;
diff --git a/c/src/lib/libbsp/shared/vmeUniverse/vmeUniverse.h b/c/src/lib/libbsp/shared/vmeUniverse/vmeUniverse.h
index fd30694b91..7cb9f8d2de 100644
--- 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>
diff --git a/c/src/lib/libbsp/shared/vmeUniverse/vmeUniverseDMA.h b/c/src/lib/libbsp/shared/vmeUniverse/vmeUniverseDMA.h
index f720c0d662..d0a3d6f0e7 100644
--- 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
diff --git a/c/src/lib/libbsp/shared/vmeUniverse/vme_am_defs.h b/c/src/lib/libbsp/shared/vmeUniverse/vme_am_defs.h
index fb6b72bc8b..efa28b3aa0 100644
--- 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