diff --git a/cmake/Makefile.sample b/cmake/Makefile.sample index e3025af0e..9480a4d3f 100644 --- a/cmake/Makefile.sample +++ b/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 diff --git a/cmake/mission_build.cmake b/cmake/mission_build.cmake index e9e961f84..a362647ab 100644 --- a/cmake/mission_build.cmake +++ b/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 diff --git a/cmake/osal-common.doxyfile.in b/cmake/osal-common.doxyfile.in new file mode 100644 index 000000000..6c4c39e62 --- /dev/null +++ b/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 = + diff --git a/cmake/osalguide.doxyfile.in b/cmake/osalguide.doxyfile.in new file mode 100644 index 000000000..c8587a832 --- /dev/null +++ b/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@ \ No newline at end of file diff --git a/docs/src/osal_fs.dox b/docs/src/osal_fs.dox new file mode 100644 index 000000000..f99a569e1 --- /dev/null +++ b/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: + + + +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: + + + +**/ + +/** +\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. + +**/ \ No newline at end of file diff --git a/docs/src/osal_timer.dox b/docs/src/osal_timer.dox new file mode 100644 index 000000000..7ff825f37 --- /dev/null +++ b/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. + + +**/ \ No newline at end of file diff --git a/docs/src/osalguide.dox b/docs/src/osalguide.dox new file mode 100644 index 000000000..a80dfd521 --- /dev/null +++ b/docs/src/osalguide.dox @@ -0,0 +1,30 @@ +/** + \page osalguide Osal API Guide + + +**/ + diff --git a/docs/src/osalmain.dox b/docs/src/osalmain.dox new file mode 100644 index 000000000..320f970d1 --- /dev/null +++ b/docs/src/osalmain.dox @@ -0,0 +1,50 @@ +/** + \mainpage Osal API Documentation + + +**/ + +/** +\page osalIntro OSAL Introduction + +The goal of this library is to promote the creation of portable and reusable real time embedded system software. Given the necessary OS abstraction layer implementations, the same embedded software should compile and run on a number of platforms ranging from spacecraft computer systems to desktop PCs. + +The OS Application Program Interfaces (APIs) are broken up into three major sections: Real Time Operating System APIs, File System APIs, and Interrupt/Exception APIs. The Real Time Operating System APIs cover functionality such as Tasks, Queues, Semaphores, Interrupts, etc. The File System API abstracts the file systems that may be present on a system, and has the ability to simulate multiple embedded file systems on a desktop computer for testing. The Interrupt/Exception APIs are for configuring interrupt and exception handlers. + +Major changes from the first version of this API include the ability to create objects “on the fly”, meaning they do not require a pre-defined ID in order to create them; instead they return the ID of the created object. Also the corresponding delete functions have been added, allowing the user to create and delete OS objects dynamically. Another change has been the removal of functions that were application specific. This release is aimed at generic embedded systems, not necessarily flight software applications. The addition of the file system API is another major addition, along with a method of simulating embedded file systems on a desktop computer. Finally, the parameters and error return codes have been cleaned up for consistency. + +Note on OSAL call restrictions: Each of these calls should be called from a task running in the context of an OSAL application. This means that the startup code should call OS_API_init, and each task/thread that is created should call OS_TaskRegister. In general, these calls should not be called from an ISR. There are a few exceptions, such as the ability to give a binary semaphore from an ISR. + +**/ + + +