Merge pull request #980 from jphickey/fix-331-retcodes

Partial #331, scrub return values

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

@@ -117,6 +117,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

@@ -149,6 +149,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);
 
@@ -169,6 +170,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);
 
@@ -191,6 +194,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);
 
@@ -206,6 +210,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);
 
@@ -221,6 +226,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);
 /**@}*/
@@ -252,6 +258,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);
 
@@ -270,6 +277,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);
 
@@ -286,6 +294,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);
 
@@ -321,6 +330,7 @@ int32 OS_SocketShutdown(osal_id_t sock_id, OS_SocketShutdownMode_t Mode);
  * @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);
 
@@ -338,6 +348,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);
 
@@ -355,6 +367,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

@@ -103,6 +103,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
@@ -244,6 +245,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);