From b41101d9e1296653584757d7bd140d0d236d9316 Mon Sep 17 00:00:00 2001 From: Jacob Hageman Date: Sun, 15 Mar 2020 16:29:43 -0400 Subject: [PATCH] Fix #577, Scrub OSAL user's guide Documentation changes only --- cmake/Makefile.sample | 2 +- cmake/cfe-usersguide.doxyfile.in | 8 +- cmake/osalguide.doxyfile.in | 14 ++-- docs/src/cfe_usersguide.dox | 51 ------------- docs/src/main.dox | 106 +++++++++++++------------- docs/src/osal_fs.dox | 124 +++++++++++++++++++++---------- docs/src/osal_timer.dox | 11 +-- docs/src/osalguide.dox | 30 -------- docs/src/osalmain.dox | 98 +++++++++++++++++------- 9 files changed, 225 insertions(+), 219 deletions(-) delete mode 100644 docs/src/cfe_usersguide.dox delete mode 100644 docs/src/osalguide.dox diff --git a/cmake/Makefile.sample b/cmake/Makefile.sample index 5c2c5e4cf..8b59d6132 100644 --- a/cmake/Makefile.sample +++ b/cmake/Makefile.sample @@ -155,7 +155,7 @@ usersguide: 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" + @/bin/echo -e "\n\nOsal Users Guide: \nfile://$(CURDIR)/$(O)/doc/osalguide/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 diff --git a/cmake/cfe-usersguide.doxyfile.in b/cmake/cfe-usersguide.doxyfile.in index 9cd8872f8..9ece79b48 100644 --- a/cmake/cfe-usersguide.doxyfile.in +++ b/cmake/cfe-usersguide.doxyfile.in @@ -2,8 +2,10 @@ # Doxygen Configuration options to generate the "cFE Users Guide" #--------------------------------------------------------------------------- -# Start with the common definitions, some of which are extended or overridden here. +# Start with the main page so document ordering is established +INPUT += @MISSION_SOURCE_DIR@/cfe/docs/src/main.dox +# Common definitions, some of which are extended or overridden here. @INCLUDE = @MISSION_BINARY_DIR@/doc/cfe-common.doxyfile PROJECT_NAME = "Core Flight Executive Users Guide" OUTPUT_DIRECTORY = users_guide @@ -15,10 +17,6 @@ GENERATE_LATEX = YES STRIP_FROM_PATH += @MISSION_SOURCE_DIR@/cfe/cmake/sample_defs INPUT += @MISSION_SOURCE_DIR@/cfe/cmake/sample_defs -# Main page for the users guide -INPUT += @MISSION_SOURCE_DIR@/cfe/docs/src/main.dox -INPUT += @MISSION_SOURCE_DIR@/cfe/docs/src/cfe_usersguide.dox - #PREDEFINED PREDEFINED += @USERGUIDE_PREDEFINED@ diff --git a/cmake/osalguide.doxyfile.in b/cmake/osalguide.doxyfile.in index c8587a832..431d8cd73 100644 --- a/cmake/osalguide.doxyfile.in +++ b/cmake/osalguide.doxyfile.in @@ -2,21 +2,17 @@ # Doxygen Configuration options to generate the "OSAL API Guide" #--------------------------------------------------------------------------- -# Start with the common definitions, some of which are extended or overridden here. +# Start with the main page so document ordering is established +INPUT += @MISSION_SOURCE_DIR@/cfe/docs/src/osalmain.dox +# 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" +PROJECT_NAME = "OSAL User's 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 +INPUT += @MISSION_OSAL_HEADERFILES@ diff --git a/docs/src/cfe_usersguide.dox b/docs/src/cfe_usersguide.dox deleted file mode 100644 index 0513c00cd..000000000 --- a/docs/src/cfe_usersguide.dox +++ /dev/null @@ -1,51 +0,0 @@ -/** - \page cfeusersguide cFE User's Guide - - - -**/ diff --git a/docs/src/main.dox b/docs/src/main.dox index 961781bb6..d3d583d84 100644 --- a/docs/src/main.dox +++ b/docs/src/main.dox @@ -2,59 +2,59 @@ \mainpage Core Flight Executive Documentation **/ diff --git a/docs/src/osal_fs.dox b/docs/src/osal_fs.dox index f99a569e1..fd8b2de7d 100644 --- a/docs/src/osal_fs.dox +++ b/docs/src/osal_fs.dox @@ -1,50 +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. 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 + 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/docs/src/osal_timer.dox b/docs/src/osal_timer.dox index 7ff825f37..793bc24c7 100644 --- a/docs/src/osal_timer.dox +++ b/docs/src/osal_timer.dox @@ -1,7 +1,8 @@ /** -\page osaltimerover Timer Overview + \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 + 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/docs/src/osalguide.dox b/docs/src/osalguide.dox deleted file mode 100644 index a80dfd521..000000000 --- a/docs/src/osalguide.dox +++ /dev/null @@ -1,30 +0,0 @@ -/** - \page osalguide Osal API Guide - - -**/ - diff --git a/docs/src/osalmain.dox b/docs/src/osalmain.dox index 320f970d1..c8a27737b 100644 --- a/docs/src/osalmain.dox +++ b/docs/src/osalmain.dox @@ -1,49 +1,97 @@ /** \mainpage Osal API Documentation - **/ /** -\page osalIntro OSAL Introduction + \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 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. + 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. **/