Merge pull request #1076 from nasa/integration-candidate

osal Integration candidate:2021-06-15

.github/pull_request_template.md

@@ -29,6 +29,6 @@ Full name and company/organization/center of all contributors ("Personal" if ind
 - If NASA Civil Servant Employee or GSFC Contractor on SES II
   - Address/email/phone and contract/task information (if applicable) must be on file
 - Else if Company
-  - **HAND SIGNED** Company CLA must be on file (once per release): [OSAL Company CLA](../doc/GSC_18370_Corp_CLA_form_1219.pdf)
+  - **HAND SIGNED** Company CLA must be on file (once per release): [OSAL Company CLA](../docs/GSC_18370_Corp_CLA_form_1219.pdf)
 - Else if Individual
-  - **HAND SIGNED** Individual CLA must be on file (once per release): [OSAL Individual CLA](../doc/GSC_18370_Ind_CLA_form_1219.pdf)
+  - **HAND SIGNED** Individual CLA must be on file (once per release): [OSAL Individual CLA](../docs/GSC_18370_Ind_CLA_form_1219.pdf)

.github/workflows/build-osal-documentation.yml

@@ -0,0 +1,68 @@
+name: "Build OSAL Documentation (API Guide)"
+
+on:
+  push:
+  pull_request:
+
+jobs:
+
+  #Check for duplicate actions. Skips push actions if there is a matching or duplicate pull-request action.
+  check-for-duplicates:
+    runs-on: ubuntu-latest
+    # Map a step output to a job output
+    outputs:
+      should_skip: ${{ steps.skip_check.outputs.should_skip }}
+    steps:
+      - id: skip_check
+        uses: fkirc/skip-duplicate-actions@master
+        with:
+          concurrent_skipping: 'same_content'
+          skip_after_successful_duplicate: 'true'
+          do_not_skip: '["pull_request", "workflow_dispatch", "schedule"]'
+
+  build-osal-apiguide:
+    #Continue if check-for-duplicates found no duplicates. Always runs for pull-requests.
+    needs: check-for-duplicates
+    if: ${{ needs.check-for-duplicates.outputs.should_skip != 'true' }}
+    runs-on: ubuntu-18.04
+    timeout-minutes: 15
+
+    steps:
+      - name: Install Dependencies
+        run: sudo apt-get install doxygen graphviz -y
+
+      - name: Checkout submodule
+        uses: actions/checkout@v2
+
+      - name: Set up for build
+        run: |
+          cp Makefile.sample Makefile
+          make prep
+
+      - name: Build OSAL API Guide
+        run: |
+          make osal-apiguide > make_osal-apiguide_stdout.txt 2> make_osal-apiguide_stderr.txt
+          mv build/docs/osal-apiguide-warnings.log osal-apiguide-warnings.log          
+
+      - name: Archive Osal Guide Build Logs
+        uses: actions/upload-artifact@v2
+        with:
+          name: OSAL Guide Artifacts
+          path: |
+            make_osal-apiguide_stdout.txt
+            make_osal-apiguide_stderr.txt
+            osal-apiguide-warnings.log
+
+      - name: Error Check
+        run: |
+          if [[ -s make_osal-apiguide_stderr.txt ]]; then
+            cat make_osal-apiguide_stderr.txt
+            exit -1
+          fi
+
+      - name: Warning Check
+        run: |
+          if [[ -s osal-apiguide-warnings.log ]]; then
+            cat osal-apiguide-warnings.log
+            exit -1
+          fi

.github/workflows/codeql-cfe-build.yml

@@ -25,7 +25,7 @@ jobs:
           skip_after_successful_duplicate: 'true'
           do_not_skip: '["pull_request", "workflow_dispatch", "schedule"]'
 
-  CodeQL-Build:
+  CodeQL-Security-Build:
     needs: check-for-duplicates
     if: ${{ needs.check-for-duplicates.outputs.should_skip != 'true' }}
     runs-on: ubuntu-18.04
@@ -50,7 +50,49 @@ jobs:
         uses: github/codeql-action/init@v1
         with:
          languages: c
-         queries: +security-extended, security-and-quality
+         config-file: nasa/cFS/.github/codeql/codeql-security.yml@main
+
+      - name: Set up for build
+        run: |
+          cp ./cfe/cmake/Makefile.sample Makefile
+          cp -r ./cfe/cmake/sample_defs sample_defs
+          make prep
+
+      - name: Build
+        run: make -j native/default_cpu1/osal/
+
+      - name: Run tests
+        run: (cd build/native/default_cpu1/osal && make test)
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v1
+
+  CodeQL-Coding-Standard-Build:
+    needs: check-for-duplicates
+    if: ${{ needs.check-for-duplicates.outputs.should_skip != 'true' }}
+    runs-on: ubuntu-18.04
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout bundle
+        uses: actions/checkout@v2
+        with:
+          repository: nasa/cFS
+          submodules: true
+
+      - name: Checkout submodule
+        uses: actions/checkout@v2
+        with:
+          path: osal
+
+      - name: Check versions
+        run: git submodule
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v1
+        with:
+         languages: c
+         config-file: nasa/cFS/.github/codeql/codeql-coding-standard.yml@main
 
       - name: Set up for build
         run: |

.github/workflows/codeql-osal-default.yml

@@ -26,9 +26,36 @@ jobs:
           concurrent_skipping: 'same_content'
           skip_after_successful_duplicate: 'true'
           do_not_skip: '["pull_request", "workflow_dispatch", "schedule"]'
+
+  CodeQL-Security-Build:
+    #Continue if check-for-duplicates found no duplicates. Always runs for pull-requests.
+    needs: check-for-duplicates
+    if: ${{ needs.check-for-duplicates.outputs.should_skip != 'true' }}
+    runs-on: ubuntu-18.04
+    timeout-minutes: 15
+
+    steps:
+      - name: Checkout submodule
+        uses: actions/checkout@v2
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v1
+        with:
+         languages: c
+         config-file: nasa/cFS/.github/codeql/codeql-security.yml@main
+
+      - name: Set up for build
+        run: |
+          cp Makefile.sample Makefile
+          make prep
+          
+      - name: Build
+        run: make -j 
 
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v1
 
-  CodeQL-Build:
+  CodeQL-Coding-Standard-Build:
     #Continue if check-for-duplicates found no duplicates. Always runs for pull-requests.
     needs: check-for-duplicates
     if: ${{ needs.check-for-duplicates.outputs.should_skip != 'true' }}
@@ -43,7 +70,7 @@ jobs:
         uses: github/codeql-action/init@v1
         with:
          languages: c
-         queries: +security-extended, security-and-quality
+         config-file: nasa/cFS/.github/codeql/codeql-coding-standard.yml@main
 
       - name: Set up for build
         run: |

CMakeLists.txt

@@ -354,7 +354,7 @@ if (HAS_PARENT)
 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)
