From d46151a66cf6471c11310ed2156f51aba895083e Mon Sep 17 00:00:00 2001 From: Joseph Hickey Date: Wed, 9 Jun 2021 11:04:43 -0400 Subject: [PATCH] Fix #399, Update error codes and documentation Updates the documentation related to status code test/check, provide description of how to check for any error status in a future-proof manner. Also updates the list of error code string conversions to match the current set (some were missing). --- src/os/inc/osapi-error.h | 29 +++++++++++++++++++++++++++++ src/os/shared/src/osapi-errors.c | 14 +++++++++++++- 2 files changed, 42 insertions(+), 1 deletion(-) diff --git a/src/os/inc/osapi-error.h b/src/os/inc/osapi-error.h index 3635ee666..f71e97eb7 100644 --- 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 index a7abfa09a..d60d1b011 100644 --- 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"},