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

@@ -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);
 

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);
 

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);
 

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);
 /**@}*/

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);
 /**@}*/

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);
 

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);
 /**@}*/

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);
 

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);
 

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);
 

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
  */

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);
 

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);

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);
 

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);