From b9c9b29d35c2a25738652cc36891130be3361ec4 Mon Sep 17 00:00:00 2001 From: Joseph Hickey Date: Tue, 4 May 2021 10:09:21 -0400 Subject: [PATCH] Fix #331, scrub return values Confirm consistency between the return values generated by each OSAL API and the doxygen documentation. Each explicitly-returned status code should have a corresponding "retval" entry in the documentation. Also confirms that each explicitly-returned status code has a matching case in the coverage tests that specifically checks for that return value. Some were actually missing, where as some were just being reported incorrectly. Finally this also corrects one argument name mismatch in QueueCreate where it was prototyped as "data_size" but implemented as "max_size". --- src/os/inc/osapi-clock.h | 2 ++ src/os/inc/osapi-common.h | 3 +- src/os/inc/osapi-dir.h | 2 ++ src/os/inc/osapi-error.h | 3 ++ src/os/inc/osapi-file.h | 8 +++++ src/os/inc/osapi-filesys.h | 17 ++++++++++ src/os/inc/osapi-heap.h | 1 + src/os/inc/osapi-idmap.h | 2 ++ src/os/inc/osapi-module.h | 2 ++ src/os/inc/osapi-network.h | 2 ++ src/os/inc/osapi-queue.h | 1 + src/os/inc/osapi-select.h | 4 +++ src/os/inc/osapi-shell.h | 1 + src/os/inc/osapi-sockets.h | 14 +++++++++ src/os/inc/osapi-task.h | 2 ++ src/os/inc/osapi-timebase.h | 9 ++++++ src/os/inc/osapi-timer.h | 5 +++ src/os/shared/src/osapi-queue.c | 6 ++-- .../shared/src/coveragetest-errors.c | 9 ++---- .../shared/src/coveragetest-file.c | 10 +++--- .../shared/src/coveragetest-filesys.c | 8 +++++ .../shared/src/coveragetest-idmap.c | 31 ++++++++++++++++--- .../shared/src/coveragetest-network.c | 9 ++---- .../shared/src/coveragetest-select.c | 2 ++ .../shared/src/coveragetest-sockets.c | 3 ++ .../shared/src/coveragetest-time.c | 13 ++------ .../shared/src/coveragetest-timebase.c | 8 +++-- 27 files changed, 135 insertions(+), 42 deletions(-) diff --git a/src/os/inc/osapi-clock.h b/src/os/inc/osapi-clock.h index e13d06635..e620adc13 100644 --- a/src/os/inc/osapi-clock.h +++ b/src/os/inc/osapi-clock.h @@ -83,6 +83,7 @@ enum * @param[out] time_struct An OS_time_t that will be set to the current time * * @return Get local time status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if time_struct is null */ int32 OS_GetLocalTime(OS_time_t *time_struct); @@ -97,6 +98,7 @@ int32 OS_GetLocalTime(OS_time_t *time_struct); * @param[in] time_struct An OS_time_t containing the current time * * @return Set local time status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if time_struct is null */ int32 OS_SetLocalTime(const OS_time_t *time_struct); diff --git a/src/os/inc/osapi-common.h b/src/os/inc/osapi-common.h index d910a2aa6..d81613240 100644 --- a/src/os/inc/osapi-common.h +++ b/src/os/inc/osapi-common.h @@ -162,8 +162,6 @@ int32 OS_API_Init(void); * For example, while this will attempt to unload all dynamically-loaded modules, doing * so may not be possible and/or may induce undefined behavior if resources are in use by * tasks/functions outside of OSAL. - * - * @return None */ void OS_API_Teardown(void); @@ -234,6 +232,7 @@ void OS_ApplicationExit(int32 Status); * @return Execution status, see @ref OSReturnCodes. * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_ERROR @copybrief OS_ERROR + * @retval #OS_INVALID_POINTER if handler is NULL */ int32 OS_RegisterEventHandler(OS_EventHandler_t handler); diff --git a/src/os/inc/osapi-dir.h b/src/os/inc/osapi-dir.h index 4d7963ca0..7b2acf0f7 100644 --- a/src/os/inc/osapi-dir.h +++ b/src/os/inc/osapi-dir.h @@ -57,6 +57,7 @@ typedef struct * @param[in] path The directory to open * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if dir_id or path is NULL */ int32 OS_DirectoryOpen(osal_id_t *dir_id, const char *path); @@ -94,6 +95,7 @@ int32 OS_DirectoryRewind(osal_id_t dir_id); * @param[out] dirent Buffer to store directory entry information * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if dirent argument is NULL */ int32 OS_DirectoryRead(osal_id_t dir_id, os_dirent_t *dirent); diff --git a/src/os/inc/osapi-error.h b/src/os/inc/osapi-error.h index b94982993..3b1b85fe2 100644 --- a/src/os/inc/osapi-error.h +++ b/src/os/inc/osapi-error.h @@ -116,6 +116,9 @@ typedef char os_err_name_t[OS_ERROR_NAME_LENGTH]; * @param[out] err_name Buffer to store error string * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS if successfully converted to a string + * @retval #OS_INVALID_POINTER if err_name is NULL + * @retval #OS_ERROR if error could not be converted */ int32 OS_GetErrorName(int32 error_num, os_err_name_t *err_name); /**@}*/ diff --git a/src/os/inc/osapi-file.h b/src/os/inc/osapi-file.h index 0b05b1df6..71b1b9007 100644 --- a/src/os/inc/osapi-file.h +++ b/src/os/inc/osapi-file.h @@ -135,6 +135,7 @@ typedef enum * @return Execution status, see @ref OSReturnCodes * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_ERROR if the command was not executed properly + * @retval #OS_INVALID_POINTER if pointer argument was NULL */ int32 OS_OpenCreate(osal_id_t *filedes, const char *path, int32 flags, int32 access_mode); @@ -236,6 +237,8 @@ int32 OS_write(osal_id_t filedes, const void *buffer, size_t nbytes); * @returns Byte count on success or appropriate error code, see @ref OSReturnCodes * @retval #OS_ERROR_TIMEOUT if no data became available during timeout period * @retval #OS_ERR_INVALID_ID if the file descriptor passed in is invalid + * @retval #OS_ERR_INVALID_SIZE if the passed-in size is not valid + * @retval #OS_INVALID_POINTER if the passed-in buffer is not valid * @retval 0 if at end of file/stream data */ int32 OS_TimedRead(osal_id_t filedes, void *buffer, size_t nbytes, int32 timeout); @@ -269,6 +272,8 @@ int32 OS_TimedRead(osal_id_t filedes, void *buffer, size_t nbytes, int32 timeout * @return A non-negative byte count or appropriate error code, see @ref OSReturnCodes * @retval #OS_ERROR_TIMEOUT if no data became available during timeout period * @retval #OS_ERR_INVALID_ID if the file descriptor passed in is invalid + * @retval #OS_ERR_INVALID_SIZE if the passed-in size is not valid + * @retval #OS_INVALID_POINTER if the passed-in buffer is not valid * @retval 0 if file/stream cannot accept any more data */ int32 OS_TimedWrite(osal_id_t filedes, const void *buffer, size_t nbytes, int32 timeout); @@ -432,6 +437,7 @@ int32 OS_mv(const char *src, const char *dest); * @return Execution status, see @ref OSReturnCodes * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_ERR_INVALID_ID if the file descriptor passed in is invalid + * @retval #OS_INVALID_POINTER if the fd_prop argument is NULL */ int32 OS_FDGetInfo(osal_id_t filedes, OS_file_prop_t *fd_prop); @@ -446,6 +452,7 @@ int32 OS_FDGetInfo(osal_id_t filedes, OS_file_prop_t *fd_prop); * * @return OS_SUCCESS if the file is open, or appropriate error code * @retval #OS_ERROR if the file is not open + * @retval #OS_INVALID_POINTER if the filename argument is NULL */ int32 OS_FileOpenCheck(const char *Filename); @@ -475,6 +482,7 @@ int32 OS_CloseAllFiles(void); * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_FS_ERR_PATH_INVALID if the file is not found * @retval #OS_ERROR if the file close returned an error + * @retval #OS_INVALID_POINTER if the filename argument is NULL */ int32 OS_CloseFileByName(const char *Filename); /**@}*/ diff --git a/src/os/inc/osapi-filesys.h b/src/os/inc/osapi-filesys.h index c9d0d567b..c1790e3f9 100644 --- a/src/os/inc/osapi-filesys.h +++ b/src/os/inc/osapi-filesys.h @@ -84,6 +84,9 @@ typedef struct * @param[in] virt_path The virtual mount point of this filesystem * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_FS_ERR_PATH_TOO_LONG if the overall phys_path is too long + * @retval #OS_ERR_NAME_TOO_LONG if the phys_path basename (filesystem name) is too long + * @retval #OS_INVALID_POINTER if any argument is NULL */ int32 OS_FileSysAddFixedMap(osal_id_t *filesys_id, const char *phys_path, const char *virt_path); @@ -113,6 +116,7 @@ int32 OS_FileSysAddFixedMap(osal_id_t *filesys_id, const char *phys_path, const * @retval #OS_SUCCESS on creating the disk */ int32 OS_mkfs(char *address, const char *devname, const char *volname, size_t blocksize, osal_blockcount_t numblocks); + /*-------------------------------------------------------------------------------------*/ /** * @brief Mounts a file system @@ -123,6 +127,9 @@ int32 OS_mkfs(char *address, const char *devname, const char *volname, size_t bl * @param[in] mountpoint The name to call this disk from now on * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_ERR_NAME_NOT_FOUND if the device name does not exist in OSAL + * @retval #OS_FS_ERR_PATH_TOO_LONG if the mount point string is too long + * @retval #OS_INVALID_POINTER if any argument is NULL */ int32 OS_mount(const char *devname, const char *mountpoint); @@ -165,6 +172,8 @@ int32 OS_initfs(char *address, const char *devname, const char *volname, size_t * @return Execution status, see @ref OSReturnCodes * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_INVALID_POINTER if devname is NULL + * @retval #OS_FS_ERR_PATH_TOO_LONG if the devname is too long + * @retval #OS_ERR_NAME_NOT_FOUND if the devname does not exist in OSAL * @retval #OS_ERROR is the drive specified cannot be located */ int32 OS_rmfs(const char *devname); @@ -185,6 +194,7 @@ int32 OS_rmfs(const char *devname); * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_INVALID_POINTER if name is NULL * @retval #OS_FS_ERR_PATH_TOO_LONG if the absolute path given is too long + * @retval #OS_ERR_NAME_NOT_FOUND if the mountpoint is not mounted in OSAL * @retval #OS_ERROR if the OS calls failed */ int32 OS_unmount(const char *mountpoint); @@ -209,6 +219,7 @@ int32 OS_unmount(const char *mountpoint); * @return Execution status, see @ref OSReturnCodes * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_INVALID_POINTER if name or statbuf is NULL + * @retval #OS_FS_ERR_PATH_TOO_LONG if the name is too long * @retval #OS_ERROR if the OS call failed */ int32 OS_FileSysStatVolume(const char *name, OS_statvfs_t *statbuf); @@ -228,6 +239,7 @@ int32 OS_FileSysStatVolume(const char *name, OS_statvfs_t *statbuf); * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_INVALID_POINTER Name is NULL * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED + * @retval #OS_FS_ERR_PATH_TOO_LONG if the name is too long * @retval #OS_ERROR @copybrief OS_ERROR */ int32 OS_chkfs(const char *name, bool repair); @@ -245,6 +257,8 @@ int32 OS_chkfs(const char *name, bool repair); * @return Execution status, see @ref OSReturnCodes * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_INVALID_POINTER if either parameter is NULL + * @retval #OS_ERR_NAME_NOT_FOUND if the MountPoint is not mounted in OSAL + * @retval #OS_FS_ERR_PATH_TOO_LONG if the MountPoint is too long * @retval #OS_ERROR if the mountpoint could not be found */ int32 OS_FS_GetPhysDriveName(char *PhysDriveName, const char *MountPoint); @@ -261,6 +275,9 @@ int32 OS_FS_GetPhysDriveName(char *PhysDriveName, const char *MountPoint); * @return Execution status, see @ref OSReturnCodes * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_INVALID_POINTER if either parameter is NULL + * @retval #OS_FS_ERR_NAME_TOO_LONG if the filename component is too long + * @retval #OS_FS_ERR_PATH_INVALID if either parameter cannot be interpreted as a path + * @retval #OS_FS_ERR_PATH_TOO_LONG if either input or output pathnames are too long */ int32 OS_TranslatePath(const char *VirtualPath, char *LocalPath); diff --git a/src/os/inc/osapi-heap.h b/src/os/inc/osapi-heap.h index 690b95e82..5313bfdd3 100644 --- a/src/os/inc/osapi-heap.h +++ b/src/os/inc/osapi-heap.h @@ -53,6 +53,7 @@ typedef struct * @param[out] heap_prop Storage buffer for heap info * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if the heap_prop argument is NULL */ int32 OS_HeapGetInfo(OS_heap_prop_t *heap_prop); /**@}*/ diff --git a/src/os/inc/osapi-idmap.h b/src/os/inc/osapi-idmap.h index 345446227..d0f7c1fb1 100644 --- a/src/os/inc/osapi-idmap.h +++ b/src/os/inc/osapi-idmap.h @@ -228,6 +228,8 @@ int32 OS_ConvertToArrayIndex(osal_id_t object_id, osal_index_t *ArrayIndex); * @return Execution status, see @ref OSReturnCodes * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_ERR_INCORRECT_OBJ_TYPE @copybrief OS_ERR_INCORRECT_OBJ_TYPE + * @retval #OS_ERR_INVALID_ID if the object_id argument is not valid + * @retval #OS_INVALID_POINTER if the ArrayIndex is NULL * */ int32 OS_ObjectIdToArrayIndex(osal_objtype_t idtype, osal_id_t object_id, osal_index_t *ArrayIndex); diff --git a/src/os/inc/osapi-module.h b/src/os/inc/osapi-module.h index 634b981b2..25cbd14da 100644 --- a/src/os/inc/osapi-module.h +++ b/src/os/inc/osapi-module.h @@ -174,6 +174,7 @@ int32 OS_ModuleSymbolLookup(osal_id_t module_id, cpuaddr *symbol_address, const * @return Execution status, see @ref OSReturnCodes * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED + * @retval #OS_INVALID_POINTER if the filename argument is NULL * @retval #OS_ERROR if the symbol table could not be read or dumped */ int32 OS_SymbolTableDump(const char *filename, size_t size_limit); @@ -199,6 +200,7 @@ int32 OS_SymbolTableDump(const char *filename, size_t size_limit); * @retval #OS_INVALID_POINTER if one of the parameters is NULL * @retval #OS_ERR_NO_FREE_IDS if the module table is full * @retval #OS_ERR_NAME_TAKEN if the name is in use + * @retval #OS_ERR_NAME_TOO_LONG if the module_name is too long */ int32 OS_ModuleLoad(osal_id_t *module_id, const char *module_name, const char *filename, uint32 flags); diff --git a/src/os/inc/osapi-network.h b/src/os/inc/osapi-network.h index bce88e364..a805ef80b 100644 --- a/src/os/inc/osapi-network.h +++ b/src/os/inc/osapi-network.h @@ -65,6 +65,8 @@ int32 OS_NetworkGetID(void); * @param[in] name_len Maximum length of host name buffer * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_ERR_INVALID_SIZE if the name_len is zero + * @retval #OS_INVALID_POINTER if the host_name is NULL */ int32 OS_NetworkGetHostName(char *host_name, size_t name_len); diff --git a/src/os/inc/osapi-queue.h b/src/os/inc/osapi-queue.h index 69a9222dc..14f9387d4 100644 --- a/src/os/inc/osapi-queue.h +++ b/src/os/inc/osapi-queue.h @@ -62,6 +62,7 @@ typedef struct * @retval #OS_ERR_NAME_TOO_LONG name length including null terminator greater than #OS_MAX_API_NAME * @retval #OS_ERR_NO_FREE_IDS if there are already the max queues created * @retval #OS_ERR_NAME_TAKEN if the name is already being used on another queue + * @retval #OS_ERR_INVALID_SIZE if data_size is 0 * @retval #OS_QUEUE_INVALID_SIZE if the queue depth exceeds the limit * @retval #OS_ERROR if the OS create call fails */ diff --git a/src/os/inc/osapi-select.h b/src/os/inc/osapi-select.h index e0c74a863..ac3b0c296 100644 --- a/src/os/inc/osapi-select.h +++ b/src/os/inc/osapi-select.h @@ -116,6 +116,7 @@ int32 OS_SelectMultiple(OS_FdSet *ReadSet, OS_FdSet *WriteSet, int32 msecs); * the OS_TimedRead/OS_TimedWrite calls. * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if argument is NULL */ int32 OS_SelectSingle(osal_id_t objid, uint32 *StateFlags, int32 msecs); @@ -126,6 +127,7 @@ int32 OS_SelectSingle(osal_id_t objid, uint32 *StateFlags, int32 msecs); * After this call the set will contain no OSAL IDs * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if argument is NULL */ int32 OS_SelectFdZero(OS_FdSet *Set); @@ -136,6 +138,7 @@ int32 OS_SelectFdZero(OS_FdSet *Set); * After this call the set will contain the given OSAL ID * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if argument is NULL */ int32 OS_SelectFdAdd(OS_FdSet *Set, osal_id_t objid); @@ -146,6 +149,7 @@ int32 OS_SelectFdAdd(OS_FdSet *Set, osal_id_t objid); * After this call the set will no longer contain the given OSAL ID * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if argument is NULL */ int32 OS_SelectFdClear(OS_FdSet *Set, osal_id_t objid); diff --git a/src/os/inc/osapi-shell.h b/src/os/inc/osapi-shell.h index c51169efd..613f75bc2 100644 --- a/src/os/inc/osapi-shell.h +++ b/src/os/inc/osapi-shell.h @@ -47,6 +47,7 @@ * @return Execution status, see @ref OSReturnCodes * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_ERROR if the command was not executed properly + * @retval #OS_INVALID_POINTER if Cmd argument is NULL * @retval #OS_ERR_INVALID_ID if the file descriptor passed in is invalid */ int32 OS_ShellOutputToFile(const char *Cmd, osal_id_t filedes); diff --git a/src/os/inc/osapi-sockets.h b/src/os/inc/osapi-sockets.h index 09e3b5a75..61ba847af 100644 --- a/src/os/inc/osapi-sockets.h +++ b/src/os/inc/osapi-sockets.h @@ -139,6 +139,7 @@ typedef struct * @param[in] Domain The address family * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if Addr argument is NULL */ int32 OS_SocketAddrInit(OS_SockAddr_t *Addr, OS_SocketDomain_t Domain); @@ -159,6 +160,8 @@ int32 OS_SocketAddrInit(OS_SockAddr_t *Addr, OS_SocketDomain_t Domain); * @param[in] Addr The network address buffer to convert * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if argument is NULL + * @retval #OS_ERR_INVALID_SIZE if passed-in buflen is not valid */ int32 OS_SocketAddrToString(char *buffer, size_t buflen, const OS_SockAddr_t *Addr); @@ -181,6 +184,7 @@ int32 OS_SocketAddrToString(char *buffer, size_t buflen, const OS_SockAddr_t *Ad * @param[in] string The string to initialize the address from. * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if argument is NULL */ int32 OS_SocketAddrFromString(OS_SockAddr_t *Addr, const char *string); @@ -196,6 +200,7 @@ int32 OS_SocketAddrFromString(OS_SockAddr_t *Addr, const char *string); * @param[in] Addr The network address buffer * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if argument is NULL */ int32 OS_SocketAddrGetPort(uint16 *PortNum, const OS_SockAddr_t *Addr); @@ -211,6 +216,7 @@ int32 OS_SocketAddrGetPort(uint16 *PortNum, const OS_SockAddr_t *Addr); * @param[out] Addr The network address buffer * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if argument is NULL */ int32 OS_SocketAddrSetPort(OS_SockAddr_t *Addr, uint16 PortNum); /**@}*/ @@ -242,6 +248,7 @@ int32 OS_SocketAddrSetPort(OS_SockAddr_t *Addr, uint16 PortNum); * @param[in] Type The type of the socket (STREAM or DATAGRAM) * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if argument is NULL */ int32 OS_SocketOpen(osal_id_t *sock_id, OS_SocketDomain_t Domain, OS_SocketType_t Type); @@ -260,6 +267,7 @@ int32 OS_SocketOpen(osal_id_t *sock_id, OS_SocketDomain_t Domain, OS_SocketType_ * @param[in] Addr The local address to bind to * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if argument is NULL */ int32 OS_SocketBind(osal_id_t sock_id, const OS_SockAddr_t *Addr); @@ -276,6 +284,7 @@ int32 OS_SocketBind(osal_id_t sock_id, const OS_SockAddr_t *Addr); * @param[in] timeout The maximum amount of time to wait, or OS_PEND to wait forever * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if Addr argument is NULL */ int32 OS_SocketConnect(osal_id_t sock_id, const OS_SockAddr_t *Addr, int32 timeout); @@ -297,6 +306,7 @@ int32 OS_SocketConnect(osal_id_t sock_id, const OS_SockAddr_t *Addr, int32 timeo * @param[in] timeout The maximum amount of time to wait, or OS_PEND to wait forever * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if argument is NULL */ int32 OS_SocketAccept(osal_id_t sock_id, osal_id_t *connsock_id, OS_SockAddr_t *Addr, int32 timeout); @@ -314,6 +324,8 @@ int32 OS_SocketAccept(osal_id_t sock_id, osal_id_t *connsock_id, OS_SockAddr_t * * @param[in] timeout The maximum amount of time to wait, or OS_PEND to wait forever * * @return Count of actual bytes received or error status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if argument is NULL + * @retval #OS_ERR_INVALID_SIZE if passed-in buflen is not valid */ int32 OS_SocketRecvFrom(osal_id_t sock_id, void *buffer, size_t buflen, OS_SockAddr_t *RemoteAddr, int32 timeout); @@ -331,6 +343,8 @@ int32 OS_SocketRecvFrom(osal_id_t sock_id, void *buffer, size_t buflen, OS_SockA * @param[in] RemoteAddr Buffer containing the remote network address to send to * * @return Count of actual bytes sent or error status, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if argument is NULL + * @retval #OS_ERR_INVALID_SIZE if passed-in buflen is not valid */ int32 OS_SocketSendTo(osal_id_t sock_id, const void *buffer, size_t buflen, const OS_SockAddr_t *RemoteAddr); diff --git a/src/os/inc/osapi-task.h b/src/os/inc/osapi-task.h index 6437f8f0f..53abde4c9 100644 --- a/src/os/inc/osapi-task.h +++ b/src/os/inc/osapi-task.h @@ -93,6 +93,7 @@ typedef osal_task((*osal_task_entry)(void)); /**< @brief For task entry point */ * @return Execution status, see @ref OSReturnCodes * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_INVALID_POINTER if any of the necessary pointers are NULL + * @retval #OS_ERR_INVALID_SIZE if the stack_size argument is zero * @retval #OS_ERR_NAME_TOO_LONG name length including null terminator greater than #OS_MAX_API_NAME * @retval #OS_ERR_INVALID_PRIORITY if the priority is bad * @retval #OS_ERR_NO_FREE_IDS if there can be no more tasks created @@ -234,6 +235,7 @@ int32 OS_TaskGetInfo(osal_id_t task_id, OS_task_prop_t *task_prop); * * @return Execution status, see @ref OSReturnCodes * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if a pointer argument is NULL */ int32 OS_TaskFindIdBySystemData(osal_id_t *task_id, const void *sysdata, size_t sysdata_size); diff --git a/src/os/inc/osapi-timebase.h b/src/os/inc/osapi-timebase.h index 3d2dd74a6..0c5939feb 100644 --- a/src/os/inc/osapi-timebase.h +++ b/src/os/inc/osapi-timebase.h @@ -78,6 +78,9 @@ typedef struct * @param[in] external_sync A synchronization function for BSP hardware-based timer ticks * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_ERR_INCORRECT_OBJ_STATE if called from timer/timebase context + * @retval #OS_ERR_NAME_TOO_LONG if the timebase_name is too long + * @retval #OS_INVALID_POINTER if a pointer argument is NULL */ int32 OS_TimeBaseCreate(osal_id_t *timebase_id, const char *timebase_name, OS_TimerSync_t external_sync); @@ -100,6 +103,8 @@ int32 OS_TimeBaseCreate(osal_id_t *timebase_id, const char *timebase_name, OS_Ti * @param[in] interval_time The amount of delay between ticks, in microseconds. * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_ERR_INCORRECT_OBJ_STATE if called from timer/timebase context + * @retval #OS_TIMER_ERR_INVALID_ARGS if start_time or interval_time are out of range */ int32 OS_TimeBaseSet(osal_id_t timebase_id, uint32 start_time, uint32 interval_time); @@ -113,6 +118,7 @@ int32 OS_TimeBaseSet(osal_id_t timebase_id, uint32 start_time, uint32 interval_t * @param[in] timebase_id The timebase resource to delete * * @return Execution status, see @ref OSReturnCodes + * @retval #OS_ERR_INCORRECT_OBJ_STATE if called from timer/timebase context */ int32 OS_TimeBaseDelete(osal_id_t timebase_id); @@ -130,6 +136,7 @@ int32 OS_TimeBaseDelete(osal_id_t timebase_id); * @retval #OS_INVALID_POINTER if timebase_id or timebase_name are NULL pointers * @retval #OS_ERR_NAME_TOO_LONG name length including null terminator greater than #OS_MAX_API_NAME * @retval #OS_ERR_NAME_NOT_FOUND if the name was not found in the table + * @retval #OS_ERR_INCORRECT_OBJ_STATE if called from timer/timebase context */ int32 OS_TimeBaseGetIdByName(osal_id_t *timebase_id, const char *timebase_name); @@ -150,6 +157,7 @@ int32 OS_TimeBaseGetIdByName(osal_id_t *timebase_id, const char *timebase_name); * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_ERR_INVALID_ID if the id passed in is not a valid timebase * @retval #OS_INVALID_POINTER if the timebase_prop pointer is null + * @retval #OS_ERR_INCORRECT_OBJ_STATE if called from timer/timebase context */ int32 OS_TimeBaseGetInfo(osal_id_t timebase_id, OS_timebase_prop_t *timebase_prop); @@ -182,6 +190,7 @@ int32 OS_TimeBaseGetInfo(osal_id_t timebase_id, OS_timebase_prop_t *timebase_pro * @return Execution status, see @ref OSReturnCodes * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_ERR_INVALID_ID if the id passed in is not a valid timebase + * @retval #OS_INVALID_POINTER if pointer argument is NULL */ int32 OS_TimeBaseGetFreeRun(osal_id_t timebase_id, uint32 *freerun_val); diff --git a/src/os/inc/osapi-timer.h b/src/os/inc/osapi-timer.h index eaf9148d6..464e0f03c 100644 --- a/src/os/inc/osapi-timer.h +++ b/src/os/inc/osapi-timer.h @@ -151,6 +151,8 @@ int32 OS_TimerAdd(osal_id_t *timer_id, const char *timer_name, osal_id_t timebas * @retval #OS_ERR_INVALID_ID if the timer_id is not valid. * @retval #OS_TIMER_ERR_INTERNAL if there was an error programming the OS timer. * @retval #OS_ERROR if both start time and interval time are zero. + * @retval #OS_ERR_INCORRECT_OBJ_STATE if called from timer/timebase context + * @retval #OS_TIMER_ERR_INVALID_ARGS if the start_time or interval_time is out of range */ int32 OS_TimerSet(osal_id_t timer_id, uint32 start_time, uint32 interval_time); @@ -167,6 +169,7 @@ int32 OS_TimerSet(osal_id_t timer_id, uint32 start_time, uint32 interval_time); * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_ERR_INVALID_ID if the timer_id is invalid. * @retval #OS_TIMER_ERR_INTERNAL if there was a problem deleting the timer in the host OS. + * @retval #OS_ERR_INCORRECT_OBJ_STATE if called from timer/timebase context */ int32 OS_TimerDelete(osal_id_t timer_id); @@ -184,6 +187,7 @@ int32 OS_TimerDelete(osal_id_t timer_id); * @retval #OS_INVALID_POINTER if timer_id or timer_name are NULL pointers * @retval #OS_ERR_NAME_TOO_LONG name length including null terminator greater than #OS_MAX_API_NAME * @retval #OS_ERR_NAME_NOT_FOUND if the name was not found in the table + * @retval #OS_ERR_INCORRECT_OBJ_STATE if called from timer/timebase context */ int32 OS_TimerGetIdByName(osal_id_t *timer_id, const char *timer_name); @@ -206,6 +210,7 @@ int32 OS_TimerGetIdByName(osal_id_t *timer_id, const char *timer_name); * @retval #OS_SUCCESS @copybrief OS_SUCCESS * @retval #OS_ERR_INVALID_ID if the id passed in is not a valid timer * @retval #OS_INVALID_POINTER if the timer_prop pointer is null + * @retval #OS_ERR_INCORRECT_OBJ_STATE if called from timer/timebase context */ int32 OS_TimerGetInfo(osal_id_t timer_id, OS_timer_prop_t *timer_prop); /**@}*/ diff --git a/src/os/shared/src/osapi-queue.c b/src/os/shared/src/osapi-queue.c index e8f8c4f46..f50278f8e 100644 --- a/src/os/shared/src/osapi-queue.c +++ b/src/os/shared/src/osapi-queue.c @@ -87,7 +87,7 @@ int32 OS_QueueAPI_Init(void) * See description in API and header file for detail * *-----------------------------------------------------------------*/ -int32 OS_QueueCreate(osal_id_t *queue_id, const char *queue_name, osal_blockcount_t queue_depth, size_t max_size, +int32 OS_QueueCreate(osal_id_t *queue_id, const char *queue_name, osal_blockcount_t queue_depth, size_t data_size, uint32 flags) { int32 return_code; @@ -97,7 +97,7 @@ int32 OS_QueueCreate(osal_id_t *queue_id, const char *queue_name, osal_blockcoun /* validate inputs */ OS_CHECK_POINTER(queue_id); OS_CHECK_APINAME(queue_name); - OS_CHECK_SIZE(max_size); + OS_CHECK_SIZE(data_size); ARGCHECK(queue_depth <= OS_QUEUE_MAX_DEPTH, OS_QUEUE_INVALID_SIZE); /* Note - the common ObjectIdAllocate routine will lock the object type and leave it locked. */ @@ -110,7 +110,7 @@ int32 OS_QueueCreate(osal_id_t *queue_id, const char *queue_name, osal_blockcoun OS_OBJECT_INIT(token, queue, queue_name, queue_name); queue->max_depth = queue_depth; - queue->max_size = max_size; + queue->max_size = data_size; /* Now call the OS-specific implementation. This reads info from the queue table. */ return_code = OS_QueueCreate_Impl(&token, flags); diff --git a/src/unit-test-coverage/shared/src/coveragetest-errors.c b/src/unit-test-coverage/shared/src/coveragetest-errors.c index 3afea3e05..dcd70c3a8 100644 --- a/src/unit-test-coverage/shared/src/coveragetest-errors.c +++ b/src/unit-test-coverage/shared/src/coveragetest-errors.c @@ -40,13 +40,8 @@ void Test_OS_GetErrorName(void) UtAssert_True(actual == expected, "OS_GetErrorName(%s) (%ld) == OS_SUCCESS", "OS_ERROR", (long)actual); UtAssert_True(strcmp(err_name, "OS_ERROR") == 0, "string(%s) == OS_ERROR", err_name); - expected = OS_ERROR; - actual = OS_GetErrorName(-555555, &err_name); - UtAssert_True(actual == expected, "OS_GetErrorName(%s) (%ld) == OS_SUCCESS", err_name, (long)actual); - - expected = OS_INVALID_POINTER; - actual = OS_GetErrorName(-555555, NULL); - UtAssert_True(actual == expected, "OS_GetErrorName(NULL) (%ld) == OS_SUCCESS", (long)actual); + OSAPI_TEST_FUNCTION_RC(OS_GetErrorName(-555555, &err_name), OS_ERROR); + OSAPI_TEST_FUNCTION_RC(OS_GetErrorName(-555555, NULL), OS_INVALID_POINTER); } /* Osapi_Test_Setup diff --git a/src/unit-test-coverage/shared/src/coveragetest-file.c b/src/unit-test-coverage/shared/src/coveragetest-file.c index 7d819166e..91f26cfa1 100644 --- a/src/unit-test-coverage/shared/src/coveragetest-file.c +++ b/src/unit-test-coverage/shared/src/coveragetest-file.c @@ -113,9 +113,8 @@ void Test_OS_TimedRead(void) UtAssert_True(actual == expected, "OS_TimedRead() (%ld) == %ld", (long)actual, (long)expected); UtAssert_True(memcmp(Buf, SrcBuf, actual) == 0, "buffer content match"); - expected = OS_INVALID_POINTER; - actual = OS_TimedRead(UT_OBJID_1, NULL, sizeof(Buf), 10); - UtAssert_True(actual == expected, "OS_TimedRead() (%ld) == %ld", (long)actual, (long)expected); + OSAPI_TEST_FUNCTION_RC(OS_TimedRead(UT_OBJID_1, NULL, sizeof(Buf), 10), OS_INVALID_POINTER); + OSAPI_TEST_FUNCTION_RC(OS_TimedRead(UT_OBJID_1, Buf, 0, 10), OS_ERR_INVALID_SIZE); } void Test_OS_TimedWrite(void) @@ -135,9 +134,8 @@ void Test_OS_TimedWrite(void) UtAssert_True(actual == expected, "OS_TimedWrite() (%ld) == %ld", (long)actual, (long)expected); UtAssert_True(memcmp(Buf, DstBuf, actual) == 0, "buffer content match"); - expected = OS_INVALID_POINTER; - actual = OS_TimedWrite(UT_OBJID_1, NULL, sizeof(Buf), 10); - UtAssert_True(actual == expected, "OS_TimedWrite() (%ld) == %ld", (long)actual, (long)expected); + OSAPI_TEST_FUNCTION_RC(OS_TimedWrite(UT_OBJID_1, NULL, sizeof(Buf), 10), OS_INVALID_POINTER); + OSAPI_TEST_FUNCTION_RC(OS_TimedWrite(UT_OBJID_1, Buf, 0, 10), OS_ERR_INVALID_SIZE); } void Test_OS_read(void) diff --git a/src/unit-test-coverage/shared/src/coveragetest-filesys.c b/src/unit-test-coverage/shared/src/coveragetest-filesys.c index d70381573..751a65f52 100644 --- a/src/unit-test-coverage/shared/src/coveragetest-filesys.c +++ b/src/unit-test-coverage/shared/src/coveragetest-filesys.c @@ -301,6 +301,14 @@ void Test_OS_FileSysStatVolume(void) expected = OS_ERR_OPERATION_NOT_SUPPORTED; actual = OS_FileSysStatVolume("/cf", &statbuf); UtAssert_True(actual == expected, "OS_FileSysStatVolume() (%ld) == OS_ERR_OPERATION_NOT_SUPPORTED", (long)actual); + UT_ResetState(UT_KEY(OS_FileSysStatVolume_Impl)); + + /* Verify OS_FS_ERR_PATH_TOO_LONG */ + UT_SetDefaultReturnValue(UT_KEY(OCS_memchr), -1); + expected = OS_FS_ERR_PATH_TOO_LONG; + actual = OS_FileSysStatVolume("/cf", &statbuf); + UtAssert_True(actual == expected, "OS_FileSysStatVolume() (%ld) == OS_FS_ERR_PATH_TOO_LONG", (long)actual); + UT_ResetState(UT_KEY(OCS_memchr)); } void Test_OS_chkfs(void) diff --git a/src/unit-test-coverage/shared/src/coveragetest-idmap.c b/src/unit-test-coverage/shared/src/coveragetest-idmap.c index 70b6e7329..c15c9ea97 100644 --- a/src/unit-test-coverage/shared/src/coveragetest-idmap.c +++ b/src/unit-test-coverage/shared/src/coveragetest-idmap.c @@ -79,10 +79,7 @@ void Test_OS_ObjectIdInit(void) * Test Case For: * int32 OS_ObjectIdInit(void) */ - int32 expected = OS_SUCCESS; - int32 actual = OS_ObjectIdInit(); - - UtAssert_True(actual == expected, "OS_ObjectIdInit() (%ld) == %ld", (long)actual, (long)expected); + OSAPI_TEST_FUNCTION_RC(OS_ObjectIdInit(), OS_SUCCESS); } void Test_OS_LockUnlockGlobal(void) @@ -156,6 +153,10 @@ void Test_OS_ObjectIdConvertToken(void) OS_common_record_t *record; osal_id_t objid; + /* confirm that calling w/invalid token returns OS_ERR_INCORRECT_OBJ_STATE */ + memset(&token, 0, sizeof(token)); + OSAPI_TEST_FUNCTION_RC(OS_ObjectIdConvertToken(&token), OS_ERR_INCORRECT_OBJ_STATE); + /* get a valid (fake) OSAL ID to start with */ OS_ObjectIdAllocateNew(OS_OBJECT_TYPE_OS_TASK, "ut", &token); objid = token.obj_id; @@ -660,6 +661,28 @@ void Test_OS_ObjectIdFindNextFree(void) /* verify that the wrap occurred */ UtAssert_True(i < (OS_OBJECT_INDEX_MASK + 2), "OS_ObjectIdFindNextFree() wrap around occurred"); + + /* Now fill the task table */ + memset(&token2, 0, sizeof(token2)); + token2.obj_type = OS_OBJECT_TYPE_OS_TASK; + for (i = 0; i < OS_MAX_TASKS; ++i) + { + token2.obj_idx = i; + + rec2 = OS_OBJECT_TABLE_GET(OS_global_task_table, token2); + OS_ObjectIdCompose_Impl(OS_OBJECT_TYPE_OS_TASK, i, &rec2->active_id); + } + + /* Attempt to allocate another task, should result in OS_ERR_NO_FREE_IDS */ + OSAPI_TEST_FUNCTION_RC(OS_ObjectIdFindNextFree(&token2), OS_ERR_NO_FREE_IDS); + + /* Clear the task table */ + memset(OS_global_task_table, 0, sizeof(OS_common_record_t) * OS_MAX_TASKS); + + /* Try to allocate an instance of an objtype which is not implemented */ + memset(&token2, 0, sizeof(token2)); + token2.obj_type = 22; + OSAPI_TEST_FUNCTION_RC(OS_ObjectIdFindNextFree(&token2), OS_ERR_NOT_IMPLEMENTED); } void Test_OS_ObjectIdAllocateNew(void) diff --git a/src/unit-test-coverage/shared/src/coveragetest-network.c b/src/unit-test-coverage/shared/src/coveragetest-network.c index 8a076a551..a9876236b 100644 --- a/src/unit-test-coverage/shared/src/coveragetest-network.c +++ b/src/unit-test-coverage/shared/src/coveragetest-network.c @@ -57,13 +57,8 @@ void Test_OS_NetworkGetHostName(void) actual = OS_NetworkGetHostName(Buffer, sizeof(Buffer)); UtAssert_True(actual == expected, "OS_NetworkGetHostName(impl error) (%ld) == -4444", (long)actual); - expected = OS_INVALID_POINTER; - actual = OS_NetworkGetHostName(NULL, sizeof(Buffer)); - UtAssert_True(actual == expected, "OS_NetworkGetHostName(Ptr=NULL) (%ld) == OS_INVALID_POINTER", (long)actual); - - expected = OS_ERR_INVALID_SIZE; - actual = OS_NetworkGetHostName(Buffer, 0); - UtAssert_True(actual == expected, "OS_NetworkGetHostName(Size=0) (%ld) == OS_ERROR", (long)actual); + OSAPI_TEST_FUNCTION_RC(OS_NetworkGetHostName(NULL, sizeof(Buffer)), OS_INVALID_POINTER); + OSAPI_TEST_FUNCTION_RC(OS_NetworkGetHostName(Buffer, 0), OS_ERR_INVALID_SIZE); } void Test_OS_NetworkGetID(void) diff --git a/src/unit-test-coverage/shared/src/coveragetest-select.c b/src/unit-test-coverage/shared/src/coveragetest-select.c index e5c848257..7f43131e4 100644 --- a/src/unit-test-coverage/shared/src/coveragetest-select.c +++ b/src/unit-test-coverage/shared/src/coveragetest-select.c @@ -47,6 +47,8 @@ void Test_OS_SelectSingle(void) /* Verify Outputs */ UtAssert_True(actual == expected, "OS_SelectSingle() (%ld) == OS_SUCCESS", (long)actual); + + OSAPI_TEST_FUNCTION_RC(OS_SelectSingle(UT_OBJID_1, NULL, 0), OS_INVALID_POINTER); } void Test_OS_SelectMultiple(void) diff --git a/src/unit-test-coverage/shared/src/coveragetest-sockets.c b/src/unit-test-coverage/shared/src/coveragetest-sockets.c index ea73c12b9..b1bf71556 100644 --- a/src/unit-test-coverage/shared/src/coveragetest-sockets.c +++ b/src/unit-test-coverage/shared/src/coveragetest-sockets.c @@ -306,6 +306,9 @@ void Test_OS_SocketRecvFrom(void) actual = OS_SocketRecvFrom(UT_OBJID_1, &Buf, sizeof(Buf), &Addr, 0); UtAssert_True(actual == expected, "OS_SocketRecvFrom() non-bound (%ld) == OS_ERR_INCORRECT_OBJ_STATE", (long)actual); + + /* Fail w/OS_ERR_INVALID_SIZE */ + OSAPI_TEST_FUNCTION_RC(OS_SocketRecvFrom(UT_OBJID_1, &Buf, 0, &Addr, 0), OS_ERR_INVALID_SIZE); } /***************************************************************************** diff --git a/src/unit-test-coverage/shared/src/coveragetest-time.c b/src/unit-test-coverage/shared/src/coveragetest-time.c index 1911196e3..00c541e07 100644 --- a/src/unit-test-coverage/shared/src/coveragetest-time.c +++ b/src/unit-test-coverage/shared/src/coveragetest-time.c @@ -281,18 +281,11 @@ void Test_OS_TimerGetIdByName(void) UtAssert_True(actual == expected, "OS_TimerGetIdByName() (%ld) == OS_SUCCESS", (long)actual); UT_ClearDefaultReturnValue(UT_KEY(OS_ObjectIdFindByName)); - expected = OS_ERR_NAME_NOT_FOUND; - actual = OS_TimerGetIdByName(&objid, "NF"); - UtAssert_True(actual == expected, "OS_TimerGetIdByName() (%ld) == %ld", (long)actual, (long)expected); - - expected = OS_INVALID_POINTER; - actual = OS_TimerGetIdByName(NULL, "NF"); - UtAssert_True(actual == expected, "OS_TimerGetIdByName() (%ld) == %ld", (long)actual, (long)expected); + OSAPI_TEST_FUNCTION_RC(OS_TimerGetIdByName(&objid, "NF"), OS_ERR_NAME_NOT_FOUND); + OSAPI_TEST_FUNCTION_RC(OS_TimerGetIdByName(NULL, "NF"), OS_INVALID_POINTER); UT_SetDefaultReturnValue(UT_KEY(OS_TaskGetId_Impl), 1 | (OS_OBJECT_TYPE_OS_TIMEBASE << OS_OBJECT_TYPE_SHIFT)); - expected = OS_ERR_INCORRECT_OBJ_STATE; - actual = OS_TimerGetIdByName(&objid, "NF"); - UtAssert_True(actual == expected, "OS_TimerGetIdByName() (%ld) == %ld", (long)actual, (long)expected); + OSAPI_TEST_FUNCTION_RC(OS_TimerGetIdByName(&objid, "NF"), OS_ERR_INCORRECT_OBJ_STATE); UT_ClearDefaultReturnValue(UT_KEY(OS_TaskGetId_Impl)); } diff --git a/src/unit-test-coverage/shared/src/coveragetest-timebase.c b/src/unit-test-coverage/shared/src/coveragetest-timebase.c index fbfb10d35..b2b28a6bd 100644 --- a/src/unit-test-coverage/shared/src/coveragetest-timebase.c +++ b/src/unit-test-coverage/shared/src/coveragetest-timebase.c @@ -168,9 +168,11 @@ void Test_OS_TimeBaseGetIdByName(void) OSAPI_TEST_OBJID(objid, !=, OS_OBJECT_ID_UNDEFINED); UT_ClearDefaultReturnValue(UT_KEY(OS_ObjectIdFindByName)); - expected = OS_ERR_NAME_NOT_FOUND; - actual = OS_TimeBaseGetIdByName(&objid, "NF"); - UtAssert_True(actual == expected, "OS_TimeBaseGetIdByName() (%ld) == %ld", (long)actual, (long)expected); + OSAPI_TEST_FUNCTION_RC(OS_TimeBaseGetIdByName(&objid, "NF"), OS_ERR_NAME_NOT_FOUND); + + UT_SetDefaultReturnValue(UT_KEY(OCS_memchr), -1); + OSAPI_TEST_FUNCTION_RC(OS_TimeBaseGetIdByName(&objid, "TL"), OS_ERR_NAME_TOO_LONG); + UT_ResetState(UT_KEY(OCS_memchr)); /* test error paths */ expected = OS_INVALID_POINTER;