Fix #445, create osal api guide with doxygen

cmake/Makefile.sample

@@ -147,6 +147,10 @@ usersguide:
 	$(MAKE) --no-print-directory -C "$(O)" cfe-usersguide
 	@/bin/echo -e "\n\ncFE Users Guide: \nfile://$(CURDIR)/$(O)/doc/users_guide/html/index.html\n"
 
+osalguide:
+	$(MAKE) --no-print-directory -C "$(O)" osalguide
+	@/bin/echo -e "\n\nOsal Users Guide: \nfile://$(CURDIR)/$(O)/doc/osal_guide/html/index.html\n"
+
 # Make all the commands that use the build tree depend on a flag file
 # that is used to indicate the prep step has been done.  This way
 # the prep step does not need to be done explicitly by the user

cmake/mission_build.cmake

@@ -213,7 +213,10 @@ function(prepare)
 
   configure_file("${CMAKE_SOURCE_DIR}/cmake/cfe-common.doxyfile.in"
     "${CMAKE_BINARY_DIR}/doc/cfe-common.doxyfile")
-
+
+ configure_file("${CMAKE_SOURCE_DIR}/cmake/osal-common.doxyfile.in"
+    "${CMAKE_BINARY_DIR}/doc/osal-common.doxyfile")
+
   configure_file("${CMAKE_SOURCE_DIR}/cmake/mission-detaildesign.doxyfile.in"
     "${CMAKE_BINARY_DIR}/doc/mission-detaildesign.doxyfile")
 
@@ -224,6 +227,11 @@ function(prepare)
     "${MISSION_SOURCE_DIR}/psp/fsw/inc/*.h")
   string(REPLACE ";" " \\\n" MISSION_USERGUIDE_HEADERFILES "${MISSION_USERGUIDE_HEADERFILES}") 
 