+    add_subdirectory(docs/src docs)
 endif(HAS_PARENT)
 
 

README.md

@@ -12,6 +12,24 @@ The autogenerated OSAL user's guide can be viewed at <https://github.com/nasa/cF
 ## Version History
 
 
+### Development Build: v5.1.0-rc1+dev530
+
+- Implement Coding Standard Rules in CodeQL
+- rename doc to docs
+- add mutex lock around UtAssert globals
+- resolve discrepancies between file API and unit tests
+- resolve discrepancies between filesys API and unit tests
+- resolve discrepancies between idmap API and unit tests
+- resolve discrepancies between select API and unit tests
+- resolve discrepancies between socket API and unit tests
+- const correct OS_SelectFdIsSet
+- Add missing OS_Select param doc
+- Add Workflow to build and verify OSAL API Guide
+- add detail design template
+- Update error codes and documentation
+- Increase UT object limit for testing
+- See <https://github.com/nasa/osal/pull/1076> and <https://github.com/nasa/cFS/pull/265>
+
 ### Development Build: v5.1.0-rc1+dev501
 
 - include doxygen targets locally
@@ -161,7 +179,7 @@ the declarations, and generates a source file with stub definitions that rely on
 - Adds _new_ accessor functions APIs to get version strings and return the values of string macros defined in `osapi-version.h`.
   - The "simple" version currently `OS_VERSION` macro - this is the semantic version without any extra detail.  This is returned by `OS_GetVersion()`.
   - The "descriptive" version in `OS_VERSION_STRING` macro - this has extra detail like the most recent official release.  This is returned by `OS_GetVersionDescription()`.
