diff --git a/CMakeLists.txt b/CMakeLists.txt index cad3c0324..8af13cb34 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -48,10 +48,10 @@ project(OSAL C) # part of the open source release. # CAUTION: The API between the OSAL and the low level implementation and/or BSP # is not stabilized, and may change with every OSAL release. No attempt is made -# to provide backward compatibility with to external sources. -set(OSAL_EXT_SOURCE_DIR "$ENV{OSAL_EXT_SOURCE_DIR}" +# to provide backward compatibility with to external sources. +set(OSAL_EXT_SOURCE_DIR "$ENV{OSAL_EXT_SOURCE_DIR}" CACHE PATH "External source directory to check for additional OS/BSP implementations") - + # Read the default compile-time configuration, and update with # any mission/project specific options in the OSAL_CONFIGURATION_FILE include("${OSAL_SOURCE_DIR}/default_config.cmake") @@ -170,7 +170,7 @@ if (OSAL_BSP_INCLUDE_DIRECTORIES) include_directories(${OSAL_BSP_INCLUDE_DIRECTORIES}) endif (OSAL_BSP_INCLUDE_DIRECTORIES) -set(BSP_SRCLIST +set(BSP_SRCLIST src/bsp/shared/src/osapi-bsp.c src/bsp/shared/src/bsp_default_app_run.c src/bsp/shared/src/bsp_default_app_startup.c @@ -351,6 +351,10 @@ if (HAS_PARENT) # when building code intended for coverage analysis. set(UT_COVERAGE_COMPILE_FLAGS "${UT_COVERAGE_COMPILE_FLAGS}" PARENT_SCOPE) set(UT_COVERAGE_LINK_FLAGS "${UT_COVERAGE_LINK_FLAGS}" PARENT_SCOPE) +else(HAS_PARENT) + # In a standalone build, also add the documentation target(s) + # Note that in a CFE/integrated build, it is expected this will be built separately. + add_subdirectory(doc/src doc) endif(HAS_PARENT) diff --git a/doc/src/CMakeLists.txt b/doc/src/CMakeLists.txt new file mode 100644 index 000000000..7d8dfd6ad --- /dev/null +++ b/doc/src/CMakeLists.txt @@ -0,0 +1,91 @@ +######################################################## +# +# CMake Recipe to build OSAL API guide documentation +# +######################################################## + +# +# This CMake script currently defines a top-level target "apiguide" +# to build the OSAL API documentation. This may be invoked either +# from the main OSAL CMakeLists.txt as a subdirectory (useful in the +# case of a self-contained/standalone build) or by a separate script +# (useful if integrating into a larger project with a separate doc build) +# +# To invoke from a separate documentation build, the following vars +# should be defined by the caller, before adding this subdirectory: +# +# OSAL_SOURCE_DIR : +# The path to the OSAL source tree +# +# OSAL_API_INCLUDE_DIRECTORIES : +# The list of directories that have the OSAL API headers +# This should include the path to osconfig.h to avoid warnings +# about undefined references. +# +# OSALDOC_PREDEFINED : +# Not used directly, but passed through to the "osal-common.doxyfile" +# This may be used to indicate preprocessor definitions that the +# documentation generator tool should be aware of +# +# Note that OSAL_API_INCLUDE_DIRECTORIES and OSAL_SOURCE_DIR are both +# defined by the parent script in a standalone build environment. +# + +cmake_minimum_required(VERSION 3.5) +project(OSAL_DOCS NONE) + +# List of dox files to include - +# note that order is relevant here, doxygen processes in the order listed. +set(OSAL_DOCFILE_LIST + ${CMAKE_CURRENT_SOURCE_DIR}/osalmain.dox + ${CMAKE_CURRENT_SOURCE_DIR}/osal_fs.dox + ${CMAKE_CURRENT_SOURCE_DIR}/osal_timer.dox +) + +# For the generated Doxyfiles, the various paths should be in native form +file(TO_NATIVE_PATH "${OSAL_SOURCE_DIR}" OSAL_NATIVE_SOURCE_DIR) + +set(OSAL_NATIVE_APIGUIDE_SOURCEFILES) +set(OSAL_NATIVE_INCLUDE_DIRS) + +foreach(SRC ${OSAL_DOCFILE_LIST}) + file(TO_NATIVE_PATH "${SRC}" SRC) + string(APPEND OSAL_NATIVE_APIGUIDE_SOURCEFILES " \\\n ${SRC}") +endforeach() + +foreach(DIR ${OSAL_API_INCLUDE_DIRECTORIES}) + file(GLOB OSAL_HEADERFILE_LIST ${DIR}/*.h) + foreach(HDR ${OSAL_HEADERFILE_LIST}) + file(TO_NATIVE_PATH "${HDR}" HDR) + string(APPEND OSAL_NATIVE_APIGUIDE_SOURCEFILES " \\\n ${HDR}") + endforeach() + file(TO_NATIVE_PATH "${DIR}" DIR) + string(APPEND OSAL_NATIVE_INCLUDE_DIRS " \\\n ${DIR}") +endforeach() + +file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/apiguide-warnings.log OSAL_NATIVE_LOGFILE) +file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/osal-common.doxyfile OSAL_NATIVE_COMMON_CFGFILE) +file(TO_NATIVE_PATH ${CMAKE_CURRENT_BINARY_DIR}/osal-apiguide.doxyfile OSAL_NATIVE_APIGUIDE_CFGFILE) + +# generate the configuration files +configure_file( + ${CMAKE_CURRENT_SOURCE_DIR}/osal-common.doxyfile.in + ${CMAKE_CURRENT_BINARY_DIR}/osal-common.doxyfile + @ONLY +) +configure_file( + ${CMAKE_CURRENT_SOURCE_DIR}/osal-apiguide.doxyfile.in + ${CMAKE_CURRENT_BINARY_DIR}/osal-apiguide.doxyfile + @ONLY +) + +add_custom_command(OUTPUT "${CMAKE_CURRENT_BINARY_DIR}/apiguide/html/index.html" + COMMAND doxygen ${OSAL_NATIVE_APIGUIDE_CFGFILE} + DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/osal-apiguide.doxyfile ${OSAL_HEADERFILE_LIST} + WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}" +) + +add_custom_target(apiguide + COMMAND echo "Generated: file://${CMAKE_CURRENT_BINARY_DIR}/apiguide/html/index.html" + DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/apiguide/html/index.html" +) diff --git a/doc/src/osal-apiguide.doxyfile.in b/doc/src/osal-apiguide.doxyfile.in new file mode 100644 index 000000000..86c0de81b --- /dev/null +++ b/doc/src/osal-apiguide.doxyfile.in @@ -0,0 +1,16 @@ +#--------------------------------------------------------------------------- +# Doxygen Configuration options to generate the "OSAL API Guide" +#--------------------------------------------------------------------------- + +# Complete list of input files +INPUT += @OSAL_NATIVE_APIGUIDE_SOURCEFILES@ + + +# Common definitions, some of which are extended or overridden here. +@INCLUDE = @OSAL_NATIVE_COMMON_CFGFILE@ +PROJECT_NAME = "OSAL User's Guide" +OUTPUT_DIRECTORY = apiguide +GENERATE_LATEX = YES + +# output the warnings to a separate file +WARN_LOGFILE = @OSAL_NATIVE_LOGFILE@ diff --git a/doc/src/osal-common.doxyfile.in b/doc/src/osal-common.doxyfile.in new file mode 100644 index 000000000..39bbba061 --- /dev/null +++ b/doc/src/osal-common.doxyfile.in @@ -0,0 +1,76 @@ +#--------------------------------------------------------------------------- +# Project related configuration options, shared for all cFE doxygen outputs +#--------------------------------------------------------------------------- +@INCLUDE_PATH = @OSAL_NATIVE_INCLUDE_DIRS@ +OUTPUT_DIRECTORY = . +ABBREVIATE_BRIEF = "The $name class " \ + "The $name widget " \ + "The $name file " \ + is \ + provides \ + specifies \ + contains \ + represents \ + a \ + an \ + the +TAB_SIZE = 4 +OPTIMIZE_OUTPUT_FOR_C = YES +ALIASES += nonnull="(must not be null)" +ALIASES += nonzero="(must not be zero)" +ALIASES += covtest="(return value only verified in coverage test)" + +PREDEFINED += @OSALDOC_PREDEFINED@ + +#--------------------------------------------------------------------------- +# Build related configuration options +#--------------------------------------------------------------------------- +EXTRACT_ALL = YES +EXTRACT_PRIVATE = YES +EXTRACT_STATIC = YES +CASE_SENSE_NAMES = NO +GENERATE_TODOLIST = NO +#--------------------------------------------------------------------------- +# configuration options related to warning and progress messages +#--------------------------------------------------------------------------- +WARN_NO_PARAMDOC = YES +#--------------------------------------------------------------------------- +# configuration options related to the input files +#--------------------------------------------------------------------------- +STRIP_FROM_PATH = @OSAL_SOURCE_NATIVE_DIR@ +FILE_PATTERNS = *.c *.cpp *.cc *.C *.h *.hh *.hpp *.H *.dox *.md +RECURSIVE = YES +EXAMPLE_PATTERNS = * +#--------------------------------------------------------------------------- +# configuration options related to source browsing +#--------------------------------------------------------------------------- +SOURCE_BROWSER = YES +REFERENCED_BY_RELATION = YES +REFERENCES_RELATION = YES +#--------------------------------------------------------------------------- +# configuration options related to the LaTeX output +#--------------------------------------------------------------------------- +GENERATE_LATEX = NO +LATEX_CMD_NAME = latex +COMPACT_LATEX = YES +PAPER_TYPE = letter +#--------------------------------------------------------------------------- +# configuration options related to the RTF output +#--------------------------------------------------------------------------- +COMPACT_RTF = YES +#--------------------------------------------------------------------------- +# Configuration options related to the dot tool +#--------------------------------------------------------------------------- +CLASS_DIAGRAMS = NO +HAVE_DOT = YES +CLASS_GRAPH = NO +COLLABORATION_GRAPH = NO +INCLUDE_GRAPH = NO +INCLUDED_BY_GRAPH = NO +CALL_GRAPH = YES +GRAPHICAL_HIERARCHY = NO +MAX_DOT_GRAPH_DEPTH = 1000 +#--------------------------------------------------------------------------- +# Configuration::additions related to the search engine +#--------------------------------------------------------------------------- +SEARCHENGINE = NO diff --git a/doc/src/osal_fs.dox b/doc/src/osal_fs.dox new file mode 100644 index 000000000..6a8b8cf29 --- /dev/null +++ b/doc/src/osal_fs.dox @@ -0,0 +1,94 @@ +/** +\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 where 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. + + All of possible file system calls are not implemented. "Special" files requiring OS + specific control/operations are by nature not portable. Abstraction in this case is + is not possible, so the raw OS calls should be used (including open/close/etc). Mixing + with OSAL calls is not supported for such cases. #OS_TranslatePath is available to + support using open directly by an app and maintain abstraction on the file system. + + 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. +**/ diff --git a/doc/src/osal_timer.dox b/doc/src/osal_timer.dox new file mode 100644 index 000000000..793bc24c7 --- /dev/null +++ b/doc/src/osal_timer.dox @@ -0,0 +1,8 @@ +/** + \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 number of timers supported is controlled by the configuration + parameter OS_MAX_TIMERS. +**/ diff --git a/doc/src/osalmain.dox b/doc/src/osalmain.dox new file mode 100644 index 000000000..7502b6991 --- /dev/null +++ b/doc/src/osalmain.dox @@ -0,0 +1,121 @@ +/** + \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 core, + file system, loader, network, and timer APIs. See the related document + sections for full descriptions. + + @note The majority of these APIs should be called from a task running + in the context of an OSAL application and in general should not be called + from an ISR. There are a few exceptions, such as the ability to give a + binary semaphore from an ISR. +**/ + + +