Merge pull request #1072 from jphickey/fix-399-statuscode-doc

Fix #399, Update error codes and documentation
nasa · Jun 15, 2021 · 0c18559 · 0c18559
2 parents afbeb8f + d46151a
commit 0c18559
Show file tree

Hide file tree

Showing 2 changed files with 42 additions and 1 deletion.
diff --git a/src/os/inc/osapi-error.h b/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
  *
  * @{
  */

diff --git a/src/os/shared/src/osapi-errors.c b/src/os/shared/src/osapi-errors.c
@@ -52,7 +52,7 @@ static const OS_ErrorTable_Entry_t OS_GLOBAL_ERROR_NAME_TABLE[] = {
     {OS_SUCCESS, "OS_SUCCESS"},
     {OS_ERROR, "OS_ERROR"},
     {OS_INVALID_POINTER, "OS_INVALID_POINTER"},
-    {OS_ERROR_ADDRESS_MISALIGNED, "OS_ADDRESS_MISALIGNED"},
+    {OS_ERROR_ADDRESS_MISALIGNED, "OS_ERROR_ADDRESS_MISALIGNED"},
     {OS_ERROR_TIMEOUT, "OS_ERROR_TIMEOUT"},
     {OS_INVALID_INT_NUM, "OS_INVALID_INT_NUM"},
     {OS_SEM_FAILURE, "OS_SEM_FAILURE"},
@@ -69,10 +69,22 @@ static const OS_ErrorTable_Entry_t OS_GLOBAL_ERROR_NAME_TABLE[] = {
     {OS_ERR_NAME_NOT_FOUND, "OS_ERR_NAME_NOT_FOUND"},
     {OS_ERR_SEM_NOT_FULL, "OS_ERR_SEM_NOT_FULL"},
     {OS_ERR_INVALID_PRIORITY, "OS_ERR_INVALID_PRIORITY"},
+    {OS_INVALID_SEM_VALUE, "OS_INVALID_SEM_VALUE"},
+    {OS_ERR_FILE, "OS_ERR_FILE"},
+    {OS_ERR_NOT_IMPLEMENTED, "OS_ERR_NOT_IMPLEMENTED"},
+    {OS_TIMER_ERR_INVALID_ARGS, "OS_TIMER_ERR_INVALID_ARGS"},
+    {OS_TIMER_ERR_TIMER_ID, "OS_TIMER_ERR_TIMER_ID"},
+    {OS_TIMER_ERR_UNAVAILABLE, "OS_TIMER_ERR_UNAVAILABLE"},
+    {OS_TIMER_ERR_INTERNAL, "OS_TIMER_ERR_INTERNAL"},
     {OS_ERR_OBJECT_IN_USE, "OS_ERR_OBJECT_IN_USE"},
     {OS_ERR_BAD_ADDRESS, "OS_ERR_BAD_ADDRESS"},
     {OS_ERR_INCORRECT_OBJ_STATE, "OS_ERR_INCORRECT_OBJ_STATE"},
     {OS_ERR_INCORRECT_OBJ_TYPE, "OS_ERR_INCORRECT_OBJ_TYPE"},
+    {OS_ERR_STREAM_DISCONNECTED, "OS_ERR_STREAM_DISCONNECTED"},
+    {OS_ERR_OPERATION_NOT_SUPPORTED, "OS_ERR_OPERATION_NOT_SUPPORTED"},
+    {OS_ERR_INVALID_SIZE, "OS_ERR_INVALID_SIZE"},
+    {OS_ERR_OUTPUT_TOO_LARGE, "OS_ERR_OUTPUT_TOO_LARGE"},
+    {OS_ERR_INVALID_ARGUMENT, "OS_ERR_INVALID_ARGUMENT"},
     {OS_FS_ERR_PATH_TOO_LONG, "OS_FS_ERR_PATH_TOO_LONG"},
     {OS_FS_ERR_NAME_TOO_LONG, "OS_FS_ERR_NAME_TOO_LONG"},
     {OS_FS_ERR_DRIVE_NOT_CREATED, "OS_FS_ERR_DRIVE_NOT_CREATED"},