-  - The release code name, now returned by `OS_GetVersionDescription()`.  
+  - The release code name, now returned by `OS_GetVersionDescription()`.
 - These accessor functions are the preferred way to get the OSAL version string, from now on users should avoid using the macro definitions as it is evaluated at OSAL library compile time, rather than application compile time, and thus will remain correct in the event that OSAL is relinked without recompiling the application.
 Adds `osapi-version.c` to implement these 3 calls and associated coverage test. This allows the version.c file to be auto-generated in the future.
 - See <https://github.com/nasa/osal/pull/835>
@@ -228,7 +246,7 @@ Adds `osapi-version.c` to implement these 3 calls and associated coverage test.
   - keep threads "attached" in POSIX, so they can be joined when deleted.
 - No longer triggers warning with OS_TaskExit() on VxWorks (see #645)
 - `OS_TaskDelete()` on POSIX does not return until the task has actually exited (see #642)
-- The chmod test is now skipped on VxWorks rather than failing. The `OS_FileChmod_Impl()` function now returns `OS_ERR_NOT_IMPLEMENTED` when run on a file system that does not have permissions, which in turn causes the unit test to be skipped rather than fail.   
+- The chmod test is now skipped on VxWorks rather than failing. The `OS_FileChmod_Impl()` function now returns `OS_ERR_NOT_IMPLEMENTED` when run on a file system that does not have permissions, which in turn causes the unit test to be skipped rather than fail.
 - Corrects a file handle leak.
 -  Add parameter check to `OS_SocketSendTo` and adjust coverage test to validate.
 - Replace `OS_fsBytesFree` and `OS_fsBlocksFree` with `OS_FileSysStatVolume`. This new API for getting stats on file system. Uses existing `OS_FileSysStatVolume_Impl` call and exposes it in the public API.
@@ -428,7 +446,7 @@ UT Hook functions now have the capability to get argument values by name, which
 - If `OSAL_EXT_SOURCE_DIR` cache variable is set, this location will be checked first for a BSP/OS implementation layer.
 - Implement `OS_GetResourceName()` and `OS_ForEachObjectOfType()`, which are new functions that allow for additional query capabilities. No impact to current behavior as the FSW does not currently use any of these new APIs.
 - A functional test enhancement to `bin-sem-test` which replicates the specific conditions for the observed bug to occur. Deletes the task calling `OS_BinSemTake()` and then attempts to use the semaphore after this.
-- Employ a `pthread` "cleanup handler" to handle the situation where a task is canceled during the `pthread_cond_wait()` call. This ensures that the `mutex` is unlocked as part of the cleanup, so other tasks may continue using the semaphore.    
+- Employ a `pthread` "cleanup handler" to handle the situation where a task is canceled during the `pthread_cond_wait()` call. This ensures that the `mutex` is unlocked as part of the cleanup, so other tasks may continue using the semaphore.
 - Change all initial `mutex` locking to be a finite "timed" wait rather than an infinite wait. In all cases, the condition variable is only held for brief periods of time and should be readily available. If a task blocks for a long time, this considers the mutex "broken" and aborts, thereby avoiding deadlock. This is a "contingency" fix in that if an exception or signal or other unknown/unhandled async event occurs that leaves the mutex permanently locked.
 - Adds the mutex to protect the timer callback `timecb` resource table.
 - See <https://github.com/nasa/osal/pull/482>
@@ -556,7 +574,7 @@ make
 make test
 ```
 
-See the [Configuration Guide](https://github.com/nasa/osal/blob/main/doc/OSAL-Configuration-Guide.md) for more information.
+See the [Configuration Guide](https://github.com/nasa/osal/blob/main/docs/OSAL-Configuration-Guide.md) for more information.
 
 See also the autogenerated user's guide: <https://github.com/nasa/cFS/blob/gh-pages/OSAL_Users_Guide.pdf>
 

doc/OSAL-Configuration-Guide.md → docs/OSAL-Configuration-Guide.md

@@ -56,7 +56,7 @@ These terms are identified as proper nouns and are capitalized.
 | MMU   |  Memory Management Unit. A piece of hardware that manages virtual memory systems.  It automatically translates addresses into physical addresses so that an application can  be linked with one set of addresses but actually reside in a different part of memory. |
 | Network | A connection between subsystems used for communication purposes.  |
 | Platform  | See "Hardware Platform" above.   |
-| User  | Anyone who interacts with the Software Application or system in its operational state.  A user can be a developer, a tester, an operator, or a maintainer. 
+| User  | Anyone who interacts with the Software Application or system in its operational state.  A user can be a developer, a tester, an operator, or a maintainer.
 
 # How to Configure, Build, and Run the OSAL
 
@@ -114,7 +114,7 @@ machine. The source distribution has the following directories:
 | `osal/src/bsp`                | The bsp directory contains the platform specific code for the OSAL as well  as code to make the OSAL run on a particular platform. Everything in  this directory is used to adapt the OSAL and Applications to a particular  hardware platform. This directory also contains the startup code for the  example programs. The included platforms are generic enough that they may be  easy to port to other platforms and processor architectures. For example:  The bsp/mcf5235-rtems board support package was ported to an ARM processor  running RTEMS with minimal effort.  |
 | `osal/src/os`                 | The os directory is the heart of the OSAL, containing the implementation of  the OSAL for each supported operating system. There is a sub-directory for  each supported operating system in this directory. The OSAL include files  are also contained in this directory (src/os/inc).  |
 | `osal/src/inc`                | The inc directory contains system wide include files that are used by the  OSAL on all platforms.  |
-| `osal/doc`                    | The doc directory contains the documentation and release notes for the OSAL. |
+| `osal/docs`                   | The docs directory contains the documentation and release notes for the OSAL. |
 
 
 The osal directory can go just about anywhere on a host development

docs/osal-detaildesign.doxyfile.in

@@ -0,0 +1,7 @@
+# All of the OSAL FSW code relevant for a detail design document is under
+# src/os and src/bsp, everything else is test and examples/support
+# Note this will include ALL OS/BSP layers, it does not currently filter
+# based on which OS/BSP is actually in use.
+INPUT    += @osal_MISSION_DIR@/src/os
+INPUT    += @osal_MISSION_DIR@/src/bsp
+

src/os/inc/osapi-error.h

@@ -49,6 +49,35 @@
 typedef char os_err_name_t[OS_ERROR_NAME_LENGTH];
 
 /** @defgroup OSReturnCodes OSAL Return Code Defines
+ *
+ * The specific status/return code definitions listed in this section may be extended or refined
+ * in future versions of OSAL.
+ *
+ * @note Application developers should assume that any OSAL API may return any status value listed
+ * here.  While the documentation of each OSAL API function indicates the return/status values that function
+ * may directly generate, functions may also pass through other status codes from related functions,
+ * so that list should not be considered absolute/exhaustive.
+ *
+ * The `int32` data type should be used to store an OSAL status code.  Negative values will always
+ * represent errors, while non-negative values indicate success.  Most APIs specifically return
+ * #OS_SUCCESS (0) upon successful execution, but some return a nonzero value, such as data size.
+ *
+ * Ideally, in order to more easily adapt to future OSAL versions and status code extensions/refinements,
+ * applications should typically check for errors as follows:
+ *
+ * @code
+ *  int32 status;
+ *  status = OS_TaskCreate(...);  (or any other API)
+ *  if (status < OS_SUCCESS)
+ *  {
+ *      handle or report error....
+ *      may also check for specific codes here.
+ *  }
+ *  else
+ *  {
+ *      handle normal/successful status...
+ *  }
+ * @endcode
  *
  * @{
  */