diff --git a/doc/OSAL Library API.doc b/doc/OSAL Library API.doc deleted file mode 100644 index cfffa8ae8..000000000 Binary files a/doc/OSAL Library API.doc and /dev/null differ diff --git a/doc/OSAL Library API.pdf b/doc/OSAL Library API.pdf deleted file mode 100644 index 2855d370f..000000000 Binary files a/doc/OSAL Library API.pdf and /dev/null differ diff --git a/src/os/inc/common_types.h b/src/os/inc/common_types.h index 9ade77ca5..9c6a6ffcc 100644 --- a/src/os/inc/common_types.h +++ b/src/os/inc/common_types.h @@ -97,7 +97,7 @@ * Define the "osalbool" type for backward compatibility. * This will be removed in a future release. */ -typedef bool osalbool; +typedef bool osalbool; /**< @deprecated Use bool */ /* * Boolean type for compatibility -- @@ -116,15 +116,15 @@ typedef bool osalbool; */ #if (!defined(_USING_RTEMS_INCLUDES_) || !defined(RTEMS_DEPRECATED_TYPES)) - typedef osalbool boolean; + typedef osalbool boolean; /**< @deprecated Use bool */ #endif #ifndef TRUE /* Boolean true */ -#define TRUE true +#define TRUE true /**< @deprecated Use true */ #endif #ifndef FALSE /* Boolean false */ -#define FALSE false +#define FALSE false /**< @deprecated Use false */ #endif diff --git a/src/os/inc/osapi-os-core.h b/src/os/inc/osapi-os-core.h index d7df853d5..d6d89d4b0 100644 --- a/src/os/inc/osapi-os-core.h +++ b/src/os/inc/osapi-os-core.h @@ -22,37 +22,51 @@ #include /* for va_list */ /* Defines constants for making object ID's unique */ -#define OS_OBJECT_INDEX_MASK 0xFFFF -#define OS_OBJECT_TYPE_SHIFT 16 - -#define OS_OBJECT_TYPE_UNDEFINED 0x00 -#define OS_OBJECT_TYPE_OS_TASK 0x01 -#define OS_OBJECT_TYPE_OS_QUEUE 0x02 -#define OS_OBJECT_TYPE_OS_COUNTSEM 0x03 -#define OS_OBJECT_TYPE_OS_BINSEM 0x04 -#define OS_OBJECT_TYPE_OS_MUTEX 0x05 -#define OS_OBJECT_TYPE_OS_STREAM 0x06 -#define OS_OBJECT_TYPE_OS_DIR 0x07 -#define OS_OBJECT_TYPE_OS_TIMEBASE 0x08 -#define OS_OBJECT_TYPE_OS_TIMECB 0x09 -#define OS_OBJECT_TYPE_OS_MODULE 0x0A -#define OS_OBJECT_TYPE_OS_FILESYS 0x0B -#define OS_OBJECT_TYPE_OS_CONSOLE 0x0C -#define OS_OBJECT_TYPE_USER 0x10 - -/* Upper limit for OSAL task priorities */ +#define OS_OBJECT_INDEX_MASK 0xFFFF /**< @brief Object index mask */ +#define OS_OBJECT_TYPE_SHIFT 16 /**< @brief Object type shift */ + +/** @defgroup OSObjectTypes OSAL Object Type Defines + * @{ + */ +#define OS_OBJECT_TYPE_UNDEFINED 0x00 /**< @brief Object type undefined */ +#define OS_OBJECT_TYPE_OS_TASK 0x01 /**< @brief Object task type */ +#define OS_OBJECT_TYPE_OS_QUEUE 0x02 /**< @brief Object queue type */ +#define OS_OBJECT_TYPE_OS_COUNTSEM 0x03 /**< @brief Object counting semaphore type */ +#define OS_OBJECT_TYPE_OS_BINSEM 0x04 /**< @brief Object binary semaphore type */ +#define OS_OBJECT_TYPE_OS_MUTEX 0x05 /**< @brief Object mutex type */ +#define OS_OBJECT_TYPE_OS_STREAM 0x06 /**< @brief Object stream type */ +#define OS_OBJECT_TYPE_OS_DIR 0x07 /**< @brief Object directory type */ +#define OS_OBJECT_TYPE_OS_TIMEBASE 0x08 /**< @brief Object timebase type */ +#define OS_OBJECT_TYPE_OS_TIMECB 0x09 /**< @brief Object timer callback type */ +#define OS_OBJECT_TYPE_OS_MODULE 0x0A /**< @brief Object module type */ +#define OS_OBJECT_TYPE_OS_FILESYS 0x0B /**< @brief Object file system type */ +#define OS_OBJECT_TYPE_OS_CONSOLE 0x0C /**< @brief Object console type */ +#define OS_OBJECT_TYPE_USER 0x10 /**< @brief Object user type */ +/**@}*/ + +/** @brief Upper limit for OSAL task priorities */ #define OS_MAX_TASK_PRIORITY 255 -/*difines constants for OS_BinSemCreate for state of semaphore */ -#define OS_SEM_FULL 1 -#define OS_SEM_EMPTY 0 +/** @defgroup OSSemaphoreStates OSAL Semaphore State Defines + * @{ + */ +#define OS_SEM_FULL 1 /**< @brief Semaphore full state */ +#define OS_SEM_EMPTY 0 /**< @brief Semaphore empty state */ +/**@}*/ -/* #define for enabling floating point operations on a task*/ +/** @brief Floating point enabled state for a task */ #define OS_FP_ENABLED 1 -/* tables for the properties of objects */ +/** @brief Error string name length + * + * The sizes of strings in OSAL functions are built with this limit in mind. + * Always check the uses of os_err_name_t when changing this value. + */ +#define OS_ERROR_NAME_LENGTH 35 + +/* Object property structures */ -/*tasks */ +/** @brief OSAL task properties */ typedef struct { char name [OS_MAX_API_NAME]; @@ -62,14 +76,14 @@ typedef struct uint32 OStask_id; }OS_task_prop_t; -/* queues */ +/** @brief OSAL queue properties */ typedef struct { char name [OS_MAX_API_NAME]; uint32 creator; }OS_queue_prop_t; -/* Binary Semaphores */ +/** @brief OSAL binary semaphore properties */ typedef struct { char name [OS_MAX_API_NAME]; @@ -77,7 +91,7 @@ typedef struct int32 value; }OS_bin_sem_prop_t; -/* Counting Semaphores */ +/** @brief OSAL counting semaphore properties */ typedef struct { char name [OS_MAX_API_NAME]; @@ -85,7 +99,7 @@ typedef struct int32 value; }OS_count_sem_prop_t; -/* Mutexes */ +/** @brief OSAL mutexe properties */ typedef struct { char name [OS_MAX_API_NAME]; @@ -93,15 +107,17 @@ typedef struct }OS_mut_sem_prop_t; -/* struct for OS_GetLocalTime() */ - +/** @brief OSAL time */ typedef struct { uint32 seconds; uint32 microsecs; }OS_time_t; -/* heap info */ +/** @brief OSAL heap properties + * + * @sa OS_HeapGetInfo() + */ typedef struct { uint32 free_bytes; @@ -109,61 +125,82 @@ typedef struct uint32 largest_free_block; }OS_heap_prop_t; +/** + * @brief An abstract structure capable of holding several OSAL IDs + * + * This is part of the select API and is manipulated using the + * related API calls. It should not be modified directly by applications. + * + * @sa OS_SelectFdZero(), OS_SelectFdAdd(), OS_SelectFdClear(), OS_SelectFdIsSet() + */ +typedef struct +{ + uint8 object_ids[(OS_MAX_NUM_OPEN_FILES + 7) / 8]; +} OS_FdSet; -/* This typedef is for the OS_GetErrorName function, to ensure +/** + * @brief For the @ref OS_GetErrorName() function, to ensure * everyone is making an array of the same length. * * Implementation note for developers: * * The sizes of strings in OSAL functions are built with this - * OS_ERROR_NAME_LENGTH limit in mind. Always check the uses of os_err_name_t + * #OS_ERROR_NAME_LENGTH limit in mind. Always check the uses of os_err_name_t * when changing this value. */ - -#define OS_ERROR_NAME_LENGTH 35 typedef char os_err_name_t[OS_ERROR_NAME_LENGTH]; /* ** These typedefs are for the task entry point */ -typedef void osal_task; -typedef osal_task ((*osal_task_entry)(void)); +typedef void osal_task; /**< @brief For task entry point */ +typedef osal_task ((*osal_task_entry)(void)); /**< @brief For task entry point */ -/* -** Typedef for general purpose OSAL callback functions -** This may be used by multiple APIS -*/ +/** + * @brief General purpose OSAL callback function + * + * This may be used by multiple APIS + */ typedef void (*OS_ArgCallback_t)(uint32 object_id, void *arg); +/** @defgroup OSAPICore OSAL Core Operation APIs + * + * These are for OSAL core operations for startup/initialization, running, and shutdown. + * Typically only used in bsps, unit tests, psps, etc. + * + * Not intended for user application use + * @{ + */ -/* -** External Declarations -*/ - -/* -** Prototype for application startup function. -** This is implemented by the BSP or user application -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Application startup + * + * Startup abstraction such that the same BSP can be used for operations and testing. + */ void OS_Application_Startup(void); -/* -** Prototype for application run function. -** This is implemented by the BSP or user application -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Application run + * + * Run abstraction such that the same BSP can be used for operations and testing. + */ void OS_Application_Run(void); -/* -** Exported Functions -*/ - /*-------------------------------------------------------------------------------------*/ /** * @brief Initialization of API * - * Initialize the tables that the OS API uses to keep track of information - * about objects + * This function returns initializes the internal data structures of the OS + * Abstraction Layer. It must be called in the application startup code before + * calling any other OS routines. * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes. Any error code (negative) + * means the OSAL can not be initialized. Typical platform specific response + * is to abort since additional OSAL calls will have undefined behavior. + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERROR @copybrief OS_ERROR */ int32 OS_API_Init (void); @@ -171,8 +208,8 @@ int32 OS_API_Init (void); /** * @brief Background thread implementation - waits forever for events to occur. * - * This should be called from the BSP main routine / initial thread after all other - * board / application initialization has taken place and all other tasks are running. + * This should be called from the BSP main routine or initial thread after all other + * board and application initialization has taken place and all other tasks are running. * * Typically just waits forever until "OS_shutdown" flag becomes true. */ @@ -198,13 +235,31 @@ void OS_DeleteAllObjects (void); * This allows the task currently blocked in OS_IdleLoop() to wake up, and * for that function to return to its caller. * - * This is preferred over e.g. ApplicationExit() which exits immediately and + * This is preferred over e.g. OS_ApplicationExit() which exits immediately and * does not provide for any means to clean up first. * - * @param flag set to true to initiate shutdown, false to cancel + * @param[in] flag set to true to initiate shutdown, false to cancel */ void OS_ApplicationShutdown (uint8 flag); +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Exit/Abort the application + * + * Indicates that the OSAL application should exit and return control to the OS + * This is intended for e.g. scripted unit testing where the test needs to end + * without user intervention. + * + * This function does not return. Production code typically should not ever call this. + * + * @note This exits the entire process including tasks that have been created. + */ +void OS_ApplicationExit(int32 Status); +/**@}*/ + +/** @defgroup OSAPIObjUtil OSAL Object Utility APIs + * @{ + */ /*-------------------------------------------------------------------------------------*/ /** @@ -214,9 +269,8 @@ void OS_ApplicationShutdown (uint8 flag); * * @param[in] object_id The object ID to operate on * - * @returns The type of object that the ID represents - * #OS_OBJECT_TYPE_OS_TASK for tasks - * #OS_OBJECT_TYPE_OS_QUEUE for queues, etc. + * @return The object type portion of the object_id, see @ref OSObjectTypes for + * expected values */ uint32 OS_IdentifyObject (uint32 object_id); @@ -232,10 +286,11 @@ uint32 OS_IdentifyObject (uint32 object_id); * This is only the conversion logic. * * @param[in] object_id The object ID to operate on - * * @param[out] *ArrayIndex The Index to return * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_INCORRECT_OBJ_TYPE @copybrief OS_ERR_INCORRECT_OBJ_TYPE */ int32 OS_ConvertToArrayIndex (uint32 object_id, uint32 *ArrayIndex); @@ -247,16 +302,19 @@ int32 OS_ConvertToArrayIndex (uint32 object_id, uint32 *ArrayIndex); * If creator_id is nonzero then only objects with matching creator id are processed. */ void OS_ForEachObject (uint32 creator_id, OS_ArgCallback_t callback_ptr, void *callback_arg); +/**@}*/ - -/* -** Task API -*/ +/** @defgroup OSAPITask OSAL Task APIs + * @{ + */ /*-------------------------------------------------------------------------------------*/ /** * @brief Creates a task and starts running it. * + * Creates a task and passes back the id of the task created. Task names must be unique; + * if the name already exists this function fails. Names cannot be NULL. + * * @param[out] task_id will be set to the ID of the newly-created resource * @param[in] task_name the name of the new resource to create * @param[in] function_pointer the entry point of the new task @@ -266,13 +324,14 @@ void OS_ForEachObject (uint32 creator_id, OS_ArgCallback_t callback_pt * @param[in] priority initial priority of the new task * @param[in] flags initial options for the new task * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if any of the necessary pointers are NULL - * OS_ERR_NAME_TOO_LONG if the name of the task is too long to be copied - * OS_ERR_INVALID_PRIORITY if the priority is bad - * OS_ERR_NO_FREE_IDS if there can be no more tasks created - * OS_ERR_NAME_TAKEN if the name specified is already used by a task - * OS_ERROR if an unspecified/other error occurs + * @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_NAME_TOO_LONG if the name of the task is too long to be copied + * @retval #OS_ERR_INVALID_PRIORITY if the priority is bad + * @retval #OS_ERR_NO_FREE_IDS if there can be no more tasks created + * @retval #OS_ERR_NAME_TAKEN if the name specified is already used by a task + * @retval #OS_ERROR if an unspecified/other error occurs */ int32 OS_TaskCreate (uint32 *task_id, const char *task_name, osal_task_entry function_pointer, @@ -289,9 +348,10 @@ int32 OS_TaskCreate (uint32 *task_id, const char *task_name, * * @param[in] task_id The object ID to operate on * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the ID given to it is invalid - * OS_ERROR if the OS delete call fails + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_INVALID_ID if the ID given to it is invalid + * @retval #OS_ERROR if the OS delete call fails */ int32 OS_TaskDelete (uint32 task_id); @@ -307,9 +367,14 @@ void OS_TaskExit (void); /** * @brief Installs a handler for when the task is deleted. * + * This function is used to install a callback that is called when the task is deleted. + * The callback is called when OS_TaskDelete is called with the task ID. A task delete + * handler is useful for cleaning up resources that a task creates, before the task is + * removed from the system. + * * @param[in] function_pointer function to be called when task exits * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_TaskInstallDeleteHandler(osal_task_entry function_pointer); @@ -317,11 +382,13 @@ int32 OS_TaskInstallDeleteHandler(osal_task_entry function_pointer); /** * @brief Delay a task for specified amount of milliseconds * + * Causes the current thread to be suspended from execution for the period of millisecond. + * * @param[in] millisecond Amount of time to delay * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERROR if sleep fails or millisecond = 0 - * OS_SUCCESS if success + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERROR if sleep fails or millisecond = 0 */ int32 OS_TaskDelay (uint32 millisecond); @@ -333,21 +400,23 @@ int32 OS_TaskDelay (uint32 millisecond); * * @param[in] new_priority Set the new priority * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the ID passed to it is invalid - * OS_ERR_INVALID_PRIORITY if the priority is greater than the max allowed - * OS_ERROR if the OS call to change the priority fails + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_INVALID_ID if the ID passed to it is invalid + * @retval #OS_ERR_INVALID_PRIORITY if the priority is greater than the max allowed + * @retval #OS_ERROR if the OS call to change the priority fails */ int32 OS_TaskSetPriority (uint32 task_id, uint32 new_priority); /*-------------------------------------------------------------------------------------*/ /** - * @brief Registration to be called by new tasks after creation + * @brief Obsolete + * @deprecated Explicit registration call no longer needed * * Obsolete function retained for compatibility purposes. * Does Nothing in the current implementation. * - * @returns OS_SUCCESS (always) + * @return #OS_SUCCESS (always), see @ref OSReturnCodes */ int32 OS_TaskRegister (void); @@ -357,7 +426,7 @@ int32 OS_TaskRegister (void); * * This function returns the task id of the calling task * - * @returns Task ID, or zero if the operation failed (zero is never a valid task ID) + * @return Task ID, or zero if the operation failed (zero is never a valid task ID) */ uint32 OS_TaskGetId (void); @@ -370,10 +439,11 @@ uint32 OS_TaskGetId (void); * @param[out] task_id will be set to the ID of the existing resource * @param[in] task_name the name of the existing resource to find * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if the pointers passed in are NULL - * OS_ERR_NAME_TOO_LONG if th ename to found is too long to begin with - * OS_ERR_NAME_NOT_FOUND if the name wasn't found in the table + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if the pointers passed in are NULL + * @retval #OS_ERR_NAME_TOO_LONG if the name to found is too long to begin with + * @retval #OS_ERR_NAME_NOT_FOUND if the name wasn't found in the table */ int32 OS_TaskGetIdByName (uint32 *task_id, const char *task_name); @@ -388,31 +458,41 @@ int32 OS_TaskGetIdByName (uint32 *task_id, const char *task_name); * @param[in] task_id The object ID to operate on * @param[out] task_prop The property object buffer to fill * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the ID passed to it is invalid - * OS_INVALID_POINTER if the task_prop pointer is NULL + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_INVALID_ID if the ID passed to it is invalid + * @retval #OS_INVALID_POINTER if the task_prop pointer is NULL */ int32 OS_TaskGetInfo (uint32 task_id, OS_task_prop_t *task_prop); +/**@}*/ -/* -** Message Queue API -*/ +/** @defgroup OSAPIMsgQueue OSAL Message Queue APIs + * @{ + */ /** * @brief Create a message queue * + * This is the function used to create a queue in the operating system. + * Depending on the underlying operating system, the memory for the queue + * will be allocated automatically or allocated by the code that sets up + * the queue. Queue names must be unique; if the name already exists this + * function fails. Names cannot be NULL. + * + * * @param[out] queue_id will be set to the ID of the newly-created resource * @param[in] queue_name the name of the new resource to create * @param[in] queue_depth the maximum depth of the queue * @param[in] data_size the size of each entry in the queue * @param[in] flags options for the queue (reserved for future use, pass as 0) * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if a pointer passed in is NULL - * OS_ERR_NAME_TOO_LONG if the name passed in is too long - * OS_ERR_NO_FREE_IDS if there are already the max queues created - * OS_ERR_NAME_TAKEN if the name is already being used on another queue - * OS_ERROR if the OS create call fails + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if a pointer passed in is NULL + * @retval #OS_ERR_NAME_TOO_LONG if the name passed in is too long + * @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_ERROR if the OS create call fails */ int32 OS_QueueCreate (uint32 *queue_id, const char *queue_name, uint32 queue_depth, uint32 data_size, uint32 flags); @@ -421,14 +501,18 @@ int32 OS_QueueCreate (uint32 *queue_id, const char *queue_name, /** * @brief Deletes the specified message queue. * + * This is the function used to delete a queue in the operating system. + * This also frees the respective queue_id to be used again when another queue is created. + * * @note If There are messages on the queue, they will be lost and any subsequent * calls to QueueGet or QueuePut to this queue will result in errors * * @param[in] queue_id The object ID to delete * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the id passed in does not exist - * OS_ERROR if the OS call to delete the queue fails + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_INVALID_ID if the id passed in does not exist + * @retval #OS_ERROR if the OS call to delete the queue fails */ int32 OS_QueueDelete (uint32 queue_id); @@ -445,12 +529,13 @@ int32 OS_QueueDelete (uint32 queue_id); * @param[out] size_copied Set to the actual size of the message * @param[in] timeout The maximum amount of time to block, or OS_PEND to wait forever * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the given ID does not exist - * OS_ERR_INVALID_POINTER if a pointer passed in is NULL - * OS_QUEUE_EMPTY if the Queue has no messages on it to be recieved - * OS_QUEUE_TIMEOUT if the timeout was OS_PEND and the time expired - * OS_QUEUE_INVALID_SIZE if the size copied from the queue was not correct + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_INVALID_ID if the given ID does not exist + * @retval #OS_INVALID_POINTER if a pointer passed in is NULL + * @retval #OS_QUEUE_EMPTY if the Queue has no messages on it to be recieved + * @retval #OS_QUEUE_TIMEOUT if the timeout was OS_PEND and the time expired + * @retval #OS_QUEUE_INVALID_SIZE if the size copied from the queue was not correct */ int32 OS_QueueGet (uint32 queue_id, void *data, uint32 size, uint32 *size_copied, int32 timeout); @@ -464,11 +549,12 @@ int32 OS_QueueGet (uint32 queue_id, void *data, uint32 size, * @param[in] size The size of the data buffer * @param[in] flags Currently reserved/unused, should be passed as 0 * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the queue id passed in is not a valid queue - * OS_INVALID_POINTER if the data pointer is NULL - * OS_QUEUE_FULL if the queue cannot accept another message - * OS_ERROR if the OS call returns an error + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_INVALID_ID if the queue id passed in is not a valid queue + * @retval #OS_INVALID_POINTER if the data pointer is NULL + * @retval #OS_QUEUE_FULL if the queue cannot accept another message + * @retval #OS_ERROR if the OS call returns an error */ int32 OS_QueuePut (uint32 queue_id, const void *data, uint32 size, uint32 flags); @@ -483,10 +569,11 @@ int32 OS_QueuePut (uint32 queue_id, const void *data, uint32 size, * @param[out] queue_id will be set to the ID of the existing resource * @param[in] queue_name the name of the existing resource to find * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if the name or id pointers are NULL - * OS_ERR_NAME_TOO_LONG the name passed in is too long - * OS_ERR_NAME_NOT_FOUND the name was not found in the table + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if the name or id pointers are NULL + * @retval #OS_ERR_NAME_TOO_LONG the name passed in is too long + * @retval #OS_ERR_NAME_NOT_FOUND the name was not found in the table */ int32 OS_QueueGetIdByName (uint32 *queue_id, const char *queue_name); @@ -500,16 +587,18 @@ int32 OS_QueueGetIdByName (uint32 *queue_id, const char *queue_name); * @param[in] queue_id The object ID to operate on * @param[out] queue_prop The property object buffer to fill * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if queue_prop is NULL - * OS_ERR_INVALID_ID if the ID given is not a valid queue - * OS_SUCCESS if the info was copied over correctly + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if queue_prop is NULL + * @retval #OS_ERR_INVALID_ID if the ID given is not a valid queue + * @retval #OS_SUCCESS if the info was copied over correctly */ int32 OS_QueueGetInfo (uint32 queue_id, OS_queue_prop_t *queue_prop); +/**@}*/ -/* -** Semaphore API -*/ +/** @defgroup OSAPISem OSAL Semaphore APIs + * @{ + */ /*-------------------------------------------------------------------------------------*/ /** @@ -524,12 +613,13 @@ int32 OS_QueueGetInfo (uint32 queue_id, OS_queue_prop_t *queue_prop); * @param[in] sem_initial_value the initial value of the binary semaphore * @param[in] options Reserved for future use, should be passed as 0. * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if sen name or sem_id are NULL - * OS_ERR_NAME_TOO_LONG if the name given is too long - * OS_ERR_NO_FREE_IDS if all of the semaphore ids are taken - * OS_ERR_NAME_TAKEN if this is already the name of a binary semaphore - * OS_SEM_FAILURE if the OS call failed + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if sen name or sem_id are NULL + * @retval #OS_ERR_NAME_TOO_LONG if the name given is too long + * @retval #OS_ERR_NO_FREE_IDS if all of the semaphore ids are taken + * @retval #OS_ERR_NAME_TAKEN if this is already the name of a binary semaphore + * @retval #OS_SEM_FAILURE if the OS call failed */ int32 OS_BinSemCreate (uint32 *sem_id, const char *sem_name, uint32 sem_initial_value, uint32 options); @@ -543,9 +633,10 @@ int32 OS_BinSemCreate (uint32 *sem_id, const char *sem_name, * * @param[in] sem_id The object ID to operate on * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the id passed in is not a binary semaphore - * OS_SEM_FAILURE if an unspecified failure occurs + * @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 binary semaphore + * @retval #OS_SEM_FAILURE if an unspecified failure occurs */ int32 OS_BinSemFlush (uint32 sem_id); @@ -561,10 +652,11 @@ int32 OS_BinSemFlush (uint32 sem_id); * * @param[in] sem_id The object ID to operate on * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_SEM_FAILURE the semaphore was not previously initialized or is not + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_SEM_FAILURE the semaphore was not previously initialized or is not * in the array of semaphores defined by the system - * OS_ERR_INVALID_ID if the id passed in is not a binary semaphore + * @retval #OS_ERR_INVALID_ID if the id passed in is not a binary semaphore */ int32 OS_BinSemGive (uint32 sem_id); @@ -580,9 +672,10 @@ int32 OS_BinSemGive (uint32 sem_id); * * @param[in] sem_id The object ID to operate on * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID the Id passed in is not a valid binary semaphore - * OS_SEM_FAILURE if the OS call failed + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_INVALID_ID the Id passed in is not a valid binary semaphore + * @retval #OS_SEM_FAILURE if the OS call failed */ int32 OS_BinSemTake (uint32 sem_id); @@ -598,11 +691,12 @@ int32 OS_BinSemTake (uint32 sem_id); * @param[in] sem_id The object ID to operate on * @param[in] msecs The maximum amount of time to block, in milliseconds * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_SEM_TIMEOUT if semaphore was not relinquished in time - * OS_SEM_FAILURE the semaphore was not previously initialized or is not + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_SEM_TIMEOUT if semaphore was not relinquished in time + * @retval #OS_SEM_FAILURE the semaphore was not previously initialized or is not * in the array of semaphores defined by the system - * OS_ERR_INVALID_ID if the ID passed in is not a valid semaphore ID + * @retval #OS_ERR_INVALID_ID if the ID passed in is not a valid semaphore ID */ int32 OS_BinSemTimedWait (uint32 sem_id, uint32 msecs); @@ -610,11 +704,15 @@ int32 OS_BinSemTimedWait (uint32 sem_id, uint32 msecs); /** * @brief Deletes the specified Binary Semaphore * + * This is the function used to delete a binary semaphore in the operating system. + * This also frees the respective sem_id to be used again when another semaphore is created. + * * @param[in] sem_id The object ID to delete * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the id passed in is not a valid binary semaphore - * OS_SEM_FAILURE the OS call failed + * @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 binary semaphore + * @retval #OS_SEM_FAILURE the OS call failed */ int32 OS_BinSemDelete (uint32 sem_id); @@ -628,10 +726,11 @@ int32 OS_BinSemDelete (uint32 sem_id); * @param[out] sem_id will be set to the ID of the existing resource * @param[in] sem_name the name of the existing resource to find * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER is semid or sem_name are NULL pointers - * OS_ERR_NAME_TOO_LONG if the name given is to long to have been stored - * OS_ERR_NAME_NOT_FOUND if the name was not found in the table + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER is semid or sem_name are NULL pointers + * @retval #OS_ERR_NAME_TOO_LONG if the name given is to long to have been stored + * @retval #OS_ERR_NAME_NOT_FOUND if the name was not found in the table */ int32 OS_BinSemGetIdByName (uint32 *sem_id, const char *sem_name); @@ -646,10 +745,10 @@ int32 OS_BinSemGetIdByName (uint32 *sem_id, const char *sem_name); * @param[in] sem_id The object ID to operate on * @param[out] bin_prop The property object buffer to fill * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the id passed in is not a valid semaphore - * OS_INVALID_POINTER if the bin_prop pointer is null - * OS_SUCCESS if success + * @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 semaphore + * @retval #OS_INVALID_POINTER if the bin_prop pointer is null */ int32 OS_BinSemGetInfo (uint32 sem_id, OS_bin_sem_prop_t *bin_prop); @@ -666,13 +765,14 @@ int32 OS_BinSemGetInfo (uint32 sem_id, OS_bin_sem_prop_t *bin_prop); * @param[in] sem_initial_value the initial value of the counting semaphore * @param[in] options Reserved for future use, should be passed as 0. * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if sen name or sem_id are NULL - * OS_ERR_NAME_TOO_LONG if the name given is too long - * OS_ERR_NO_FREE_IDS if all of the semaphore ids are taken - * OS_ERR_NAME_TAKEN if this is already the name of a counting semaphore - * OS_SEM_FAILURE if the OS call failed - * OS_INVALID_SEM_VALUE if the semaphore value is too high + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if sen name or sem_id are NULL + * @retval #OS_ERR_NAME_TOO_LONG if the name given is too long + * @retval #OS_ERR_NO_FREE_IDS if all of the semaphore ids are taken + * @retval #OS_ERR_NAME_TAKEN if this is already the name of a counting semaphore + * @retval #OS_SEM_FAILURE if the OS call failed + * @retval #OS_INVALID_SEM_VALUE if the semaphore value is too high */ int32 OS_CountSemCreate (uint32 *sem_id, const char *sem_name, uint32 sem_initial_value, uint32 options); @@ -689,10 +789,11 @@ int32 OS_CountSemCreate (uint32 *sem_id, const char *sem_name, * * @param[in] sem_id The object ID to operate on * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_SEM_FAILURE the semaphore was not previously initialized or is not + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_SEM_FAILURE the semaphore was not previously initialized or is not * in the array of semaphores defined by the system - * OS_ERR_INVALID_ID if the id passed in is not a counting semaphore + * @retval #OS_ERR_INVALID_ID if the id passed in is not a counting semaphore */ int32 OS_CountSemGive (uint32 sem_id); @@ -708,9 +809,10 @@ int32 OS_CountSemGive (uint32 sem_id); * * @param[in] sem_id The object ID to operate on * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID the Id passed in is not a valid counting semaphore - * OS_SEM_FAILURE if the OS call failed + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_INVALID_ID the Id passed in is not a valid counting semaphore + * @retval #OS_SEM_FAILURE if the OS call failed */ int32 OS_CountSemTake (uint32 sem_id); @@ -726,11 +828,12 @@ int32 OS_CountSemTake (uint32 sem_id); * @param[in] sem_id The object ID to operate on * @param[in] msecs The maximum amount of time to block, in milliseconds * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_SEM_TIMEOUT if semaphore was not relinquished in time - * OS_SEM_FAILURE the semaphore was not previously initialized or is not + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_SEM_TIMEOUT if semaphore was not relinquished in time + * @retval #OS_SEM_FAILURE the semaphore was not previously initialized or is not * in the array of semaphores defined by the system - * OS_ERR_INVALID_ID if the ID passed in is not a valid semaphore ID + * @retval #OS_ERR_INVALID_ID if the ID passed in is not a valid semaphore ID */ int32 OS_CountSemTimedWait (uint32 sem_id, uint32 msecs); @@ -740,9 +843,10 @@ int32 OS_CountSemTimedWait (uint32 sem_id, uint32 msecs); * * @param[in] sem_id The object ID to delete * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the id passed in is not a valid counting semaphore - * OS_SEM_FAILURE the OS call failed + * @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 counting semaphore + * @retval #OS_SEM_FAILURE the OS call failed */ int32 OS_CountSemDelete (uint32 sem_id); @@ -756,10 +860,11 @@ int32 OS_CountSemDelete (uint32 sem_id); * @param[out] sem_id will be set to the ID of the existing resource * @param[in] sem_name the name of the existing resource to find * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER is semid or sem_name are NULL pointers - * OS_ERR_NAME_TOO_LONG if the name given is to long to have been stored - * OS_ERR_NAME_NOT_FOUND if the name was not found in the table + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER is semid or sem_name are NULL pointers + * @retval #OS_ERR_NAME_TOO_LONG if the name given is to long to have been stored + * @retval #OS_ERR_NAME_NOT_FOUND if the name was not found in the table */ int32 OS_CountSemGetIdByName (uint32 *sem_id, const char *sem_name); @@ -774,16 +879,13 @@ int32 OS_CountSemGetIdByName (uint32 *sem_id, const char *sem_name); * @param[in] sem_id The object ID to operate on * @param[out] count_prop The property object buffer to fill * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the id passed in is not a valid semaphore - * OS_INVALID_POINTER if the count_prop pointer is null + * @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 semaphore + * @retval #OS_INVALID_POINTER if the count_prop pointer is null */ int32 OS_CountSemGetInfo (uint32 sem_id, OS_count_sem_prop_t *count_prop); -/* -** Mutex API -*/ - /*-------------------------------------------------------------------------------------*/ /** * @brief Creates a mutex semaphore @@ -794,12 +896,13 @@ int32 OS_CountSemGetInfo (uint32 sem_id, OS_count_sem_prop_t *count_prop * @param[in] sem_name the name of the new resource to create * @param[in] options reserved for future use. Should be passed as 0. * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if sem_id or sem_name are NULL - * OS_ERR_NAME_TOO_LONG if the sem_name is too long to be stored - * OS_ERR_NO_FREE_IDS if there are no more free mutex Ids - * OS_ERR_NAME_TAKEN if there is already a mutex with the same name - * OS_SEM_FAILURE if the OS call failed + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if sem_id or sem_name are NULL + * @retval #OS_ERR_NAME_TOO_LONG if the sem_name is too long to be stored + * @retval #OS_ERR_NO_FREE_IDS if there are no more free mutex Ids + * @retval #OS_ERR_NAME_TAKEN if there is already a mutex with the same name + * @retval #OS_SEM_FAILURE if the OS call failed */ int32 OS_MutSemCreate (uint32 *sem_id, const char *sem_name, uint32 options); @@ -814,9 +917,10 @@ int32 OS_MutSemCreate (uint32 *sem_id, const char *sem_name, uint32 op * * @param[in] sem_id The object ID to operate on * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the id passed in is not a valid mutex - * OS_SEM_FAILURE if an unspecified error occurs + * @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 mutex + * @retval #OS_SEM_FAILURE if an unspecified error occurs */ int32 OS_MutSemGive (uint32 sem_id); @@ -831,10 +935,11 @@ int32 OS_MutSemGive (uint32 sem_id); * * @param[in] sem_id The object ID to operate on * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_SEM_FAILURE if the semaphore was not previously initialized or is + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_SEM_FAILURE if the semaphore was not previously initialized or is * not in the array of semaphores defined by the system - * OS_ERR_INVALID_ID the id passed in is not a valid mutex + * @retval #OS_ERR_INVALID_ID the id passed in is not a valid mutex */ int32 OS_MutSemTake (uint32 sem_id); @@ -842,11 +947,15 @@ int32 OS_MutSemTake (uint32 sem_id); /** * @brief Deletes the specified Mutex Semaphore. * + * Delete the semaphore. This also frees the respective sem_id such that it can be + * used again when another is created. + * * @param[in] sem_id The object ID to delete * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the id passed in is not a valid mutex - * OS_SEM_FAILURE if the OS call failed + * @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 mutex + * @retval #OS_SEM_FAILURE if the OS call failed */ int32 OS_MutSemDelete (uint32 sem_id); @@ -854,16 +963,17 @@ int32 OS_MutSemDelete (uint32 sem_id); /** * @brief Find an existing mutex ID by name * - * This function tries to find a mutex sem Id given the name of a mut_sem + * This function tries to find a mutex sem Id given the name of a mut_sem. * The id is returned through sem_id * * @param[out] sem_id will be set to the ID of the existing resource * @param[in] sem_name the name of the existing resource to find * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER is semid or sem_name are NULL pointers - * OS_ERR_NAME_TOO_LONG if the name given is to long to have been stored - * OS_ERR_NAME_NOT_FOUND if the name was not found in the table + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER is semid or sem_name are NULL pointers + * @retval #OS_ERR_NAME_TOO_LONG if the name given is to long to have been stored + * @retval #OS_ERR_NAME_NOT_FOUND if the name was not found in the table */ int32 OS_MutSemGetIdByName (uint32 *sem_id, const char *sem_name); @@ -878,15 +988,17 @@ int32 OS_MutSemGetIdByName (uint32 *sem_id, const char *sem_name); * @param[in] sem_id The object ID to operate on * @param[out] mut_prop The property object buffer to fill * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the id passed in is not a valid semaphore - * OS_INVALID_POINTER if the mut_prop pointer is null + * @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 semaphore + * @retval #OS_INVALID_POINTER if the mut_prop pointer is null */ int32 OS_MutSemGetInfo (uint32 sem_id, OS_mut_sem_prop_t *mut_prop); +/**@}*/ -/* -** OS Time/Tick related API -*/ +/** @defgroup OSAPITime OSAL Time/Tick APIs + * @{ + */ /*-------------------------------------------------------------------------------------*/ /** @@ -899,7 +1011,7 @@ int32 OS_MutSemGetInfo (uint32 sem_id, OS_mut_sem_prop_t *mut_prop); * * @param[in] milli_seconds the number of milliseconds * - * @returns the number of ticks + * @return The number of ticks */ int32 OS_Milli2Ticks (uint32 milli_seconds); @@ -912,21 +1024,21 @@ int32 OS_Milli2Ticks (uint32 milli_seconds); * @note care is taken to ensure this does not return "0" since it is often used * as the divisor in mathematical operations * - * @returns duration of a system tick in microseconds + * @return Duration of a system tick in microseconds */ - int32 OS_Tick2Micros (void); - /*-------------------------------------------------------------------------------------*/ /** * @brief Get the local time * - * This function gets the local time of the machine its on + * This function gets the local time from the underlying OS. + * + * @note Mission time management typically uses the cFE Time Service * * @param[out] time_struct An OS_time_t that will be set to the current time * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Get local time status, see @ref OSReturnCodes */ int32 OS_GetLocalTime (OS_time_t *time_struct); @@ -935,47 +1047,72 @@ int32 OS_GetLocalTime (OS_time_t *time_struct); /** * @brief Set the local time * - * This function sets the local time of the machine its on + * This function sets the local time on the underlying OS. + * + * @note Mission time management typically uses the cFE Time Services * * @param[in] time_struct An OS_time_t containing the current time * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Set local time status, see @ref OSReturnCodes */ int32 OS_SetLocalTime (OS_time_t *time_struct); +/**@}*/ -/* -** Exception API -** NOTE: Not implemented in current OSAL version -*/ +/** + * @defgroup OSAPIExc OSAL Exception APIs + * + * @note Not implemented in current OSAL version + * + * @deprecated Planning move to PSP due to platform dependencies + * + * @{ + */ /*-------------------------------------------------------------------------------------*/ -/* placeholder; not currently implemented */ +/** + * @brief placeholder; not currently implemented + * @deprecated Planning move to PSP due to platform dependencies + */ int32 OS_ExcAttachHandler (uint32 ExceptionNumber, void (*ExceptionHandler)(uint32, const void *,uint32), int32 parameter); /*-------------------------------------------------------------------------------------*/ -/* placeholder; not currently implemented */ +/** + * @brief placeholder; not currently implemented + * @deprecated Planning move to PSP due to platform dependencies + */ int32 OS_ExcEnable (int32 ExceptionNumber); /*-------------------------------------------------------------------------------------*/ -/* placeholder; not currently implemented */ +/** @brief placeholder; not currently implemented + * @deprecated Planning move to PSP due to platform dependencies + */ int32 OS_ExcDisable (int32 ExceptionNumber); +/**@}*/ -/* -** Floating Point Unit API -*/ +/** @defgroup OSAPIFPUExc OSAL Floating Point Unit Exception APIs + * @deprecated Planning move to PSP due to platform dependencies + * @{ + */ /*-------------------------------------------------------------------------------------*/ /** * @brief Set an FPU exception handler function * + * The call associates a specified C routine to a specified FPU exception number. + * When the specified FPU Exception occurs , the ExceptionHandler routine will be + * called and passed the parameter. + * + * @deprecated Planning move to PSP due to platform dependencies + * * @param[in] ExceptionNumber The exception number to attach to * @param[in] ExceptionHandler Pointer to handler function * @param[in] parameter Argument to pass to handler * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_NOT_IMPLEMENTED on platforms that do not support this function + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED */ int32 OS_FPUExcAttachHandler (uint32 ExceptionNumber, osal_task_entry ExceptionHandler, int32 parameter); @@ -984,10 +1121,13 @@ int32 OS_FPUExcAttachHandler (uint32 ExceptionNumber, osal_task_entry Exceptio /** * @brief Enable FPU exceptions * + * @deprecated Planning move to PSP due to platform dependencies + * * @param[in] ExceptionNumber The exception number to enable * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_NOT_IMPLEMENTED on platforms that do not support this function + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED */ int32 OS_FPUExcEnable (int32 ExceptionNumber); @@ -995,10 +1135,13 @@ int32 OS_FPUExcEnable (int32 ExceptionNumber); /** * @brief Disable FPU exceptions * + * @deprecated Planning move to PSP due to platform dependencies + * * @param[in] ExceptionNumber The exception number to disable * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_NOT_IMPLEMENTED on platforms that do not support this function + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED */ int32 OS_FPUExcDisable (int32 ExceptionNumber); @@ -1006,13 +1149,16 @@ int32 OS_FPUExcDisable (int32 ExceptionNumber); /** * @brief Sets the FPU exception mask * + * @deprecated Planning move to PSP due to platform dependencies + * * This function sets the FPU exception mask * * @note The exception environment is local to each task Therefore this must be * called for each task that that wants to do floating point and catch exceptions. * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_NOT_IMPLEMENTED on platforms that do not support this function + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED */ int32 OS_FPUExcSetMask (uint32 mask); @@ -1020,19 +1166,23 @@ int32 OS_FPUExcSetMask (uint32 mask); /** * @brief Gets the FPU exception mask * + * @deprecated Planning move to PSP due to platform dependencies + * * This function gets the FPU exception mask * * @note The exception environment is local to each task Therefore this must be * called for each task that that wants to do floating point and catch exceptions. * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_NOT_IMPLEMENTED on platforms that do not support this function + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED */ int32 OS_FPUExcGetMask (uint32 *mask); +/**@}*/ -/* -** Interrupt API -*/ +/** @defgroup OSAPIInterrupt OSAL Interrupt APIs + * @{ + */ /*-------------------------------------------------------------------------------------*/ /** @@ -1046,9 +1196,10 @@ int32 OS_FPUExcGetMask (uint32 *mask); * @param[in] InterruptHandler The ISR associated with this interrupt * @param[in] parameter Argument that is passed to the ISR * - * @returns OS_SUCCESS on success or appropriate error code - * OS_INVALID_POINTER if the Interrupt handler pointer is NULL - * OS_ERR_NOT_IMPLEMENTED on platforms that do not support this function + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER The Interrupt handler pointer is NULL + * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED */ int32 OS_IntAttachHandler (uint32 InterruptNumber, osal_task_entry InterruptHandler, int32 parameter); @@ -1058,8 +1209,9 @@ int32 OS_IntAttachHandler (uint32 InterruptNumber, osal_task_entry InterruptHan * * @param[in] IntLevel value from previous call to OS_IntLock() * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_NOT_IMPLEMENTED on platforms that do not support this function + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED */ int32 OS_IntUnlock (int32 IntLevel); @@ -1067,8 +1219,10 @@ int32 OS_IntUnlock (int32 IntLevel); /** * @brief Disable interrupts * - * @returns An key value to be passed to OS_IntUnlock() to restore interrupts - * OS_ERR_NOT_IMPLEMENTED on platforms that do not support this function + * @return An key value to be passed to OS_IntUnlock() to restore interrupts or error + * status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED */ int32 OS_IntLock (void); @@ -1078,8 +1232,9 @@ int32 OS_IntLock (void); * * @param[in] Level the interrupts to enable * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_NOT_IMPLEMENTED on platforms that do not support this function + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED */ int32 OS_IntEnable (int32 Level); @@ -1089,8 +1244,9 @@ int32 OS_IntEnable (int32 Level); * * @param[in] Level the interrupts to disable * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_NOT_IMPLEMENTED on platforms that do not support this function + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED */ int32 OS_IntDisable (int32 Level); @@ -1102,8 +1258,9 @@ int32 OS_IntDisable (int32 Level); * * @param[in] mask The value to set in the register * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_NOT_IMPLEMENTED on platforms that do not support this function + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED */ int32 OS_IntSetMask (uint32 mask); @@ -1115,47 +1272,75 @@ int32 OS_IntSetMask (uint32 mask); * * @param[out] mask The register value will be stored to this location * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_NOT_IMPLEMENTED on platforms that do not support this function + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED */ int32 OS_IntGetMask (uint32 *mask); /*-------------------------------------------------------------------------------------*/ -/* placeholder; not currently implemented */ +/** + * @brief Acknowledge the corresponding interrupt number. + * + * @note: placeholder; not currently implemented in sample implementations + * + * @param[in] InterruptNumber The interrupt number to be acknowledged. + * + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_INT_NUM @copybrief OS_INVALID_INT_NUM + * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED + */ int32 OS_IntAck (int32 InterruptNumber); +/**@}*/ -/* -** Shared memory API -** NOTE: Not implemented in current OSAL version -*/ +/** + * @defgroup OSAPIShMem OSAL Shared memory APIs + * @deprecated Not in current implementations + * + * @{ + */ /*-------------------------------------------------------------------------------------*/ -/* placeholder; not currently implemented */ +/** @brief placeholder; not currently implemented + * @deprecated Never implemented + */ int32 OS_ShMemInit (void); /*-------------------------------------------------------------------------------------*/ -/* placeholder; not currently implemented */ +/** @brief placeholder; not currently implemented + * @deprecated Never implemented + */ int32 OS_ShMemCreate (uint32 *Id, uint32 NBytes, const char* SegName); /*-------------------------------------------------------------------------------------*/ -/* placeholder; not currently implemented */ +/** @brief placeholder; not currently implemented + * @deprecated Never implemented + */ int32 OS_ShMemSemTake (uint32 Id); /*-------------------------------------------------------------------------------------*/ -/* placeholder; not currently implemented */ +/** @brief placeholder; not currently implemented + * @deprecated Never implemented + */ int32 OS_ShMemSemGive (uint32 Id); /*-------------------------------------------------------------------------------------*/ -/* placeholder; not currently implemented */ +/** @brief placeholder; not currently implemented + * @deprecated Never implemented + */ int32 OS_ShMemAttach (cpuaddr * Address, uint32 Id); /*-------------------------------------------------------------------------------------*/ -/* placeholder; not currently implemented */ +/** @brief placeholder; not currently implemented + * @deprecated Never implemented + */ int32 OS_ShMemGetIdByName (uint32 *ShMemId, const char *SegName ); +/**@}*/ -/* -** Heap API -*/ +/** @defgroup OSAPIHeap OSAL Heap APIs + * @{ + */ /*-------------------------------------------------------------------------------------*/ /** @@ -1163,13 +1348,14 @@ int32 OS_ShMemGetIdByName (uint32 *ShMemId, const char *SegName ); * * @param[out] heap_prop Storage buffer for heap info * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_HeapGetInfo (OS_heap_prop_t *heap_prop); +/**@}*/ -/* -** API for useful debugging function -*/ +/** @defgroup OSAPIError OSAL Error Info APIs + * @{ + */ /*-------------------------------------------------------------------------------------*/ /** @@ -1178,22 +1364,14 @@ int32 OS_HeapGetInfo (OS_heap_prop_t *heap_prop); * @param[in] error_num Error number to convert * @param[out] err_name Buffer to store error string * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_GetErrorName (int32 error_num, os_err_name_t* err_name); +/**@}*/ -/** - * @brief An abstract structure capable of holding several OSAL IDs - * - * This is part of the select API and is manipulated using the - * related API calls. It should not be modified directly by applications. - * - * @sa OS_SelectFdZero(), OS_SelectFdAdd(), OS_SelectFdClear(), OS_SelectFdIsSet() +/** @defgroup OSAPISelect OSAL Select APIs + * @{ */ -typedef struct -{ - uint8 object_ids[(OS_MAX_NUM_OPEN_FILES + 7) / 8]; -} OS_FdSet; /*-------------------------------------------------------------------------------------*/ /** @@ -1219,7 +1397,7 @@ typedef struct * the results are undefined. Because of this limitation, it is recommended * to use OS_SelectSingle() whenever possible. * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_SelectMultiple(OS_FdSet *ReadSet, OS_FdSet *WriteSet, int32 msecs); @@ -1244,7 +1422,7 @@ int32 OS_SelectMultiple(OS_FdSet *ReadSet, OS_FdSet *WriteSet, int32 msecs); * To mitigate this risk the application may prefer to use * the OS_TimedRead/OS_TimedWrite calls. * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_SelectSingle(uint32 objid, uint32 *StateFlags, int32 msecs); @@ -1254,7 +1432,7 @@ int32 OS_SelectSingle(uint32 objid, uint32 *StateFlags, int32 msecs); * * After this call the set will contain no OSAL IDs * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_SelectFdZero(OS_FdSet *Set); @@ -1264,7 +1442,7 @@ int32 OS_SelectFdZero(OS_FdSet *Set); * * After this call the set will contain the given OSAL ID * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_SelectFdAdd(OS_FdSet *Set, uint32 objid); @@ -1274,19 +1452,25 @@ int32 OS_SelectFdAdd(OS_FdSet *Set, uint32 objid); * * After this call the set will no longer contain the given OSAL ID * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_SelectFdClear(OS_FdSet *Set, uint32 objid); /*-------------------------------------------------------------------------------------*/ /** * @brief Check if an FdSet structure contains a given ID + * + * @return Boolean set status + * @retval true FdSet structure contains ID + * @retval false FDSet structure does not contain ID */ bool OS_SelectFdIsSet(OS_FdSet *Set, uint32 objid); +/**@}*/ + +/** @defgroup OSAPIPrintf OSAL Printf APIs + * @{ + */ -/* -** Abstraction for printf statements -*/ /*-------------------------------------------------------------------------------------*/ /** * @brief Abstraction for the system printf() call @@ -1296,7 +1480,8 @@ bool OS_SelectFdIsSet(OS_FdSet *Set, uint32 objid); * print statements for the real time systems. * * Operates in a manner similar to the printf() call defined by the standard C - * library. This abstraction may implement additional buffering, if necessary, + * library and takes all the parameters and formatting options of printf. + * This abstraction may implement additional buffering, if necessary, * to improve the real-time performance of the call. * * The output of this routine also may be dynamically enabled or disabled by @@ -1308,29 +1493,16 @@ void OS_printf( const char *string, ...) OS_PRINTF(1,2); /*-------------------------------------------------------------------------------------*/ /** - * @brief This function disables the output to the console from OS_printf. + * @brief This function disables the output from OS_printf. */ void OS_printf_disable(void); /*-------------------------------------------------------------------------------------*/ /** - * @brief This function enables the output to the console through OS_printf. + * @brief This function enables the output from OS_printf. * */ void OS_printf_enable(void); - -/*-------------------------------------------------------------------------------------*/ -/** - * @brief Exit/Abort the application - * - * Indicates that the OSAL application should exit and return control to the OS - * This is intended for e.g. scripted unit testing where the test needs to end - * without user intervention. - * - * This function does not return. Production code typically should not ever call this. - * - * @note This exits the entire process including tasks that have been created. - */ -void OS_ApplicationExit(int32 Status); +/**@}*/ #endif diff --git a/src/os/inc/osapi-os-filesys.h b/src/os/inc/osapi-os-filesys.h index 1d2a6e2c9..06a6a5e3e 100644 --- a/src/os/inc/osapi-os-filesys.h +++ b/src/os/inc/osapi-os-filesys.h @@ -19,36 +19,49 @@ #ifndef _osapi_filesys_ #define _osapi_filesys_ -#define OS_READ_ONLY 0 -#define OS_WRITE_ONLY 1 -#define OS_READ_WRITE 2 - -#define OS_SEEK_SET 0 -#define OS_SEEK_CUR 1 -#define OS_SEEK_END 2 +/** @defgroup OSFileAccess OSAL File Access Option Defines + * @{ + */ +#define OS_READ_ONLY 0 /**< Read only file access */ +#define OS_WRITE_ONLY 1 /**< Write only file access */ +#define OS_READ_WRITE 2 /**< Read write file access */ +/**@}*/ -#define OS_CHK_ONLY 0 -#define OS_REPAIR 1 +/** @defgroup OSFileOffset OSAL Refernce Point For Seek Offset Defines + * @{ + */ +#define OS_SEEK_SET 0 /**< Seek offset set */ +#define OS_SEEK_CUR 1 /**< Seek offset current */ +#define OS_SEEK_END 2 /**< Seek offset end */ +/**@}*/ -#define FS_BASED 0 -#define RAM_DISK 1 -#define EEPROM_DISK 2 -#define ATA_DISK 3 +#define OS_CHK_ONLY 0 /**< Unused, API takes bool */ +#define OS_REPAIR 1 /**< Unused, API takes bool */ +/** @defgroup OSVolType OSAL Volume Type Defines + * @{ + */ +#define FS_BASED 0 /**< Volume type FS based */ +#define RAM_DISK 1 /**< Volume type RAM disk */ +#define EEPROM_DISK 2 /**< Volume type EEPROM disk */ +#define ATA_DISK 3 /**< Volume type ATA disk */ +/**@}*/ -/* -** Number of entries in the internal volume table -*/ +/** + * @brief Number of entries in the internal volume table + */ #define NUM_TABLE_ENTRIES 14 /* ** Length of a Device and Volume name */ -#define OS_FS_DEV_NAME_LEN 32 -#define OS_FS_PHYS_NAME_LEN 64 -#define OS_FS_VOL_NAME_LEN 32 - +#define OS_FS_DEV_NAME_LEN 32 /**< Device name length */ +#define OS_FS_PHYS_NAME_LEN 64 /**< Physical drive name length */ +#define OS_FS_VOL_NAME_LEN 32 /**< Volume name length */ +/** @addtogroup OSReturnCodes + * @{ + */ /* ** Defines for File System Calls */ @@ -57,26 +70,27 @@ * other OSAPI error codes. They now start at -100 * to avoid this overlap. */ -#define OS_FS_ERR_PATH_TOO_LONG (-103) -#define OS_FS_ERR_NAME_TOO_LONG (-104) -#define OS_FS_ERR_DRIVE_NOT_CREATED (-106) -#define OS_FS_ERR_DEVICE_NOT_FREE (-107) -#define OS_FS_ERR_PATH_INVALID (-108) +#define OS_FS_ERR_PATH_TOO_LONG (-103) /**< @brief FS path too long */ +#define OS_FS_ERR_NAME_TOO_LONG (-104) /**< @brief FS name too long */ +#define OS_FS_ERR_DRIVE_NOT_CREATED (-106) /**< @brief FS drive not created */ +#define OS_FS_ERR_DEVICE_NOT_FREE (-107) /**< @brief FS device not free */ +#define OS_FS_ERR_PATH_INVALID (-108) /**< @brief FS path invalid */ /* * Map some codes used by the file API back to the generic counterparts * where there is overlap between them. Do not duplicate error codes. */ -#define OS_FS_SUCCESS OS_SUCCESS -#define OS_FS_ERROR OS_ERROR -#define OS_FS_ERR_INVALID_POINTER OS_INVALID_POINTER -#define OS_FS_ERR_NO_FREE_FDS OS_ERR_NO_FREE_IDS -#define OS_FS_ERR_INVALID_FD OS_ERR_INVALID_ID -#define OS_FS_UNIMPLEMENTED OS_ERR_NOT_IMPLEMENTED +#define OS_FS_SUCCESS OS_SUCCESS /**< @brief Successful execution */ +#define OS_FS_ERROR OS_ERROR /**< @brief Failed execution */ +#define OS_FS_ERR_INVALID_POINTER OS_INVALID_POINTER /**< @brief Invalid pointer */ +#define OS_FS_ERR_NO_FREE_FDS OS_ERR_NO_FREE_IDS /**< @brief No free IDs */ +#define OS_FS_ERR_INVALID_FD OS_ERR_INVALID_ID /**< @brief Invalid ID */ +#define OS_FS_UNIMPLEMENTED OS_ERR_NOT_IMPLEMENTED /**< @brief Not implemented */ +/**@}*/ -/* This typedef is for the OS_FS_GetErrorName function, to ensure +/* This typedef is for OS_FS_GetErrorName(), to ensure * everyone is making an array of the same length * * Implementation note for developers: @@ -91,10 +105,10 @@ typedef os_err_name_t os_fs_err_name_t; -/* -** Internal structure of the OS volume table for -** mounted file systems and path translation -*/ +/** + * @brief Internal structure of the OS volume table for + * mounted file systems and path translation + */ typedef struct { char DeviceName [OS_FS_DEV_NAME_LEN]; @@ -109,15 +123,16 @@ typedef struct } OS_VolumeInfo_t; +/** @brief OSAL file system info */ typedef struct { - uint32 MaxFds; /* Total number of file descriptors */ - uint32 FreeFds; /* Total number that are free */ - uint32 MaxVolumes; /* Maximum number of volumes */ - uint32 FreeVolumes; /* Total number of volumes free */ + uint32 MaxFds; /**< @brief Total number of file descriptors */ + uint32 FreeFds; /**< @brief Total number that are free */ + uint32 MaxVolumes; /**< @brief Maximum number of volumes */ + uint32 FreeVolumes; /**< @brief Total number of volumes free */ } os_fsinfo_t; - +/** @brief OSAL file properties */ typedef struct { char Path[OS_MAX_PATH_LEN]; @@ -125,14 +140,14 @@ typedef struct uint8 IsValid; /* For backward compatibility -- always true if OS_FDGetInfo returned true */ }OS_file_prop_t; - -/* - * NOTE: This used to be directly typedef'ed to the "struct stat" from the C library +/** + * @brief File system status + * + * @note This used to be directly typedef'ed to the "struct stat" from the C library * - * Some C libraries (glibc in particular) actually #define member names to reference into + * Some C libraries (glibc in particular) actually define member names to reference into * sub-structures, so attempting to reuse a name like "st_mtime" might not work. */ - typedef struct { uint32 FileModeBits; @@ -140,7 +155,10 @@ typedef struct uint32 FileSize; } os_fstat_t; -/* We must also define replacements for the stat structure's mode bits. +/** + * @brief File stat mode bits + * + * We must also define replacements for the stat structure's mode bits. * This is currently just a small subset since the OSAL just presents a very * simplified view of the filesystem to the upper layers. And since not all * OS'es are POSIX, the more POSIX-specific bits are not relevant anyway. @@ -153,50 +171,54 @@ enum OS_FILESTAT_MODE_DIR = 0x10000 }; +/** @brief Access file stat mode bits */ #define OS_FILESTAT_MODE(x) ((x).FileModeBits) +/** @brief File stat is directory logical */ #define OS_FILESTAT_ISDIR(x) ((x).FileModeBits & OS_FILESTAT_MODE_DIR) +/** @brief File stat is executable logical */ #define OS_FILESTAT_EXEC(x) ((x).FileModeBits & OS_FILESTAT_MODE_EXEC) +/** @brief File stat is write enabled logical */ #define OS_FILESTAT_WRITE(x) ((x).FileModeBits & OS_FILESTAT_MODE_WRITE) +/** @brief File stat is read enabled logical */ #define OS_FILESTAT_READ(x) ((x).FileModeBits & OS_FILESTAT_MODE_READ) +/** @brief Access file stat size field */ #define OS_FILESTAT_SIZE(x) ((x).FileSize) +/** @brief Access file stat time field */ #define OS_FILESTAT_TIME(x) ((x).FileTime) - +/** @brief Directory entry */ typedef struct { char FileName[OS_MAX_PATH_LEN]; } os_dirent_t; +#ifndef OSAL_OMIT_DEPRECATED /* * Preserve the old type names for compatibility; * but instead of DIR* it is now just a void* */ -#ifndef OSAL_OMIT_DEPRECATED /* Provide something to implement os_dirp_t */ -typedef void * os_dirp_t; +typedef void * os_dirp_t; /**< @deprecated */ #endif -/* - * Macro to access filename part of the dirent structure - */ +/** @brief Access filename part of the dirent structure */ #define OS_DIRENTRY_NAME(x) ((x).FileName) +#ifndef OSAL_OMIT_DEPRECATED /* * Several old type names can be aliases for compatibility */ -#ifndef OSAL_OMIT_DEPRECATED -typedef int32 os_fshealth_t; -typedef OS_file_prop_t OS_FDTableEntry; +typedef int32 os_fshealth_t; /**< @deprecated type no longer used */ +typedef OS_file_prop_t OS_FDTableEntry; /**< @deprecated Use OS_file_prop_t */ #endif /* * Exported Functions */ - -/****************************************************************************** -** Standard File system API -******************************************************************************/ +/** @defgroup OSAPIFile OSAL Standard File APIs + * @{ + */ /*-------------------------------------------------------------------------------------*/ /** @@ -207,18 +229,18 @@ typedef OS_file_prop_t OS_FDTableEntry; * create call. * * @param[in] path File name to create - * @param[in] access Intended access mode - OS_WRITE_ONLY or OS_READ_WRITE + * @param[in] access Intended access mode - see @ref OSFileAccess * * @note Valid handle IDs are never negative. Failure of this * call can be checked by testing if the result is less than 0. * - * @returns A file handle ID on success, or appropriate error code - * OS_INVALID_POINTER if path is NULL - * OS_FS_ERR_PATH_TOO_LONG if path exceeds the maximum number of chars - * OS_FS_ERR_PATH_INVALID if path cannot be parsed - * OS_FS_ERR_NAME_TOO_LONG if the name of the file is too long - * OS_ERROR if permissions are unknown or OS call fails - * OS_ERR_NO_FREE_IDS if there are no free file descriptors left + * @return A file handle ID or appropriate error code, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if path is NULL + * @retval #OS_FS_ERR_PATH_TOO_LONG if path exceeds the maximum number of chars + * @retval #OS_FS_ERR_PATH_INVALID if path cannot be parsed + * @retval #OS_FS_ERR_NAME_TOO_LONG if the name of the file is too long + * @retval #OS_ERROR if permissions are unknown or OS call fails + * @retval #OS_ERR_NO_FREE_IDS if there are no free file descriptors left */ int32 OS_creat (const char *path, int32 access); @@ -227,26 +249,24 @@ int32 OS_creat (const char *path, int32 access); /** * @brief Opens a file * - * Opens a file. access parameters are OS_READ_ONLY, OS_WRITE_ONLY, or - * OS_READ_WRITE + * Opens a file. * * @param[in] path File name to create - * @param[in] access Intended access mode - OS_READ_ONLY, OS_WRITE_ONLY or OS_READ_WRITE + * @param[in] access Intended access mode - see @ref OSFileAccess * @param[in] mode The file permissions. This parameter is passed through to the * native open call, but will be ignored. The file mode (or permissions) * are ignored by the POSIX open call when the O_CREAT access flag is not passed in. * - * * @note Valid handle IDs are never negative. Failure of this * call can be checked by testing if the result is less than 0. * - * @returns A file handle ID on success, or appropriate error code - * OS_INVALID_POINTER if path is NULL - * OS_FS_ERR_PATH_TOO_LONG if path exceeds the maximum number of chars - * OS_FS_ERR_PATH_INVALID if path cannot be parsed - * OS_FS_ERR_NAME_TOO_LONG if the name of the file is too long - * OS_ERROR if permissions are unknown or OS call fails - * OS_ERR_NO_FREE_IDS if there are no free file descriptors left + * @return A file handle ID or appropriate error code, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if path is NULL + * @retval #OS_FS_ERR_PATH_TOO_LONG if path exceeds the maximum number of chars + * @retval #OS_FS_ERR_PATH_INVALID if path cannot be parsed + * @retval #OS_FS_ERR_NAME_TOO_LONG if the name of the file is too long + * @retval #OS_ERROR if permissions are unknown or OS call fails + * @retval #OS_ERR_NO_FREE_IDS if there are no free file descriptors left */ int32 OS_open (const char *path, int32 access, uint32 mode); @@ -260,9 +280,10 @@ int32 OS_open (const char *path, int32 access, uint32 mode); * * @param[in] filedes The handle ID to operate on * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERROR if file descriptor could not be closed - * OS_ERR_INVALID_ID if the file descriptor passed in is invalid + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERROR if file descriptor could not be closed + * @retval #OS_ERR_INVALID_ID if the file descriptor passed in is invalid */ int32 OS_close (uint32 filedes); @@ -271,7 +292,7 @@ int32 OS_close (uint32 filedes); /** * @brief Read from a file handle * - * reads up to nbytes from a file, and puts them into buffer. + * Reads up to nbytes from a file, and puts them into buffer. * * @param[in] filedes The handle ID to operate on * @param[out] buffer Storage location for file data @@ -280,10 +301,10 @@ int32 OS_close (uint32 filedes); * @note All OSAL error codes are negative int32 values. Failure of this * call can be checked by testing if the result is less than 0. * - * @returns A non-negative byte count on success, or appropriate error code - * OS_INVALID_POINTER if buffer is a null pointer - * OS_ERROR if OS call failed - * OS_ERR_INVALID_ID if the file descriptor passed in is invalid + * @return A non-negative byte count or appropriate error code, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if buffer is a null pointer + * @retval #OS_ERROR if OS call failed + * @retval #OS_ERR_INVALID_ID if the file descriptor passed in is invalid */ int32 OS_read (uint32 filedes, void *buffer, uint32 nbytes); @@ -292,7 +313,7 @@ int32 OS_read (uint32 filedes, void *buffer, uint32 nbytes); /** * @brief Write to a file handle * - * writes to a file. copies up to a maximum of nbytes of buffer to the file + * Writes to a file. copies up to a maximum of nbytes of buffer to the file * described in filedes * * @param[in] filedes The handle ID to operate on @@ -302,10 +323,10 @@ int32 OS_read (uint32 filedes, void *buffer, uint32 nbytes); * @note All OSAL error codes are negative int32 values. Failure of this * call can be checked by testing if the result is less than 0. * - * @returns A non-negative byte count on success, or appropriate error code - * OS_INVALID_POINTER if buffer is NULL - * OS_ERROR if OS call failed - * OS_ERR_INVALID_ID if the file descriptor passed in is invalid + * @return A non-negative byte count or appropriate error code, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if buffer is NULL + * @retval #OS_ERROR if OS call failed + * @retval #OS_ERR_INVALID_ID if the file descriptor passed in is invalid */ int32 OS_write (uint32 filedes, const void *buffer, uint32 nbytes); @@ -335,8 +356,8 @@ int32 OS_write (uint32 filedes, const void *buffer, uint32 nbytes); * @param[in] nbytes Maximum number of bytes to read * @param[in] timeout Maximum time to wait, in milliseconds (OS_PEND = forever) * - * @returns A non-negative byte count on success, or appropriate error code - * Returns zero if the timeout period expired. + * @return Byte count on success, zero for timeout, or appropriate error code, + * see @ref OSReturnCodes */ int32 OS_TimedRead(uint32 filedes, void *buffer, uint32 nbytes, int32 timeout); @@ -367,8 +388,8 @@ int32 OS_TimedRead(uint32 filedes, void *buffer, uint32 nbytes, int32 * @param[in] nbytes Maximum number of bytes to read * @param[in] timeout Maximum time to wait, in milliseconds (OS_PEND = forever) * - * @returns A non-negative byte count on success, or appropriate error code - * Returns zero if the timeout period expired. + * @return Byte count on success, zero for timeout, or appropriate error code, + * see @ref OSReturnCodes */ int32 OS_TimedWrite(uint32 filedes, const void *buffer, uint32 nbytes, int32 timeout); @@ -378,11 +399,11 @@ int32 OS_TimedWrite(uint32 filedes, const void *buffer, uint32 nbytes * @brief Changes the permissions of a file * * @param[in] path File to change - * @param[in] access Desired access mode - OS_READ_ONLY, OS_WRITE_ONLY or OS_READ_WRITE + * @param[in] access Desired access mode - see @ref OSFileAccess * * @note Some file systems do not implement permissions * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_chmod (const char *path, uint32 access); @@ -391,17 +412,18 @@ int32 OS_chmod (const char *path, uint32 access); /** * @brief Obtain information about a file or directory * - * returns information about a file or directory in a os_fs_stat structure + * Returns information about a file or directory in a os_fstat_t structure * * @param[in] path The file to operate on * @param[out] filestats Buffer to store file information * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if path or filestats is NULL - * OS_FS_ERR_PATH_TOO_LONG if the path is too long to be stored locally - * OS_FS_ERR_NAME_TOO_LONG if the name of the file is too long to be stored - * OS_FS_ERR_PATH_INVALID if path cannot be parsed - * OS_ERROR if the OS call failed + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if path or filestats is NULL + * @retval #OS_FS_ERR_PATH_TOO_LONG if the path is too long to be stored locally + * @retval #OS_FS_ERR_NAME_TOO_LONG if the name of the file is too long to be stored + * @retval #OS_FS_ERR_PATH_INVALID if path cannot be parsed + * @retval #OS_ERROR if the OS call failed */ int32 OS_stat (const char *path, os_fstat_t *filestats); @@ -410,16 +432,16 @@ int32 OS_stat (const char *path, os_fstat_t *filestats); /** * @brief Seeks to the specified position of an open file * - * sets the read/write pointer to a specific offset in a specific file. - * Whence is either OS_SEEK_SET,OS_SEEK_CUR, or OS_SEEK_END + * Sets the read/write pointer to a specific offset in a specific file. * * @param[in] filedes The handle ID to operate on * @param[in] offset The file offset to seek to - * @param[in] whence The reference point for offset + * @param[in] whence The reference point for offset, see @ref OSFileOffset * - * @returns On success, a non-negative byte offset from the beginning of the file - * OS_ERR_INVALID_ID if the file descriptor passed in is invalid - * OS_ERROR if OS call failed + * @return Byte offset from the beginning of the file or appropriate error code, + see @ref OSReturnCodes + * @retval #OS_ERR_INVALID_ID if the file descriptor passed in is invalid + * @retval #OS_ERROR if OS call failed */ int32 OS_lseek (uint32 filedes, int32 offset, uint32 whence); @@ -436,12 +458,13 @@ int32 OS_lseek (uint32 filedes, int32 offset, uint32 whence); * * @param[in] path The file to operate on * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERROR if there is no device or the driver returns error - * OS_INVALID_POINTER if path is NULL - * OS_FS_ERR_PATH_TOO_LONG if path is too long to be stored locally - * OS_FS_ERR_PATH_INVALID if path cannot be parsed - * OS_FS_ERR_NAME_TOO_LONG if the name of the file to remove is too long + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERROR if there is no device or the driver returns error + * @retval #OS_INVALID_POINTER if path is NULL + * @retval #OS_FS_ERR_PATH_TOO_LONG if path is too long to be stored locally + * @retval #OS_FS_ERR_PATH_INVALID if path cannot be parsed + * @retval #OS_FS_ERR_NAME_TOO_LONG if the name of the file to remove is too long */ int32 OS_remove (const char *path); @@ -460,12 +483,13 @@ int32 OS_remove (const char *path); * @param[in] old_filename The original filename * @param[in] new_filename The desired filename * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERROR if the file could not be opened or renamed. - * OS_INVALID_POINTER if old or new are NULL - * OS_FS_ERR_PATH_INVALID if path cannot be parsed - * OS_FS_ERR_PATH_TOO_LONG if the paths given are too long to be stored locally - * OS_FS_ERR_NAME_TOO_LONG if the new name is too long to be stored locally + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERROR if the file could not be opened or renamed. + * @retval #OS_INVALID_POINTER if old or new are NULL + * @retval #OS_FS_ERR_PATH_INVALID if path cannot be parsed + * @retval #OS_FS_ERR_PATH_TOO_LONG if the paths given are too long to be stored locally + * @retval #OS_FS_ERR_NAME_TOO_LONG if the new name is too long to be stored locally */ int32 OS_rename (const char *old_filename, const char *new_filename); @@ -477,12 +501,13 @@ int32 OS_rename (const char *old_filename, const char *new_filename); * @param[in] src The source file to operate on * @param[in] dest The destination file * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERROR if the file could not be accessed - * OS_INVALID_POINTER if src or dest are NULL - * OS_FS_ERR_PATH_INVALID if path cannot be parsed - * OS_FS_ERR_PATH_TOO_LONG if the paths given are too long to be stored locally - * OS_FS_ERR_NAME_TOO_LONG if the dest name is too long to be stored locally + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERROR if the file could not be accessed + * @retval #OS_INVALID_POINTER if src or dest are NULL + * @retval #OS_FS_ERR_PATH_INVALID if path cannot be parsed + * @retval #OS_FS_ERR_PATH_TOO_LONG if the paths given are too long to be stored locally + * @retval #OS_FS_ERR_NAME_TOO_LONG if the dest name is too long to be stored locally */ int32 OS_cp (const char *src, const char *dest); @@ -500,12 +525,13 @@ int32 OS_cp (const char *src, const char *dest); * @param[in] src The source file to operate on * @param[in] dest The destination file * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERROR if the file could not be renamed. - * OS_INVALID_POINTER if src or dest are NULL - * OS_FS_ERR_PATH_INVALID if path cannot be parsed - * OS_FS_ERR_PATH_TOO_LONG if the paths given are too long to be stored locally - * OS_FS_ERR_NAME_TOO_LONG if the dest name is too long to be stored locally + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERROR if the file could not be renamed. + * @retval #OS_INVALID_POINTER if src or dest are NULL + * @retval #OS_FS_ERR_PATH_INVALID if path cannot be parsed + * @retval #OS_FS_ERR_PATH_TOO_LONG if the paths given are too long to be stored locally + * @retval #OS_FS_ERR_NAME_TOO_LONG if the dest name is too long to be stored locally */ int32 OS_mv (const char *src, const char *dest); @@ -519,9 +545,9 @@ int32 OS_mv (const char *src, const char *dest); * @param[in] filedes The handle ID to operate on * @param[out] fd_prop Storage buffer for file information * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the file descriptor passed in is invalid - * OS_FS_SUCCESS if the copying was successfull + * @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 */ int32 OS_FDGetInfo (uint32 filedes, OS_file_prop_t *fd_prop); @@ -529,10 +555,13 @@ int32 OS_FDGetInfo (uint32 filedes, OS_file_prop_t *fd_prop); /** * @brief Checks to see if a file is open * + * This function takes a filename and determines if the file is open. The function + * will return success if the file is open. + * * @param[in] Filename The file to operate on * - * @returns OS_SUCCESS if the file is open, or appropriate error code - * OS_ERROR if the file is not open + * @return OS_SUCCESS if the file is open, or appropriate error code + * @retval #OS_ERROR if the file is not open */ int32 OS_FileOpenCheck(const char *Filename); @@ -543,8 +572,9 @@ int32 OS_FileOpenCheck(const char *Filename); * * Closes All open files that were opened through the OSAL * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERROR if one or more file close returned an error + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERROR if one or more file close returned an error */ int32 OS_CloseAllFiles(void); @@ -559,46 +589,45 @@ int32 OS_CloseAllFiles(void); * * @param[in] Filename The file to close * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_FS_ERR_PATH_INVALID if the file is not found - * OS_ERROR if the file close returned an error + * @return Execution status, see @ref OSReturnCodes + * @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 */ int32 OS_CloseFileByName(const char *Filename); +/**@}*/ - -/****************************************************************************** -** Directory API -******************************************************************************/ +/** @defgroup OSAPIDir OSAL Directory APIs + * @{ + */ #ifndef OSAL_OMIT_DEPRECATED -/* - * Opens a directory for searching - * Replaced by OS_DirectoryOpen() +/** + * @brief Opens a directory for searching + * @deprecated Replaced by OS_DirectoryOpen() */ os_dirp_t OS_opendir (const char *path); /* - * Closes an open directory - * Replaced by OS_DirectoryClose() + * @brief Closes an open directory + * @deprecated Replaced by OS_DirectoryClose() */ int32 OS_closedir(os_dirp_t directory); /* - * Rewinds an open directory - * Replaced by OS_DirectoryRewind() + * @brief Rewinds an open directory + * @deprecated Replaced by OS_DirectoryRewind() */ void OS_rewinddir(os_dirp_t directory); /* - * Reads the next object in the directory - * Replaced by OS_DirectoryRead() + * @brief Reads the next object in the directory + * @deprecated Replaced by OS_DirectoryRead() */ os_dirent_t * OS_readdir (os_dirp_t directory); #endif - - /*-------------------------------------------------------------------------------------*/ /** * @brief Opens a directory @@ -608,7 +637,7 @@ os_dirent_t * OS_readdir (os_dirp_t directory); * @param[out] dir_id The handle ID of the directory * @param[in] path The directory to open * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_DirectoryOpen(uint32 *dir_id, const char *path); @@ -621,7 +650,7 @@ int32 OS_DirectoryOpen(uint32 *dir_id, const char *path); * * @param[in] dir_id The handle ID of the directory * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_DirectoryClose(uint32 dir_id); @@ -634,7 +663,7 @@ int32 OS_DirectoryClose(uint32 dir_id); * * @param[in] dir_id The handle ID of the directory * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_DirectoryRewind(uint32 dir_id); @@ -648,7 +677,7 @@ int32 OS_DirectoryRewind(uint32 dir_id); * @param[in] dir_id The handle ID of the directory * @param[out] dirent Buffer to store directory entry information * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_DirectoryRead(uint32 dir_id, os_dirent_t *dirent); @@ -657,20 +686,21 @@ int32 OS_DirectoryRead(uint32 dir_id, os_dirent_t *dirent); /** * @brief Makes a new directory * - * makes a directory specified by path. + * Makes a directory specified by path. * * @param[in] path The new directory name * @param[in] access The permissions for the directory (reserved for future use) * - * @note current implementations do not utilize the "access" parameter. Applications - * should still pass the intended value (OS_READ_WRITE or OS_READ_ONLY) to be compatible + * @note Current implementations do not utilize the "access" parameter. Applications + * should still pass the intended value (#OS_READ_WRITE or #OS_READ_ONLY) to be compatible * with future implementations. * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if path is NULL - * OS_FS_ERR_PATH_TOO_LONG if the path is too long to be stored locally - * OS_FS_ERR_PATH_INVALID if path cannot be parsed - * OS_ERROR if the OS call fails + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if path is NULL + * @retval #OS_FS_ERR_PATH_TOO_LONG if the path is too long to be stored locally + * @retval #OS_FS_ERR_PATH_INVALID if path cannot be parsed + * @retval #OS_ERROR if the OS call fails */ int32 OS_mkdir (const char *path, uint32 access); @@ -684,17 +714,19 @@ int32 OS_mkdir (const char *path, uint32 access); * * @param[in] path The directory to remove * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if path is NULL - * OS_FS_ERR_PATH_INVALID if path cannot be parsed - * OS_FS_ER_PATH_TOO_LONG - * OS_ERROR if the directory remove operation failed + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if path is NULL + * @retval #OS_FS_ERR_PATH_INVALID if path cannot be parsed + * @retval #OS_FS_ERR_PATH_TOO_LONG + * @retval #OS_ERROR if the directory remove operation failed */ int32 OS_rmdir (const char *path); +/**@}*/ -/****************************************************************************** -** System Level API -******************************************************************************/ +/** @defgroup OSAPIFileSys OSAL File System Level APIs + * @{ + */ /*-------------------------------------------------------------------------------------*/ /** @@ -707,7 +739,7 @@ int32 OS_rmdir (const char *path); * @param[in] phys_path The native system directory (an existing mount point) * @param[in] virt_path The virtual mount point of this filesystem * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_FileSysAddFixedMap(uint32 *filesys_id, const char *phys_path, const char *virt_path); @@ -716,13 +748,22 @@ int32 OS_FileSysAddFixedMap(uint32 *filesys_id, const char *phys_path, /** * @brief Makes a file system on the target * - * Makes a file system on the target + * Makes a file system on the target. Highly dependent on underlying OS and + * dependent on OS volume table definition. + * + * @param[in] address The address at which to start the new disk. If address == 0 + * space will be allocated by the OS. + * @param[in] devname The name of the "generic" drive + * @param[in] volname The name of the volume (if needed, used on VxWorks) + * @param[in] blocksize The size of a single block on the drive + * @param[in] numblocks The number of blocks to allocate for the drive * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if devname is NULL - * OS_FS_ERR_DRIVE_NOT_CREATED if the OS calls to create the the drive failed - * OS_FS_ERR_DEVICE_NOT_FREE if the volume table is full - * OS_FS_SUCCESS on creating the disk + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if devname is NULL + * @retval #OS_FS_ERR_DRIVE_NOT_CREATED if the OS calls to create the the drive failed + * @retval #OS_FS_ERR_DEVICE_NOT_FREE if the volume table is full + * @retval #OS_FS_SUCCESS on creating the disk */ int32 OS_mkfs (char *address, const char *devname, const char *volname, uint32 blocksize, uint32 numblocks); @@ -730,9 +771,12 @@ int32 OS_mkfs (char *address, const char *devname, const char * /** * @brief Mounts a file system * - * mounts a file system / block device at the given mount point + * Mounts a file system / block device at the given mount point. + * + * @param[in] devname The name of the drive to mount. devname is the same from #OS_mkfs + * @param[in] mountpoint The name to call this disk from now on * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_mount (const char *devname, const char *mountpoint); @@ -742,11 +786,19 @@ int32 OS_mount (const char *devname, const char *mountpoint); * * Initializes a file system on the target. * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if devname or volname are NULL - * OS_FS_ERR_PATH_TOO_LONG if the name is too long - * OS_FS_ERR_DEVICE_NOT_FREE if the volume table is full - * OS_FS_ERR_DRIVE_NOT_CREATED on error + * @param[in] address The address at which to start the new disk. If address == 0, + * then space will be allocated by the OS + * @param[in] devname The name of the "generic" drive + * @param[in] volname The name of the volume (if needed, used on VxWorks) + * @param[in] blocksize The size of a single block on the drive + * @param[in] numblocks The number of blocks to allocate for the drive + * + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if devname or volname are NULL + * @retval #OS_FS_ERR_PATH_TOO_LONG if the name is too long + * @retval #OS_FS_ERR_DEVICE_NOT_FREE if the volume table is full + * @retval #OS_FS_ERR_DRIVE_NOT_CREATED on error */ int32 OS_initfs (char *address, const char *devname, const char *volname, uint32 blocksize, uint32 numblocks); @@ -755,10 +807,15 @@ int32 OS_initfs (char *address, const char *devname, const char * /** * @brief Removes a file system * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if devname is NULL - * OS_ERROR is the drive specified cannot be located - * OS_FS_SUCCESS on removing the disk + * This function will remove or un-map the target file system. Note that this is not + * the same as un-mounting the file system. + * + * @param[in] devname The name of the "generic" drive + * + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if devname is NULL + * @retval #OS_ERROR is the drive specified cannot be located */ int32 OS_rmfs (const char *devname); @@ -766,13 +823,19 @@ int32 OS_rmfs (const char *devname); /** * @brief Unmounts a mounted file system * + * This function will unmount a drive from the file system and make all open file + * descriptors useless. + * * @note Any open file descriptors referencing this file system should * be closed prior to unmounting a drive * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if name is NULL - * OS_FS_ERR_PATH_TOO_LONG if the absolute path given is too long - * OS_ERROR if the OS calls failed + * @param[in] mountpoint The mount point to remove from #OS_mount + * + * @return Execution status, see @ref OSReturnCodes + * @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_ERROR if the OS calls failed */ int32 OS_unmount (const char *mountpoint); @@ -784,10 +847,10 @@ int32 OS_unmount (const char *mountpoint); * * @param[in] name The device/path to operate on * - * @returns non-negative block count on success, or appropriate error code - * OS_INVALID_POINTER if name is NULL - * OS_FS_ERR_PATH_TOO_LONG if the name is too long - * OS_ERROR if the OS call failed + * @return Block count or appropriate error code, see @ref OSReturnCodes + * @retval #OS_INVALID_POINTER if name 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_fsBlocksFree (const char *name); @@ -803,10 +866,11 @@ int32 OS_fsBlocksFree (const char *name); * @param[in] name The device/path to operate on * @param[out] bytes_free The number of free bytes * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if name is NULL - * OS_FS_ERR_PATH_TOO_LONG if the name is too long - * OS_ERROR if the OS call failed + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if name 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_fsBytesFree (const char *name, uint64 *bytes_free); @@ -821,10 +885,11 @@ int32 OS_fsBytesFree (const char *name, uint64 *bytes_free); * @param[in] name The device/path to operate on * @param[in] repair Whether to also repair inconsistencies * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if name is NULL - * OS_ERR_NOT_IMPLEMENTED if not supported - * OS_ERROR if the OS calls fail + * @return Execution status, see @ref OSReturnCodes + * @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_ERROR @copybrief OS_ERROR */ int32 OS_chkfs (const char *name, bool repair); @@ -838,9 +903,10 @@ int32 OS_chkfs (const char *name, bool repair); * @param[out] PhysDriveName Buffer to store physical drive name * @param[in] MountPoint OSAL mount point * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if either parameter is NULL - * OS_ERROR if the mountpoint could not be found + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if either parameter is NULL + * @retval #OS_ERROR if the mountpoint could not be found */ int32 OS_FS_GetPhysDriveName (char * PhysDriveName, const char * MountPoint); @@ -853,8 +919,9 @@ int32 OS_FS_GetPhysDriveName (char * PhysDriveName, const char * MountPoi * @param[in] VirtualPath OSAL virtual path name * @param[out] LocalPath Buffer to store native/translated path name * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if either parameter is NULL + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if either parameter is NULL */ int32 OS_TranslatePath ( const char *VirtualPath, char *LocalPath); @@ -862,19 +929,21 @@ int32 OS_TranslatePath ( const char *VirtualPath, char *LocalPath); /** * @brief Returns information about the file system * - * returns information about the file system in an os_fsinfo_t + * Returns information about the file system in an os_fsinfo_t. * This includes the number of open files and file systems * * @param[out] filesys_info Buffer to store filesystem information * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if filesys_info is NULL + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if filesys_info is NULL */ int32 OS_GetFsInfo(os_fsinfo_t *filesys_info); +/**@}*/ -/****************************************************************************** -** Shell API -******************************************************************************/ +/** @defgroup OSAPIShell OSAL Shell APIs + * @{ + */ /*-------------------------------------------------------------------------------------*/ /** @@ -886,10 +955,12 @@ int32 OS_GetFsInfo(os_fsinfo_t *filesys_info); * @param[in] Cmd Command to pass to shell * @param[in] filedes File to send output to. * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERROR if the command was not executed properly - * OS_ERR_INVALID_ID if the file descriptor passed in is invalid + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERROR if the command was not executed properly + * @retval #OS_ERR_INVALID_ID if the file descriptor passed in is invalid */ int32 OS_ShellOutputToFile(const char* Cmd, uint32 filedes); +/**@}*/ #endif diff --git a/src/os/inc/osapi-os-loader.h b/src/os/inc/osapi-os-loader.h index 537be1a4c..7eb807e29 100644 --- a/src/os/inc/osapi-os-loader.h +++ b/src/os/inc/osapi-os-loader.h @@ -28,6 +28,7 @@ ** Typedefs */ +/** @brief OSAL module address properties */ typedef struct { uint32 valid; @@ -40,6 +41,7 @@ typedef struct cpuaddr bss_size; } OS_module_address_t; +/** @brief OSAL module properties */ typedef struct { cpuaddr entry_point; @@ -50,7 +52,7 @@ typedef struct } OS_module_prop_t; /** - * Associates a single symbol name with a memory address. + * @brief Associates a single symbol name with a memory address. * * If the OS_STATIC_SYMBOL_TABLE feature is enabled, then * an array of these structures should be provided by the @@ -69,7 +71,7 @@ typedef const struct const char *Module; } OS_static_symbol_record_t; - +#ifndef OSAL_OMIT_DEPRECATED /* * Define the former "OS_module_record_t" type as equivalent * to the OS_module_prop_t. This is what the OS_ModuleInfo() @@ -81,10 +83,13 @@ typedef const struct * Ideally OS_module_record_t type should be removed to avoid confusion, * but this would break existing code that calls OS_ModuleInfo(). */ -#ifndef OSAL_OMIT_DEPRECATED -typedef OS_module_prop_t OS_module_record_t; +typedef OS_module_prop_t OS_module_record_t; /**< @deprecated Use OS_module_prop_t */ #endif +/** @defgroup OSAPILoader OSAL Dynamic Loader and Symbol APIs + * @{ + */ + /*-------------------------------------------------------------------------------------*/ /** * @brief Find the Address of a Symbol @@ -98,9 +103,10 @@ typedef OS_module_prop_t OS_module_record_t; * @param[out] symbol_address Set to the address of the symbol * @param[in] symbol_name Name of the symbol to look up * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERROR if the symbol could not be found - * OS_INVALID_POINTER if one of the pointers passed in are NULL + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERROR if the symbol could not be found + * @retval #OS_INVALID_POINTER if one of the pointers passed in are NULL */ int32 OS_SymbolLookup (cpuaddr *symbol_address, const char *symbol_name ); @@ -108,13 +114,15 @@ int32 OS_SymbolLookup (cpuaddr *symbol_address, const char *symbol_name ); /** * @brief Dumps the system symbol table to a file * + * Dumps the system symbol table to the specified filename + * * @param[in] filename File to write to * @param[in] size_limit Maximum number of bytes to write * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_NOT_IMPLEMENTED if the system does not support this function - * OS_ERROR if the symbol table could not be read or dumped - * OS_INVALID_FILE if the file could not be opened or written + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_NOT_IMPLEMENTED @copybrief OS_ERR_NOT_IMPLEMENTED + * @retval #OS_ERROR if the symbol table could not be read or dumped */ int32 OS_SymbolTableDump ( const char *filename, uint32 size_limit ); @@ -128,11 +136,12 @@ int32 OS_SymbolTableDump ( const char *filename, uint32 size_limit ); * @param[in] module_name Name of module * @param[in] filename File containing the object code to load * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERROR if the module cannot be loaded - * OS_INVALID_POINTER if one of the parameters is NULL - * OS_ERR_NO_FREE_IDS if the module table is full - * OS_ERR_NAME_TAKEN if the name is in use + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERROR if the module cannot be loaded + * @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 */ int32 OS_ModuleLoad ( uint32 *module_id, const char *module_name, const char *filename ); @@ -144,8 +153,9 @@ int32 OS_ModuleLoad ( uint32 *module_id, const char *module_name, const char *fi * * @param[in] module_id OSAL ID of the previously the loaded module * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERROR if the module is invalid or cannot be unloaded + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERROR if the module is invalid or cannot be unloaded */ int32 OS_ModuleUnload ( uint32 module_id ); @@ -158,11 +168,12 @@ int32 OS_ModuleUnload ( uint32 module_id ); * @param[in] module_id OSAL ID of the previously the loaded module * @param[out] module_info Buffer to store module information * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the module id invalid - * OS_INVALID_POINTER if the pointer to the ModuleInfo structure is invalid + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_ERR_INVALID_ID if the module id invalid + * @retval #OS_INVALID_POINTER if the pointer to the ModuleInfo structure is invalid */ int32 OS_ModuleInfo ( uint32 module_id, OS_module_prop_t *module_info ); - +/**@}*/ #endif diff --git a/src/os/inc/osapi-os-net.h b/src/os/inc/osapi-os-net.h index aade7932c..f8d514965 100644 --- a/src/os/inc/osapi-os-net.h +++ b/src/os/inc/osapi-os-net.h @@ -49,24 +49,26 @@ * -------------------------------------------------------------------------------------- */ +/** @brief Socket domain */ typedef enum { - OS_SocketDomain_INVALID, - OS_SocketDomain_INET, /**< IPv4 address family, most commonly used) */ - OS_SocketDomain_INET6, /**< IPv6 address family, depends on OS/network stack support */ - OS_SocketDomain_MAX + OS_SocketDomain_INVALID, /**< @brief Invalid */ + OS_SocketDomain_INET, /**< @brief IPv4 address family, most commonly used) */ + OS_SocketDomain_INET6, /**< @brief IPv6 address family, depends on OS/network stack support */ + OS_SocketDomain_MAX /**< @brief Maximum */ } OS_SocketDomain_t; +/** @brief Socket type */ typedef enum { - OS_SocketType_INVALID, - OS_SocketType_DATAGRAM, /**< A connectionless, message-oriented socket */ - OS_SocketType_STREAM, /**< A stream-oriented socket with the concept of a connection */ - OS_SocketType_MAX + OS_SocketType_INVALID, /**< @brief Invalid */ + OS_SocketType_DATAGRAM, /**< @brief A connectionless, message-oriented socket */ + OS_SocketType_STREAM, /**< @brief A stream-oriented socket with the concept of a connection */ + OS_SocketType_MAX /**< @brief Maximum */ } OS_SocketType_t; /** - * Storage buffer for generic network address + * @brief Storage buffer for generic network address * * This is a union type that helps to ensure a minimum * alignment value for the data storage, such that it can @@ -75,13 +77,13 @@ typedef enum */ typedef union { - uint8 Buffer[OS_SOCKADDR_MAX_LEN]; /**< Ensures length of at least OS_SOCKADDR_MAX_LEN */ - uint32 AlignU32; /**< Ensures uint32 alignment */ - void* AlignPtr; /**< Ensures pointer alignment */ + uint8 Buffer[OS_SOCKADDR_MAX_LEN]; /**< @brief Ensures length of at least OS_SOCKADDR_MAX_LEN */ + uint32 AlignU32; /**< @brief Ensures uint32 alignment */ + void* AlignPtr; /**< @brief Ensures pointer alignment */ } OS_SockAddrData_t; /** - * Encapsulates a generic network address + * @brief Encapsulates a generic network address * * This is just an abstract buffer type that holds a network address. * It is allocated for the worst-case size defined by OS_SOCKADDR_MAX_LEN, @@ -89,12 +91,12 @@ typedef union */ typedef struct { - uint32 ActualLength; /**< Length of the actual address data */ - OS_SockAddrData_t AddrData; /**< Abstract Address data */ + uint32 ActualLength; /**< @brief Length of the actual address data */ + OS_SockAddrData_t AddrData; /**< @brief Abstract Address data */ } OS_SockAddr_t; /** - * Encapsulates socket properties + * @brief Encapsulates socket properties * * This is for consistency with other OSAL resource types. * Currently no extra properties are exposed here but this @@ -102,23 +104,20 @@ typedef struct */ typedef struct { - char name [OS_MAX_API_NAME]; /**< Name of the socket */ - uint32 creator; /**< OSAL TaskID which opened the socket */ + char name [OS_MAX_API_NAME]; /**< @brief Name of the socket */ + uint32 creator; /**< @brief OSAL TaskID which opened the socket */ } OS_socket_prop_t; - - - -/* - * -------------------------------------------------------------------------------------- - * Socket Address API Functions +/** + * @defgroup OSAPISocketAddr OSAL Socket Address APIs * * These functions provide a means to manipulate network addresses in a manner that * is (mostly) agnostic to the actual network address type. * * Every network address should be representable as a string (i.e. dotted decimal IP, etc). * This can serve as a the "common denominator" to all address types. - * -------------------------------------------------------------------------------------- + * + * @{ */ /*-------------------------------------------------------------------------------------*/ @@ -129,7 +128,8 @@ typedef struct * * @param[out] Addr The address buffer to initialize * @param[in] Domain The address family - * @returns OS_SUCCESS if successful + * + * @return Execution status, see @ref OSReturnCodes */ int32 OS_SocketAddrInit(OS_SockAddr_t *Addr, OS_SocketDomain_t Domain); @@ -148,7 +148,8 @@ int32 OS_SocketAddrInit(OS_SockAddr_t *Addr, OS_SocketDomain_t Domain); * @param[out] buffer Buffer to hold the output string * @param[in] buflen Maximum length of the output string * @param[in] Addr The network address buffer to convert - * @returns OS_SUCCESS if successful + * + * @return Execution status, see @ref OSReturnCodes */ int32 OS_SocketAddrToString(char *buffer, uint32 buflen, const OS_SockAddr_t *Addr); @@ -169,7 +170,8 @@ int32 OS_SocketAddrToString(char *buffer, uint32 buflen, const OS_SockAddr_t *Ad * * @param[out] Addr The address buffer to initialize * @param[in] string The string to initialize the address from. - * @returns OS_SUCCESS if successful + * + * @return Execution status, see @ref OSReturnCodes */ int32 OS_SocketAddrFromString(OS_SockAddr_t *Addr, const char *string); @@ -183,7 +185,8 @@ int32 OS_SocketAddrFromString(OS_SockAddr_t *Addr, const char *string); * * @param[out] PortNum Buffer to store the port number * @param[in] Addr The network address buffer - * @returns OS_SUCCESS if successful + * + * @return Execution status, see @ref OSReturnCodes */ int32 OS_SocketAddrGetPort(uint16 *PortNum, const OS_SockAddr_t *Addr); @@ -197,15 +200,15 @@ int32 OS_SocketAddrGetPort(uint16 *PortNum, const OS_SockAddr_t *Addr); * * @param[in] PortNum The port number to set * @param[out] Addr The network address buffer - * @returns OS_SUCCESS if successful + * + * @return Execution status, see @ref OSReturnCodes */ int32 OS_SocketAddrSetPort(OS_SockAddr_t *Addr, uint16 PortNum); +/**@}*/ - -/* - * -------------------------------------------------------------------------------------- - * Sockets API Functions +/** + * @defgroup OSALAPISocket OSAL Socket Management APIs * * These functions are loosely related to the BSD Sockets API but made to be * more consistent with other OSAL API functions. That is, they operate on @@ -215,9 +218,10 @@ int32 OS_SocketAddrSetPort(OS_SockAddr_t *Addr, uint16 PortNum); * number space. Additionally, the file OS_read() / OS_write() / OS_close() * calls also work on sockets. * - * Note that all of functions may return OS_ERROR_NOT_IMPLEMENTED if network support + * Note that all of functions may return #OS_ERR_NOT_IMPLEMENTED if network support * is not configured at compile time. - * -------------------------------------------------------------------------------------- + * + * @{ */ /** @@ -229,7 +233,7 @@ int32 OS_SocketAddrSetPort(OS_SockAddr_t *Addr, uint16 PortNum); * @param[in] Domain The domain / address family of the socket (INET or INET6, etc) * @param[in] Type The type of the socket (STREAM or DATAGRAM) * - * @returns OS_SUCCESS if successful + * @return Execution status, see @ref OSReturnCodes */ int32 OS_SocketOpen(uint32 *sock_id, OS_SocketDomain_t Domain, OS_SocketType_t Type); @@ -246,7 +250,8 @@ int32 OS_SocketOpen(uint32 *sock_id, OS_SocketDomain_t Domain, OS_SocketType_t T * * @param[in] sock_id The socket ID * @param[in] Addr The local address to bind to - * @returns OS_SUCCESS if successful + * + * @return Execution status, see @ref OSReturnCodes */ int32 OS_SocketBind(uint32 sock_id, const OS_SockAddr_t *Addr); @@ -261,7 +266,8 @@ int32 OS_SocketBind(uint32 sock_id, const OS_SockAddr_t *Addr); * @param[in] sock_id The socket ID * @param[in] Addr The remote address to connect to * @param[in] timeout The maximum amount of time to wait, or OS_PEND to wait forever - * @returns OS_SUCCESS if successful + * + * @return Execution status, see @ref OSReturnCodes */ int32 OS_SocketConnect(uint32 sock_id, const OS_SockAddr_t *Addr, int32 timeout); @@ -282,7 +288,7 @@ int32 OS_SocketConnect(uint32 sock_id, const OS_SockAddr_t *Addr, int32 timeout) * @param[in] Addr The remote address of the incoming connection * @param[in] timeout The maximum amount of time to wait, or OS_PEND to wait forever * - * @returns OS_SUCCESS if successful + * @return Execution status, see @ref OSReturnCodes */ int32 OS_SocketAccept(uint32 sock_id, uint32 *connsock_id, OS_SockAddr_t *Addr, int32 timeout); @@ -299,7 +305,7 @@ int32 OS_SocketAccept(uint32 sock_id, uint32 *connsock_id, OS_SockAddr_t *Addr, * @param[out] RemoteAddr Buffer to store the remote network address (may be NULL) * @param[in] timeout The maximum amount of time to wait, or OS_PEND to wait forever * - * @returns non-negative count of actual bytes received if successful, or an appropriate error code + * @return Count of actual bytes received or error status, see @ref OSReturnCodes */ int32 OS_SocketRecvFrom(uint32 sock_id, void *buffer, uint32 buflen, OS_SockAddr_t *RemoteAddr, int32 timeout); @@ -316,7 +322,7 @@ int32 OS_SocketRecvFrom(uint32 sock_id, void *buffer, uint32 buflen, OS_SockAddr * @param[in] buflen The length of the message data to send * @param[in] RemoteAddr Buffer containing the remote network address to send to * - * @returns non-negative count of actual bytes sent if successful, or an appropriate error code + * @return Count of actual bytes sent or error status, see @ref OSReturnCodes */ int32 OS_SocketSendTo(uint32 sock_id, const void *buffer, uint32 buflen, const OS_SockAddr_t *RemoteAddr); @@ -331,10 +337,11 @@ int32 OS_SocketSendTo(uint32 sock_id, const void *buffer, uint32 buflen, const O * @param[out] sock_id Buffer to hold result * @param[in] sock_name Name of socket to find * - * @returns OS_SUCCESS if successful, or appropriate error code - * OS_INVALID_POINTER is id or name are NULL pointers - * OS_ERR_NAME_TOO_LONG if the name given is to long to have been stored - * OS_ERR_NAME_NOT_FOUND if the name was not found in the table + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER is id or name are NULL pointers + * @retval #OS_ERR_NAME_TOO_LONG if the name given is to long to have been stored + * @retval #OS_ERR_NAME_NOT_FOUND if the name was not found in the table */ int32 OS_SocketGetIdByName (uint32 *sock_id, const char *sock_name); @@ -348,9 +355,10 @@ int32 OS_SocketGetIdByName (uint32 *sock_id, const char *sock_name); * @param[in] sock_id The socket ID * @param[out] sock_prop Buffer to hold socket information * - * @returns OS_SUCCESS if successful, or appropriate error code - * OS_ERR_INVALID_ID if the id passed in is not a valid semaphore - * OS_INVALID_POINTER if the count_prop pointer is null + * @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 semaphore + * @retval #OS_INVALID_POINTER if the count_prop pointer is null */ int32 OS_SocketGetInfo (uint32 sock_id, OS_socket_prop_t *sock_prop); @@ -362,14 +370,12 @@ int32 OS_SocketGetInfo (uint32 sock_id, OS_socket_prop_t *sock_prop); * The ID is an implementation-defined value and may not be consistent * in meaning across different platform types. * - * @note this API may be removed in a future version of OSAL due to - * inconsistencies between platforms. - * - * @returns The ID or fixed value of -1 if the host id could not be found - * - * Note it is not possible to differentiate between error codes and valid - * network IDs here. It is assumed, however, that -1 is never a valid ID. + * @note This API may be removed in a future version of OSAL due to + * inconsistencies between platforms. * + * @return The ID or fixed value of -1 if the host id could not be found. + * Note it is not possible to differentiate between error codes and valid + * network IDs here. It is assumed, however, that -1 is never a valid ID. */ int32 OS_NetworkGetID (void); @@ -384,8 +390,9 @@ int32 OS_NetworkGetID (void); * @param[out] host_name Buffer to hold name information * @param[in] name_len Maximum length of host name buffer * - * @returns OS_SUCCESS if successful + * @return Execution status, see @ref OSReturnCodes */ int32 OS_NetworkGetHostName (char *host_name, uint32 name_len); +/**@}*/ #endif diff --git a/src/os/inc/osapi-os-timer.h b/src/os/inc/osapi-os-timer.h index 5a197c237..6416067cc 100644 --- a/src/os/inc/osapi-os-timer.h +++ b/src/os/inc/osapi-os-timer.h @@ -22,9 +22,10 @@ /* ** Typedefs */ -typedef void (*OS_TimerCallback_t)(uint32 timer_id); -typedef uint32 (*OS_TimerSync_t)(uint32 timer_id); +typedef void (*OS_TimerCallback_t)(uint32 timer_id); /**< @brief Timer callback */ +typedef uint32 (*OS_TimerSync_t)(uint32 timer_id); /**< @brief Timer sync */ +/** @brief Timer properties */ typedef struct { char name[OS_MAX_API_NAME]; @@ -35,6 +36,7 @@ typedef struct } OS_timer_prop_t; +/** @brief Time base properties */ typedef struct { char name[OS_MAX_API_NAME]; @@ -44,6 +46,9 @@ typedef struct uint32 accuracy; } OS_timebase_prop_t; +/** @defgroup OSAPITimer OSAL Timer APIs + * @{ + */ /*-------------------------------------------------------------------------------------*/ /** @@ -73,7 +78,7 @@ typedef struct * @param[in] timebase_name The name of the time base * @param[in] external_sync A synchronization function for BSP hardware-based timer ticks * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_TimeBaseCreate (uint32 *timebase_id, const char *timebase_name, OS_TimerSync_t external_sync); @@ -95,7 +100,7 @@ int32 OS_TimeBaseCreate (uint32 *timebase_id, const char *timebase_name, * @param[in] start_time The amount of delay for the first tick, in microseconds. * @param[in] interval_time The amount of delay between ticks, in microseconds. * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_TimeBaseSet (uint32 timebase_id, uint32 start_time, uint32 interval_time); @@ -108,7 +113,7 @@ int32 OS_TimeBaseSet (uint32 timebase_id, uint32 start_time, uint32 i * * @param[in] timebase_id The timebase resource to delete * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_TimeBaseDelete (uint32 timebase_id); @@ -121,10 +126,11 @@ int32 OS_TimeBaseDelete (uint32 timebase_id); * @param[out] timebase_id The timebase resource ID * @param[in] timebase_name The name of the timebase resource to find * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if timebase_id or timebase_name are NULL pointers - * OS_ERR_NAME_TOO_LONG if the name given is to long to have been stored - * OS_ERR_NAME_NOT_FOUND if the name was not found in the table + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if timebase_id or timebase_name are NULL pointers + * @retval #OS_ERR_NAME_TOO_LONG if the name given is to long to have been stored + * @retval #OS_ERR_NAME_NOT_FOUND if the name was not found in the table */ int32 OS_TimeBaseGetIdByName (uint32 *timebase_id, const char *timebase_name); @@ -141,9 +147,10 @@ int32 OS_TimeBaseGetIdByName (uint32 *timebase_id, const char *timebase_name) * @param[in] timebase_id The timebase resource ID * @param[out] timebase_prop Buffer to store timebase properties * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the id passed in is not a valid timebase - * OS_INVALID_POINTER if the timebase_prop pointer is null + * @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 the timebase_prop pointer is null */ int32 OS_TimeBaseGetInfo (uint32 timebase_id, OS_timebase_prop_t *timebase_prop); @@ -173,8 +180,9 @@ int32 OS_TimeBaseGetInfo (uint32 timebase_id, OS_timebase_prop_t *timebas * @param[in] timebase_id The timebase to operate on * @param[out] freerun_val Buffer to store the free run counter * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the id passed in is not a valid timebase + * @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 */ int32 OS_TimeBaseGetFreeRun (uint32 timebase_id, uint32 *freerun_val); @@ -189,14 +197,20 @@ int32 OS_TimeBaseGetFreeRun (uint32 timebase_id, uint32 *freerun_val); * which is created and deleted with the timer object itself. The internal time base * is configured for an OS simulated timer tick at the same interval as the timer. * + * @note clock_accuracy comes from the underlying OS tick value. The nearest integer + * microsecond value is returned, so may not be exact. + * * @param[out] timer_id The resource ID of the timer object * @param[in] timer_name Name of the timer object - * @param[out] clock_accuracy Expected precision of the timer, in microseconds. + * @param[out] clock_accuracy Expected precision of the timer, in microseconds. This + * is the underlying tick value rounded to the nearest + * microsecond integer. * @param[in] callback_ptr Application-provided function to invoke * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if any parameters are NULL - * OS_TIMER_ERR_INVALID_ARGS if the callback function is not valid + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if any parameters are NULL + * @retval #OS_TIMER_ERR_INVALID_ARGS if the callback function is not valid */ int32 OS_TimerCreate (uint32 *timer_id, const char *timer_name, uint32 *clock_accuracy, OS_TimerCallback_t callback_ptr); @@ -222,7 +236,7 @@ int32 OS_TimerCreate (uint32 *timer_id, const char *timer_name, uint3 * @param[in] callback_ptr Application-provided function to invoke * @param[in] callback_arg Opaque argument to pass to callback function * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_TimerAdd (uint32 *timer_id, const char *timer_name, uint32 timebase_id, OS_ArgCallback_t callback_ptr, void *callback_arg); @@ -249,7 +263,7 @@ int32 OS_TimerAdd (uint32 *timer_id, const char *timer_name, uint3 * @param[in] start_time Time to the first expiration * @param[in] interval_time Time between subsequent intervals * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_TimerSet (uint32 timer_id, uint32 start_time, uint32 interval_time); @@ -262,7 +276,7 @@ int32 OS_TimerSet (uint32 timer_id, uint32 start_time, uint32 inte * * @param[in] timer_id The timer ID to operate on * - * @returns OS_SUCCESS on success, or appropriate error code + * @return Execution status, see @ref OSReturnCodes */ int32 OS_TimerDelete (uint32 timer_id); @@ -275,10 +289,11 @@ int32 OS_TimerDelete (uint32 timer_id); * @param[out] timer_id The timer ID corresponding to the name * @param[in] timer_name The timer name to find * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_INVALID_POINTER if timer_id or timer_name are NULL pointers - * OS_ERR_NAME_TOO_LONG if the name given is to long to have been stored - * OS_ERR_NAME_NOT_FOUND if the name was not found in the table + * @return Execution status, see @ref OSReturnCodes + * @retval #OS_SUCCESS @copybrief OS_SUCCESS + * @retval #OS_INVALID_POINTER if timer_id or timer_name are NULL pointers + * @retval #OS_ERR_NAME_TOO_LONG if the name given is to long to have been stored + * @retval #OS_ERR_NAME_NOT_FOUND if the name was not found in the table */ int32 OS_TimerGetIdByName (uint32 *timer_id, const char *timer_name); @@ -293,10 +308,12 @@ int32 OS_TimerGetIdByName (uint32 *timer_id, const char *timer_name); * @param[in] timer_id The timer ID to operate on * @param[out] timer_prop Buffer containing timer properties * - * @returns OS_SUCCESS on success, or appropriate error code - * OS_ERR_INVALID_ID if the id passed in is not a valid timer - * OS_INVALID_POINTER if the timer_prop pointer is null + * @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 timer + * @retval #OS_INVALID_POINTER if the timer_prop pointer is null */ int32 OS_TimerGetInfo (uint32 timer_id, OS_timer_prop_t *timer_prop); +/**@}*/ #endif diff --git a/src/os/inc/osapi-version.h b/src/os/inc/osapi-version.h index 24f8d9a85..311909586 100644 --- a/src/os/inc/osapi-version.h +++ b/src/os/inc/osapi-version.h @@ -18,10 +18,10 @@ #ifndef _osapi_version_h_ #define _osapi_version_h_ -#define OS_MAJOR_VERSION 5 -#define OS_MINOR_VERSION 0 -#define OS_REVISION 7 -#define OS_MISSION_REV 0 +#define OS_MAJOR_VERSION 5 /**< @brief Major version number */ +#define OS_MINOR_VERSION 0 /**< @brief Minor version number */ +#define OS_REVISION 7 /**< @brief Revision number */ +#define OS_MISSION_REV 0 /**< @brief Mission revision */ /** * Combine the revision components into a single value that application code can check against diff --git a/src/os/inc/osapi.h b/src/os/inc/osapi.h index 516433519..e17c59cbe 100644 --- a/src/os/inc/osapi.h +++ b/src/os/inc/osapi.h @@ -42,38 +42,42 @@ extern "C" { #endif -#define OS_SUCCESS (0) -#define OS_ERROR (-1) -#define OS_INVALID_POINTER (-2) -#define OS_ERROR_ADDRESS_MISALIGNED (-3) -#define OS_ERROR_TIMEOUT (-4) -#define OS_INVALID_INT_NUM (-5) -#define OS_SEM_FAILURE (-6) -#define OS_SEM_TIMEOUT (-7) -#define OS_QUEUE_EMPTY (-8) -#define OS_QUEUE_FULL (-9) -#define OS_QUEUE_TIMEOUT (-10) -#define OS_QUEUE_INVALID_SIZE (-11) -#define OS_QUEUE_ID_ERROR (-12) -#define OS_ERR_NAME_TOO_LONG (-13) -#define OS_ERR_NO_FREE_IDS (-14) -#define OS_ERR_NAME_TAKEN (-15) -#define OS_ERR_INVALID_ID (-16) -#define OS_ERR_NAME_NOT_FOUND (-17) -#define OS_ERR_SEM_NOT_FULL (-18) -#define OS_ERR_INVALID_PRIORITY (-19) -#define OS_INVALID_SEM_VALUE (-20) -#define OS_ERR_FILE (-27) -#define OS_ERR_NOT_IMPLEMENTED (-28) -#define OS_TIMER_ERR_INVALID_ARGS (-29) -#define OS_TIMER_ERR_TIMER_ID (-30) -#define OS_TIMER_ERR_UNAVAILABLE (-31) -#define OS_TIMER_ERR_INTERNAL (-32) -#define OS_ERR_OBJECT_IN_USE (-33) -#define OS_ERR_BAD_ADDRESS (-34) -#define OS_ERR_INCORRECT_OBJ_STATE (-35) -#define OS_ERR_INCORRECT_OBJ_TYPE (-36) -#define OS_ERR_STREAM_DISCONNECTED (-37) +/** @defgroup OSReturnCodes OSAL Return Code Defines + * @{ + */ +#define OS_SUCCESS (0) /**< @brief Successful execution */ +#define OS_ERROR (-1) /**< @brief Failed execution */ +#define OS_INVALID_POINTER (-2) /**< @brief Invalid pointer */ +#define OS_ERROR_ADDRESS_MISALIGNED (-3) /**< @brief Address misalignment */ +#define OS_ERROR_TIMEOUT (-4) /**< @brief Error timeout */ +#define OS_INVALID_INT_NUM (-5) /**< @brief Invalid Interrupt number */ +#define OS_SEM_FAILURE (-6) /**< @brief Semaphore failure */ +#define OS_SEM_TIMEOUT (-7) /**< @brief Semaphore timeout */ +#define OS_QUEUE_EMPTY (-8) /**< @brief Queue empty */ +#define OS_QUEUE_FULL (-9) /**< @brief Queue full */ +#define OS_QUEUE_TIMEOUT (-10) /**< @brief Queue timeout */ +#define OS_QUEUE_INVALID_SIZE (-11) /**< @brief Queue invalid size */ +#define OS_QUEUE_ID_ERROR (-12) /**< @brief Queue ID error */ +#define OS_ERR_NAME_TOO_LONG (-13) /**< @brief Name too long */ +#define OS_ERR_NO_FREE_IDS (-14) /**< @brief No free IDs */ +#define OS_ERR_NAME_TAKEN (-15) /**< @brief Name taken */ +#define OS_ERR_INVALID_ID (-16) /**< @brief Invalid ID */ +#define OS_ERR_NAME_NOT_FOUND (-17) /**< @brief Name not found */ +#define OS_ERR_SEM_NOT_FULL (-18) /**< @brief Semaphore not full */ +#define OS_ERR_INVALID_PRIORITY (-19) /**< @brief Invalid priority */ +#define OS_INVALID_SEM_VALUE (-20) /**< @brief Invalid semaphore value */ +#define OS_ERR_FILE (-27) /**< @brief File error */ +#define OS_ERR_NOT_IMPLEMENTED (-28) /**< @brief Not implemented */ +#define OS_TIMER_ERR_INVALID_ARGS (-29) /**< @brief Timer invalid arguments */ +#define OS_TIMER_ERR_TIMER_ID (-30) /**< @brief Timer ID error */ +#define OS_TIMER_ERR_UNAVAILABLE (-31) /**< @brief Timer unavailable */ +#define OS_TIMER_ERR_INTERNAL (-32) /**< @brief Timer internal error */ +#define OS_ERR_OBJECT_IN_USE (-33) /**< @brief Object in use */ +#define OS_ERR_BAD_ADDRESS (-34) /**< @brief Bad address */ +#define OS_ERR_INCORRECT_OBJ_STATE (-35) /**< @brief Incorrect object state */ +#define OS_ERR_INCORRECT_OBJ_TYPE (-36) /**< @brief Incorrect object type */ +#define OS_ERR_STREAM_DISCONNECTED (-37) /**< @brief Stream disconnected */ +/**@}*/ /* ** Defines for Queue Timeout parameters