+  # OSAL API GUIDE include PUBLIC API
+  file(GLOB MISSION_OSAL_HEADERFILES 
+    "${osal_MISSION_DIR}/src/os/inc/*.h")
+  string(REPLACE ";" " \\\n" MISSION_OSAL_HEADERFILES "${MISSION_OSAL_HEADERFILES}") 
+
   # Addition to usersguide
   file(GLOB USERGUIDE_MISC_ADDITION
        "${cfe-core_MISSION_DIR}/src/inc/private/*.h"
@@ -235,9 +243,15 @@ function(prepare)
   # PREDEFINED
   set(USERGUIDE_PREDEFINED 
       "MESSAGE_FORMAT_IS_CCSDS")
+
+  set(OSALGUIDE_PREDEFINED 
+      "MESSAGE_FORMAT_IS_CCSDS")
 
   configure_file("${CMAKE_SOURCE_DIR}/cmake/cfe-usersguide.doxyfile.in"
     "${CMAKE_BINARY_DIR}/doc/cfe-usersguide.doxyfile")
+
+  configure_file("${CMAKE_SOURCE_DIR}/cmake/osalguide.doxyfile.in"
+    "${CMAKE_BINARY_DIR}/doc/osalguide.doxyfile")  
 
   add_custom_target(mission-doc 
     doxygen mission-detaildesign.doxyfile 
@@ -247,6 +261,10 @@ function(prepare)
     doxygen cfe-usersguide.doxyfile 
     WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/doc") 
 
+  add_custom_target(osalguide 
+    doxygen osalguide.doxyfile 
+    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/doc") 
+
   # Certain runtime variables need to be "exported" to the subordinate build, such as
   # the specific arch settings and the location of all the apps.  This is done by creating
   # a temporary file within the dir and then the subprocess will read that file and re-create

cmake/osal-common.doxyfile.in

@@ -0,0 +1,248 @@
+#---------------------------------------------------------------------------
+# Project related configuration options, shared for all cFE doxygen outputs
+#---------------------------------------------------------------------------
+@INCLUDE_PATH          = @MISSION_SOURCE_DIR@
+DOXYFILE_ENCODING      = UTF-8 
+CREATE_SUBDIRS         = NO
+OUTPUT_LANGUAGE        = English
+OUTPUT_DIRECTORY       = .
+BRIEF_MEMBER_DESC      = YES
+REPEAT_BRIEF           = NO
+ABBREVIATE_BRIEF       = "The $name class " \
+                         "The $name widget " \
+                         "The $name file " \
+                         is \
+                         provides \
+                         specifies \
+                         contains \
+                         represents \
+                         a \
+                         an \
+                         the
+ALWAYS_DETAILED_SEC    = NO
+INLINE_INHERITED_MEMB  = NO
+FULL_PATH_NAMES        = YES
+SHORT_NAMES            = NO
+JAVADOC_AUTOBRIEF      = NO
+QT_AUTOBRIEF           = NO
+MULTILINE_CPP_IS_BRIEF = NO
+DETAILS_AT_TOP         = NO
+INHERIT_DOCS           = YES
+SEPARATE_MEMBER_PAGES  = NO
+TAB_SIZE               = 8
+OPTIMIZE_OUTPUT_FOR_C  = YES
+OPTIMIZE_OUTPUT_JAVA   = NO
+BUILTIN_STL_SUPPORT    = NO
+CPP_CLI_SUPPORT        = NO
+SIP_SUPPORT            = NO
+DISTRIBUTE_GROUP_DOC   = NO
+SUBGROUPING            = YES
+TYPEDEF_HIDES_STRUCT   = NO
+#---------------------------------------------------------------------------
+# Build related configuration options
+#---------------------------------------------------------------------------
+EXTRACT_ALL            = YES
+EXTRACT_PRIVATE        = YES
+EXTRACT_STATIC         = YES
+EXTRACT_LOCAL_CLASSES  = YES
+EXTRACT_LOCAL_METHODS  = NO
+EXTRACT_ANON_NSPACES   = NO
+HIDE_UNDOC_MEMBERS     = NO
+HIDE_UNDOC_CLASSES     = NO
+HIDE_FRIEND_COMPOUNDS  = NO
+HIDE_IN_BODY_DOCS      = NO
+INTERNAL_DOCS          = NO
+CASE_SENSE_NAMES       = NO
+HIDE_SCOPE_NAMES       = NO
+SHOW_INCLUDE_FILES     = YES
+INLINE_INFO            = YES
+SORT_MEMBER_DOCS       = YES
+SORT_BRIEF_DOCS        = NO
+SORT_BY_SCOPE_NAME     = NO
+GENERATE_TODOLIST      = NO
+GENERATE_TESTLIST      = YES
+GENERATE_BUGLIST       = YES
+GENERATE_DEPRECATEDLIST= YES
+ENABLED_SECTIONS       = 
+MAX_INITIALIZER_LINES  = 30
+SHOW_USED_FILES        = YES
+SHOW_DIRECTORIES       = YES
+FILE_VERSION_FILTER    = 
+#---------------------------------------------------------------------------
+# configuration options related to warning and progress messages
+#---------------------------------------------------------------------------
+QUIET                  = NO
+WARNINGS               = YES
+WARN_IF_UNDOCUMENTED   = YES
+WARN_IF_DOC_ERROR      = YES
+WARN_NO_PARAMDOC       = YES
+WARN_FORMAT            = "$file:$line: $text "
+WARN_LOGFILE           = @CMAKE_BINARY_DIR@/doc/warnings.log
+#---------------------------------------------------------------------------
+# configuration options related to the input files
+#---------------------------------------------------------------------------
+INPUT_ENCODING         = UTF-8
+STRIP_FROM_PATH        = @MISSION_SOURCE_DIR@ 
+
+# Always include a standard set of CFE documentation in the input set
+# This is applicable to both users guide and detail design outputs
+#IMAGE_PATH            += 
+INPUT                  += @MISSION_SOURCE_DIR@/cfe/docs/src/osal_fs.dox 
+INPUT                  += @MISSION_SOURCE_DIR@/cfe/docs/src/osal_timer.dox 
+
+FILE_PATTERNS          = *.c *.cpp *.cc *.C *.h *.hh *.hpp *.H *.dox *.md
+RECURSIVE              = YES
+EXCLUDE                = 
+EXCLUDE_SYMLINKS       = NO
+EXCLUDE_PATTERNS       = 
+EXCLUDE_SYMBOLS        = 
+EXAMPLE_PATH           = 
+EXAMPLE_PATTERNS       = *
+EXAMPLE_RECURSIVE      = NO
+INPUT_FILTER           = 
+FILTER_PATTERNS        = 
+FILTER_SOURCE_FILES    = NO
+#---------------------------------------------------------------------------
+# configuration options related to source browsing
+#---------------------------------------------------------------------------
+SOURCE_BROWSER         = YES
+INLINE_SOURCES         = NO
+STRIP_CODE_COMMENTS    = YES
+REFERENCED_BY_RELATION = YES
+REFERENCES_RELATION    = YES
+REFERENCES_LINK_SOURCE = YES
+USE_HTAGS              = NO
+VERBATIM_HEADERS       = YES
+#---------------------------------------------------------------------------
+# configuration options related to the alphabetical class index
+#---------------------------------------------------------------------------
+ALPHABETICAL_INDEX     = YES
+COLS_IN_ALPHA_INDEX    = 5
+IGNORE_PREFIX          = 
+#---------------------------------------------------------------------------
+# configuration options related to the HTML output
+#---------------------------------------------------------------------------
+GENERATE_HTML          = YES
+HTML_OUTPUT            = html
+HTML_FILE_EXTENSION    = .html
+HTML_HEADER            = 
+HTML_FOOTER            = 
+HTML_STYLESHEET        = 
+HTML_ALIGN_MEMBERS     = YES
+GENERATE_HTMLHELP      = NO
+HTML_DYNAMIC_SECTIONS  = NO
+CHM_FILE               = 
+HHC_LOCATION           = 
+GENERATE_CHI           = NO
+BINARY_TOC             = NO
+TOC_EXPAND             = NO
+DISABLE_INDEX          = NO
+ENUM_VALUES_PER_LINE   = 4
+GENERATE_TREEVIEW      = NO
+TREEVIEW_WIDTH         = 250
+#---------------------------------------------------------------------------
+# configuration options related to the LaTeX output
+#---------------------------------------------------------------------------
+GENERATE_LATEX         = NO
+LATEX_OUTPUT           = latex
+LATEX_CMD_NAME         = latex
+MAKEINDEX_CMD_NAME     = makeindex
+COMPACT_LATEX          = YES
+PAPER_TYPE             = letter
+EXTRA_PACKAGES         = 
+LATEX_HEADER           = 
+PDF_HYPERLINKS         = YES
+USE_PDFLATEX           = YES
+LATEX_BATCHMODE        = NO
+LATEX_HIDE_INDICES     = NO
+#---------------------------------------------------------------------------
+# configuration options related to the RTF output
+#---------------------------------------------------------------------------
+GENERATE_RTF           = NO
+RTF_OUTPUT             = rtf
+COMPACT_RTF            = YES
+RTF_HYPERLINKS         = NO
+RTF_STYLESHEET_FILE    = 
+RTF_EXTENSIONS_FILE    = 
+#---------------------------------------------------------------------------
+# configuration options related to the man page output
+#---------------------------------------------------------------------------
+GENERATE_MAN           = NO
+MAN_OUTPUT             = man
+MAN_EXTENSION          = .3
+MAN_LINKS              = NO
+#---------------------------------------------------------------------------
+# configuration options related to the XML output
+#---------------------------------------------------------------------------
+GENERATE_XML           = NO
+XML_OUTPUT             = xml
+XML_SCHEMA             = 
+XML_DTD                = 
+XML_PROGRAMLISTING     = YES
+#---------------------------------------------------------------------------
+# configuration options for the AutoGen Definitions output
+#---------------------------------------------------------------------------
+GENERATE_AUTOGEN_DEF   = NO
+#---------------------------------------------------------------------------
+# configuration options related to the Perl module output
+#---------------------------------------------------------------------------
+GENERATE_PERLMOD       = NO
+PERLMOD_LATEX          = NO
+PERLMOD_PRETTY         = YES
+PERLMOD_MAKEVAR_PREFIX = 
+#---------------------------------------------------------------------------
+# Configuration options related to the preprocessor   
+#---------------------------------------------------------------------------
+ENABLE_PREPROCESSING   = YES
+MACRO_EXPANSION        = NO
+EXPAND_ONLY_PREDEF     = NO
+SEARCH_INCLUDES        = YES
+INCLUDE_PATH           = 
+INCLUDE_FILE_PATTERNS  = 
+EXPAND_AS_DEFINED      = 
+SKIP_FUNCTION_MACROS   = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to external references   
+#---------------------------------------------------------------------------
+TAGFILES               = 
+GENERATE_TAGFILE       = 
+ALLEXTERNALS           = NO
+EXTERNAL_GROUPS        = YES
+PERL_PATH              = /usr/bin/perl
+#---------------------------------------------------------------------------
+# Configuration options related to the dot tool   
+#---------------------------------------------------------------------------
+CLASS_DIAGRAMS         = NO
+MSCGEN_PATH            = 
+HIDE_UNDOC_RELATIONS   = YES
+HAVE_DOT               = YES
+CLASS_GRAPH            = NO
+COLLABORATION_GRAPH    = NO
+GROUP_GRAPHS           = YES
+UML_LOOK               = NO
+TEMPLATE_RELATIONS     = NO
+INCLUDE_GRAPH          = NO
+INCLUDED_BY_GRAPH      = NO
+CALL_GRAPH             = YES
+CALLER_GRAPH           = NO
+GRAPHICAL_HIERARCHY    = NO
+DIRECTORY_GRAPH        = YES
+DOT_IMAGE_FORMAT       = png
+DOT_PATH               = 
+DOTFILE_DIRS           = 
+DOT_GRAPH_MAX_NODES    = 50
+MAX_DOT_GRAPH_DEPTH    = 1000
+DOT_TRANSPARENT        = NO
+DOT_MULTI_TARGETS      = NO
+GENERATE_LEGEND        = YES
+DOT_CLEANUP            = YES
+#---------------------------------------------------------------------------
+# Configuration::additions related to the search engine   
+#---------------------------------------------------------------------------
+SEARCHENGINE           = NO
+
+#---------------------------------------------------------------------------
+# OSAL mnemonic mappings
+#---------------------------------------------------------------------------
+#@INCLUDE = 
+

cmake/osalguide.doxyfile.in

@@ -0,0 +1,22 @@
+#---------------------------------------------------------------------------
+# Doxygen Configuration options to generate the "OSAL API Guide"
+#---------------------------------------------------------------------------
+
+# Start with the common definitions, some of which are extended or overridden here.
+
+@INCLUDE               = @MISSION_BINARY_DIR@/doc/osal-common.doxyfile
+PROJECT_NAME           = "Core Flight Executive OSAL API Guide"
+OUTPUT_DIRECTORY       = osalguide
+GENERATE_LATEX         = YES
+
+# Main page for the osal guide
+INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/osalmain.dox 
+INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/osalguide.dox
+
+#PREDEFINED
+PREDEFINED            += @OSALGUIDE_PREDEFINED@
+
+# Bring in the cFE header files for the documentation of the various API calls
+INPUT                 += \
+@MISSION_OSAL_HEADERFILES@ \
+@OSAL_MISC_ADDITION@                

docs/src/osal_fs.dox

@@ -0,0 +1,50 @@
+/**
+\page osalfsovr File System Overview
+
+The File System API is a thin wrapper around a selection of POSIX file APIs. In addition the File System API presents a common directory structure and volume view regardless of the underlying system type. For example, vxWorks uses MS-DOS style volume names and directories. For example, a vxWorks RAM disk might have the volume “RAM:0”. With this File System API, volumes are represented as Unix-style paths where each volume is mounted on the root file system: 
+
+<UL>
+    <LI>RAM:0/file1.dat becomes /mnt/ram/file1.dat
+    <LI>FL:0/file2.dat becomes /mnt/fl/file2.dat
+</UL>
+
+This abstraction allows the applications to use the same paths regardless of the implementation and it also allows file systems to be simulated on a desktop system for testing. On a desktop Linux system, the file system abstraction can be set up to map virtual devices to a regular directory. This is accomplished through the OS_mkfs call, OS_mount call, and a BSP specific volume table that maps the virtual devices to real devices or underlying file systems.
+
+In order to make this file system volume abstraction work, a “Volume Table” needs to be provided in the Board Support Package of the application. The table has the following fields:
+
+<UL>
+   <LI> Device Name: This is the name of the virtual device that the Application uses. Common names are “ramdisk1”, “flash1”, or “volatile1” etc. But the name can be any unique string.
+
+   <LI>Physical Device Name: This is an implementation specific field. For vxWorks it is not needed and can be left blank. For a File system based implementation, it is the “mount point” on the root file system where all of the volume will be mounted. A common place for this on Linux could be a user’s home directory, “/tmp”, or even the current working directory “.”. In the example of “/tmp” all of the directories created for the volumes would be under “/tmp” on the Linux file system. For a real disk device in Linux, such as a RAM disk, this field is the device name “/dev/ram0”. 
+
+   <LI>Volume Type: This field defines the type of volume. The types are: FS_BASED which uses the existing file system, RAM_DISK which uses a RAM_DISK device in vxWorks, RTEMS, or Linux, FLASH_DISK_FORMAT which uses a flash disk that is to be formatted before use, FLASH_DISK_INIT which uses a flash disk with an existing format that is just to be initialized before it’s use, EEPROM which is for an EEPROM or PROM based system.
+
+   <LI>Volatile Flag: This flag indicates that the volume or disk is a volatile disk (RAM disk ) or a non-volatile disk, that retains its contents when the system is rebooted. This should be set to TRUE or FALSE. 
+
+   <LI>Free Flag: This is an internal flag that should be set to FALSE or zero.
+
+   <LI>Is Mounted Flag: This is an internal flag that should be set to FALSE or zero. Note that a “pre-mounted” FS_BASED path can be set up by setting this flag to one.
+
+   <LI>Volume Name: This is an internal field and should be set to a space character “ “.
+
+   <LI>Mount Point Field: This is an internal field and should be set to a space character “ “.
+
+   <LI>Block Size Field: This is used to record the block size of the device and does not need to be set by the user.
+</UL>
+
+**/
+
+/**
+\page osalfsfd File Descriptors In Osal 
+
+The OSAL uses abstracted file descriptors. This means that the file descriptors passed back from the OS_open and OS_creat calls will only work with other OSAL OS_* calls. The reasoning for this is as follows:
+
+Because the OSAL now keeps track of all file descriptors, OSAL specific information can be associated with a specific file descriptor in an OS independent way. For instance, the path of the file that the file descriptor points to can be easily retrieved. Also, the OSAL task ID of the task that opened the file can also be retrieved easily.  Both of these pieces of information are very useful when trying to determine statistics for a task, or the entire system. This information can all be retrieved with a single API, OS_FDGetInfo. 
+
+Realizing that we cannot provide all of the file system calls that everyone would need, we also provide the underlying OS's file descriptor for any valid OSAL file descriptor. This way, you can manipulate the underlying file descriptor as needed.
+
+There are some small drawbacks with the OSAL file descriptors. Because the related information is kept in a table., there is a define called OS_MAX_NUM_OPEN_FILES that defines the maximum number of file descriptors available. This is a configuration parameter, and can be changed to fit your needs. 
+
+Also, if you open or create a file not using the OSAL calls (OS_open or OS_creat) then none of the other OS_* calls that accept a file descriptor as a parameter will work (the results of doing so are undefined). Therefore, if you open a file with the underlying OS's open call, you must continue to use the OS's calls until you close the file descriptor. Be aware that by doing this your software may no longer be OS agnostic.
+
+**/

docs/src/osal_timer.dox

@@ -0,0 +1,7 @@
+/**
+\page osaltimerover Timer Overview
+
+The timer API is a generic interface to the OS timer facilities. It is implemented using the POSIX timers on Linux and vxWorks and the native timer API on RTEMS. The OS X version is not complete, and will have to be simulated, since the POSIX timer API is not supported on OS X. Cygwin support is TBD. The number of timers supported is controlled by the configuration parameter OS_MAX_TIMERS.
+
+
+**/