From ce66b73a46079c8685f52dd00c0b296e33cf9a91 Mon Sep 17 00:00:00 2001 From: Avi Date: Thu, 2 Sep 2021 08:55:47 +0200 Subject: [PATCH] Fix #1147, Correct documentation typos --- CMakeLists.txt | 4 ++-- README.md | 20 +++++++++---------- SECURITY.md | 2 +- docs/OSAL-Configuration-Guide.md | 18 ++++++++--------- docs/src/osal_fs.dox | 4 ++-- src/os/portable/README.txt | 2 +- src/tests/file-api-test/README.txt | 12 +++++------ src/tests/osal-core-test/README.txt | 4 ++-- src/unit-test-coverage/shared/CMakeLists.txt | 2 +- .../shared/adaptors/CMakeLists.txt | 2 +- src/unit-test-coverage/ut-stubs/inc/README.md | 2 +- .../vxworks/adaptors/CMakeLists.txt | 2 +- ut_assert/README.txt | 6 +++--- 13 files changed, 40 insertions(+), 40 deletions(-) diff --git a/CMakeLists.txt b/CMakeLists.txt index 519183d1e..3dbc9ef66 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -48,7 +48,7 @@ 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. +# to provide backward compatibility with external sources. set(OSAL_EXT_SOURCE_DIR "$ENV{OSAL_EXT_SOURCE_DIR}" CACHE PATH "External source directory to check for additional OS/BSP implementations") @@ -106,7 +106,7 @@ add_subdirectory(ut_assert) # OSAL_SYSTEM_BSPTYPE indicate which of the BSP packages -# to build. These is required and must be defined. Confirm that this exists +# to build. This is required and must be defined. Confirm that this exists # and error out now if it does not. if (NOT DEFINED OSAL_SYSTEM_BSPTYPE) message(FATAL_ERROR "OSAL_SYSTEM_BSPTYPE must be set to the appropriate BSP") diff --git a/README.md b/README.md index d0986500c..3ca65635a 100644 --- a/README.md +++ b/README.md @@ -5,7 +5,7 @@ This repository contains NASA's Operating System Abstraction Layer (OSAL), which is a framework component of the Core Flight System. -This is a collection of abstractio APIs and associated framework to be located in the `osal` subdirectory of a cFS Mission Tree. The Core Flight System is bundled at , which includes build and execution instructions. +This is a collection of abstraction APIs and associated framework to be located in the `osal` subdirectory of a cFS Mission Tree. The Core Flight System is bundled at , which includes build and execution instructions. The autogenerated OSAL user's guide can be viewed at . @@ -134,14 +134,14 @@ See and and ### Development Build: v5.1.0-rc1+dev411 -- [docs] Clarifies that that zero will be returned on EOF condition in the API documentation for OS_read/write/TimedRead/TimedWrite. In the case of the timed API calls, the `OS_ERR_TIMEOUT` status code will be returned if the timeout expired without the handle becoming readable/writable during that time. -- Addresses a shortcomings in the UT Assert hook functions. Namely the assumed return type of int32 which is not always the case. +- [docs] Clarifies that zero will be returned on EOF condition in the API documentation for OS_read/write/TimedRead/TimedWrite. In the case of the timed API calls, the `OS_ERR_TIMEOUT` status code will be returned if the timeout expired without the handle becoming readable/writable during that time. +- Addresses shortcomings in the UT Assert hook functions. Namely the assumed return type of int32 which is not always the case. - Adds the concept of a "handler" function to UT assert to replace hard-coded custom logic in UT assert. A handler is the custom logic that exists between the hook function and the return to the stub caller. The handler is directly responsible for setting all outputs. - Adds a script to auto-generate stub functions that match this pattern. Given an API header file, the script extracts the declarations, and generates a source file with stub definitions that rely on a separate handler to deal with the needed outputs. @@ -156,7 +156,7 @@ the declarations, and generates a source file with stub definitions that rely on ### Development Build: v5.1.0-rc1+dev393 - Changes parameter names to avoid collisions. Renames `access` as `access_mode` in `osapi-file.h`. Renames `time` as `TimeSp` in `os-impl-posix-gettime.c`. -- Deletes the broken RTEMS `os-impl-shell.c` file so so OSAL builds with `OSAL_CONFIG_INCLUDE_SHELL=true`. RTEMS will always report `OS_ERR_NOT_IMPLEMENTED`. +- Deletes the broken RTEMS `os-impl-shell.c` file so OSAL builds with `OSAL_CONFIG_INCLUDE_SHELL=true`. RTEMS will always report `OS_ERR_NOT_IMPLEMENTED`. - See and ### Development Build: v5.1.0-rc1+dev387 @@ -172,7 +172,7 @@ the declarations, and generates a source file with stub definitions that rely on ### Development Build: v5.1.0-rc1+dev378 - Replaces nonstandard header file block comments and include guards. No behavior changes -- Removes `CLOCK_MONOTONIC` as the osal colck source since PSP no longer needs it. `OS_GetLocalTime()` and `OS_SetLocalTime()` will work as described. +- Removes `CLOCK_MONOTONIC` as the osal clock source since PSP no longer needs it. `OS_GetLocalTime()` and `OS_SetLocalTime()` will work as described. - Replaces `shellName` with a specific `localShellName` that can be polled safely and changes its type to a char of `OS_MAX_API_NAME` length for safety. - See and @@ -182,7 +182,7 @@ the declarations, and generates a source file with stub definitions that rely on - Applies minor code and documentation cleanup: white space, typos, etc. - Adds test to get full coverage of vxworks in `os-impl-bsd-socket.c` resulting in full line coverage for OSAL - Adds more descriptive return codes if `OS_SymbolTableDump_Impl` does not do what is expected. Adds a new error `OS_ERR_OUTPUT_TOO_LARGE` if the size limit was insufficient. Return `OS_ERROR` if an empty file was written - this likely indicates some fundamental issue with the VxWorks symbol table. Returns `OS_ERR_NAME_TOO_LONG` if one of the symbol names was too long. Improves unit test to check for/verify these responses. -- Removes the unneeded `OS_TaskRegister()` and all references to it in code, tests, and documentation. No impact to behavior, but does affect API and has depenedencies +- Removes the unneeded `OS_TaskRegister()` and all references to it in code, tests, and documentation. No impact to behavior, but does affect API and has dependencies - Removes unused `-SCRIPT_MODE` flag in cmake - Remove comparison between `osal_id_t` and `integers` to use the provided comparison function, `OS_ObjectIdDefined()`. System builds and runs again when using a type-safe/non-integer osal_id_t type. - See @@ -379,7 +379,7 @@ OS_MutSemTake():216:WARNING: Task 65547 taking mutex 327685 while owned by task ### Development Build: v5.1.0-rc1+dev60 -- Appliy standard formating, whitespace-only changes +- Apply standard formatting, whitespace-only changes - See ### Development Build: v5.1.0-rc1+dev55 @@ -407,7 +407,7 @@ OS_MutSemTake():216:WARNING: Task 65547 taking mutex 327685 while owned by task ### Development Build: v5.1.0-rc1+dev34 -- Move this existing function into the public API, as it is performs more verification than the OS_ConvertToArrayIndex function. +- Move this existing function into the public API, as it performs more verification than the OS_ConvertToArrayIndex function. - The C library type is signed, and this makes the result check work as intended. - See @@ -453,7 +453,7 @@ a common location for additional table-deletion-related logic. - No impact to current unit testing which runs UT assert as a standalone app. Add a position independent code (PIC) variant of the ut_assert library, which can be dynamically loaded into other applications rather than running as a standalone OSAL application. This enables loading UT assert as a CFE library. - Unit tests pass on RTEMS. -- Resolve inconsistency in how the stack size is treated across different OS implemntations. With this change the user-requested size is passed through to the underlying OS without an enforced minimum. An additional sanity check is added at the shared layer to ensure that the stack size is never passed as 0. +- Resolve inconsistency in how the stack size is treated across different OS implementations. With this change the user-requested size is passed through to the underlying OS without an enforced minimum. An additional sanity check is added at the shared layer to ensure that the stack size is never passed as 0. - Update Licenses for Apache 2.0 - See diff --git a/SECURITY.md b/SECURITY.md index c53d27f70..15371021a 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -6,7 +6,7 @@ To report a vulnerability for the OSAL subsystem please [submit an issue](https: For general cFS vulnerabilities please [open a cFS framework issue](https://github.com/nasa/cfs/issues/new/choose) and see our [top-level security policy](https://github.com/nasa/cFS/security/policy) for additional information. -In either case please use the "Bug Report" template and provide as much information as possible. Apply appropraite labels for each report. For security related reports, tag the issue with the "security" label. +In either case please use the "Bug Report" template and provide as much information as possible. Apply appropriate labels for each report. For security related reports, tag the issue with the "security" label. ## Testing diff --git a/docs/OSAL-Configuration-Guide.md b/docs/OSAL-Configuration-Guide.md index 710aed2f5..a2c4660a4 100644 --- a/docs/OSAL-Configuration-Guide.md +++ b/docs/OSAL-Configuration-Guide.md @@ -76,7 +76,7 @@ The following sections provide instructions on how to: - Configure the build directory for an OSAL application -- Configure a OSAL Application +- Configure an OSAL Application - Build the OSAL Application @@ -135,7 +135,7 @@ Most parameters set upper bounds on the number of OS objects that can be created the OSAL keeps track of allocated OS objects using fixed size tables. If customization is desired, one should not modify the `default_config.cmake` file directly, -but rather provide a alternative values by one of the override methods: +but rather provide alternative values by one of the override methods: - If configuring OSAL as a standalone build for testing, values for options can be specified as `-D` options on the cmake command. This is a common method of specifying @@ -486,13 +486,13 @@ software to remain portable. There are a few ways to map these host file systems to OSAL file systems: -- **Map existing target file systems to a OSAL path**. This is one of +- **Map existing target file systems to an OSAL path**. This is one of the most common ways to map the Non-Volatile disk to the OSAL. The OSAL relies on the target OS to create/mount a file system and it simply is given a mapping to the disk to allow the OSAL to access it. - **Create EEPROM/Flash/ATA File systems**. The OSAL has the ability -on some targets to format or initialize a EEPROM or ATA disk device. +on some targets to format or initialize an EEPROM or ATA disk device. This is less commonly used. - **Create RAM File Systems**. The OSAL can create RAM disks on the @@ -510,7 +510,7 @@ mappings via API calls during its startup. This may be done any time after call `OS_API_Init()`. For example, for Core Flight System (cFS) configurations that require persistent -storage to be provided under a virual directory called `/cf`, the platform-specific +storage to be provided under a virtual directory called `/cf`, the platform-specific CFE PSP layer configures the mapping in an appropriate manner by calling the `OS_FileSysAddFixedMap()` API during its OS_Application_Startup() implementation. @@ -633,14 +633,14 @@ qemu-system-i386 -m 128 -no-reboot -display none -serial stdio \ ``` Where `.exe` refers to any of the test programs or applications -that are provided with OSAL. This command puts the virual console on +that are provided with OSAL. This command puts the virtual console on the same terminal where the QEMU emulator is started. The program should run automatically after the kernel boots. The system may be stopped by issuing the "shutdown" command at the shell, or by pressing the CTRL+A followed by CTRL+C which terminates QEMU. -## Generc Linux Platform +## Generic Linux Platform The OSAL can run on many Linux distributions. Testing is done with currently supported Ubuntu LTS versions (up through 20.04 at the time of the current @@ -690,7 +690,7 @@ each OSAL subsystem is specially compiled with special flags to enable profiling (to track line and branch coverage) and linked with _stub_ implementations of all other dependencies. This way, test cases can trigger error paths from library calls that would otherwise not be possible -in a black box test enviornment. +in a black box test environment. These test programs are executed just as any other application program. @@ -720,7 +720,7 @@ the test programs will be copied to the output location/staging area. ### Option 1: Execute single test directly from a build tree The tests can be executed directly in-place in the build directory. This method often useful -when debugging, as the exectuable can also be run in a debugger (i.e. gdb) this way. +when debugging, as the executable can also be run in a debugger (i.e. gdb) this way. The following example executes the task subsystem coverage test for the shared layer, but any other test can be run in a similar fashion. diff --git a/docs/src/osal_fs.dox b/docs/src/osal_fs.dox index 6a8b8cf29..c909055ba 100644 --- a/docs/src/osal_fs.dox +++ b/docs/src/osal_fs.dox @@ -74,8 +74,8 @@ instance, the path of the file that the file descriptor points to can be easily 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 + All of the possible file system calls are not implemented. "Special" files requiring + OS specific control/operations are by nature not portable. Abstraction in this case 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. diff --git a/src/os/portable/README.txt b/src/os/portable/README.txt index 1f7ffd425..f4d985249 100644 --- a/src/os/portable/README.txt +++ b/src/os/portable/README.txt @@ -1,4 +1,4 @@ -Files in this directory contain an implmentation that adheres to a defined API +Files in this directory contain an implementation that adheres to a defined API that is applicable to more than one of the supported OS's, but not all. For example, the BSD-style sockets API is implemented in VxWorks, RTEMS, and Linux. Therefore it is beneficial to put the code in here and let each implementation diff --git a/src/tests/file-api-test/README.txt b/src/tests/file-api-test/README.txt index b8b0b07c9..948801543 100644 --- a/src/tests/file-api-test/README.txt +++ b/src/tests/file-api-test/README.txt @@ -4,7 +4,7 @@ test2.c is designed to test the functionality of the functions provided in osfil The modules are separate and independent. Each does not interfere with the others. -These modules are placed in a specific order, however, which assumes that the previous module worked. This is due to the uncircumventable nature of a filesystem (i.e. you cannot open a file for reading/writing without being able to create the file, and you can testing reading/writing without being able to open a file) +These modules are placed in a specific order, however, which assumes that the previous module worked. This is due to the uncircumventable nature of a filesystem (i.e. you cannot open a file for reading/writing without being able to create the file, and you can test reading/writing without being able to open a file) NOTE: When all is working properly, the output from each test will start with "OK", and not "ERROR" @@ -17,22 +17,22 @@ It also tests removing files that are not on the drive. TestOpenClose: -This module tests the ability to open and close files, opening nonexistant files, and closing files multiple times. +This module tests the ability to open and close files, opening non-existent files, and closing files multiple times. TestReadWriteLseek: -This module tests reading to a file, writing to a file, and seeking to a specific byte in a file. Once something is written, the read/write pointer is position at the beginning, and the contents are read, and compared to what was written. +This module tests reading to a file, writing to a file, and seeking to a specific byte in a file. Once something is written, the read/write pointer is positioned at the beginning, and the contents are read, and compared to what was written. TestMkRmDirFreeBytes: -This module making and removing different directories, with files in them. It also tests reading and writing to those files. +This module tests making and removing different directories, with files in them. It also tests reading and writing to those files. It also includes three calls to OS_FreeBytes, to test its functionality TestOpenCloseReadDir: -This module tests opening and closing directories, as well as reading though the directories in search of specific files or sub-level directories. +This module tests opening and closing directories, as well as reading through the directories in search of specific files or sub-level directories. TestRename: -This module create 2 directories, with a file in each, writes data to the file, then tries to rename the files and the directories, and then reads the data written to the files back out after the renaming. +This module creates 2 directories, with a file in each, writes data to the file, then tries to rename the files and the directories, and then reads the data written to the files back out after the renaming. diff --git a/src/tests/osal-core-test/README.txt b/src/tests/osal-core-test/README.txt index 79c6a2087..9f4144c1d 100644 --- a/src/tests/osal-core-test/README.txt +++ b/src/tests/osal-core-test/README.txt @@ -1,6 +1,6 @@ Explanation: -This osal-core-test.c file is a test to designed to demonstrate the functionality of the functions of osapi.c in the ../os// directory. The tests are separated into different modules- tasks, queues, binary semaphores, mutexes, and *GetInfo functions. +This osal-core-test.c file is a test designed to demonstrate the functionality of the functions of osapi.c in the ../os// directory. The tests are separated into different modules- tasks, queues, binary semaphores, mutexes, and *GetInfo functions. This separation allows for the modules to be run individually or concurrently. Each module does not affect any of the others. @@ -18,7 +18,7 @@ Tries to get the ID of the tasks by their names. Tries to Delete the tasks created previously. -NOTE: for clairity, the tasks are declared in test1.h +NOTE: for clarity, the tasks are declared in test1.h ************ TestQueues ************* diff --git a/src/unit-test-coverage/shared/CMakeLists.txt b/src/unit-test-coverage/shared/CMakeLists.txt index 7c51940aa..2aafdde48 100644 --- a/src/unit-test-coverage/shared/CMakeLists.txt +++ b/src/unit-test-coverage/shared/CMakeLists.txt @@ -54,7 +54,7 @@ foreach(MODNAME ${MODULE_LIST}) ) endforeach(MODNAME ${MODULE_LIST}) -# Add extra defintion to force the OS_STATIC_SYMTABLE_SOURCE to the +# Add extra definition to force the OS_STATIC_SYMTABLE_SOURCE to the # local value within the module coverage test target_compile_definitions(utobj_coverage-shared-module PRIVATE "OS_STATIC_SYMTABLE_SOURCE=OS_UT_STATIC_SYMBOL_TABLE" diff --git a/src/unit-test-coverage/shared/adaptors/CMakeLists.txt b/src/unit-test-coverage/shared/adaptors/CMakeLists.txt index 58caa998b..19a620d04 100644 --- a/src/unit-test-coverage/shared/adaptors/CMakeLists.txt +++ b/src/unit-test-coverage/shared/adaptors/CMakeLists.txt @@ -2,7 +2,7 @@ # are otherwise not exposed. This is generally required for any OSAL subsystem # which tracks an internal resource state (i.e. anything with a table). -# NOTE: These source files are compile with OVERRIDES on the headers just like +# NOTE: These source files are compiled with OVERRIDES on the headers just like # the FSW code is compiled. This is how it is able to include internal headers # which otherwise would fail. But that also means that adaptor code cannot call # any library functions, as this would also reach a stub, not the real function. diff --git a/src/unit-test-coverage/ut-stubs/inc/README.md b/src/unit-test-coverage/ut-stubs/inc/README.md index 720a7bffd..5a8cd1f0b 100644 --- a/src/unit-test-coverage/ut-stubs/inc/README.md +++ b/src/unit-test-coverage/ut-stubs/inc/README.md @@ -1,7 +1,7 @@ ABOUT THE SYSTEM HEADER OVERRIDES ================================= -The "overrides" directory contain replacement versions of many system-provided +The "overrides" directory contains replacement versions of many system-provided header files. All replacement functions and types are identified using an `OCS_` prefix. diff --git a/src/unit-test-coverage/vxworks/adaptors/CMakeLists.txt b/src/unit-test-coverage/vxworks/adaptors/CMakeLists.txt index 459d59373..eb22c05de 100644 --- a/src/unit-test-coverage/vxworks/adaptors/CMakeLists.txt +++ b/src/unit-test-coverage/vxworks/adaptors/CMakeLists.txt @@ -2,7 +2,7 @@ # are otherwise not exposed. This is generally required for any OSAL subsystem # which tracks an internal resource state (i.e. anything with a table). -# NOTE: These source files are compile with OVERRIDES on the headers just like +# NOTE: These source files are compiled with OVERRIDES on the headers just like # the FSW code is compiled. This is how it is able to include internal headers # which otherwise would fail. But that also means that adaptor code cannot call # any library functions, as this would also reach a stub, not the real function. diff --git a/ut_assert/README.txt b/ut_assert/README.txt index 4fde6aa99..98ba7e275 100644 --- a/ut_assert/README.txt +++ b/ut_assert/README.txt @@ -21,7 +21,7 @@ is true or false. This approach is much different than the Flight Software Branc historical approach to unit testing that creates a log file that requires developer analysis in order to determine whether a test passed or failed. In order to use the tools a developer populates the framework with their unit tests and links with the -ut-asssert library to create an executable. +ut-assert library to create an executable. Project Goals @@ -40,9 +40,9 @@ analysis in order to determine whether a test passed or failed. Functional Goals This approach allows developers to write self-verifying unit tests and the tools -provide a framework that allow unit tests to be bundled into a single executional +provide a framework that allow unit tests to be bundled into single executable units. This aggregation allows comprehensive automated unit testing so as FSRL -components are added and/or modfiied automated regression unit testing can be +components are added and/or modified automated regression unit testing can be performed. Evolvability Goals