-
Notifications
You must be signed in to change notification settings - Fork 215
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #1058 from nasa/integration-candidate
osal Integration candidate: 2021-06-01
- Loading branch information
Showing
46 changed files
with
1,116 additions
and
397 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,88 @@ | ||
| ######################################################## | ||
| # | ||
| # 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_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 is 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 | ||
| set(OSAL_NATIVE_APIGUIDE_SOURCEFILES) | ||
| set(OSAL_NATIVE_INCLUDE_DIRS) | ||
| set(OSAL_DOC_DEPENDENCY_LIST) | ||
|
|
||
| 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}) | ||
| list(APPEND OSAL_DOC_DEPENDENCY_LIST ${HDR}) | ||
| 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}/osal-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_DOCFILE_LIST} ${OSAL_DOC_DEPENDENCY_LIST} | ||
| WORKING_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}" | ||
| ) | ||
|
|
||
| add_custom_target(osal-apiguide | ||
| COMMAND echo "OSAL API Guide: file://${CMAKE_CURRENT_BINARY_DIR}/apiguide/html/index.html" | ||
| DEPENDS "${CMAKE_CURRENT_BINARY_DIR}/apiguide/html/index.html" | ||
| ) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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@ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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: | ||
|
|
||
| <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. | ||
|
|
||
| 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. | ||
| **/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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. | ||
| **/ |
Oops, something went wrong.