diff --git a/doc/OSAL Library API.doc b/doc/OSAL Library API.doc index 83fdeed66..cfffa8ae8 100644 Binary files a/doc/OSAL Library API.doc and b/doc/OSAL Library API.doc differ diff --git a/doc/OSAL Library API.pdf b/doc/OSAL Library API.pdf index ea64b4851..2855d370f 100644 Binary files a/doc/OSAL Library API.pdf and b/doc/OSAL Library API.pdf differ diff --git a/src/os/inc/osapi-os-core.h b/src/os/inc/osapi-os-core.h index 715ca200a..4884588c4 100644 --- a/src/os/inc/osapi-os-core.h +++ b/src/os/inc/osapi-os-core.h @@ -151,54 +151,94 @@ void OS_Application_Startup(void); ** Exported Functions */ -/* -** Initialization of API -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Initialization of API + * + * Initialize the tables that the OS API uses to keep track of information + * about objects + * + * @returns OS_SUCCESS on success, or appropriate error code + */ int32 OS_API_Init (void); -/* -** OS-specific 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. -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @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. + * + * Typically just waits forever until "OS_shutdown" flag becomes true. + */ void OS_IdleLoop (void); -/* -** OS_DeleteAllObjects() provides a means to clean up all resources allocated by this -** instance of OSAL. It would typically be used during an orderly shutdown but may also -** be helpful for testing purposes. -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief delete all resources created in OSAL. + * + * provides a means to clean up all resources allocated by this + * instance of OSAL. It would typically be used during an orderly + * shutdown but may also be helpful for testing purposes. + */ void OS_DeleteAllObjects (void); -/* -** OS_ApplicationShutdown() provides a means for a user-created thread to request the orderly -** shutdown of the whole system, such as part of a user-commanded reset command. -** This is preferred over e.g. ApplicationExit() which exits immediately and does not -** provide for any means to clean up first. -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Initiate orderly shutdown + * + * Indicates that the OSAL application should perform an orderly shutdown + * of ALL tasks, clean up all resources, and exit the application. + * + * 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 + * does not provide for any means to clean up first. + * + * @param flag set to true to initiate shutdown, false to cancel + */ void OS_ApplicationShutdown (uint8 flag); -/* -** Some general purpose helper functions -- -** These are only available when using enhanced object IDs (-ng variants) -*/ - -/* -** OS_IdentifyObject() will return the type of an object given an arbitrary object ID -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Obtain the type of an object given an arbitrary object ID + * + * Given an arbitrary object ID, get the type of the object + * + * @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. + */ uint32 OS_IdentifyObject (uint32 object_id); -/* -** OS_ConvertToArrayIndex() will return a unique integer number in the range of [0,MAX) -** for any valid object ID. This may be used by application code as an array index. -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Converts an abstract ID into a number suitable for use as an array index. + * + * This will return a unique zero-based integer number in the range of [0,MAX) for + * any valid object ID. This may be used by application code as an array index + * for indexing into local tables. + * + * @note This does NOT verify the validity of the ID, that is left to the caller. + * This is only the conversion logic. + * + * @param[in] object_id The object ID to operate on + * + * @returns OS_SUCCESS on success, or appropriate error code + */ int32 OS_ConvertToArrayIndex (uint32 object_id, uint32 *ArrayIndex); -/* -** OS_ForEachObject() will call the supplied callback function for all valid object IDs. -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief call the supplied callback function for all valid object IDs + * + * Loops through all defined OSAL objects and calls callback_ptr on each one + * 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); @@ -206,139 +246,935 @@ void OS_ForEachObject (uint32 creator_id, OS_ArgCallback_t callback_pt ** Task API */ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Creates a task and starts running it. + * + * @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 + * @param[in] stack_pointer pointer to the stack for the task, or NULL + * to allocate a stack from the system memory heap + * @param[in] stack_size the size of the stack, or 0 to use a default stack size. + * @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 + */ int32 OS_TaskCreate (uint32 *task_id, const char *task_name, osal_task_entry function_pointer, uint32 *stack_pointer, uint32 stack_size, uint32 priority, uint32 flags); +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Deletes the specified Task + * + * The task will be removed from the local tables. and the OS will + * be configured to stop executing the task at the next opportunity. + * + * @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 + */ int32 OS_TaskDelete (uint32 task_id); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Exits the calling task + * + * The calling thread is terminated. This function does not return. + */ void OS_TaskExit (void); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Installs a handler for when the task is deleted. + * + * @param[in] function_pointer function to be called when task exits + * + * @returns OS_SUCCESS on success, or appropriate error code + */ int32 OS_TaskInstallDeleteHandler(osal_task_entry function_pointer); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Delay a task for specified amount of milliseconds + * + * @param[in] milliseconds 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 + */ int32 OS_TaskDelay (uint32 millisecond); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Sets the given task to a new priority + * + * @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 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 + */ int32 OS_TaskSetPriority (uint32 task_id, uint32 new_priority); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Registration to be called by new tasks after creation + * + * Obsolete function retained for compatibility purposes. + * Does Nothing in the current implementation. + * + * @returns OS_SUCCESS (always) + */ int32 OS_TaskRegister (void); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Obtain the task id of the calling task + * + * 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) + */ uint32 OS_TaskGetId (void); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Find an existing task ID by name + * + * This function tries to find a task Id given the name of a task + * + * @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 + */ int32 OS_TaskGetIdByName (uint32 *task_id, const char *task_name); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Fill a property object buffer with details regarding the resource + * + * This function will pass back a pointer to structure that contains + * all of the relevant info (creator, stack size, priority, name) about the + * specified task. + * + * @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 + */ int32 OS_TaskGetInfo (uint32 task_id, OS_task_prop_t *task_prop); /* ** Message Queue API */ -/* -** Queue Create now has the Queue ID returned to the caller. -*/ +/** + * @brief Create a message queue + * + * @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 + */ int32 OS_QueueCreate (uint32 *queue_id, const char *queue_name, uint32 queue_depth, uint32 data_size, uint32 flags); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Deletes the specified message queue. + * + * @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 + */ int32 OS_QueueDelete (uint32 queue_id); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Receive a message on a message queue + * + * If a message is pending, it is returned immediately. Otherwise the calling task + * will block until a message arrives or the timeout expires. + * + * @param[in] queue_id The object ID to operate on + * @param[out] data The buffer to store the received message + * @param[in] size The size of the data buffer + * @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 + */ int32 OS_QueueGet (uint32 queue_id, void *data, uint32 size, uint32 *size_copied, int32 timeout); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Put a message on a message queue. + * + * @param[in] queue_id The object ID to operate on + * @param[in] data The buffer containing the message to put + * @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 + */ int32 OS_QueuePut (uint32 queue_id, const void *data, uint32 size, uint32 flags); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Find an existing queue ID by name + * + * This function tries to find a queue Id given the name of the queue. The + * id of the queue is passed back in queue_id. + * + * @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 + */ int32 OS_QueueGetIdByName (uint32 *queue_id, const char *queue_name); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Fill a property object buffer with details regarding the resource + * + * This function will pass back a pointer to structure that contains + * all of the relevant info (name and creator) about the specified queue. + * + * @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 + */ int32 OS_QueueGetInfo (uint32 queue_id, OS_queue_prop_t *queue_prop); /* ** Semaphore API */ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Creates a binary semaphore + * + * Creates a binary semaphore with initial value specified by + * sem_initial_value and name specified by sem_name. sem_id will be + * returned to the caller + * + * @param[out] sem_id will be set to the ID of the newly-created resource + * @param[in] sem_name the name of the new resource to create + * @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 + */ int32 OS_BinSemCreate (uint32 *sem_id, const char *sem_name, uint32 sem_initial_value, uint32 options); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Unblock all tasks pending on the specified semaphore + * + * The function unblocks all tasks pending on the specified semaphore. However, + * this function does not change the state of the semaphore. + * + * @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 + */ int32 OS_BinSemFlush (uint32 sem_id); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Increment the semaphore value + * + * The function unlocks the semaphore referenced by sem_id by performing + * a semaphore unlock operation on that semaphore. If the semaphore value + * resulting from this operation is positive, then no threads were blocked + * waiting for the semaphore to become unlocked; the semaphore value is + * simply incremented for this semaphore. + * + * @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 + * in the array of semaphores defined by the system + * OS_ERR_INVALID_ID if the id passed in is not a binary semaphore + */ int32 OS_BinSemGive (uint32 sem_id); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Decrement the semaphore value + * + * The locks the semaphore referenced by sem_id by performing a + * semaphore lock operation on that semaphore. If the semaphore value + * is currently zero, then the calling thread shall not return from + * the call until it either locks the semaphore or the call is + * interrupted. + * + * @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 + */ int32 OS_BinSemTake (uint32 sem_id); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Decrement the semaphore value with a timeout + * + * The function locks the semaphore referenced by sem_id. However, + * if the semaphore cannot be locked without waiting for another process + * or thread to unlock the semaphore, this wait shall be terminated when + * the specified timeout, msecs, expires. + * + * @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 + * in the array of semaphores defined by the system + * OS_ERR_INVALID_ID if the ID passed in is not a valid semaphore ID + */ int32 OS_BinSemTimedWait (uint32 sem_id, uint32 msecs); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Deletes the specified Binary Semaphore + * + * @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 + */ int32 OS_BinSemDelete (uint32 sem_id); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Find an existing semaphore ID by name + * + * This function tries to find a binary sem Id given the name of a bin_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 + */ int32 OS_BinSemGetIdByName (uint32 *sem_id, const char *sem_name); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Fill a property object buffer with details regarding the resource + * + * This function will pass back a pointer to structure that contains + * all of the relevant info( name and creator) about the specified binary + * semaphore. + * + * @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 + */ int32 OS_BinSemGetInfo (uint32 sem_id, OS_bin_sem_prop_t *bin_prop); +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Creates a counting semaphore + * + * Creates a counting semaphore with initial value specified by + * sem_initial_value and name specified by sem_name. sem_id will be + * returned to the caller + * + * @param[out] sem_id will be set to the ID of the newly-created resource + * @param[in] sem_name the name of the new resource to create + * @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 + */ int32 OS_CountSemCreate (uint32 *sem_id, const char *sem_name, uint32 sem_initial_value, uint32 options); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Increment the semaphore value + * + * The function unlocks the semaphore referenced by sem_id by performing + * a semaphore unlock operation on that semaphore. If the semaphore value + * resulting from this operation is positive, then no threads were blocked + * waiting for the semaphore to become unlocked; the semaphore value is + * simply incremented for this semaphore. + * + * @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 + * in the array of semaphores defined by the system + * OS_ERR_INVALID_ID if the id passed in is not a counting semaphore + */ int32 OS_CountSemGive (uint32 sem_id); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Decrement the semaphore value + * + * The locks the semaphore referenced by sem_id by performing a + * semaphore lock operation on that semaphore. If the semaphore value + * is currently zero, then the calling thread shall not return from + * the call until it either locks the semaphore or the call is + * interrupted. + * + * @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 + */ int32 OS_CountSemTake (uint32 sem_id); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Decrement the semaphore value with timeout + * + * The function locks the semaphore referenced by sem_id. However, + * if the semaphore cannot be locked without waiting for another process + * or thread to unlock the semaphore, this wait shall be terminated when + * the specified timeout, msecs, expires. + * + * @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 + * in the array of semaphores defined by the system + * OS_ERR_INVALID_ID if the ID passed in is not a valid semaphore ID + */ int32 OS_CountSemTimedWait (uint32 sem_id, uint32 msecs); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Deletes the specified counting Semaphore. + * + * @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 + */ int32 OS_CountSemDelete (uint32 sem_id); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Find an existing semaphore ID by name + * + * This function tries to find a counting sem Id given the name of a count_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 + */ int32 OS_CountSemGetIdByName (uint32 *sem_id, const char *sem_name); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Fill a property object buffer with details regarding the resource + * + * This function will pass back a pointer to structure that contains + * all of the relevant info( name and creator) about the specified counting + * semaphore. + * + * @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 + */ int32 OS_CountSemGetInfo (uint32 sem_id, OS_count_sem_prop_t *count_prop); /* ** Mutex API */ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Creates a mutex semaphore + * + * Mutex semaphores are always created in the unlocked (full) state. + * + * @param[out] sem_id will be set to the ID of the newly-created resource + * @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 + */ int32 OS_MutSemCreate (uint32 *sem_id, const char *sem_name, uint32 options); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Releases the mutex object referenced by sem_id. + * + * If there are threads blocked on the mutex object referenced by + * mutex when this function is called, resulting in the mutex becoming + * available, the scheduling policy shall determine which thread shall + * acquire the mutex. + * + * @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 + */ int32 OS_MutSemGive (uint32 sem_id); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Acquire the mutex object referenced by sem_id. + * + * If the mutex is already locked, the calling thread shall + * block until the mutex becomes available. This operation shall + * return with the mutex object referenced by mutex in the locked state + * with the calling thread as its owner. + * + * @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 + * not in the array of semaphores defined by the system + * OS_ERR_INVALID_ID the id passed in is not a valid mutex + */ int32 OS_MutSemTake (uint32 sem_id); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Deletes the specified Mutex Semaphore. + * + * @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 + */ 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 + * 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 + */ int32 OS_MutSemGetIdByName (uint32 *sem_id, const char *sem_name); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Fill a property object buffer with details regarding the resource + * + * This function will pass back a pointer to structure that contains + * all of the relevant info( name and creator) about the specified mutex + * semaphore. + * + * @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 + */ int32 OS_MutSemGetInfo (uint32 sem_id, OS_mut_sem_prop_t *mut_prop); /* ** OS Time/Tick related API */ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Convert time units from milliseconds to system ticks + * + * This function accepts a time interval in milliseconds and + * returns the tick equivalent. If the result is not an exact + * number of system ticks, the result will be rounded up to + * the nearest tick. + * + * @param[in] milli_seconds the number of milliseconds + * + * @returns the number of ticks + */ int32 OS_Milli2Ticks (uint32 milli_seconds); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Get the system tick size, in microseconds + * + * This function returns the duration of a system tick in micro 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 + */ + int32 OS_Tick2Micros (void); + + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Get the local time + * + * This function gets the local time of the machine its on + * + * @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 + */ int32 OS_GetLocalTime (OS_time_t *time_struct); + + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Set the local time + * + * This function sets the local time of the machine its on + * + * @param[in] time_struct An OS_time_t containing the current time + * + * @returns OS_SUCCESS on success, or appropriate error code + */ int32 OS_SetLocalTime (OS_time_t *time_struct); /* ** Exception API +** NOTE: Not implemented in current OSAL version */ +/*-------------------------------------------------------------------------------------*/ +/* placeholder; not currently implemented */ int32 OS_ExcAttachHandler (uint32 ExceptionNumber, void (*ExceptionHandler)(uint32, const void *,uint32), int32 parameter); + +/*-------------------------------------------------------------------------------------*/ +/* placeholder; not currently implemented */ int32 OS_ExcEnable (int32 ExceptionNumber); + +/*-------------------------------------------------------------------------------------*/ +/* placeholder; not currently implemented */ int32 OS_ExcDisable (int32 ExceptionNumber); /* ** Floating Point Unit API */ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Set an FPU exception handler function + * + * @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 + */ int32 OS_FPUExcAttachHandler (uint32 ExceptionNumber, void * ExceptionHandler , int32 parameter); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Enable FPU exceptions + * + * @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 + */ int32 OS_FPUExcEnable (int32 ExceptionNumber); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Disable FPU exceptions + * + * @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 + */ int32 OS_FPUExcDisable (int32 ExceptionNumber); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Sets the FPU exception mask + * + * 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 + */ int32 OS_FPUExcSetMask (uint32 mask); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Gets the FPU exception mask + * + * 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 + */ int32 OS_FPUExcGetMask (uint32 *mask); /* ** Interrupt API */ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Associate an interrupt number to a specified handler routine + * + * The call associates a specified C routine to a specified interrupt + * number. Upon occurring of the InterruptNumber, the InerruptHandler + * routine will be called and passed the parameter. + * + * @param[in] InterruptNumber The Interrupt Number that will cause the start of the ISR + * @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 + */ int32 OS_IntAttachHandler (uint32 InterruptNumber, osal_task_entry InterruptHandler, int32 parameter); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Enable interrupts + * + * @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 + */ 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 + */ int32 OS_IntLock (void); +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Enables interrupts through Level + * + * @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 + */ int32 OS_IntEnable (int32 Level); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Disable interrupts through 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 + */ int32 OS_IntDisable (int32 Level); +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Set the CPU interrupt mask register + * + * @note The interrupt bits are architecture-specific. + * + * @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 + */ int32 OS_IntSetMask (uint32 mask); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Get the CPU interrupt mask register + * + * @note The interrupt bits are architecture-specific. + * + * @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 + */ int32 OS_IntGetMask (uint32 *mask); + +/*-------------------------------------------------------------------------------------*/ +/* placeholder; not currently implemented */ int32 OS_IntAck (int32 InterruptNumber); /* -** Shared memory API +** Shared memory API +** NOTE: Not implemented in current OSAL version */ + +/*-------------------------------------------------------------------------------------*/ +/* placeholder; not currently implemented */ int32 OS_ShMemInit (void); + +/*-------------------------------------------------------------------------------------*/ +/* placeholder; not currently implemented */ int32 OS_ShMemCreate (uint32 *Id, uint32 NBytes, const char* SegName); + +/*-------------------------------------------------------------------------------------*/ +/* placeholder; not currently implemented */ int32 OS_ShMemSemTake (uint32 Id); + +/*-------------------------------------------------------------------------------------*/ +/* placeholder; not currently implemented */ int32 OS_ShMemSemGive (uint32 Id); + +/*-------------------------------------------------------------------------------------*/ +/* placeholder; not currently implemented */ int32 OS_ShMemAttach (cpuaddr * Address, uint32 Id); + +/*-------------------------------------------------------------------------------------*/ +/* placeholder; not currently implemented */ int32 OS_ShMemGetIdByName (uint32 *ShMemId, const char *SegName ); /* ** Heap API */ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Return current info on the heap + * + * @param[out] heap_prop Storage buffer for heap info + * + * @returns OS_SUCCESS on success, or appropriate error code + */ int32 OS_HeapGetInfo (OS_heap_prop_t *heap_prop); /* ** API for useful debugging function */ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Convert an error number to a string + * + * @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 + */ int32 OS_GetErrorName (int32 error_num, os_err_name_t* err_name); /** - * An abstract structure capable of holding several OSAL IDs + * @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. @@ -350,7 +1186,10 @@ typedef struct uint8 object_ids[(OS_MAX_NUM_OPEN_FILES + 7) / 8]; } OS_FdSet; +/*-------------------------------------------------------------------------------------*/ /** + * @brief Wait for events across multiple file handles + * * Wait for any of the given sets of IDs to be become readable or writable * * This function will block until any of the following occurs: @@ -370,10 +1209,15 @@ typedef struct * is closed or modified by another while this function is in progress, * 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 */ int32 OS_SelectMultiple(OS_FdSet *ReadSet, OS_FdSet *WriteSet, int32 msecs); +/*-------------------------------------------------------------------------------------*/ /** + * @brief Wait for events on a single file handle + * * Wait for a single OSAL filehandle to change state * * This function can be used to wait for a single OSAL stream ID @@ -390,47 +1234,94 @@ 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 */ int32 OS_SelectSingle(uint32 objid, uint32 *StateFlags, int32 msecs); +/*-------------------------------------------------------------------------------------*/ /** - * Clear a FdSet structure + * @brief Clear a FdSet structure * * After this call the set will contain no OSAL IDs + * + * @returns OS_SUCCESS on success, or appropriate error code */ int32 OS_SelectFdZero(OS_FdSet *Set); +/*-------------------------------------------------------------------------------------*/ /** - * Add an ID to an FdSet structure + * @brief Add an ID to an FdSet structure * * After this call the set will contain the given OSAL ID + * + * @returns OS_SUCCESS on success, or appropriate error code */ int32 OS_SelectFdAdd(OS_FdSet *Set, uint32 objid); +/*-------------------------------------------------------------------------------------*/ /** - * Clear an ID from an FdSet structure + * @brief Clear an ID from an FdSet structure * * After this call the set will no longer contain the given OSAL ID + * + * @returns OS_SUCCESS on success, or appropriate error code */ int32 OS_SelectFdClear(OS_FdSet *Set, uint32 objid); +/*-------------------------------------------------------------------------------------*/ /** - * Check if an FdSet structure contains a given ID + * @brief Check if an FdSet structure contains a given ID */ bool OS_SelectFdIsSet(OS_FdSet *Set, uint32 objid); /* ** Abstraction for printf statements */ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Abstraction for the system printf() call + * + * This function abstracts out the printf type statements. This is + * useful for using OS- specific thats that will allow non-polled + * 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, + * to improve the real-time performance of the call. + * + * The output of this routine also may be dynamically enabled or disabled by + * the OS_printf_enable() and OS_printf_disable() calls, respectively. + * + * @param[in] string Format string, followed by additional arguments + */ void OS_printf( const char *string, ...) OS_PRINTF(1,2); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief This function disables the output to the console from OS_printf. + */ void OS_printf_disable(void); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief This function enables the output to the console through OS_printf. + * + */ void OS_printf_enable(void); -/* -** Call to exit the running application -** Normally embedded applications run forever, but for debugging purposes -** (unit testing for example) this is needed in order to end the test -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @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 0612bbd34..59614054c 100644 --- a/src/os/inc/osapi-os-filesys.h +++ b/src/os/inc/osapi-os-filesys.h @@ -197,39 +197,117 @@ typedef OS_file_prop_t OS_FDTableEntry; /****************************************************************************** ** Standard File system API ******************************************************************************/ -/* - * Initializes the File System functions -*/ - -int32 OS_FS_Init(void); -/* - * Creates a file specified by path -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Creates a file specified by path + * + * Creates a file specified by const char *path, with read/write + * permissions by access. The file is also automatically opened by the + * create call. + * + * @param[in] path File name to create + * @param[in] access Intended access mode - OS_WRITE_ONLY or OS_READ_WRITE + * + * @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 + */ int32 OS_creat (const char *path, int32 access); -/* - * Opend a file for reading/writing. Returns file descriptor -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Opens a file + * + * Opens a file. access parameters are OS_READ_ONLY, OS_WRITE_ONLY, or + * OS_READ_WRITE + * + * @param[in] path File name to create + * @param[in] access Intended access mode - OS_READ_ONLY, OS_WRITE_ONLY or OS_READ_WRITE + * + * @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 + */ int32 OS_open (const char *path, int32 access, uint32 mode); -/* - * Closes an open file. -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Closes an open file handle + * + * This closes regular file handles and any other file-like resource, such as + * network streams or pipes. + * + * @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 + */ int32 OS_close (uint32 filedes); -/* - * Reads nbytes bytes from file into buffer -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Read from a file handle + * + * 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 + * @param[in] nbytes Maximum number of bytes to read + * + * @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 + */ int32 OS_read (uint32 filedes, void *buffer, uint32 nbytes); -/* - * Write nybytes bytes of buffer into the file -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Write to a file handle + * + * 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 + * @param[in] buffer Source location for file data + * @param[in] nbytes Maximum number of bytes to read + * + * @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 + */ int32 OS_write (uint32 filedes, const void *buffer, uint32 nbytes); +/*-------------------------------------------------------------------------------------*/ /** - * File/Stream input read with a timeout + * @brief File/Stream input read with a timeout * * This implements a time-limited read and is primarily intended for use with * sockets but may also work with any other stream-like resource that the underlying @@ -247,11 +325,21 @@ int32 OS_write (uint32 filedes, const void *buffer, uint32 nbytes); * data is available. It will not attempt to read the entire input buffer. * * If an EOF condition occurs prior to timeout, this function returns zero. + * + * @param[in] filedes The handle ID to operate on + * @param[in] buffer Source location for file data + * @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. */ int32 OS_TimedRead(uint32 filedes, void *buffer, uint32 nbytes, int32 timeout); + +/*-------------------------------------------------------------------------------------*/ /** - * File/Stream output write with a timeout + * @brief File/Stream output write with a timeout * * This implements a time-limited write and is primarily intended for use with * sockets but may also work with any other stream-like resource that the underlying @@ -269,62 +357,208 @@ int32 OS_TimedRead(uint32 filedes, void *buffer, uint32 nbytes, int32 * data is output. It will _not_ attempt to write the entire output buffer. * * If an EOF condition occurs prior to timeout, this function returns zero. + * + * @param[in] filedes The handle ID to operate on + * @param[in] buffer Source location for file data + * @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. */ int32 OS_TimedWrite(uint32 filedes, const void *buffer, uint32 nbytes, int32 timeout); -/* - * Changes the permissions of a file -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @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 + * + * @note Some file systems do not implement permissions + * + * @returns OS_SUCCESS on success, or appropriate error code + */ int32 OS_chmod (const char *path, uint32 access); -/* - * Returns file status information in filestats -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Obtain information about a file or directory + * + * returns information about a file or directory in a os_fs_stat 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 + */ int32 OS_stat (const char *path, os_fstat_t *filestats); -/* - * Seeks to the specified position of an open file -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @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 + * + * @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 + * + * @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 + */ int32 OS_lseek (uint32 filedes, int32 offset, uint32 whence); -/* - * Removes a file from the file system -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Removes a file from the file system + * + * Removes a given filename from the drive + * + * @note Some file systems permit removal of open files while others do not. For + * portability, it is recommended that applications ensure the file is closed prior + * to removal. + * + * @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 + */ int32 OS_remove (const char *path); -/* - * Renames a file in the file system -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Renames a file + * + * Changes the name of a file, where the source and destination + * reside on the same file system. + * + * @note Some file systems permit renaming of open files while others do not. For + * portability, it is recommended that applications ensure the file is closed prior + * to rename. + * + * @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 + */ int32 OS_rename (const char *old_filename, const char *new_filename); -/* - * copies a single file from src to dest -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Copies a single file from src to 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 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 + */ int32 OS_cp (const char *src, const char *dest); -/* - * moves a single file from src to dest -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Move a single file from src to dest + * + * This first attempts to rename the file, which is faster if + * the source and destination reside on the same file system. + * + * If this fails, it falls back to copying the file and removing + * the original. + * + * @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 + */ int32 OS_mv (const char *src, const char *dest); -/* - * Copies the info of an open file to the structure -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Obtain information about an open file + * + * Copies the information of the given file descriptor into a structure passed in + * + * @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 + */ int32 OS_FDGetInfo (uint32 filedes, OS_file_prop_t *fd_prop); -/* -** Check to see if a file is open -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Checks to see if a 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 + */ int32 OS_FileOpenCheck(const char *Filename); -/* -** Close all open files -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Close all open files + * + * 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 + */ int32 OS_CloseAllFiles(void); -/* -** Close a file by filename -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Close a file by filename + * + * Allows a file to be closed by name. + * This will only work if the name passed in is the same name used to open + * the file. + * + * @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 + */ int32 OS_CloseFileByName(const char *Filename); @@ -335,58 +569,122 @@ int32 OS_CloseFileByName(const char *Filename); #ifndef OSAL_OMIT_DEPRECATED /* * Opens a directory for searching -*/ + * Replaced by OS_DirectoryOpen() + */ os_dirp_t OS_opendir (const char *path); /* * Closes an open directory -*/ + * Replaced by OS_DirectoryClose() + */ int32 OS_closedir(os_dirp_t directory); /* * Rewinds an open directory -*/ + * Replaced by OS_DirectoryRewind() + */ void OS_rewinddir(os_dirp_t directory); /* * Reads the next object in the directory -*/ + * Replaced by OS_DirectoryRead() + */ os_dirent_t * OS_readdir (os_dirp_t directory); #endif -/* - * Opens a directory for searching - * Same as OS_opendir but with a OSAL-style API + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Opens a directory + * + * Prepares for reading the files within a 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 */ int32 OS_DirectoryOpen(uint32 *dir_id, const char *path); -/* - * Closes an open directory - * Same as OS_closedir but with a OSAL-style API + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Closes an open directory + * + * The directory referred to by dir_id will be closed + * + * @param[in] dir_id The handle ID of the directory + * + * @returns OS_SUCCESS on success, or appropriate error code */ int32 OS_DirectoryClose(uint32 dir_id); -/* - * Rewinds an open directory - * Same as OS_rewinddir but with a OSAL-style API + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Rewinds an open directory + * + * Resets a directory read handle back to the first file. + * + * @param[in] dir_id The handle ID of the directory + * + * @returns OS_SUCCESS on success, or appropriate error code */ int32 OS_DirectoryRewind(uint32 dir_id); -/* - * Reads the next object in the directory - * Same as OS_readdir but with a OSAL-style API + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Reads the next name in the directory + * + * Obtains directory entry data for the next file from an open directory + * + * @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 */ int32 OS_DirectoryRead(uint32 dir_id, os_dirent_t *dirent); -/* - * Makes a new directory -*/ + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Makes a new directory + * + * 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 + * 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 + */ int32 OS_mkdir (const char *path, uint32 access); -/* - * Removes an empty directory from the file system. + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Removes a directory from the file system. + * + * Removes a directory from the structure. + * The directory must be empty prior to this operation. + * + * @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 */ int32 OS_rmdir (const char *path); @@ -394,84 +692,200 @@ int32 OS_rmdir (const char *path); ** System Level API ******************************************************************************/ -/* - * Create a fixed mapping between an existing directory and a virtual OSAL mount point. +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Create a fixed mapping between an existing directory and a virtual OSAL mount point. * * This mimics the behavior of a "FS_BASED" entry in the VolumeTable but is registered - * at runtime. It is intended to be called by the PSP/BSP prior to starting the + * at runtime. It is intended to be called by the PSP/BSP prior to starting the OSAL. + * + * @param[out] filesys_id An OSAL ID reflecting the file system + * @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 */ int32 OS_FileSysAddFixedMap(uint32 *filesys_id, const char *phys_path, const char *virt_path); -/* - * Makes a file system -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Makes a file system on the target + * + * Makes a file system on the target + * + * @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 + */ int32 OS_mkfs (char *address, const char *devname, const char *volname, uint32 blocksize, uint32 numblocks); -/* - * Mounts a file system -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Mounts a file system + * + * mounts a file system / block device at the given mount point + * + * @returns OS_SUCCESS on success, or appropriate error code + */ int32 OS_mount (const char *devname, const char *mountpoint); -/* - * Initializes an existing file system -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Initializes an existing file system + * + * 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 + */ int32 OS_initfs (char *address, const char *devname, const char *volname, uint32 blocksize, uint32 numblocks); -/* - * removes a file system -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @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 + */ int32 OS_rmfs (const char *devname); -/* - * Unmounts a mounted file system -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Unmounts a mounted file system + * + * @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 + */ int32 OS_unmount (const char *mountpoint); -/* - * Returns the number of free blocks in a file system -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Obtain number of blocks free + * + * Returns the number of free blocks in a volume + * + * @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 + */ int32 OS_fsBlocksFree (const char *name); -/* -** Returns the number of free bytes in a file system -** Note the 64 bit data type to support filesystems that -** are greater than 4 Gigabytes -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Obtains the number of free bytes in a volume + * + * Returns the number of free bytes in a volume + * + * @note uses a 64 bit data type to support filesystems that + * are greater than 4 Gigabytes + * + * @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 + */ int32 OS_fsBytesFree (const char *name, uint64 *bytes_free); -/* - * Checks the health of a file system and repairs it if necessary +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Checks the health of a file system and repairs it if necessary * - * Modified to return an "int32" like all other functions - this used to - * have its own dedicated return typedef, which was also an integer, - * even though the same OSAL return codes seem to be used. - * (VxWorks is the only OS that currently does something in this call) + * Checks the drives for inconsistencies and optionally also repairs it + * + * @note not all operating systems implement this function + * + * @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 */ int32 OS_chkfs (const char *name, bool repair); -/* - * Returns in the parameter the physical drive underneith the mount point -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Obtains the physical drive name associated with a mount point + * + * Returns the name of the physical volume associated with the drive, + * when given the OSAL mount point of the drive + * + * @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 + */ int32 OS_FS_GetPhysDriveName (char * PhysDriveName, const char * MountPoint); -/* -** Translates a OSAL Virtual file system path to a host Local path -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Translates a OSAL Virtual file system path to a host Local path + * + * Translates a virtual path to an actual system path name + * + * @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 + */ int32 OS_TranslatePath ( const char *VirtualPath, char *LocalPath); -/* -** Returns information about the file system in an os_fsinfo_t -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Returns information about the file system + * + * 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 + */ int32 OS_GetFsInfo(os_fsinfo_t *filesys_info); /****************************************************************************** ** Shell API ******************************************************************************/ -/* executes the shell command passed into is and writes the output of that - * command to the file specified by the given OSAPI file descriptor */ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Executes the command and sends output to a file + * + * Takes a shell command in and writes the output of that command to the specified file + * The output file must be opened previously with write access (OS_WRITE_ONLY or OS_READ_WRITE). + * + * @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 + */ 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 827915bab..537be1a4c 100644 --- a/src/os/inc/osapi-os-loader.h +++ b/src/os/inc/osapi-os-loader.h @@ -85,19 +85,83 @@ typedef const struct typedef OS_module_prop_t OS_module_record_t; #endif -/* -** Loader API -*/ -int32 OS_ModuleTableInit ( void ); - +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Find the Address of a Symbol + * + * This calls to the OS dynamic symbol lookup implementation, + * and/or checks a static symbol table for a matching symbol name. + * + * The static table is intended to support embedded targets that do + * not have module loading capability or have it disabled. + * + * @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 + */ int32 OS_SymbolLookup (cpuaddr *symbol_address, const char *symbol_name ); +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Dumps the system symbol table to a file + * + * @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 + */ int32 OS_SymbolTableDump ( const char *filename, uint32 size_limit ); +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Loads an object file + * + * Loads an object file into the running operating system + * + * @param[out] module_id OSAL ID corresponding to the loaded module + * @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 + */ int32 OS_ModuleLoad ( uint32 *module_id, const char *module_name, const char *filename ); +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Unloads the module file + * + * Unloads the module file from the running operating system + * + * @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 + */ int32 OS_ModuleUnload ( uint32 module_id ); +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Obtain information about a module + * + * Returns information about the loadable module + * + * @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 + */ int32 OS_ModuleInfo ( uint32 module_id, OS_module_prop_t *module_info ); diff --git a/src/os/inc/osapi-os-net.h b/src/os/inc/osapi-os-net.h index 8a2c92558..9039a604e 100644 --- a/src/os/inc/osapi-os-net.h +++ b/src/os/inc/osapi-os-net.h @@ -107,19 +107,21 @@ typedef struct * -------------------------------------------------------------------------------------- */ +/*-------------------------------------------------------------------------------------*/ /** - * Initialize a socket address structure to hold an address of the given family + * @brief Initialize a socket address structure to hold an address of the given family * * The address is set to a suitable default value for the family. * - * @param Addr The address buffer to initialize - * @param Domain The address family + * @param[out] Addr The address buffer to initialize + * @param[in] Domain The address family * @returns OS_SUCCESS if successful */ int32 OS_SocketAddrInit(OS_SockAddr_t *Addr, OS_SocketDomain_t Domain); +/*-------------------------------------------------------------------------------------*/ /** - * Get a string representation of a network host address + * @brief Get a string representation of a network host address * * The specific format of the output string depends on the address family. * @@ -129,15 +131,16 @@ int32 OS_SocketAddrInit(OS_SockAddr_t *Addr, OS_SocketDomain_t Domain); * * @note For IPv4, this would typically be the dotted-decimal format (X.X.X.X). * - * @param buffer Buffer to hold the output string - * @param buflen Maximum length of the output string - * @param Addr The network address buffer to convert + * @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 */ int32 OS_SocketAddrToString(char *buffer, uint32 buflen, const OS_SockAddr_t *Addr); +/*-------------------------------------------------------------------------------------*/ /** - * Set a network host address from a string representation + * @brief Set a network host address from a string representation * * The specific format of the output string depends on the address family. * @@ -150,34 +153,36 @@ int32 OS_SocketAddrToString(char *buffer, uint32 buflen, const OS_SockAddr_t *Ad * Since many embedded deployments do not have name services, this should * not be relied upon. * - * @param Addr The address buffer to initialize - * @param string The string to initialize the address from. + * @param[out] Addr The address buffer to initialize + * @param[in] string The string to initialize the address from. * @returns OS_SUCCESS if successful */ int32 OS_SocketAddrFromString(OS_SockAddr_t *Addr, const char *string); +/*-------------------------------------------------------------------------------------*/ /** - * Get the port number of a network address + * @brief Get the port number of a network address * * For network prototcols that have the concept of a port number (such * as TCP/IP and UDP/IP) this function gets the port number from the * address structure. * - * @param PortNum Buffer to store the port number - * @param Addr The network address buffer + * @param[out] PortNum Buffer to store the port number + * @param[in] Addr The network address buffer * @returns OS_SUCCESS if successful */ int32 OS_SocketAddrGetPort(uint16 *PortNum, const OS_SockAddr_t *Addr); +/*-------------------------------------------------------------------------------------*/ /** - * Get the port number of a network address + * @brief Set the port number of a network address * * For network prototcols that have the concept of a port number (such - * as TCP/IP and UDP/IP) this function gets the port number from the + * as TCP/IP and UDP/IP) this function sets the port number from the * address structure. * - * @param PortNum Buffer to store the port number - * @param Addr The network address buffer + * @param[in] PortNum The port number to set + * @param[out] Addr The network address buffer * @returns OS_SUCCESS if successful */ int32 OS_SocketAddrSetPort(OS_SockAddr_t *Addr, uint16 PortNum); @@ -202,19 +207,21 @@ int32 OS_SocketAddrSetPort(OS_SockAddr_t *Addr, uint16 PortNum); */ /** - * Opens a socket. + * @brief Opens a socket. * * A new, unconnected and unbound socket is allocated of the given domain and type. * - * @param sock_id Buffer to hold the OSAL ID - * @param Domain The domain / address family of the socket (INET or INET6, etc) - * @param Type The type of the socket (STREAM or DATAGRAM) + * @param[out] sock_id Buffer to hold the OSAL ID + * @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 */ int32 OS_SocketOpen(uint32 *sock_id, OS_SocketDomain_t Domain, OS_SocketType_t Type); +/*-------------------------------------------------------------------------------------*/ /** - * Binds a socket to a given local address. + * @brief Binds a socket to a given local address. * * The specified socket will be bound to the local address and port, if available. * @@ -223,28 +230,30 @@ int32 OS_SocketOpen(uint32 *sock_id, OS_SocketDomain_t Domain, OS_SocketType_t T * If the socket is connection-oriented (stream), then this will also put the * socket into a listening state for incoming connections at the local address. * - * @param sock_id The socket ID - * @param Addr The local address to bind to + * @param[in] sock_id The socket ID + * @param[in] Addr The local address to bind to * @returns OS_SUCCESS if successful */ int32 OS_SocketBind(uint32 sock_id, const OS_SockAddr_t *Addr); +/*-------------------------------------------------------------------------------------*/ /** - * Connects a socket to a given remote address. + * @brief Connects a socket to a given remote address. * * The socket will be connected to the remote address and port, if available. * This only applies to stream-oriented sockets. Calling this on a datagram * socket will return an error (these sockets should use SendTo/RecvFrom). * - * @param sock_id The socket ID - * @param Addr The remote address to connect to - * @param timeout The maximum amount of time to wait, or OS_PEND to wait forever + * @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 */ int32 OS_SocketConnect(uint32 sock_id, const OS_SockAddr_t *Addr, int32 timeout); +/*-------------------------------------------------------------------------------------*/ /** - * Waits for and accept the next incoming connection on the given socket + * @brief Waits for and accept the next incoming connection on the given socket * * This is used for sockets operating in a "server" role. The socket must be * a stream type (connection-oriented) and previously bound to a local address @@ -254,85 +263,113 @@ int32 OS_SocketConnect(uint32 sock_id, const OS_SockAddr_t *Addr, int32 timeout) * The new stream connection is then returned to the caller and the original * server socket ID can be reused for the next connection. * - * @param sock_id The server socket ID, previously bound using OS_SocketBind() - * @param connsock_id The connection socket, a new ID that can be read/written - * @param Addr The remote address of the incoming connection - * @param timeout The maximum amount of time to wait, or OS_PEND to wait forever + * @param[in] sock_id The server socket ID, previously bound using OS_SocketBind() + * @param[out] connsock_id The connection socket, a new ID that can be read/written + * @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 */ int32 OS_SocketAccept(uint32 sock_id, uint32 *connsock_id, OS_SockAddr_t *Addr, int32 timeout); +/*-------------------------------------------------------------------------------------*/ /** - * Reads data from a message-oriented (datagram) socket + * @brief Reads data from a message-oriented (datagram) socket * * If a message is already available on the socket, this should immediately return * that data without blocking. Otherwise, it may block up to the given timeout. * - * @param sock_id The socket ID, previously bound using OS_SocketBind() - * @param buffer Pointer to message data receive buffer - * @param buflen The maximum length of the message data to receive - * @param RemoteAddr Buffer to store the remote network address (may be NULL) - * @param timeout The maximum amount of time to wait, or OS_PEND to wait forever - * @returns OS_SUCCESS if successful + * @param[in] sock_id The socket ID, previously bound using OS_SocketBind() + * @param[out] buffer Pointer to message data receive buffer + * @param[in] buflen The maximum length of the message data to receive + * @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 */ int32 OS_SocketRecvFrom(uint32 sock_id, void *buffer, uint32 buflen, OS_SockAddr_t *RemoteAddr, int32 timeout); +/*-------------------------------------------------------------------------------------*/ /** - * Sends data to a message-oriented (datagram) socket + * @brief Sends data to a message-oriented (datagram) socket * * This sends data in a non-blocking mode. If the socket is not currently able to * queue the message, such as if its outbound buffer is full, then this returns * an error code. * - * @param sock_id The socket ID, which must be of the datagram type - * @param buffer Pointer to message data to send - * @param buflen The length of the message data to send - * @param RemoteAddr Buffer containing the remote network address to send to - * @returns OS_SUCCESS if successful + * @param[in] sock_id The socket ID, which must be of the datagram type + * @param[in] buffer Pointer to message data to send + * @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 */ int32 OS_SocketSendTo(uint32 sock_id, const void *buffer, uint32 buflen, const OS_SockAddr_t *RemoteAddr); +/*-------------------------------------------------------------------------------------*/ /** - * Gets an OSAL ID from a given name + * @brief Gets an OSAL ID from a given name * - * OSAL Sockets use generated names according to the address and type. + * @note OSAL Sockets use generated names according to the address and type. * * @sa OS_SocketGetInfo() * - * @param sock_id Buffer to hold result - * @param sock_name Name of socket to find - * @returns OS_SUCCESS if successful + * @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 */ int32 OS_SocketGetIdByName (uint32 *sock_id, const char *sock_name); +/*-------------------------------------------------------------------------------------*/ /** - * Gets information about an OSAL Socket ID + * @brief Gets information about an OSAL Socket ID * * OSAL Sockets use generated names according to the address and type. * This allows applications to find the name of a given socket. * - * @param sock_id The socket ID - * @param sock_prop Buffer to hold socket information - * @returns OS_SUCCESS if successful + * @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 */ int32 OS_SocketGetInfo (uint32 sock_id, OS_socket_prop_t *sock_prop); -/* -** OS_NetworkGetID is currently [[deprecated]] as its behavior is -** unknown and not consistent across operating systems. -*/ +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Gets the network ID of the local machine + * + * 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. + * + */ int32 OS_NetworkGetID (void); +/*-------------------------------------------------------------------------------------*/ /** - * Gets the local machine network host name + * @brief Gets the local machine network host name * * If configured in the underlying network stack, * this function retrieves the local hostname of the system. * - * @param host_name Buffer to hold name information - * @param name_len Maximum length of host name buffer + * @param[out] host_name Buffer to hold name information + * @param[in] name_len Maximum length of host name buffer + * * @returns OS_SUCCESS if successful */ int32 OS_NetworkGetHostName (char *host_name, uint32 name_len); diff --git a/src/os/inc/osapi-os-timer.h b/src/os/inc/osapi-os-timer.h index a3ed25ea7..5a197c237 100644 --- a/src/os/inc/osapi-os-timer.h +++ b/src/os/inc/osapi-os-timer.h @@ -44,24 +44,259 @@ typedef struct uint32 accuracy; } OS_timebase_prop_t; -/* -** Timer API -*/ -int32 OS_TimerAPIInit (void); +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Create an abstract Time Base resource + * + * An OSAL time base is an abstraction of a "timer tick" that can, in turn, be + * used for measurement of elapsed time between events. + * + * Time bases can be simulated by the operating system using the OS kernel-provided + * timing facilities, or based on a hardware timing source if provided by the BSP. + * + * A time base object has a servicing task associated with it, that runs at elevated + * priority and will thereby interrupt user-level tasks when timing ticks occur. + * + * If the external_sync function is passed as NULL, the operating system kernel + * timing resources will be utilized for a simulated timer tick. + * + * If the external_sync function is not NULL, this should point to a BSP-provided + * function that will block the calling task until the next tick occurs. This + * can be used for synchronizing with hardware events. + * + * @note When provisioning a tunable RTOS kernel, such as RTEMS, the kernel should + * be configured to support at least (OS_MAX_TASKS + OS_MAX_TIMEBASES) threads, + * to account for the helper threads associated with time base objects. + * + * @param[out] timebase_id An identifier corresponding to the timebase resource + * @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 + */ int32 OS_TimeBaseCreate (uint32 *timebase_id, const char *timebase_name, OS_TimerSync_t external_sync); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Sets the tick period for simulated time base objects + * + * This sets the actual tick period for timing ticks that are + * simulated by the RTOS kernel (i.e. the "external_sync" parameter + * on the call to OS_TimeBaseCreate() is NULL). + * + * The RTOS will be configured to wake up the helper thread at the + * requested interval. + * + * This function has no effect for time bases that are using + * a BSP-provided external_sync function. + * + * @param[in] timebase_id The timebase resource to configure + * @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 + */ int32 OS_TimeBaseSet (uint32 timebase_id, uint32 start_time, uint32 interval_time); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Deletes a time base object + * + * The helper task and any other resources associated with the time base + * abstraction will be freed. + * + * @param[in] timebase_id The timebase resource to delete + * + * @returns OS_SUCCESS on success, or appropriate error code + */ int32 OS_TimeBaseDelete (uint32 timebase_id); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Find the ID of an existing time base resource + * + * Given a time base name, find and output the ID associated with it. + * + * @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 + */ int32 OS_TimeBaseGetIdByName (uint32 *timebase_id, const char *timebase_name); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Obtain information about a timebase resource + * + * Fills the buffer referred to by the timebase_prop parameter with + * relevant information about the time base resource. + * + * This function will pass back a pointer to structure that contains + * all of the relevant info( name and creator) about the specified timebase. + * + * @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 + */ int32 OS_TimeBaseGetInfo (uint32 timebase_id, OS_timebase_prop_t *timebase_prop); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Read the value of the timebase free run counter + * + * Poll the timer free-running time counter in a lightweight fashion. + * + * The free run count is a monotonically increasing value reflecting the + * total time elapsed since the timebase inception. Units are the + * same as the timebase itself, usually microseconds. + * + * Applications may quickly and efficiently calculate relative time + * differences by polling this value and subtracting the previous + * counter value. + * + * The absolute value of this counter is not relevant, because it + * will "roll over" after 2^32 units of time. For a timebase with + * microsecond units, this occurs approximately every 4294 seconds, + * or about 1.2 hours. + * + * @note To ensure consistency of results, the application should + * sample the value at a minimum of two times the roll over frequency, + * and calculate the difference between the consecutive samples. + * + * @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 + */ int32 OS_TimeBaseGetFreeRun (uint32 timebase_id, uint32 *freerun_val); +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Create a timer object + * + * A timer object is a resource that invokes the specified application-provided function + * upon timer expiration. Timers may be one-shot or periodic in nature. + * + * This function creates a dedicated (hidden) time base object to service this timer, + * 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. + * + * @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[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 + */ int32 OS_TimerCreate (uint32 *timer_id, const char *timer_name, uint32 *clock_accuracy, OS_TimerCallback_t callback_ptr); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Add a timer object based on an existing TimeBase resource + * + * A timer object is a resource that invokes the specified application-provided function + * upon timer expiration. Timers may be one-shot or periodic in nature. + * + * This function uses an existing time base object to service this timer, which must + * exist prior to adding the timer. The precision of the timer is the same + * as that of the underlying time base object. Multiple timer objects can be + * created referring to a single time base object. + * + * This routine also uses a different callback function prototype from OS_TimerCreate(), + * allowing a single opaque argument to be passed to the callback routine. + * The OSAL implementation does not use this parameter, and may be set NULL. + * + * @param[out] timer_id The resource ID of the timer object + * @param[in] timer_name Name of the timer object + * @param[in] timebase_id The time base resource to use as a reference + * @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 + */ int32 OS_TimerAdd (uint32 *timer_id, const char *timer_name, uint32 timebase_id, OS_ArgCallback_t callback_ptr, void *callback_arg); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Configures the expiration time of the timer object + * + * Sets a timer to expire at the given start_time and + * interval_time. Units are the same as the underlying + * time base object. This is generally microseconds for + * RTOS-provided (simulated) time base objects, but may be + * different for BSP-provided time base objects. + * + * For a "one-shot" timer, the start_time configures the + * expiration time, and the interval_time should be passed as + * zero to indicate the timer is not to be automatically reset. + * + * For a periodic timer, the interval_time indicates the + * desired period between callbacks. + * + * The start_time and interval_time should not both be zero. + * + * @param[in] timer_id The timer ID to operate on + * @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 + */ int32 OS_TimerSet (uint32 timer_id, uint32 start_time, uint32 interval_time); + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Deletes a timer resource + * + * The application callback associated with the timer will be stopped, + * and the resources freed for future use. + * + * @param[in] timer_id The timer ID to operate on + * + * @returns OS_SUCCESS on success, or appropriate error code + */ int32 OS_TimerDelete (uint32 timer_id); +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Locate an existing timer resource by name + * + * Outputs the ID associated with the given timer, if it exists. + * + * @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 + */ int32 OS_TimerGetIdByName (uint32 *timer_id, const char *timer_name); + + +/*-------------------------------------------------------------------------------------*/ +/** + * @brief Gets information about an existing timer + * + * This function will populate structure with + * the relevant info (name and creator) about the specified timer. + * + * @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 + */ int32 OS_TimerGetInfo (uint32 timer_id, OS_timer_prop_t *timer_prop); #endif diff --git a/src/os/portable/os-impl-bsd-select.c b/src/os/portable/os-impl-bsd-select.c index c0bf95f9d..b15507794 100644 --- a/src/os/portable/os-impl-bsd-select.c +++ b/src/os/portable/os-impl-bsd-select.c @@ -14,6 +14,9 @@ * * Purpose: This file contains wrappers around the select() system call * + * NOTE: This is a "template" file and not a directly usable source file. + * It must be adapted/instantiated from within the OS-specific + * implementation on platforms that wish to use this template. */ /**************************************************************************************** @@ -38,14 +41,16 @@ LOCAL FUNCTIONS ***************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_FdSet_ConvertIn_Impl - - Purpose: Helper function to convert an OS_FdSet (OSAL) structure into an fd_set (POSIX) - which can then be passed to the POSIX select function. - - returns: Highest numbered file descriptor in the output fd_set ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * Function: OS_FdSet_ConvertIn_Impl + * + * Purpose: Local helper routine, not part of OSAL API. + * + * Convert an OS_FdSet (OSAL) structure into an fd_set (POSIX) + * which can then be passed to the POSIX select function. + * + * returns: Highest numbered file descriptor in the output fd_set + *-----------------------------------------------------------------*/ static int OS_FdSet_ConvertIn_Impl(fd_set *os_set, OS_FdSet *OSAL_set) { uint32 offset; @@ -81,19 +86,19 @@ static int OS_FdSet_ConvertIn_Impl(fd_set *os_set, OS_FdSet *OSAL_set) } return maxfd; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_FdSet_ConvertOut_Impl - - Purpose: Helper function to convert a POSIX fd_set structure into an OSAL OS_FdSet - which can then be returned back to the application. +} /* end OS_FdSet_ConvertIn_Impl */ - This actually un-sets any bits in the "Input" parameter which are also set in - the "output" parameter. - - returns: None ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * Function: OS_FdSet_ConvertOut_Impl + * + * Purpose: Local helper routine, not part of OSAL API. + * + * Convert a POSIX fd_set structure into an OSAL OS_FdSet + * which can then be returned back to the application. + * + * This actually un-sets any bits in the "Input" parameter + * which are also set in the "output" parameter. + *-----------------------------------------------------------------*/ static void OS_FdSet_ConvertOut_Impl(fd_set *output, OS_FdSet *Input) { uint32 offset; @@ -121,16 +126,16 @@ static void OS_FdSet_ConvertOut_Impl(fd_set *output, OS_FdSet *Input) objids >>= 1; } } -} +} /* end OS_FdSet_ConvertOut_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_DoSelect - - Purpose: Local helper function with actual implementation of select() call - Used by SelectSingle and SelectMultiple implementations (below) - - returns: OS_SUCCESS or OS_ERROR ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * Function: OS_DoSelect + * + * Purpose: Local helper routine, not part of OSAL API. + * + * Actual implementation of select() call + * Used by SelectSingle and SelectMultiple implementations (below) + *-----------------------------------------------------------------*/ static int32 OS_DoSelect(int maxfd, fd_set *rd_set, fd_set *wr_set, int32 msecs) { int os_status; @@ -210,24 +215,21 @@ static int32 OS_DoSelect(int maxfd, fd_set *rd_set, fd_set *wr_set, int32 msecs) } return return_code; -} +} /* end OS_DoSelect */ /**************************************************************************************** SELECT API ***************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_SelectSingle_Impl - - Purpose: Waits for activity on a single file descriptor - This wrapper is usable by the File or Socket API - The type of activity to wait for is indicated by "SelectFlags" - msecs indicates the timeout. Positive values will wait up to that many milliseconds. - Zero will not wait (poll) or negative values will wait forever (pend) - - returns: OS_SUCCESS or OS_ERROR - Bits in "SelectFlags" will be unset according to activity ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SelectSingle_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SelectSingle_Impl(uint32 stream_id, uint32 *SelectFlags, int32 msecs) { int32 return_code; @@ -272,28 +274,17 @@ int32 OS_SelectSingle_Impl(uint32 stream_id, uint32 *SelectFlags, int32 msecs) } return return_code; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_SelectMultiple +} /* end OS_SelectSingle_Impl */ - Purpose: Waits for activity on multiple file descriptors - This wrapper is usable by the File or Socket API - Will wait for any file descriptor in "ReadSet" to be readable OR - any descriptor in "WriteSet" to be writable. - Time-Limited to "msecs" (negative to wait forever, zero to poll) - - Notes: It is not possible for this function to verify that the file descriptors - passed in are actually valid. In order to do so would require a different - approach to the OS_FdSet structure (this is currently just a bitmask so - the actual file descriptor value is lost in translation). - - Using an array of uint32's would solve the problem but make the structures - much bigger. - - returns: OS_SUCCESS or OS_ERROR - File descriptors in sets be modified according to activity ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SelectMultiple_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SelectMultiple_Impl(OS_FdSet *ReadSet, OS_FdSet *WriteSet, int32 msecs) { fd_set wr_set; @@ -337,7 +328,7 @@ int32 OS_SelectMultiple_Impl(OS_FdSet *ReadSet, OS_FdSet *WriteSet, int32 msecs) } return return_code; -} +} /* end OS_SelectMultiple_Impl */ diff --git a/src/os/portable/os-impl-bsd-sockets.c b/src/os/portable/os-impl-bsd-sockets.c index a06b377f8..a32bcd1ca 100644 --- a/src/os/portable/os-impl-bsd-sockets.c +++ b/src/os/portable/os-impl-bsd-sockets.c @@ -14,6 +14,10 @@ * * Purpose: This file contains the network functionality for for * systems which implement the BSD-style socket API. + * + * NOTE: This is a "template" file and not a directly usable source file. + * It must be adapted/instantiated from within the OS-specific + * implementation on platforms that wish to use this template. */ /**************************************************************************************** @@ -54,14 +58,15 @@ typedef union Network API ***************************************************************************************/ -/*-------------------------------------------------------------------------------------- - Name: OS_NetworkGetHostName - - Purpose: Gets the name of the current host - - Returns: OS_ERROR if the host name could not be found - OS_SUCCESS if the name was copied to host_name successfully ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_NetworkGetHostName_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_NetworkGetHostName_Impl (char *host_name, uint32 name_len) { int32 return_code; @@ -81,16 +86,18 @@ int32 OS_NetworkGetHostName_Impl (char *host_name, uint32 name_len) } return(return_code); -}/* end OS_NetworkGetHostName */ - +} /* end OS_NetworkGetHostName_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_SocketOpen_Impl - Purpose: Opens the OS socket indicated by the sock_id table entry - - returns: OS_SUCCESS or error code ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketOpen_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketOpen_Impl(uint32 sock_id) { int os_domain; @@ -173,15 +180,17 @@ int32 OS_SocketOpen_Impl(uint32 sock_id) ((os_flags & O_NONBLOCK) != 0); return OS_SUCCESS; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_SocketBind_Impl - - Purpose: Binds the indicated socket table entry to the passed-in address +} /* end OS_SocketOpen_Impl */ - returns: OS_SUCCESS or error code ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketBind_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketBind_Impl(uint32 sock_id, const OS_SockAddr_t *Addr) { int os_result; @@ -228,15 +237,17 @@ int32 OS_SocketBind_Impl(uint32 sock_id, const OS_SockAddr_t *Addr) } } return OS_SUCCESS; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_SocketConnect_Impl +} /* end OS_SocketBind_Impl */ - Purpose: Connects the socket to a remote address. Socket must be of the STREAM variety. - - returns: OS_SUCCESS or error code ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketConnect_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketConnect_Impl(uint32 sock_id, const OS_SockAddr_t *Addr, int32 timeout) { int32 return_code; @@ -304,18 +315,17 @@ int32 OS_SocketConnect_Impl(uint32 sock_id, const OS_SockAddr_t *Addr, int32 tim } } return return_code; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_SocketAccept_Impl +} /* end OS_SocketConnect_Impl */ - Purpose: Accept an incoming connection on the indicated socket (must be a STREAM socket) - Will wait up to "timeout" milliseconds for an incoming connection - Will wait forever if timeout is negative - - returns: OS_SUCCESS or OS_ERROR - Bits in "SelectFlags" will be unset according to activity ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketAccept_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketAccept_Impl(uint32 sock_id, uint32 connsock_id, OS_SockAddr_t *Addr, int32 timeout) { int32 return_code; @@ -367,19 +377,17 @@ int32 OS_SocketAccept_Impl(uint32 sock_id, uint32 connsock_id, OS_SockAddr_t *Ad } return return_code; -} +} /* end OS_SocketAccept_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_SocketRecvFrom_Impl - - Purpose: Receives a datagram from the specified socket (must be of the DATAGRAM type) - Stores the datagram in "buffer" which has a maximum size of "buflen" - Stores the remote address (sender of the datagram) in "RemoteAddr" - Will wait up to "timeout" milliseconds to receive a packet - (zero to poll, negative to wait forever) - - returns: OS_SUCCESS or error code ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketRecvFrom_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketRecvFrom_Impl(uint32 sock_id, void *buffer, uint32 buflen, OS_SockAddr_t *RemoteAddr, int32 timeout) { int32 return_code; @@ -459,17 +467,17 @@ int32 OS_SocketRecvFrom_Impl(uint32 sock_id, void *buffer, uint32 buflen, OS_Soc return return_code; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_SocketSendTo_Impl +} /* end OS_SocketRecvFrom_Impl */ - Purpose: Sends a datagram from the specified socket (must be of the DATAGRAM type) - to the remote address specified by "RemoteAddr" - The datagram to send must be stored in "buffer" with a size of "buflen" - - returns: OS_SUCCESS or error code ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketSendTo_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketSendTo_Impl(uint32 sock_id, const void *buffer, uint32 buflen, const OS_SockAddr_t *RemoteAddr) { int os_result; @@ -505,28 +513,32 @@ int32 OS_SocketSendTo_Impl(uint32 sock_id, const void *buffer, uint32 buflen, co } return os_result; -} - +} /* end OS_SocketSendTo_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_SocketGetInfo_Impl - Purpose: No operation, sockets do not have extra properties at this layer - - returns: OS_SUCCESS or error code ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketGetInfo_Impl (uint32 sock_id, OS_socket_prop_t *sock_prop) { return OS_SUCCESS; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_SocketAddrInit - - Purpose: Initializes an OSAL SockAddr structure to the given address domain +} /* end OS_SocketGetInfo_Impl */ - returns: OS_SUCCESS or OS_ERR_NOT_IMPLEMENTED if the socket domain is not supported ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketAddrInit_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketAddrInit_Impl(OS_SockAddr_t *Addr, OS_SocketDomain_t Domain) { sa_family_t sa_family; @@ -562,16 +574,17 @@ int32 OS_SocketAddrInit_Impl(OS_SockAddr_t *Addr, OS_SocketDomain_t Domain) Accessor->sockaddr.sa_family = sa_family; return OS_SUCCESS; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_SocketAddrToString +} /* end OS_SocketAddrInit_Impl */ - Purpose: Converts a Socket Address structure to a printable string - Useful for including a dotted-decimal IP address in a message or log - - returns: OS_SUCCESS or error code ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketAddrToString_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketAddrToString_Impl(char *buffer, uint32 buflen, const OS_SockAddr_t *Addr) { const void *addrbuffer; @@ -600,16 +613,17 @@ int32 OS_SocketAddrToString_Impl(char *buffer, uint32 buflen, const OS_SockAddr_ } return OS_SUCCESS; -} +} /* end OS_SocketAddrToString_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_SocketAddrFromString - - Purpose: Sets the Address portion of the SockAddr structure according to the strign - For IPV4 (SocketDomain_INET) this will parse the dotted decimal IP address. - - returns: OS_SUCCESS or error code ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketAddrFromString_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketAddrFromString_Impl(OS_SockAddr_t *Addr, const char *string) { void *addrbuffer; @@ -638,18 +652,17 @@ int32 OS_SocketAddrFromString_Impl(OS_SockAddr_t *Addr, const char *string) } return OS_SUCCESS; -} +} /* end OS_SocketAddrFromString_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_SocketAddrGetPort - - Purpose: Retrieve the TCP/UDP port number from the SockAddr structure - - NOTE: The port number is output to the caller in native byte order - (the value is converted from network order before return) - - returns: OS_SUCCESS or OS_ERR_BAD_ADDRESS ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketAddrGetPort_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketAddrGetPort_Impl(uint16 *PortNum, const OS_SockAddr_t *Addr) { in_port_t sa_port; @@ -675,18 +688,17 @@ int32 OS_SocketAddrGetPort_Impl(uint16 *PortNum, const OS_SockAddr_t *Addr) *PortNum = ntohs(sa_port); return OS_SUCCESS; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_SocketAddrSetPort - - Purpose: Set the TCP/UDP port number in the SockAddr structure +} /* end OS_SocketAddrGetPort_Impl */ - NOTE: The port number should be passed in native byte order - (this function will convert to network order) - - returns: OS_SUCCESS or OS_ERR_BAD_ADDRESS ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketAddrSetPort_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketAddrSetPort_Impl(OS_SockAddr_t *Addr, uint16 PortNum) { in_port_t sa_port; @@ -710,7 +722,7 @@ int32 OS_SocketAddrSetPort_Impl(OS_SockAddr_t *Addr, uint16 PortNum) } return OS_SUCCESS; -} +} /* end OS_SocketAddrSetPort_Impl */ diff --git a/src/os/portable/os-impl-console-directwrite.c b/src/os/portable/os-impl-console-directwrite.c index d26c8b0fc..e9b6efa79 100644 --- a/src/os/portable/os-impl-console-directwrite.c +++ b/src/os/portable/os-impl-console-directwrite.c @@ -17,6 +17,9 @@ * using a standard file descriptor provided by the C library using * the write() call. * + * NOTE: This is a "template" file and not a directly usable source file. + * It must be adapted/instantiated from within the OS-specific + * implementation on platforms that wish to use this template. */ /**************************************************************************************** @@ -29,13 +32,15 @@ CONSOLE OUTPUT ***************************************************************************************/ -/* - * Name: OS_ConsoleOutput_Impl + +/*---------------------------------------------------------------- * - * Purpose: Transfer output data to the real console. + * Function: OS_ConsoleOutput_Impl * - * The data is already formatted, this just writes the characters. - */ + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_ConsoleOutput_Impl(uint32 local_id) { uint32 StartPos; @@ -83,7 +88,7 @@ void OS_ConsoleOutput_Impl(uint32 local_id) /* Update the global with the new read location */ console->ReadPos = StartPos; -} +} /* end OS_ConsoleOutput_Impl */ diff --git a/src/os/portable/os-impl-no-network.c b/src/os/portable/os-impl-no-network.c index fa4b83495..4122aef1f 100644 --- a/src/os/portable/os-impl-no-network.c +++ b/src/os/portable/os-impl-no-network.c @@ -17,6 +17,10 @@ * systems which do not implement any networking (OS_INCLUDE_NETWORK is false). * * It implements the required calls and returns OS_ERR_NOT_IMPLEMENTED for all of them. + * + * NOTE: This is a "template" file and not a directly usable source file. + * It must be adapted/instantiated from within the OS-specific + * implementation on platforms that wish to use this template. */ @@ -25,29 +29,34 @@ ***************************************************************************************/ -/*-------------------------------------------------------------------------------------- - Name: OS_NetworkGetID - - Purpose: Gets the ID of the current Network ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_NetworkGetID_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_NetworkGetID_Impl (int32 *IdBuf) { return OS_ERR_NOT_IMPLEMENTED; -}/* end OS_NetworkGetID */ +} /* end OS_NetworkGetID_Impl */ -/*-------------------------------------------------------------------------------------- - Name: OS_NetworkGetHostName - - Purpose: Gets the name of the current host - - Returns: OS_ERROR if the host name could not be found - OS_SUCCESS if the name was copied to host_name successfully ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_NetworkGetHostName_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_NetworkGetHostName_Impl (char *host_name, uint32 name_len) { return OS_ERR_NOT_IMPLEMENTED; -}/* end OS_NetworkGetHostName */ +} /* end OS_NetworkGetHostName_Impl */ diff --git a/src/os/portable/os-impl-posix-dirs.c b/src/os/portable/os-impl-posix-dirs.c index 4007b6c7b..0aa9c112c 100644 --- a/src/os/portable/os-impl-posix-dirs.c +++ b/src/os/portable/os-impl-posix-dirs.c @@ -15,6 +15,9 @@ * Purpose: This file Contains all of the api calls for manipulating files * in a file system / C library that implements the UNIX-style file API * + * NOTE: This is a "template" file and not a directly usable source file. + * It must be adapted/instantiated from within the OS-specific + * implementation on platforms that wish to use this template. */ /**************************************************************************************** @@ -35,10 +38,15 @@ GLOBAL DATA ***************************************************************************************/ -/* - * Directory API implementation - */ - + +/*---------------------------------------------------------------- + * + * Function: OS_DirCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_DirCreate_Impl(const char *local_path, uint32 access) { struct stat st; @@ -63,8 +71,16 @@ int32 OS_DirCreate_Impl(const char *local_path, uint32 access) } return return_code; -} - +} /* end OS_DirCreate_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_DirOpen_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_DirOpen_Impl(uint32 local_id, const char *local_path) { OS_impl_dir_table[local_id] = opendir(local_path); @@ -73,15 +89,31 @@ int32 OS_DirOpen_Impl(uint32 local_id, const char *local_path) return OS_FS_ERROR; } return OS_FS_SUCCESS; -} - +} /* end OS_DirOpen_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_DirClose_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_DirClose_Impl(uint32 local_id) { closedir(OS_impl_dir_table[local_id]); OS_impl_dir_table[local_id] = NULL; return OS_FS_SUCCESS; -} - +} /* end OS_DirClose_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_DirRead_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_DirRead_Impl(uint32 local_id, os_dirent_t *dirent) { struct dirent *de; @@ -105,14 +137,30 @@ int32 OS_DirRead_Impl(uint32 local_id, os_dirent_t *dirent) dirent->FileName[OS_MAX_PATH_LEN - 1] = 0; return OS_FS_SUCCESS; -} - +} /* end OS_DirRead_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_DirRewind_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_DirRewind_Impl(uint32 local_id) { rewinddir(OS_impl_dir_table[local_id]); return OS_FS_SUCCESS; -} - +} /* end OS_DirRewind_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_DirRemove_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_DirRemove_Impl(const char *local_path) { if ( rmdir(local_path) < 0 ) @@ -121,4 +169,4 @@ int32 OS_DirRemove_Impl(const char *local_path) } return OS_FS_SUCCESS; -} +} /* end OS_DirRemove_Impl */ diff --git a/src/os/portable/os-impl-posix-dl.c b/src/os/portable/os-impl-posix-dl.c index d7358380d..23aba192a 100644 --- a/src/os/portable/os-impl-posix-dl.c +++ b/src/os/portable/os-impl-posix-dl.c @@ -16,6 +16,9 @@ * that implement a POSIX-style dynamic module loader. This includes * RTEMS even if built without its native POSIX API. * + * NOTE: This is a "template" file and not a directly usable source file. + * It must be adapted/instantiated from within the OS-specific + * implementation on platforms that wish to use this template. */ /**************************************************************************************** @@ -81,28 +84,34 @@ OS_impl_module_internal_record_t OS_impl_module_table[OS_MAX_MODULES]; /**************************************************************************************** INITIALIZATION FUNCTION ***************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_Posix_ModuleAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_Posix_ModuleAPI_Impl_Init(void) { #if (OS_MAX_MODULES > 0) memset(OS_impl_module_table, 0, sizeof(OS_impl_module_table)); #endif return(OS_SUCCESS); -} +} /* end OS_Posix_ModuleAPI_Impl_Init */ /**************************************************************************************** Symbol table API ***************************************************************************************/ -/*-------------------------------------------------------------------------------------- - Name: OS_SymbolLookup - - Purpose: Find the Address of a Symbol - - Parameters: - - Returns: OS_SUCCESS if the symbol is found - - The address of the symbol will be stored in the pointer that is passed in. ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SymbolLookup_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SymbolLookup_Impl( cpuaddr *SymbolAddress, const char *SymbolName ) { int32 status = OS_ERROR; @@ -125,26 +134,22 @@ int32 OS_SymbolLookup_Impl( cpuaddr *SymbolAddress, const char *SymbolName ) return status; -}/* end OS_SymbolLookup */ +} /* end OS_SymbolLookup_Impl */ /**************************************************************************************** Module Loader API ***************************************************************************************/ -/*-------------------------------------------------------------------------------------- - Name: OS_ModuleLoad - - Purpose: Loads an object file into the running operating system - - Parameters: - - Returns: 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 - OS_SUCCESS if the module is loaded successfuly ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ModuleLoad_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ModuleLoad_Impl ( uint32 module_id, char *translated_path ) { int32 status = OS_ERROR; @@ -164,18 +169,17 @@ int32 OS_ModuleLoad_Impl ( uint32 module_id, char *translated_path ) return status; -}/* end OS_ModuleLoad */ - -/*-------------------------------------------------------------------------------------- - Name: OS_ModuleUnload +} /* end OS_ModuleLoad_Impl */ - Purpose: Unloads the module file from the running operating system - - Parameters: - - Returns: OS_ERROR if the module is invalid or cannot be unloaded - OS_SUCCESS if the module was unloaded successfuly ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ModuleUnload_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ModuleUnload_Impl ( uint32 module_id ) { int32 status = OS_ERROR; @@ -198,7 +202,7 @@ int32 OS_ModuleUnload_Impl ( uint32 module_id ) return status; -}/* end OS_ModuleUnload */ +} /* end OS_ModuleUnload_Impl */ diff --git a/src/os/portable/os-impl-posix-files.c b/src/os/portable/os-impl-posix-files.c index 1e4d9f4d2..0120e9244 100644 --- a/src/os/portable/os-impl-posix-files.c +++ b/src/os/portable/os-impl-posix-files.c @@ -15,6 +15,9 @@ * Purpose: This file Contains all of the api calls for manipulating files * in a file system / C library that implements the POSIX-style file API * + * NOTE: This is a "template" file and not a directly usable source file. + * It must be adapted/instantiated from within the OS-specific + * implementation on platforms that wish to use this template. */ /**************************************************************************************** @@ -34,13 +37,15 @@ -/*--------------------------------------------------------------------------------------- - Name: OS_FileOpen_Impl - - Purpose: Opens the file indicated by "local_path" - - returns: OS_SUCCESS or OS_ERROR ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileOpen_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileOpen_Impl(uint32 local_id, const char *local_path, int32 flags, int32 access) { int os_perm; @@ -94,8 +99,16 @@ int32 OS_FileOpen_Impl(uint32 local_id, const char *local_path, int32 flags, int ((os_perm & O_NONBLOCK) != 0); return OS_FS_SUCCESS; -} - +} /* end OS_FileOpen_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_FileStat_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileStat_Impl(const char *local_path, os_fstat_t *FileStats) { struct stat st; @@ -152,15 +165,17 @@ int32 OS_FileStat_Impl(const char *local_path, os_fstat_t *FileStats) } return OS_FS_SUCCESS; -} - -/*-------------------------------------------------------------------------------------- - Name: OS_FileChmod_Impl +} /* end OS_FileStat_Impl */ - Returns: OS_FS_SUCCESS if success - OS_FS_ERROR if the OS calls fail - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileChmod_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileChmod_Impl(const char *local_path, uint32 access) { mode_t readbits; @@ -229,11 +244,16 @@ int32 OS_FileChmod_Impl(const char *local_path, uint32 access) return OS_SUCCESS; -}/* end OS_FileSysChmod_Impl */ - - - - +} /* end OS_FileChmod_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_FileRemove_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileRemove_Impl(const char *local_path) { if ( remove (local_path) < 0 ) @@ -242,8 +262,16 @@ int32 OS_FileRemove_Impl(const char *local_path) } return OS_SUCCESS; -} - +} /* end OS_FileRemove_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_FileRename_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileRename_Impl(const char *old_path, const char *new_path) { if ( rename (old_path, new_path) < 0 ) @@ -252,5 +280,5 @@ int32 OS_FileRename_Impl(const char *old_path, const char *new_path) } return OS_SUCCESS; -} +} /* end OS_FileRename_Impl */ diff --git a/src/os/portable/os-impl-posix-gettime.c b/src/os/portable/os-impl-posix-gettime.c index 904a9ecb2..5ba273ef2 100644 --- a/src/os/portable/os-impl-posix-gettime.c +++ b/src/os/portable/os-impl-posix-gettime.c @@ -18,6 +18,9 @@ * The OS-specific code must #include the correct headers that define the * prototypes for these functions before including this implementation file. * + * NOTE: This is a "template" file and not a directly usable source file. + * It must be adapted/instantiated from within the OS-specific + * implementation on platforms that wish to use this template. */ /**************************************************************************************** @@ -31,12 +34,15 @@ FUNCTIONS ***************************************************************************************/ -/*--------------------------------------------------------------------------------------- - * Name: OS_GetLocalTime + +/*---------------------------------------------------------------- * - * Purpose: This functions get the local time of the machine its on - * ------------------------------------------------------------------------------------*/ - + * Function: OS_GetLocalTime_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_GetLocalTime_Impl(OS_time_t *time_struct) { int Status; @@ -58,14 +64,17 @@ int32 OS_GetLocalTime_Impl(OS_time_t *time_struct) } return ReturnCode; -}/* end OS_GetLocalTime */ +} /* end OS_GetLocalTime_Impl */ -/*--------------------------------------------------------------------------------------- - * Name: OS_SetLocalTime + +/*---------------------------------------------------------------- * - * Purpose: This functions set the local time of the machine its on - * ------------------------------------------------------------------------------------*/ - + * Function: OS_SetLocalTime_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SetLocalTime_Impl(const OS_time_t *time_struct) { int Status; @@ -88,5 +97,5 @@ int32 OS_SetLocalTime_Impl(const OS_time_t *time_struct) return ReturnCode; -} /*end OS_SetLocalTime */ +} /* end OS_SetLocalTime_Impl */ diff --git a/src/os/portable/os-impl-posix-io.c b/src/os/portable/os-impl-posix-io.c index 0b613a3a5..834e553b8 100644 --- a/src/os/portable/os-impl-posix-io.c +++ b/src/os/portable/os-impl-posix-io.c @@ -17,6 +17,10 @@ * * These generic ops may apply to regular files, sockets, pipes, or * special devices, depending on the OS in use. + * + * NOTE: This is a "template" file and not a directly usable source file. + * It must be adapted/instantiated from within the OS-specific + * implementation on platforms that wish to use this template. */ /**************************************************************************************** @@ -34,10 +38,15 @@ #define GENERIC_IO_CONST_DATA_CAST #endif -/**************************************************************************************** - Low Level Input/Output API - ****************************************************************************************/ - + +/*---------------------------------------------------------------- + * + * Function: OS_GenericClose_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_GenericClose_Impl(uint32 local_id) { int result; @@ -60,8 +69,16 @@ int32 OS_GenericClose_Impl(uint32 local_id) } OS_impl_filehandle_table[local_id].fd = -1; return OS_FS_SUCCESS; -} - +} /* end OS_GenericClose_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_GenericSeek_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_GenericSeek_Impl (uint32 local_id, int32 offset, uint32 whence) { int where; @@ -107,8 +124,16 @@ int32 OS_GenericSeek_Impl (uint32 local_id, int32 offset, uint32 whence) } return result; -} - +} /* end OS_GenericSeek_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_GenericRead_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_GenericRead_Impl (uint32 local_id, void *buffer, uint32 nbytes, int32 timeout) { int32 return_code; @@ -150,8 +175,16 @@ int32 OS_GenericRead_Impl (uint32 local_id, void *buffer, uint32 nbytes, int32 t } return (return_code); -} - +} /* end OS_GenericRead_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_GenericWrite_Impl + * + * Purpose: Implemented per internal OSAL API + * See description in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_GenericWrite_Impl(uint32 local_id, const void *buffer, uint32 nbytes, int32 timeout) { int32 return_code; @@ -196,5 +229,5 @@ int32 OS_GenericWrite_Impl(uint32 local_id, const void *buffer, uint32 nbytes, i } return (return_code); -} +} /* end OS_GenericWrite_Impl */ diff --git a/src/os/posix/osapi.c b/src/os/posix/osapi.c index 5f28844ac..64d17119f 100644 --- a/src/os/posix/osapi.c +++ b/src/os/posix/osapi.c @@ -164,23 +164,28 @@ static void OS_CompAbsDelayTime( uint32 milli_second , struct timespec * tm); static int OS_PriorityRemap(uint32 InputPri); -/*--------------------------------------------------------------------------------------- - Name: OS_NoopSigHandler - - Purpose: A POSIX signal handler that does nothing ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_NoopSigHandler + * + * Purpose: Local helper routine, not part of OSAL API. + * A POSIX signal handler that does nothing + * + *-----------------------------------------------------------------*/ static void OS_NoopSigHandler (int signal) { -} +} /* end OS_NoopSigHandler */ -/*--------------------------------------------------------------------------------------- - Name: OS_Lock_Global_Impl - - Purpose: Locks the global table identified by "idtype" - - returns: OS_SUCCESS or OS_ERROR ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_Lock_Global_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_Lock_Global_Impl(uint32 idtype) { POSIX_GlobalLock_t *mut; @@ -214,15 +219,17 @@ int32 OS_Lock_Global_Impl(uint32 idtype) mut->sigmask = previous; return OS_SUCCESS; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_Unlock_Global_Impl - - Purpose: Unlocks the global table identified by "idtype" +} /* end OS_Lock_Global_Impl */ - returns: OS_SUCCESS or OS_ERROR ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_Unlock_Global_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_Unlock_Global_Impl(uint32 idtype) { POSIX_GlobalLock_t *mut; @@ -253,7 +260,7 @@ int32 OS_Unlock_Global_Impl(uint32 idtype) pthread_sigmask(SIG_SETMASK, &previous, NULL); return OS_SUCCESS; -} +} /* end OS_Unlock_Global_Impl */ /*--------------------------------------------------------------------------------------- @@ -358,16 +365,17 @@ int32 OS_API_Impl_Init(uint32 idtype) return(return_code); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_IdleLoop - - Purpose: Should be called after all initialization is done - This is used to wait for and handle timer expiration events +} /* end OS_API_Impl_Init */ - returns: no value ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_IdleLoop_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_IdleLoop_Impl() { /* @@ -379,17 +387,17 @@ void OS_IdleLoop_Impl() * timebase objects have a dedicated thread that will be doing "sigwait" on those. */ sigsuspend(&POSIX_GlobalVars.NormalSigMask); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_ApplicationShutdown_Impl - - Purpose: Ensures that the thread waiting in OS_IdleLoop_Impl is waken up - - returns: no value +} /* end OS_IdleLoop_Impl */ - NOTE: Might be called from an ISR/signal handler ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ApplicationShutdown_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_ApplicationShutdown_Impl() { /* @@ -397,7 +405,7 @@ void OS_ApplicationShutdown_Impl() * which should break it out of the sigsuspend() call. */ kill(getpid(), SIGHUP); -} +} /* end OS_ApplicationShutdown_Impl */ /*--------------------------------------------------------------------------------------- @@ -485,7 +493,7 @@ static bool OS_Posix_GetSchedulerParams(int sched_policy, POSIX_PriorityLimits_t OS_DEBUG("Policy %d: available, min-max: %d-%d\n", sched_policy, (int)PriLim->PriorityMin, (int)PriLim->PriorityMax); return true; -} +} /* end OS_Posix_GetSchedulerParams */ /* ********************************************************************************* @@ -716,8 +724,16 @@ int32 OS_Posix_TaskAPI_Impl_Init(void) #endif return OS_SUCCESS; -} +} /* end OS_Posix_TaskAPI_Impl_Init */ + +/*---------------------------------------------------------------- + * + * Function: OS_Posix_InternalTaskCreate_Impl + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_Posix_InternalTaskCreate_Impl(pthread_t *pthr, uint32 priority, size_t stacksz, PthreadFuncPtr_t entry, void *entry_arg) { int return_code = 0; @@ -833,24 +849,17 @@ int32 OS_Posix_InternalTaskCreate_Impl(pthread_t *pthr, uint32 priority, size_t } return OS_SUCCESS; -} +} /* end OS_Posix_InternalTaskCreate_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_TaskCreate - - Purpose: Creates a task and starts running it. - - returns: 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 the operating system calls fail - OS_SUCCESS if success - - NOTES: the flags parameter is unused. - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskCreate_Impl (uint32 task_id, uint32 flags) { OS_U32ValueWrapper_t arg; @@ -867,16 +876,17 @@ int32 OS_TaskCreate_Impl (uint32 task_id, uint32 flags) arg.opaque_arg); return return_code; -}/* end OS_TaskCreate */ - -/*-------------------------------------------------------------------------------------- - Name: OS_TaskMatch - - Purpose: Determines if the caller matches the given global_task_id +} /* end OS_TaskCreate_Impl */ - returns: OS_ERROR if not a match - OS_SUCCESS if match ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskMatch_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskMatch_Impl(uint32 task_id) { if (pthread_equal(pthread_self(), OS_impl_task_table[task_id].id) == 0) @@ -885,17 +895,17 @@ int32 OS_TaskMatch_Impl(uint32 task_id) } return OS_SUCCESS; -} - -/*-------------------------------------------------------------------------------------- - Name: OS_TaskDelete +} /* end OS_TaskMatch_Impl */ - Purpose: Deletes the specified Task and removes it from the OS_global_task_table. - - returns: OS_ERR_INVALID_ID if the ID given to it is invalid - OS_ERROR if the OS delete call fails - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskDelete_Impl (uint32 task_id) { /* @@ -907,29 +917,32 @@ int32 OS_TaskDelete_Impl (uint32 task_id) pthread_cancel(OS_impl_task_table[task_id].id); return OS_SUCCESS; -}/* end OS_TaskDelete */ - -/*-------------------------------------------------------------------------------------- - Name: OS_TaskExit +} /* end OS_TaskDelete_Impl */ - Purpose: Exits the calling task and removes it from the OS_global_task_table. - - returns: Nothing ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskExit_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_TaskExit_Impl() { pthread_exit(NULL); -}/*end OS_TaskExit */ - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskDelay - - Purpose: Delay a task for specified amount of milliseconds +} /* end OS_TaskExit_Impl */ - returns: OS_ERROR if sleep fails or millisecond = 0 - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskDelay_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskDelay_Impl(uint32 millisecond) { struct timespec sleep_end; @@ -959,19 +972,17 @@ int32 OS_TaskDelay_Impl(uint32 millisecond) { return OS_SUCCESS; } -}/* end OS_TaskDelay */ - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskSetPriority - - Purpose: Sets the given task to a new priority +} /* end OS_TaskDelay_Impl */ - returns: 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 - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskSetPriority_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskSetPriority_Impl (uint32 task_id, uint32 new_priority) { int os_priority; @@ -995,16 +1006,17 @@ int32 OS_TaskSetPriority_Impl (uint32 task_id, uint32 new_priority) } return OS_SUCCESS; -} /* end OS_TaskSetPriority */ - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskRegister +} /* end OS_TaskSetPriority_Impl */ - Purpose: Registers the calling task id with the task by adding the thread-specific variable - This is now _always_ called by the task entry function and no longer up to the - user to do so. - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskRegister_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskRegister_Impl(uint32 global_task_id) { int32 return_code; @@ -1025,17 +1037,17 @@ int32 OS_TaskRegister_Impl(uint32 global_task_id) } return return_code; -} +} /* end OS_TaskRegister_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_TaskGetId - - Purpose: This function returns the #defined task id of the calling task - - Notes: The OS_task_key is initialized by the task switch if AND ONLY IF the - OS_task_key has been registered via OS_TaskRegister(..). If this is not - called prior to this call, the value will be old and wrong. ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskGetId_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ uint32 OS_TaskGetId_Impl (void) { OS_U32ValueWrapper_t self_record; @@ -1043,20 +1055,17 @@ uint32 OS_TaskGetId_Impl (void) self_record.opaque_arg = pthread_getspecific(POSIX_GlobalVars.ThreadKey); return(self_record.value); -}/* end OS_TaskGetId */ +} /* end OS_TaskGetId_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_TaskGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info (creator, stack size, priority, name) about the - specified task. - - Returns: OS_ERR_INVALID_ID if the ID passed to it is invalid - OS_INVALID_POINTER if the task_prop pointer is NULL - OS_SUCCESS if it copied all of the relevant info over - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskGetInfo_Impl (uint32 task_id, OS_task_prop_t *task_prop) { size_t copy_sz; @@ -1083,7 +1092,7 @@ int32 OS_TaskGetInfo_Impl (uint32 task_id, OS_task_prop_t *task_prop) memcpy(&task_prop->OStask_id, &OS_impl_task_table[task_id].id, copy_sz); return OS_SUCCESS; -} /* end OS_TaskGetInfo */ +} /* end OS_TaskGetInfo_Impl */ /**************************************************************************************** MESSAGE QUEUE API @@ -1139,23 +1148,18 @@ int32 OS_Posix_QueueAPI_Impl_Init(void) #endif return OS_SUCCESS; -} - - -/*--------------------------------------------------------------------------------------- - Name: OS_QueueCreate +} /* end OS_Posix_QueueAPI_Impl_Init */ - Purpose: Create a message queue which can be refered to by name or ID - Returns: 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 - OS_SUCCESS if success - - Notes: the flags parameter is unused. - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_QueueCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueCreate_Impl (uint32 queue_id, uint32 flags) { int return_code; @@ -1225,20 +1229,17 @@ int32 OS_QueueCreate_Impl (uint32 queue_id, uint32 flags) } return return_code; -}/* end OS_QueueCreate */ - -/*-------------------------------------------------------------------------------------- - Name: OS_QueueDelete - - Purpose: Deletes the specified message queue. +} /* end OS_QueueCreate_Impl */ - Returns: OS_ERR_INVALID_ID if the id passed in does not exist - OS_ERROR if the OS call to delete the queue fails - OS_SUCCESS if success - - Notes: 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 - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_QueueDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueDelete_Impl (uint32 queue_id) { int32 return_code; @@ -1255,20 +1256,17 @@ int32 OS_QueueDelete_Impl (uint32 queue_id) } return return_code; -} /* end OS_QueueDelete */ +} /* end OS_QueueDelete_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_QueueGet - - Purpose: Receive a message on a message queue. Will pend or timeout on the receive. - Returns: 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 of the buffer passed in is not big enough for the - maximum size message - OS_SUCCESS if success - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_QueueGet_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueGet_Impl (uint32 queue_id, void *data, uint32 size, uint32 *size_copied, int32 timeout) { int32 return_code; @@ -1358,22 +1356,17 @@ int32 OS_QueueGet_Impl (uint32 queue_id, void *data, uint32 size, uint32 *size_c } return return_code; -} /* end OS_QueueGet */ - -/*--------------------------------------------------------------------------------------- - Name: OS_QueuePut - - Purpose: Put a message on a message queue. - - Returns: 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 - OS_SUCCESS if SUCCESS +} /* end OS_QueueGet_Impl */ - Notes: The flags parameter is not used. The message put is always configured to - immediately return an error if the receiving message queue is full. - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_QueuePut_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_QueuePut_Impl (uint32 queue_id, const void *data, uint32 size, uint32 flags) { int32 return_code; @@ -1411,7 +1404,7 @@ int32 OS_QueuePut_Impl (uint32 queue_id, const void *data, uint32 size, uint32 f return return_code; -} /* end OS_QueuePut */ +} /* end OS_QueuePut_Impl */ @@ -1437,25 +1430,17 @@ int32 OS_Posix_BinSemAPI_Impl_Init(void) { memset(OS_impl_bin_sem_table, 0, sizeof(OS_impl_bin_sem_table)); return OS_SUCCESS; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemCreate +} /* end OS_Posix_BinSemAPI_Impl_Init */ - Purpose: Creates a binary semaphore with initial value specified by - sem_initial_value and name specified by sem_name. sem_id will be - returned to the caller - - Returns: 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 - OS_SUCCESS if success - - - Notes: options is an unused parameter ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemCreate_Impl (uint32 sem_id, uint32 initial_value, uint32 options) { int ret; @@ -1568,21 +1553,17 @@ int32 OS_BinSemCreate_Impl (uint32 sem_id, uint32 initial_value, uint32 options) return return_code; -}/* end OS_BinSemCreate */ - -/*-------------------------------------------------------------------------------------- - Name: OS_BinSemDelete - - Purpose: Deletes the specified Binary Semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid binary semaphore - OS_SEM_FAILURE the OS call failed - OS_SUCCESS if success +} /* end OS_BinSemCreate_Impl */ - Notes: Since we can't delete a semaphore which is currently locked by some task - (as it may ber crucial to completing the task), the semaphore must be full to - allow deletion. ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemDelete_Impl (uint32 sem_id) { OS_impl_binsem_internal_record_t *sem; @@ -1612,25 +1593,18 @@ int32 OS_BinSemDelete_Impl (uint32 sem_id) } return return_code; -}/* end OS_BinSemDelete */ - - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemGive - - Purpose: The function unlocks the semaphore referenced by sem_id by performing - a semaphore unlock operation on that semaphore.If the semaphore value - resulting from this operation is positive, then no threads were blocked - waiting for the semaphore to become unlocked; the semaphore value is - simply incremented for this semaphore. - +} /* end OS_BinSemDelete_Impl */ - Returns: 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 - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemGive_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemGive_Impl ( uint32 sem_id ) { OS_impl_binsem_internal_record_t *sem; @@ -1663,21 +1637,17 @@ int32 OS_BinSemGive_Impl ( uint32 sem_id ) pthread_mutex_unlock(&(sem->id)); return OS_SUCCESS; -}/* end OS_BinSemGive */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemFlush +} /* end OS_BinSemGive_Impl */ - Purpose: The function unblocks all tasks pending on the specified semaphore. However, - this function does not change the state of the semaphore. - - - Returns: 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 - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemFlush_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemFlush_Impl (uint32 sem_id) { OS_impl_binsem_internal_record_t *sem; @@ -1702,7 +1672,7 @@ int32 OS_BinSemFlush_Impl (uint32 sem_id) pthread_mutex_unlock(&(sem->id)); return OS_SUCCESS; -}/* end OS_BinSemFlush */ +} /* end OS_BinSemFlush_Impl */ /*--------------------------------------------------------------------------------------- Name: OS_GenericBinSemTake_Impl @@ -1771,42 +1741,31 @@ static int32 OS_GenericBinSemTake_Impl (OS_impl_binsem_internal_record_t *sem, c pthread_mutex_unlock(&(sem->id)); return return_code; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemTake - - Purpose: The locks the semaphore referenced by sem_id by performing a - semaphore lock operation on that semaphore.If the semaphore value - is currently zero, then the calling thread shall not return from - the call until it either locks the semaphore or the call is - interrupted by a signal. - - Return: OS_ERR_INVALID_ID the Id passed in is not a valid binary semaphore - OS_SEM_FAILURE if the OS call failed - OS_SUCCESS if success +} /* end OS_GenericBinSemTake_Impl */ -----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemTake_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemTake_Impl ( uint32 sem_id ) { return (OS_GenericBinSemTake_Impl (&OS_impl_bin_sem_table[sem_id], NULL)); -}/* end OS_BinSemTake */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemTimedWait - - Purpose: The function locks the semaphore referenced by sem_id . However, - if the semaphore cannot be locked without waiting for another process - or thread to unlock the semaphore , this wait shall be terminated when - the specified timeout ,msecs, expires. +} /* end OS_BinSemTake_Impl */ - Returns: OS_SEM_TIMEOUT if semaphore was not relinquished in time - OS_SUCCESS if success - 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 - -----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemTimedWait_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemTimedWait_Impl ( uint32 sem_id, uint32 msecs ) { struct timespec ts; @@ -1817,24 +1776,23 @@ int32 OS_BinSemTimedWait_Impl ( uint32 sem_id, uint32 msecs ) OS_CompAbsDelayTime(msecs, &ts); return (OS_GenericBinSemTake_Impl (&OS_impl_bin_sem_table[sem_id], &ts)); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info( name and creator) about the specified counting - semaphore. - - Returns: OS_SUCCESS ----------------------------------------------------------------------------------------*/ +} /* end OS_BinSemTimedWait_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemGetInfo_Impl (uint32 sem_id, OS_bin_sem_prop_t *sem_prop) { /* put the info into the stucture */ sem_prop -> value = OS_impl_bin_sem_table[sem_id].current_value; return OS_SUCCESS; -} /* end OS_CountSemGetInfo */ +} /* end OS_BinSemGetInfo_Impl */ /**************************************************************************************** @@ -1858,26 +1816,17 @@ int32 OS_Posix_CountSemAPI_Impl_Init(void) { memset(OS_impl_count_sem_table, 0, sizeof(OS_impl_count_sem_table)); return OS_SUCCESS; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemCreate - - Purpose: Creates a counting semaphore with initial value specified by - sem_initial_value and name specified by sem_name. sem_id will be - returned to the caller - - Returns: 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 - OS_SUCCESS if success - +} /* end OS_Posix_CountSemAPI_Impl_Init */ - Notes: options is an unused parameter ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemCreate_Impl (uint32 sem_id, uint32 sem_initial_value, uint32 options) { if (sem_initial_value > SEM_VALUE_MAX) @@ -1892,21 +1841,17 @@ int32 OS_CountSemCreate_Impl (uint32 sem_id, uint32 sem_initial_value, uint32 op return OS_SUCCESS; -}/* end OS_CountSemCreate */ - -/*-------------------------------------------------------------------------------------- - Name: OS_CountSemDelete - - Purpose: Deletes the specified Counting Semaphore. +} /* end OS_CountSemCreate_Impl */ - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid counting semaphore - OS_SEM_FAILURE the OS call failed - OS_SUCCESS if success - - Notes: Since we can't delete a semaphore which is currently locked by some task - (as it may ber crucial to completing the task), the semaphore must be full to - allow deletion. ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemDelete_Impl (uint32 sem_id) { if (sem_destroy(&OS_impl_count_sem_table[sem_id].id) < 0) @@ -1916,24 +1861,17 @@ int32 OS_CountSemDelete_Impl (uint32 sem_id) return OS_SUCCESS; -}/* end OS_CountSemDelete */ - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemGive - - Purpose: The function unlocks the semaphore referenced by sem_id by performing - a semaphore unlock operation on that semaphore.If the semaphore value - resulting from this operation is positive, then no threads were blocked - waiting for the semaphore to become unlocked; the semaphore value is - simply incremented for this semaphore. - +} /* end OS_CountSemDelete_Impl */ - Returns: 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 - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemGive_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemGive_Impl ( uint32 sem_id ) { if (sem_post(&OS_impl_count_sem_table[sem_id].id) < 0) @@ -1943,22 +1881,17 @@ int32 OS_CountSemGive_Impl ( uint32 sem_id ) return OS_SUCCESS; -}/* end OS_CountSemGive */ - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemTake +} /* end OS_CountSemGive_Impl */ - Purpose: The locks the semaphore referenced by sem_id by performing a - semaphore lock operation on that semaphore.If the semaphore value - is currently zero, then the calling thread shall not return from - the call until it either locks the semaphore or the call is - interrupted by a signal. - - Return: OS_ERR_INVALID_ID the Id passed in is not a valid counting semaphore - OS_SEM_FAILURE if the OS call failed - OS_SUCCESS if success - -----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemTake_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemTake_Impl ( uint32 sem_id ) { if (sem_wait(&OS_impl_count_sem_table[sem_id].id) < 0) @@ -1967,23 +1900,17 @@ int32 OS_CountSemTake_Impl ( uint32 sem_id ) } return OS_SUCCESS; -}/* end OS_CountSemTake */ - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemTimedWait - - Purpose: The function locks the semaphore referenced by sem_id . However, - if the semaphore cannot be locked without waiting for another process - or thread to unlock the semaphore , this wait shall be terminated when - the specified timeout ,msecs, expires. - - Returns: OS_SEM_TIMEOUT if semaphore was not relinquished in time - OS_SUCCESS if success - 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 +} /* end OS_CountSemTake_Impl */ -----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemTimedWait_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemTimedWait_Impl ( uint32 sem_id, uint32 msecs ) { struct timespec ts; @@ -2009,18 +1936,17 @@ int32 OS_CountSemTimedWait_Impl ( uint32 sem_id, uint32 msecs ) } return result; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info( name and creator) about the specified counting - semaphore. - - Returns: OS_SUCCESS ----------------------------------------------------------------------------------------*/ +} /* end OS_CountSemTimedWait_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemGetInfo_Impl (uint32 sem_id, OS_count_sem_prop_t *count_prop) { int sval; @@ -2033,33 +1959,35 @@ int32 OS_CountSemGetInfo_Impl (uint32 sem_id, OS_count_sem_prop_t *count_prop) /* put the info into the stucture */ count_prop -> value = sval; return OS_SUCCESS; -} /* end OS_CountSemGetInfo */ +} /* end OS_CountSemGetInfo_Impl */ /**************************************************************************************** MUTEX API ***************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_Posix_MutexAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_Posix_MutexAPI_Impl_Init(void) { memset(OS_impl_mut_sem_table, 0, sizeof(OS_impl_mut_sem_table)); return OS_SUCCESS; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemCreate - - Purpose: Creates a mutex semaphore initially full. +} /* end OS_Posix_MutexAPI_Impl_Init */ - Returns: 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 - OS_SUCCESS if success - - Notes: the options parameter is not used in this implementation - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemCreate_Impl (uint32 sem_id, uint32 options) { int return_code; @@ -2111,21 +2039,17 @@ int32 OS_MutSemCreate_Impl (uint32 sem_id, uint32 options) } return OS_SUCCESS; -}/* end OS_MutexSemCreate */ - -/*-------------------------------------------------------------------------------------- - Name: OS_MutSemDelete - - Purpose: Deletes the specified Mutex Semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid mutex - OS_SEM_FAILURE if the OS call failed - OS_SUCCESS if success - - Notes: The mutex must be full to take it, so we have to check for fullness - ----------------------------------------------------------------------------------------*/ +} /* end OS_MutSemCreate_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemDelete_Impl (uint32 sem_id) { int status; @@ -2139,24 +2063,17 @@ int32 OS_MutSemDelete_Impl (uint32 sem_id) return OS_SUCCESS; -}/* end OS_MutSemDelete */ - -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemGive - - Purpose: The function releases the mutex object referenced by sem_id.The - manner in which a mutex is released is dependent upon the mutex's type - attribute. If there are threads blocked on the mutex object referenced by - mutex when this function is called, resulting in the mutex becoming - available, the scheduling policy shall determine which thread shall - acquire the mutex. - - Returns: OS_SUCCESS if success - OS_SEM_FAILURE if the semaphore was not previously initialized - OS_ERR_INVALID_ID if the id passed in is not a valid mutex - ----------------------------------------------------------------------------------------*/ +} /* end OS_MutSemDelete_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemGive_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemGive_Impl ( uint32 sem_id ) { int status; @@ -2171,22 +2088,17 @@ int32 OS_MutSemGive_Impl ( uint32 sem_id ) } return OS_SUCCESS; -} /* end OS_MutSemGive */ +} /* end OS_MutSemGive_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemTake - - Purpose: The mutex object referenced by sem_id shall be locked by calling this - function. If the mutex is already locked, the calling thread shall - block until the mutex becomes available. This operation shall return - with the mutex object referenced by mutex in the locked state with the - calling thread as its owner. - - Returns: OS_SUCCESS if success - 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 ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemTake_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemTake_Impl ( uint32 sem_id ) { int status; @@ -2201,236 +2113,154 @@ int32 OS_MutSemTake_Impl ( uint32 sem_id ) } return OS_SUCCESS; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info( name and creator) about the specified mutex - semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid semaphore - OS_INVALID_POINTER if the mut_prop pointer is null - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ +} /* end OS_MutSemTake_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemGetInfo_Impl (uint32 sem_id, OS_mut_sem_prop_t *mut_prop) { return OS_SUCCESS; -} /* end OS_MutSemGetInfo */ +} /* end OS_MutSemGetInfo_Impl */ /**************************************************************************************** INT API ***************************************************************************************/ -/*--------------------------------------------------------------------------------------- - * Name: OS_IntAttachHandler - * - * Purpose: - * The call associates a specified C routine to a specified interrupt - * number.Upon occurring of the InterruptNumber , the InerruptHandler - * routine will be called and passed the parameter. - * - * Assumptions and Notes: - * - * Parameters: - * InterruptNumber : The Interrupt Number that will cause the start of - * the ISR - * InerruptHandler : The ISR associatd with this interrupt - * parameter :The parameter that is passed to the ISR + +/*---------------------------------------------------------------- * - * Global Inputs: None + * Function: OS_IntAttachHandler_Impl * - * Global Outputs: None + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * - * Return Values: - * OS_SUCCESS on success - * OS_INVALID_POINTER if the Interrupt handler pointer is NULL ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_IntAttachHandler_Impl (uint32 InterruptNumber, osal_task_entry InterruptHandler, int32 parameter) { return(OS_ERR_NOT_IMPLEMENTED); -} +} /* end OS_IntAttachHandler_Impl */ -/*--------------------------------------------------------------------------------------- - * Name: OS_IntUnlock - * Purpose: - * Enable the interrupts. - * - * Assumptions and Notes: - * - * Parameters: - * - * Global Inputs: None + +/*---------------------------------------------------------------- * - * Global Outputs: None + * Function: OS_IntUnlock_Impl * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Return Values: - * OS_SUCCESS ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_IntUnlock_Impl (int32 IntLevel) { return(OS_ERR_NOT_IMPLEMENTED); -} +} /* end OS_IntUnlock_Impl */ -/*--------------------------------------------------------------------------------------- - * Name: OS_Intlock - * Purpose: - * Disable the interrupts. - * - * Assumptions and Notes: - * - * Parameters: - * - * Global Inputs: None + +/*---------------------------------------------------------------- * - * Global Outputs: None + * Function: OS_IntLock_Impl * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Return Values: - * OS_SUCCESS ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_IntLock_Impl ( void ) { return(OS_ERR_NOT_IMPLEMENTED); -} -/*--------------------------------------------------------------------------------------- - * Name: OS_IntEnable - * Purpose: - * Enables interrupts through Level - * - * Assumptions and Notes: - * - * Parameters: - * Level - the interrupts to enable - * - * Global Inputs: None +} /* end OS_IntLock_Impl */ + +/*---------------------------------------------------------------- * - * Global Outputs: None + * Function: OS_IntEnable_Impl * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Return Values: - * OS_SUCCESS ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_IntEnable_Impl(int32 Level) { return(OS_ERR_NOT_IMPLEMENTED); -} +} /* end OS_IntEnable_Impl */ -/*--------------------------------------------------------------------------------------- - * Name: OS_IntDisable - * Purpose: - * Disables interrupts through Level - * - * Assumptions and Notes: - * - * Parameters: - * Level - the interrupts to disable - * - * Global Inputs: None + +/*---------------------------------------------------------------- * - * Global Outputs: None + * Function: OS_IntDisable_Impl * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Return Values: - * OS_SUCCESS ----------------------------------------------------------------------------------------*/ - + *-----------------------------------------------------------------*/ int32 OS_IntDisable_Impl(int32 Level) { return(OS_ERR_NOT_IMPLEMENTED); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_HeapGetInfo - - Purpose: Return current info on the heap +} /* end OS_IntDisable_Impl */ - Parameters: - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_HeapGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_HeapGetInfo_Impl(OS_heap_prop_t *heap_prop) { /* ** Not implemented yet */ return (OS_ERR_NOT_IMPLEMENTED); -} +} /* end OS_HeapGetInfo_Impl */ -/*--------------------------------------------------------------------------------------- - * Name: OS_SetMask - * Purpose: - * Set the masking register to mask and unmask interrupts - * - * Assumptions and Notes: - * HW interrupt control is not supported from a user task - * - * Parameters: - * MaskSetting :the value to be written into the mask register + +/*---------------------------------------------------------------- * - * Global Inputs: None + * Function: OS_IntSetMask_Impl * - * Global Outputs: None + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * - * Return Values: - * ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_IntSetMask_Impl ( uint32 MaskSetting ) { return(OS_ERR_NOT_IMPLEMENTED); -} +} /* end OS_IntSetMask_Impl */ -/*-------------------------------------------------------------------------------------- - * Name: OS_GetMask - * Purpose: - * Read and report the setting of the cpu mask register. - * - * Assumptions and Notes: - * HW interrupt control is not supported from a user task - * - * Parameters: - * MaskSettingPtr : pointer to a location where the function store the - * reading of the cpu mask register. + +/*---------------------------------------------------------------- * - * Global Inputs: None + * Function: OS_IntGetMask_Impl * - * Global Outputs: None + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * - * Return Values: - * ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_IntGetMask_Impl ( uint32 * MaskSettingPtr ) { *MaskSettingPtr = 0; return(OS_ERR_NOT_IMPLEMENTED); -} +} /* end OS_IntGetMask_Impl */ -/*--------------------------------------------------------------------------------------- - * Name: OS_CompAbsDelayTime +/*---------------------------------------------------------------- + * + * Function: OS_CompAbsDelayTime + * + * Purpose: Local helper function * - * Purpose: * This function accept time interval, msecs, as an input and * computes the absolute time at which this time interval will expire. * The absolute time is programmed into a struct. * - * Assumptions and Notes: - * - * Parameters: - * - * Global Inputs: None - * - * Global Outputs: None - * - * - * Return Values: OS_SUCCESS, ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ void OS_CompAbsDelayTime( uint32 msecs, struct timespec * tm) { clock_gettime( CLOCK_REALTIME, tm ); @@ -2445,7 +2275,7 @@ void OS_CompAbsDelayTime( uint32 msecs, struct timespec * tm) tm->tv_nsec -= 1000000000L ; tm->tv_sec ++ ; } -} +} /* end OS_CompAbsDelayTime */ /*---------------------------------------------------------------------------- * Name: OS_PriorityRemap @@ -2456,7 +2286,6 @@ void OS_CompAbsDelayTime( uint32 msecs, struct timespec * tm) * to be within the range of [0,OS_MAX_TASK_PRIORITY] * ----------------------------------------------------------------------------*/ - static int OS_PriorityRemap(uint32 InputPri) { int OutputPri; @@ -2488,9 +2317,16 @@ static int OS_PriorityRemap(uint32 InputPri) } return OutputPri; -}/*end OS_PriortyRemap*/ - - +} /* end OS_PriorityRemap */ + +/*---------------------------------------------------------------- + * + * Function: OS_FPUExcAttachHandler_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FPUExcAttachHandler_Impl(uint32 ExceptionNumber, void * ExceptionHandler, int32 parameter) { @@ -2498,50 +2334,66 @@ int32 OS_FPUExcAttachHandler_Impl(uint32 ExceptionNumber, void * ExceptionHandle ** Not implemented in linux. */ return(OS_ERR_NOT_IMPLEMENTED); -} - +} /* end OS_FPUExcAttachHandler_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_FPUExcEnable_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FPUExcEnable_Impl(int32 ExceptionNumber) { /* ** Not implemented in linux. */ return(OS_SUCCESS); -} - +} /* end OS_FPUExcEnable_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_FPUExcDisable_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FPUExcDisable_Impl(int32 ExceptionNumber) { /* ** Not implemented in linux. */ return(OS_SUCCESS); -} +} /* end OS_FPUExcDisable_Impl */ -/* + +/*---------------------------------------------------------------- * - * Name: OS_FPUExcSetMask + * Function: OS_FPUExcSetMask_Impl * - * Purpose: This function sets the FPU exception mask + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Notes: 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. - */ + *-----------------------------------------------------------------*/ int32 OS_FPUExcSetMask_Impl(uint32 mask) { /* ** Not implemented in linux. */ return(OS_SUCCESS); -} +} /* end OS_FPUExcSetMask_Impl */ -/* + +/*---------------------------------------------------------------- * - * Name: OS_FPUExcGetMask + * Function: OS_FPUExcGetMask_Impl * - * Purpose: This function gets the FPU exception mask + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Notes: 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. - */ + *-----------------------------------------------------------------*/ int32 OS_FPUExcGetMask_Impl(uint32 *mask) { /* @@ -2549,7 +2401,7 @@ int32 OS_FPUExcGetMask_Impl(uint32 *mask) */ *mask = 0; return(OS_SUCCESS); -} +} /* end OS_FPUExcGetMask_Impl */ /********************************************************************/ /* CONSOLE OUTPUT */ @@ -2557,8 +2409,15 @@ int32 OS_FPUExcGetMask_Impl(uint32 *mask) /* use the portable version of OS_ConsoleWrite_Impl() */ #include "../portable/os-impl-console-directwrite.c" - - + +/*---------------------------------------------------------------- + * + * Function: OS_ConsoleWakeup_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_ConsoleWakeup_Impl(uint32 local_id) { OS_impl_console_internal_record_t *local = &OS_impl_console_table[local_id]; @@ -2573,8 +2432,16 @@ void OS_ConsoleWakeup_Impl(uint32 local_id) /* output directly */ OS_ConsoleOutput_Impl(local_id); } -} +} /* end OS_ConsoleWakeup_Impl */ +/*---------------------------------------------------------------- + * + * Function: OS_ConsoleTask_Entry + * + * Purpose: Local Helper function + * Implements the console output task + * + *-----------------------------------------------------------------*/ static void* OS_ConsoleTask_Entry(void* arg) { OS_U32ValueWrapper_t local_arg; @@ -2588,8 +2455,16 @@ static void* OS_ConsoleTask_Entry(void* arg) sem_wait(&local->data_sem); } return NULL; -} - +} /* end OS_ConsoleTask_Entry */ + +/*---------------------------------------------------------------- + * + * Function: OS_ConsoleCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ConsoleCreate_Impl(uint32 local_id) { OS_impl_console_internal_record_t *local = &OS_impl_console_table[local_id]; @@ -2629,5 +2504,5 @@ int32 OS_ConsoleCreate_Impl(uint32 local_id) } return return_code; -} +} /* end OS_ConsoleCreate_Impl */ diff --git a/src/os/posix/osfileapi.c b/src/os/posix/osfileapi.c index 75a040094..140a705a4 100644 --- a/src/os/posix/osfileapi.c +++ b/src/os/posix/osfileapi.c @@ -123,7 +123,7 @@ int32 OS_Posix_StreamAPI_Impl_Init(void) OS_IMPL_SELF_EGID = getegid(); return OS_SUCCESS; -} +} /* end OS_Posix_StreamAPI_Impl_Init */ /* -------------------------------------------------------------------------------------- Name: OS_Posix_DirAPI_Impl_Init @@ -136,19 +136,19 @@ int32 OS_Posix_DirAPI_Impl_Init(void) { memset(OS_impl_dir_table, 0, sizeof(OS_impl_dir_table)); return OS_SUCCESS; -} +} /* end OS_Posix_DirAPI_Impl_Init */ -/* -------------------------------------------------------------------------------------- - Name: OS_ShellOutputToFile - - Purpose: Takes a shell command in and writes the output of that command to the specified file - - Returns: OS_FS_ERROR if the command was not executed properly - OS_FS_ERR_INVALID_FD if the file descriptor passed in is invalid - OS_SUCCESS if success - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ShellOutputToFile_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ShellOutputToFile_Impl(uint32 file_id, const char* Cmd) { pid_t cpid; @@ -200,5 +200,5 @@ int32 OS_ShellOutputToFile_Impl(uint32 file_id, const char* Cmd) } return OS_SUCCESS; -}/* end OS_ShellOutputToFile */ +} /* end OS_ShellOutputToFile_Impl */ diff --git a/src/os/posix/osfilesys.c b/src/os/posix/osfilesys.c index 54cd4f85c..1a02a14dd 100644 --- a/src/os/posix/osfilesys.c +++ b/src/os/posix/osfilesys.c @@ -63,21 +63,22 @@ int32 OS_Posix_FileSysAPI_Impl_Init(void) { return OS_SUCCESS; -} +} /* end OS_Posix_FileSysAPI_Impl_Init */ /* * System Level API */ -/*--------------------------------------------------------------------------------------- - Name: OS_FileSysStartVolume_Impl - - Purpose: Starts/Registers a file system on the target - - Returns: OS_FS_SUCCESS on creating the disk - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysStartVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysStartVolume_Impl (uint32 filesys_id) { OS_filesys_internal_record_t *local = &OS_filesys_table[filesys_id]; @@ -161,14 +162,14 @@ int32 OS_FileSysStartVolume_Impl (uint32 filesys_id) } /* end OS_FileSysStartVolume_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_FileSysStopVolume_Impl - - Purpose: Stops/Unregisters a file system on the target - - Returns: OS_FS_SUCCESS on creating the disk - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_FileSysStopVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysStopVolume_Impl (uint32 filesys_id) { /* @@ -182,16 +183,16 @@ int32 OS_FileSysStopVolume_Impl (uint32 filesys_id) */ return OS_SUCCESS; -} /* end OS_FileSysStartVolume_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_FileSysFormatVolume_Impl +} /* end OS_FileSysStopVolume_Impl */ - Purpose: Formats a file system on the target to prepare it for use - - Returns: OS_FS_SUCCESS on creating the disk - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_FileSysFormatVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysFormatVolume_Impl (uint32 filesys_id) { /* @@ -205,17 +206,17 @@ int32 OS_FileSysFormatVolume_Impl (uint32 filesys_id) */ return OS_SUCCESS; -} /* end OS_FileSysStartVolume_Impl */ - - -/*-------------------------------------------------------------------------------------- - Name: OS_mount +} /* end OS_FileSysFormatVolume_Impl */ - Purpose: mounts a drive. - - Returns: OS_FS_SUCCESS if success ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_FileSysMountVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysMountVolume_Impl (uint32 filesys_id) { OS_filesys_internal_record_t *local = &OS_filesys_table[filesys_id]; @@ -261,16 +262,16 @@ int32 OS_FileSysMountVolume_Impl (uint32 filesys_id) return OS_FS_SUCCESS; -}/* end OS_mount */ - -/*-------------------------------------------------------------------------------------- - Name: OS_FileSysUnmountVolume_Impl - - Purpose: unmounts a drive. - - Returns: OS_FS_SUCCESS if success ----------------------------------------------------------------------------------------*/ +} /* end OS_FileSysMountVolume_Impl */ +/*---------------------------------------------------------------- + * + * Function: OS_FileSysUnmountVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysUnmountVolume_Impl (uint32 filesys_id) { /* @@ -282,15 +283,16 @@ int32 OS_FileSysUnmountVolume_Impl (uint32 filesys_id) */ return OS_FS_SUCCESS; -}/* end OS_umount */ - -/*-------------------------------------------------------------------------------------- - Name: OS_FileSysStatVolume_Impl +} /* end OS_FileSysUnmountVolume_Impl */ - Purpose: Returns stats about a volume - - Returns: OS_FS_SUCCESS or OS_FS_ERROR if the OS call failed ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_FileSysStatVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysStatVolume_Impl (uint32 filesys_id, OS_statvfs_t *result) { OS_filesys_internal_record_t *local = &OS_filesys_table[filesys_id]; @@ -298,7 +300,7 @@ int32 OS_FileSysStatVolume_Impl (uint32 filesys_id, OS_statvfs_t *result) if ( statvfs(local->system_mountpt, &stat_buf) != 0 ) { - return OS_FS_ERROR; + return OS_ERROR; } result->block_size = stat_buf.f_bsize; @@ -306,19 +308,19 @@ int32 OS_FileSysStatVolume_Impl (uint32 filesys_id, OS_statvfs_t *result) result->total_blocks = stat_buf.f_blocks; return(OS_FS_SUCCESS); -}/* end OS_fsBlocksFree */ - +} /* end OS_FileSysStatVolume_Impl */ -/*-------------------------------------------------------------------------------------- - Name: OS_FileSysCheckVolume_Impl - Purpose: Checks the drives for inconsisenties and either repairs it or not - - Returns: OS_FS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_FileSysCheckVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysCheckVolume_Impl (uint32 filesys_id, bool repair) { - return OS_FS_UNIMPLEMENTED; -}/* end OS_FileSysCheckVolume_Impl */ + return OS_ERR_NOT_IMPLEMENTED; +} /* end OS_FileSysCheckVolume_Impl */ diff --git a/src/os/posix/osloader.c b/src/os/posix/osloader.c index 4256c4f66..f74e1520f 100644 --- a/src/os/posix/osloader.c +++ b/src/os/posix/osloader.c @@ -31,17 +31,15 @@ */ #include "../portable/os-impl-posix-dl.c" -/*-------------------------------------------------------------------------------------- - Name: OS_ModuleInfo - - Purpose: Returns information about the loadable module - - Parameters: - - Returns: OS_ERR_INVALID_ID if the module id invalid - OS_INVALID_POINTER if the pointer to the ModuleInfo structure is invalid - OS_SUCCESS if the module info was filled out successfuly ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ModuleGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ModuleGetInfo_Impl ( uint32 module_id, OS_module_prop_t *module_prop ) { /* @@ -51,25 +49,22 @@ int32 OS_ModuleGetInfo_Impl ( uint32 module_id, OS_module_prop_t *module_prop ) */ return(OS_SUCCESS); -}/* end OS_ModuleInfo */ - +} /* end OS_ModuleGetInfo_Impl */ -/*-------------------------------------------------------------------------------------- - Name: OS_SymbolTableDump_Impl - Purpose: Dumps the system symbol table to a file - - Parameters: - - Returns: OS_ERROR if the symbol table could not be read or dumped - OS_INVALID_FILE if the file could not be opened or written - OS_SUCCESS if the symbol is found ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SymbolTableDump_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SymbolTableDump_Impl ( const char *filename, uint32 SizeLimit ) { return(OS_ERR_NOT_IMPLEMENTED); -}/* end OS_SymbolTableDump */ - +} /* end OS_SymbolTableDump_Impl */ diff --git a/src/os/posix/osnetwork.c b/src/os/posix/osnetwork.c index b7bfba80d..4a07b1989 100644 --- a/src/os/posix/osnetwork.c +++ b/src/os/posix/osnetwork.c @@ -63,21 +63,20 @@ const int OS_IMPL_SOCKET_FLAGS = O_NONBLOCK; These are specific to this particular operating system ****************************************************************************************/ -/*-------------------------------------------------------------------------------------- - Name: OS_NetworkGetID - - Purpose: Gets the ID of the current Network - - NOTE: This is included here outside the portable bsd socket block - because even though it is a BSD-defined function, it is a historical one - and not all BSD socket implementations actually have it. ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_NetworkGetID_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_NetworkGetID_Impl (int32 *IdBuf) { /* BSD-style gethostid() has no failure modes */ *IdBuf = gethostid(); return OS_SUCCESS; -} +} /* end OS_NetworkGetID_Impl */ #else /* OS_INCLUDE_NETWORK */ diff --git a/src/os/posix/ostimer.c b/src/os/posix/ostimer.c index 825dd5e9a..d3d5ae4e0 100644 --- a/src/os/posix/ostimer.c +++ b/src/os/posix/ostimer.c @@ -78,12 +78,14 @@ OS_impl_timebase_internal_record_t OS_impl_timebase_table[OS_MAX_TIMEBASES]; ***************************************************************************************/ -/****************************************************************************** - ** Function: OS_UsecToTimespec - ** - ** Purpose: Convert Microseconds to a POSIX timespec structure. - ** - */ +/*---------------------------------------------------------------- + * + * Function: OS_UsecToTimespec + * + * Purpose: Local helper routine, not part of OSAL API. + * Convert Microseconds to a POSIX timespec structure. + * + *-----------------------------------------------------------------*/ static void OS_UsecToTimespec(uint32 usecs, struct timespec *time_spec) { @@ -97,18 +99,42 @@ static void OS_UsecToTimespec(uint32 usecs, struct timespec *time_spec) time_spec->tv_sec = usecs / 1000000; time_spec->tv_nsec = (usecs % 1000000) * 1000; } -} - +} /* end OS_UsecToTimespec */ + +/*---------------------------------------------------------------- + * + * Function: OS_TimeBaseLock_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_TimeBaseLock_Impl(uint32 local_id) { pthread_mutex_lock(&OS_impl_timebase_table[local_id].handler_mutex); -} - +} /* end OS_TimeBaseLock_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_TimeBaseUnlock_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_TimeBaseUnlock_Impl(uint32 local_id) { pthread_mutex_unlock(&OS_impl_timebase_table[local_id].handler_mutex); -} +} /* end OS_TimeBaseUnlock_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_TimeBase_SoftWaitImpl + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ static uint32 OS_TimeBase_SoftWaitImpl(uint32 timer_id) { int ret; @@ -171,7 +197,7 @@ static uint32 OS_TimeBase_SoftWaitImpl(uint32 timer_id) while (ret != 0); return interval_time; -} +} /* end OS_TimeBase_SoftWaitImpl */ /**************************************************************************************** @@ -293,7 +319,7 @@ int32 OS_Posix_TimeBaseAPI_Impl_Init(void) return(return_code); -} +} /* end OS_Posix_TimeBaseAPI_Impl_Init */ /**************************************************************************************** Time Base API @@ -308,15 +334,14 @@ static void *OS_TimeBasePthreadEntry(void *arg) return NULL; } -/****************************************************************************** - * Function: OS_TimeBaseCreate +/*---------------------------------------------------------------- * - * Purpose: Create a new OSAL Time base + * Function: OS_TimeBaseCreate_Impl * - * Arguments: + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Return: - */ + *-----------------------------------------------------------------*/ int32 OS_TimeBaseCreate_Impl(uint32 timer_id) { int32 return_code; @@ -447,19 +472,16 @@ int32 OS_TimeBaseCreate_Impl(uint32 timer_id) } return return_code; -} +} /* end OS_TimeBaseCreate_Impl */ -/****************************************************************************** - * Function: OS_TimeBaseSet +/*---------------------------------------------------------------- * - * Purpose: + * Function: OS_TimeBaseSet_Impl * - * Arguments: - * (none) + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Return: - * (none) - */ + *-----------------------------------------------------------------*/ int32 OS_TimeBaseSet_Impl(uint32 timer_id, int32 start_time, int32 interval_time) { OS_impl_timebase_internal_record_t *local; @@ -505,20 +527,18 @@ int32 OS_TimeBaseSet_Impl(uint32 timer_id, int32 start_time, int32 interval_time local->reset_flag = (return_code == OS_SUCCESS); return return_code; -} +} /* end OS_TimeBaseSet_Impl */ -/****************************************************************************** - * Function: OS_TimerDelete + +/*---------------------------------------------------------------- * - * Purpose: + * Function: OS_TimeBaseDelete_Impl * - * Arguments: - * (none) + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Return: - * (none) - */ + *-----------------------------------------------------------------*/ int32 OS_TimeBaseDelete_Impl(uint32 timer_id) { OS_impl_timebase_internal_record_t *local; @@ -544,23 +564,22 @@ int32 OS_TimeBaseDelete_Impl(uint32 timer_id) } return OS_SUCCESS; -} +} /* end OS_TimeBaseDelete_Impl */ -/*************************************************************************************** - * Name: OS_TimerGetInfo + +/*---------------------------------------------------------------- * - * Purpose: This function will pass back a pointer to structure that contains - * all of the relevant info( name and creator) about the specified timer. + * Function: OS_TimeBaseGetInfo_Impl * - * Returns: OS_ERR_INVALID_ID if the id passed in is not a valid timer - * OS_INVALID_POINTER if the timer_prop pointer is null - * OS_SUCCESS if success - */ + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TimeBaseGetInfo_Impl (uint32 timer_id, OS_timebase_prop_t *timer_prop) { return OS_SUCCESS; -} /* end OS_TimerGetInfo */ +} /* end OS_TimeBaseGetInfo_Impl */ /**************************************************************************************** Other Time-Related API Implementation diff --git a/src/os/rtems/osapi.c b/src/os/rtems/osapi.c index ad4e47d73..56ce59f83 100644 --- a/src/os/rtems/osapi.c +++ b/src/os/rtems/osapi.c @@ -148,8 +148,15 @@ enum const OS_ErrorTable_Entry_t OS_IMPL_ERROR_NAME_TABLE[] = { { 0, NULL } }; RTEMS_GlobalVars_t RTEMS_GlobalVars = { 0 }; - - + +/*---------------------------------------------------------------- + * + * Function: OS_Lock_Global_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_Lock_Global_Impl(uint32 idtype) { rtems_id *mut; @@ -174,8 +181,16 @@ int32 OS_Lock_Global_Impl(uint32 idtype) } return OS_SUCCESS; -} - +} /* end OS_Lock_Global_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_Unlock_Global_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_Unlock_Global_Impl(uint32 idtype) { rtems_id *mut; @@ -200,7 +215,7 @@ int32 OS_Unlock_Global_Impl(uint32 idtype) } return OS_SUCCESS; -} +} /* end OS_Unlock_Global_Impl */ @@ -278,30 +293,32 @@ int32 OS_API_Impl_Init(uint32 idtype) return(return_code); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_IdleLoop - - Purpose: Wait for external events. +} /* end OS_API_Impl_Init */ - returns: no value ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_IdleLoop_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_IdleLoop_Impl() { RTEMS_GlobalVars.IdleTaskId = rtems_task_self(); rtems_task_suspend(RTEMS_SELF); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_ApplicationShutdown_Impl - - Purpose: Ensures that the thread waiting in OS_IdleLoop_Impl is waken up +} /* end OS_IdleLoop_Impl */ - returns: no value - - NOTE: Might be called from an ISR/signal handler ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ApplicationShutdown_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_ApplicationShutdown_Impl() { /* Note that setting the IdleTaskId and suspending @@ -309,7 +326,7 @@ void OS_ApplicationShutdown_Impl() * is a remote chance that this could attempt to * resume a task that is not yet suspended. */ rtems_task_resume(RTEMS_GlobalVars.IdleTaskId); -} +} /* end OS_ApplicationShutdown_Impl */ @@ -324,7 +341,7 @@ void OS_ApplicationShutdown_Impl() static rtems_task OS_RtemsEntry(rtems_task_argument arg) { OS_TaskEntryPoint((uint32)arg); -} +} /* end OS_RtemsEntry */ @@ -332,30 +349,29 @@ static rtems_task OS_RtemsEntry(rtems_task_argument arg) TASK API ***************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_Rtems_TaskAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_Rtems_TaskAPI_Impl_Init(void) { memset(OS_impl_task_table, 0, sizeof(OS_impl_task_table)); return (OS_SUCCESS); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskCreate - - Purpose: Creates a task and starts running it. - - returns: 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 the operating system calls fail - OS_SUCCESS if success - - NOTES: task_id is passed back to the user as the ID. stack_pointer is usually null. - - ----------------------------------------------------------------------------------------*/ +} /* end OS_Rtems_TaskAPI_Impl_Init */ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskCreate_Impl (uint32 task_id, uint32 flags) { rtems_status_code status; @@ -411,18 +427,17 @@ int32 OS_TaskCreate_Impl (uint32 task_id, uint32 flags) return OS_SUCCESS; -} /* end OS_TaskCreate */ - -/*-------------------------------------------------------------------------------------- - Name: OS_TaskDelete - - Purpose: Deletes the specified Task and removes it from the OS_task_table. - - returns: OS_ERR_INVALID_ID if the ID given to it is invalid - OS_ERROR if the OS delete call fails - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ +} /* end OS_TaskCreate_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskDelete_Impl (uint32 task_id) { /* @@ -434,29 +449,32 @@ int32 OS_TaskDelete_Impl (uint32 task_id) rtems_task_delete(OS_impl_task_table[task_id].id); return OS_SUCCESS; -}/* end OS_TaskDelete */ - -/*-------------------------------------------------------------------------------------- - Name: OS_TaskExit +} /* end OS_TaskDelete_Impl */ - Purpose: Exits the calling task and removes it from the OS_task_table. - - returns: Nothing ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskExit_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_TaskExit_Impl() { rtems_task_delete(RTEMS_SELF); -}/*end OS_TaskExit */ - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskDelay - - Purpose: Delay a task for specified amount of milliseconds +} /* end OS_TaskExit_Impl */ - returns: OS_ERROR if sleep fails - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskDelay_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskDelay_Impl (uint32 milli_second) { rtems_interval ticks; @@ -469,19 +487,17 @@ int32 OS_TaskDelay_Impl (uint32 milli_second) */ return (OS_SUCCESS); -}/* end OS_TaskDelay */ - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskSetPriority - - Purpose: Sets the given task to a new priority +} /* end OS_TaskDelay_Impl */ - returns: 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 - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskSetPriority_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskSetPriority_Impl (uint32 task_id, uint32 new_priority) { rtems_task_priority old_pri; @@ -497,16 +513,17 @@ int32 OS_TaskSetPriority_Impl (uint32 task_id, uint32 new_priority) return OS_SUCCESS; -}/* end OS_TaskSetPriority */ - -/*-------------------------------------------------------------------------------------- - Name: OS_TaskMatch - - Purpose: Determines if the caller matches the given task_id +} /* end OS_TaskSetPriority_Impl */ - returns: OS_ERROR if not a match - OS_SUCCESS if match ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskMatch_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskMatch_Impl(uint32 task_id) { /* @@ -519,18 +536,17 @@ int32 OS_TaskMatch_Impl(uint32 task_id) return OS_SUCCESS; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskRegister - - Purpose: Registers the calling task id with the task by adding the var to the tcb - - Returns: OS_ERR_INVALID_ID if there the specified ID could not be found - OS_ERROR if the OS call fails - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ +} /* end OS_TaskMatch_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskRegister_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskRegister_Impl (uint32 global_task_id) { /* @@ -551,17 +567,17 @@ int32 OS_TaskRegister_Impl (uint32 global_task_id) */ return OS_SUCCESS; -}/* end OS_TaskRegister */ +} /* end OS_TaskRegister_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_TaskGetId - - Purpose: This function returns the OSAL task id of the calling task - - Notes: The OS_task_key is initialized by the task switch if AND ONLY IF the - OS_task_key has been registered via OS_TaskRegister(..). If this is not - called prior to this call, the value will be old and wrong. ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskGetId_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ uint32 OS_TaskGetId_Impl (void) { uint32 global_task_id; @@ -584,53 +600,52 @@ uint32 OS_TaskGetId_Impl (void) return global_task_id; -}/* end OS_TaskGetId */ - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info (creator, stack size, priority, name) about the - specified task. - - Returns: OS_ERR_INVALID_ID if the ID passed to it is invalid - OS_INVALID_POINTER if the task_prop pointer is NULL - OS_SUCCESS if it copied all of the relevant info over +} /* end OS_TaskGetId_Impl */ ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskGetInfo_Impl (uint32 task_id, OS_task_prop_t *task_prop) { task_prop->OStask_id = (uint32) OS_impl_task_table[task_id].id; return OS_SUCCESS; -} /* end OS_TaskGetInfo */ +} /* end OS_TaskGetInfo_Impl */ /**************************************************************************************** MESSAGE QUEUE API ***************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_Rtems_QueueAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_Rtems_QueueAPI_Impl_Init(void) { memset(OS_impl_queue_table, 0, sizeof(OS_impl_queue_table)); return (OS_SUCCESS); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_QueueCreate - - Purpose: Create a message queue which can be refered to by name or ID - - Returns: 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 - OS_SUCCESS if success - - Notes: the flahs parameter is unused. ----------------------------------------------------------------------------------------*/ +} /* end OS_Rtems_QueueAPI_Impl_Init */ + +/*---------------------------------------------------------------- + * + * Function: OS_QueueCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueCreate_Impl (uint32 queue_id, uint32 flags) { rtems_status_code status; @@ -669,20 +684,17 @@ int32 OS_QueueCreate_Impl (uint32 queue_id, uint32 flags) return OS_SUCCESS; -} /* end OS_QueueCreate */ - -/*-------------------------------------------------------------------------------------- - Name: OS_QueueDelete +} /* end OS_QueueCreate_Impl */ - Purpose: Deletes the specified message queue. - - Returns: OS_ERR_INVALID_ID if the id passed in does not exist - OS_ERROR if the OS call to delete the queue fails - OS_SUCCESS if success - - Notes: 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 ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_QueueDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueDelete_Impl (uint32 queue_id) { rtems_status_code status; @@ -697,21 +709,18 @@ int32 OS_QueueDelete_Impl (uint32 queue_id) return OS_SUCCESS; -} /* end OS_QueueDelete */ +} /* end OS_QueueDelete_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_QueueGet - - Purpose: Receive a message on a message queue. Will pend or timeout on the receive. - Returns: OS_ERR_INVALID_ID if the given ID does not exist - OS_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 passed in may be too small for the message - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_QueueGet_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueGet_Impl (uint32 queue_id, void *data, uint32 size, uint32 *size_copied, int32 timeout) { @@ -791,23 +800,17 @@ int32 OS_QueueGet_Impl (uint32 queue_id, void *data, uint32 size, uint32 *size_c } return return_code; -}/* end OS_QueueGet */ - -/*--------------------------------------------------------------------------------------- - Name: OS_QueuePut - - Purpose: Put a message on a message queue. - - Returns: 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 - OS_SUCCESS if SUCCESS - - Notes: The flags parameter is not used. The message put is always configured to - immediately return an error if the receiving message queue is full. ----------------------------------------------------------------------------------------*/ +} /* end OS_QueueGet_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_QueuePut_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_QueuePut_Impl (uint32 queue_id, const void *data, uint32 size, uint32 flags) { rtems_status_code status; @@ -843,53 +846,52 @@ int32 OS_QueuePut_Impl (uint32 queue_id, const void *data, uint32 size, uint32 f return OS_SUCCESS; -}/* end OS_QueuePut */ - -/*--------------------------------------------------------------------------------------- - Name: OS_QueueGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info (name and creator) about the specified queue. - - Returns: 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 ----------------------------------------------------------------------------------------*/ +} /* end OS_QueuePut_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_QueueGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueGetInfo_Impl (uint32 queue_id, OS_queue_prop_t *queue_prop) { /* No extra info for queues in the OS implementation */ return OS_SUCCESS; -} /* end OS_QueueGetInfo */ +} /* end OS_QueueGetInfo_Impl */ + + /**************************************************************************************** SEMAPHORE API ***************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_Rtems_BinSemAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_Rtems_BinSemAPI_Impl_Init(void) { memset(OS_impl_bin_sem_table, 0, sizeof(OS_impl_bin_sem_table)); return (OS_SUCCESS); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemCreate - - Purpose: Creates a binary semaphore with initial value specified by - sem_initial_value and name specified by sem_name. sem_id will be - returned to the caller - - Returns: 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 - OS_SUCCESS if success - - - Notes: options is an unused parameter ----------------------------------------------------------------------------------------*/ +} /* end OS_Rtems_BinSemAPI_Impl_Init */ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemCreate_Impl (uint32 sem_id, uint32 sem_initial_value, uint32 options) { rtems_status_code status; @@ -923,20 +925,18 @@ int32 OS_BinSemCreate_Impl (uint32 sem_id, uint32 sem_initial_value, uint32 opti return OS_SUCCESS; -}/* end OS_BinSemCreate */ - +} /* end OS_BinSemCreate_Impl */ -/*-------------------------------------------------------------------------------------- - Name: OS_BinSemDelete - - Purpose: Deletes the specified Binary Semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid binary semaphore - OS_SEM_FAILURE the OS call failed - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemDelete_Impl (uint32 sem_id) { rtems_status_code status; @@ -950,25 +950,17 @@ int32 OS_BinSemDelete_Impl (uint32 sem_id) return OS_SUCCESS; -}/* end OS_BinSemDelete */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemGive - - Purpose: The function unlocks the semaphore referenced by sem_id by performing - a semaphore unlock operation on that semaphore.If the semaphore value - resulting from this operation is positive, then no threads were blocked - waiting for the semaphore to become unlocked; the semaphore value is - simply incremented for this semaphore. - - - Returns: 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 - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +} /* end OS_BinSemDelete_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemGive_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemGive_Impl (uint32 sem_id) { rtems_status_code status; @@ -981,21 +973,17 @@ int32 OS_BinSemGive_Impl (uint32 sem_id) } return OS_SUCCESS; -}/* end OS_BinSemGive */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemFlush - - Purpose: The function releases all the tasks pending on this semaphore. Note - that the state of the semaphore is not changed by this operation. - - Returns: 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 - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +} /* end OS_BinSemGive_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemFlush_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemFlush_Impl (uint32 sem_id) { rtems_status_code status; @@ -1010,24 +998,17 @@ int32 OS_BinSemFlush_Impl (uint32 sem_id) return OS_SUCCESS; -}/* end OS_BinSemFlush */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemTake - - Purpose: The locks the semaphore referenced by sem_id by performing a - semaphore lock operation on that semaphore.If the semaphore value - is currently zero, then the calling thread shall not return from - the call until it either locks the semaphore or the call is - interrupted by a signal. - - Return: OS_ERR_INVALID_ID : the semaphore was not previously initialized - or is not in the array of semaphores defined by the system - OS_SEM_FAILURE if the OS call failed and the semaphore is not obtained - OS_SUCCESS if success - -----------------------------------------------------------------------------------------*/ +} /* end OS_BinSemFlush_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemTake_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemTake_Impl (uint32 sem_id) { rtems_status_code status; @@ -1049,22 +1030,16 @@ int32 OS_BinSemTake_Impl (uint32 sem_id) return OS_SUCCESS; -}/* end OS_BinSemTake */ -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemTimedWait - - Purpose: The function locks the semaphore referenced by sem_id . However, - if the semaphore cannot be locked without waiting for another process - or thread to unlock the semaphore , this wait shall be terminated when - the specified timeout ,msecs, expires. - - Returns: OS_SEM_TIMEOUT if semaphore was not relinquished in time - OS_SUCCESS if success - 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 -----------------------------------------------------------------------------------------*/ - +} /* end OS_BinSemTake_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemTimedWait_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemTimedWait_Impl (uint32 sem_id, uint32 msecs) { rtems_status_code status; @@ -1088,51 +1063,48 @@ int32 OS_BinSemTimedWait_Impl (uint32 sem_id, uint32 msecs) return OS_SUCCESS; -}/* end OS_BinSemTimedWait */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info( name and creator) about the specified binary - semaphore. - - Returns: 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 ----------------------------------------------------------------------------------------*/ +} /* end OS_BinSemTimedWait_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemGetInfo_Impl (uint32 sem_id, OS_bin_sem_prop_t *bin_prop) { /* RTEMS has no API for obtaining the current value of a semaphore */ return OS_SUCCESS; -} /* end OS_BinSemGetInfo */ +} /* end OS_BinSemGetInfo_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_Rtems_CountSemAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_Rtems_CountSemAPI_Impl_Init(void) { memset(OS_impl_count_sem_table, 0, sizeof(OS_impl_count_sem_table)); return (OS_SUCCESS); -} - - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemCreate +} /* end OS_Rtems_CountSemAPI_Impl_Init */ - Purpose: Creates a countary semaphore with initial value specified by - sem_initial_value and name specified by sem_name. sem_id will be - returned to the caller - - Returns: 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 countary semaphore - OS_SEM_FAILURE if the OS call failed - OS_SUCCESS if success - - Notes: options is an unused parameter ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemCreate_Impl (uint32 sem_id, uint32 sem_initial_value, uint32 options) { rtems_status_code status; @@ -1166,19 +1138,17 @@ int32 OS_CountSemCreate_Impl (uint32 sem_id, uint32 sem_initial_value, uint32 op return OS_SUCCESS; -}/* end OS_CountSemCreate */ - -/*-------------------------------------------------------------------------------------- - Name: OS_CountSemDelete - - Purpose: Deletes the specified Counting Semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid countary semaphore - OS_SEM_FAILURE the OS call failed - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +} /* end OS_CountSemCreate_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemDelete_Impl (uint32 sem_id) { rtems_status_code status; @@ -1192,25 +1162,17 @@ int32 OS_CountSemDelete_Impl (uint32 sem_id) return OS_SUCCESS; -}/* end OS_CountSemDelete */ - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemGive - - Purpose: The function unlocks the semaphore referenced by sem_id by performing - a semaphore unlock operation on that semaphore.If the semaphore value - resulting from this operation is positive, then no threads were blocked - waiting for the semaphore to become unlocked; the semaphore value is - simply incremented for this semaphore. - - - Returns: 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 countary semaphore - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +} /* end OS_CountSemDelete_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemGive_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemGive_Impl (uint32 sem_id) { rtems_status_code status; @@ -1224,25 +1186,17 @@ int32 OS_CountSemGive_Impl (uint32 sem_id) return(OS_SUCCESS); -}/* end OS_CountSemGive */ - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemTake - - Purpose: The locks the semaphore referenced by sem_id by performing a - semaphore lock operation on that semaphore.If the semaphore value - is currently zero, then the calling thread shall not return from - the call until it either locks the semaphore or the call is - interrupted by a signal. - - Return: 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 the Id passed in is not a valid countar semaphore - OS_SEM_FAILURE if the OS call failed - OS_SUCCESS if success - -----------------------------------------------------------------------------------------*/ +} /* end OS_CountSemGive_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemTake_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemTake_Impl (uint32 sem_id) { rtems_status_code status; @@ -1256,24 +1210,18 @@ int32 OS_CountSemTake_Impl (uint32 sem_id) return OS_SUCCESS; -}/* end OS_CountSemTake */ - - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemTimedWait - - Purpose: The function locks the semaphore referenced by sem_id . However, - if the semaphore cannot be locked without waiting for another process - or thread to unlock the semaphore , this wait shall be terminated when - the specified timeout ,msecs, expires. +} /* end OS_CountSemTake_Impl */ - Returns: OS_SEM_TIMEOUT if semaphore was not relinquished in time - OS_SUCCESS if success - 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 -----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemTimedWait_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemTimedWait_Impl (uint32 sem_id, uint32 msecs) { rtems_status_code status; @@ -1295,54 +1243,52 @@ int32 OS_CountSemTimedWait_Impl (uint32 sem_id, uint32 msecs) return OS_SUCCESS; -}/* end OS_CountSemTimedWait */ - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info( name and creator) about the specified countary - semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid semaphore - OS_INVALID_POINTER if the count_prop pointer is null - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ +} /* end OS_CountSemTimedWait_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemGetInfo_Impl (uint32 sem_id, OS_count_sem_prop_t *count_prop) { /* RTEMS does not provide an API to get the value */ return OS_SUCCESS; -} /* end OS_CountSemGetInfo */ +} /* end OS_CountSemGetInfo_Impl */ /**************************************************************************************** MUTEX API ***************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_Rtems_MutexAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_Rtems_MutexAPI_Impl_Init(void) { memset(OS_impl_mut_sem_table, 0, sizeof(OS_impl_mut_sem_table)); return (OS_SUCCESS); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemCreate - - Purpose: Creates a mutex semaphore initially full. - - Returns: 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 - OS_SUCCESS if success - - Notes: the options parameter is not used in this implementation - ----------------------------------------------------------------------------------------*/ +} /* end OS_Rtems_MutexAPI_Impl_Init */ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemCreate_Impl (uint32 sem_id, uint32 options) { rtems_status_code status; @@ -1365,19 +1311,17 @@ int32 OS_MutSemCreate_Impl (uint32 sem_id, uint32 options) return OS_SUCCESS; -}/* end OS_MutSemCreate */ - -/*-------------------------------------------------------------------------------------- - Name: OS_MutSemDelete - - Purpose: Deletes the specified Mutex Semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid mutex - OS_SEM_FAILURE if the OS call failed - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +} /* end OS_MutSemCreate_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemDelete_Impl (uint32 sem_id) { rtems_status_code status; @@ -1392,25 +1336,18 @@ int32 OS_MutSemDelete_Impl (uint32 sem_id) return OS_SUCCESS; -}/* end OS_MutSemDelete */ - - -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemGive - - Purpose: The function releases the mutex object referenced by sem_id.The - manner in which a mutex is released is dependent upon the mutex's type - attribute. If there are threads blocked on the mutex object referenced by - mutex when this function is called, resulting in the mutex becoming - available, the scheduling policy shall determine which thread shall - acquire the mutex. +} /* end OS_MutSemDelete_Impl */ - Returns: OS_SUCCESS if success - OS_SEM_FAILURE if the semaphore was not previously initialized - OS_ERR_INVALID_ID if the id passed in is not a valid mutex - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemGive_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemGive_Impl (uint32 sem_id) { rtems_status_code status; @@ -1426,22 +1363,17 @@ int32 OS_MutSemGive_Impl (uint32 sem_id) return OS_SUCCESS; -}/* end OS_MutSemGive */ +} /* end OS_MutSemGive_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemTake - - Purpose: The mutex object referenced by sem_id shall be locked by calling this - function. If the mutex is already locked, the calling thread shall - block until the mutex becomes available. This operation shall return - with the mutex object referenced by mutex in the locked state with the - calling thread as its owner. - - Returns: OS_SUCCESS if success - 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 ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemTake_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemTake_Impl (uint32 sem_id) { rtems_status_code status; @@ -1456,26 +1388,23 @@ int32 OS_MutSemTake_Impl (uint32 sem_id) return OS_SUCCESS; -}/* end OS_MutSemGive */ - -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info( name and creator) about the specified mutex - semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid semaphore - OS_INVALID_POINTER if the mut_prop pointer is null - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ +} /* end OS_MutSemTake_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemGetInfo_Impl (uint32 sem_id, OS_mut_sem_prop_t *mut_prop) { /* RTEMS provides no additional info */ return OS_SUCCESS; -} /* end OS_MutSemGetInfo */ +} /* end OS_MutSemGetInfo_Impl */ /**************************************************************************************** TICK API @@ -1485,19 +1414,15 @@ int32 OS_MutSemGetInfo_Impl (uint32 sem_id, OS_mut_sem_prop_t *mut_prop) INT API ***************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_IntAttachHandler - - Purpose: The call associates a specified C routine to a specified interrupt - number.Upon occurring of the InterruptNumber the InerruptHandler - routine will be called and passed the parameter. - - Parameters: - InterruptNumber : The Interrupt Number that will cause the start of the ISR - InerruptHandler : The ISR associatd with this interrupt - parameter :The parameter that is passed to the ISR - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_IntAttachHandler_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_IntAttachHandler_Impl (uint32 InterruptNumber, osal_task_entry InterruptHandler, int32 parameter) { #if (CPU_SIMPLE_VECTORED_INTERRUPTS == false) @@ -1532,33 +1457,32 @@ int32 OS_IntAttachHandler_Impl (uint32 InterruptNumber, osal_task_entry Interru } return(status) ; #endif -}/* end OS_IntAttachHandler */ -/*--------------------------------------------------------------------------------------- - Name: OS_IntUnlock - - Purpose: Enable previous state of interrupts - - Parameters: - IntLevel : The Interrupt Level to be reinstated ----------------------------------------------------------------------------------------*/ - +} /* end OS_IntAttachHandler_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_IntUnlock_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_IntUnlock_Impl (int32 IntLevel) { rtems_interrupt_enable ( (rtems_interrupt_level) IntLevel); return (OS_SUCCESS); -}/* end OS_IntUnlock */ - -/*--------------------------------------------------------------------------------------- - Name: OS_IntLock - - Purpose: Disable interrupts. - - Parameters: - - Returns: Interrupt level ----------------------------------------------------------------------------------------*/ +} /* end OS_IntUnlock_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_IntLock_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_IntLock_Impl (void) { rtems_interrupt_level rtems_int_level; @@ -1566,50 +1490,50 @@ int32 OS_IntLock_Impl (void) rtems_interrupt_disable(rtems_int_level) ; return ( (int32) rtems_int_level) ; -}/* end OS_IntLock */ +} /* end OS_IntLock_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_IntEnable - - Purpose: Enable previous state of interrupts - - Parameters: - IntLevel : The Interrupt Level to be reinstated ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_IntEnable_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_IntEnable_Impl (int32 Level) { rtems_interrupt_enable ( (rtems_interrupt_level) Level); return(OS_SUCCESS); -}/* end OS_IntEnable */ - -/*--------------------------------------------------------------------------------------- - Name: OS_IntDisable - - Purpose: Disable the corresponding interrupt number. - - Parameters: - - Returns: Interrupt level before OS_IntDisable Call ----------------------------------------------------------------------------------------*/ +} /* end OS_IntEnable_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_IntDisable_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_IntDisable_Impl (int32 Level) { rtems_interrupt_level rtems_int_level; rtems_interrupt_disable(rtems_int_level) ; return ( (int32) rtems_int_level) ; -}/* end OS_IntDisable */ +} /* end OS_IntDisable_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_HeapGetInfo - - Purpose: Return current info on the heap - - Parameters: - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_HeapGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_HeapGetInfo_Impl (OS_heap_prop_t *heap_prop) { region_information_block info; @@ -1627,58 +1551,45 @@ int32 OS_HeapGetInfo_Impl (OS_heap_prop_t *heap_prop) heap_prop->largest_free_block = (uint32) info.Free.largest; return (OS_SUCCESS); -} +} /* end OS_HeapGetInfo_Impl */ -/*--------------------------------------------------------------------------------------- - * Name: OS_SetMask - * Purpose: - * Set the masking register to mask and unmask interrupts - * - * Assumptions and Notes: - * HW interrupt control is not supported from a user task - * - * Parameters: - * MaskSetting :the value to be written into the mask register - * - * Global Inputs: None + +/*---------------------------------------------------------------- * - * Global Outputs: None + * Function: OS_IntSetMask_Impl * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Return Values: - * ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_IntSetMask_Impl ( uint32 MaskSetting ) { return(OS_ERR_NOT_IMPLEMENTED); -} +} /* end OS_IntSetMask_Impl */ -/*-------------------------------------------------------------------------------------- - * Name: OS_GetMask - * Purpose: - * Read and report the setting of the cpu mask register. - * - * Assumptions and Notes: - * HW interrupt control is not supported from a user task - * - * Parameters: - * MaskSettingPtr : pointer to a location where the function store the - * reading of the cpu mask register. - * - * Global Inputs: None + +/*---------------------------------------------------------------- * - * Global Outputs: None + * Function: OS_IntGetMask_Impl * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Return Values: - * ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_IntGetMask_Impl ( uint32 * MaskSettingPtr ) { *MaskSettingPtr = 0; return(OS_ERR_NOT_IMPLEMENTED); -} - +} /* end OS_IntGetMask_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_FPUExcAttachHandler_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FPUExcAttachHandler_Impl(uint32 ExceptionNumber, void * ExceptionHandler, int32 parameter) { @@ -1686,57 +1597,73 @@ int32 OS_FPUExcAttachHandler_Impl(uint32 ExceptionNumber, void * ExceptionHandle ** Not implemented in RTEMS. */ return(OS_ERR_NOT_IMPLEMENTED); -} - +} /* end OS_FPUExcAttachHandler_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_FPUExcEnable_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FPUExcEnable_Impl(int32 ExceptionNumber) { /* ** Not implemented in RTEMS. */ return(OS_SUCCESS); -} - +} /* end OS_FPUExcEnable_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_FPUExcDisable_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FPUExcDisable_Impl(int32 ExceptionNumber) { /* ** Not implemented in RTEMS. */ return(OS_SUCCESS); -} +} /* end OS_FPUExcDisable_Impl */ -/* + +/*---------------------------------------------------------------- * - * Name: OS_FPUExcSetMask + * Function: OS_FPUExcSetMask_Impl * - * Purpose: This function sets the FPU exception mask + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Notes: 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. - */ + *-----------------------------------------------------------------*/ int32 OS_FPUExcSetMask_Impl(uint32 mask) { /* ** Not implemented in RTEMS. */ return(OS_SUCCESS); -} +} /* end OS_FPUExcSetMask_Impl */ -/* + +/*---------------------------------------------------------------- * - * Name: OS_FPUExcGetMask + * Function: OS_FPUExcGetMask_Impl * - * Purpose: This function gets the FPU exception mask + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Notes: 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. - */ + *-----------------------------------------------------------------*/ int32 OS_FPUExcGetMask_Impl(uint32 *mask) { /* ** Not implemented in RTEMS. */ return(OS_SUCCESS); -} +} /* end OS_FPUExcGetMask_Impl */ /********************************************************************/ /* CONSOLE OUTPUT */ @@ -1744,8 +1671,15 @@ int32 OS_FPUExcGetMask_Impl(uint32 *mask) /* use the portable version of OS_ConsoleWrite_Impl() */ #include "../portable/os-impl-console-directwrite.c" - - + +/*---------------------------------------------------------------- + * + * Function: OS_ConsoleWakeup_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_ConsoleWakeup_Impl(uint32 local_id) { OS_impl_console_internal_record_t *local = &OS_impl_console_table[local_id]; @@ -1760,8 +1694,16 @@ void OS_ConsoleWakeup_Impl(uint32 local_id) /* output directly */ OS_ConsoleOutput_Impl(local_id); } -} +} /* end OS_ConsoleWakeup_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_ConsoleTask_Entry + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ static void OS_ConsoleTask_Entry(rtems_task_argument arg) { uint32 local_id = arg; @@ -1773,8 +1715,16 @@ static void OS_ConsoleTask_Entry(rtems_task_argument arg) OS_ConsoleOutput_Impl(local_id); rtems_semaphore_obtain(local->data_sem, RTEMS_WAIT, RTEMS_NO_TIMEOUT); } -} - +} /* end OS_ConsoleTask_Entry */ + +/*---------------------------------------------------------------- + * + * Function: OS_ConsoleCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ConsoleCreate_Impl(uint32 local_id) { OS_impl_console_internal_record_t *local = &OS_impl_console_table[local_id]; @@ -1849,6 +1799,6 @@ int32 OS_ConsoleCreate_Impl(uint32 local_id) } return return_code; -} +} /* end OS_ConsoleCreate_Impl */ diff --git a/src/os/rtems/osfileapi.c b/src/os/rtems/osfileapi.c index b8698b394..f7733a31e 100644 --- a/src/os/rtems/osfileapi.c +++ b/src/os/rtems/osfileapi.c @@ -120,7 +120,7 @@ int32 OS_Rtems_StreamAPI_Impl_Init(void) } return OS_SUCCESS; -} +} /* end OS_Rtems_StreamAPI_Impl_Init */ /* -------------------------------------------------------------------------------------- Name: OS_Rtems_DirAPI_Impl_Init @@ -133,20 +133,20 @@ int32 OS_Rtems_DirAPI_Impl_Init(void) { memset(OS_impl_dir_table, 0, sizeof(OS_impl_dir_table)); return OS_SUCCESS; -} +} /* end OS_Rtems_DirAPI_Impl_Init */ /* FIXME - need to do something better here */ -/* -------------------------------------------------------------------------------------- - Name: OS_ShellOutputToFile - - Purpose: Takes a shell command in and writes the output of that command to the specified file - - Returns: OS_FS_ERROR if the command was not executed properly - OS_FS_ERR_INVALID_FD if the file descriptor passed in is invalid - OS_SUCCESS if success - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ShellOutputToFile_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ShellOutputToFile_Impl(uint32 file_id, const char *Cmd) { /* @@ -179,5 +179,5 @@ int32 OS_ShellOutputToFile_Impl(uint32 file_id, const char *Cmd) return OS_FS_ERROR; } return OS_SUCCESS; -}/* end OS_ShellOutputToFile */ +} /* end OS_ShellOutputToFile_Impl */ diff --git a/src/os/rtems/osfilesys.c b/src/os/rtems/osfilesys.c index c22aa8fe1..f7d46996e 100644 --- a/src/os/rtems/osfilesys.c +++ b/src/os/rtems/osfilesys.c @@ -90,17 +90,18 @@ int32 OS_Rtems_FileSysAPI_Impl_Init(void) /* clear the local filesys table */ memset(OS_impl_filesys_table, 0, sizeof(OS_impl_filesys_table)); return OS_SUCCESS; -} +} /* end OS_Rtems_FileSysAPI_Impl_Init */ -/*--------------------------------------------------------------------------------------- - Name: OS_FileSysStartVolume_Impl - - Purpose: Starts/Registers a file system on the target - - Returns: OS_FS_SUCCESS on creating the disk - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysStartVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysStartVolume_Impl (uint32 filesys_id) { OS_filesys_internal_record_t *local = &OS_filesys_table[filesys_id]; @@ -202,29 +203,31 @@ int32 OS_FileSysStartVolume_Impl (uint32 filesys_id) } /* end OS_FileSysStartVolume_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_FileSysStopVolume_Impl - - Purpose: Stops/Unregisters a file system on the target - - Returns: OS_FS_SUCCESS on creating the disk - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysStopVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysStopVolume_Impl (uint32 filesys_id) { /* Currently nothing to do here */ return OS_SUCCESS; -} /* end OS_FileSysStartVolume_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_FileSysFormatVolume_Impl +} /* end OS_FileSysStopVolume_Impl */ - Purpose: Formats a file system on the target to prepare it for use - - Returns: OS_FS_SUCCESS on creating the disk - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysFormatVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysFormatVolume_Impl (uint32 filesys_id) { OS_filesys_internal_record_t *local = &OS_filesys_table[filesys_id]; @@ -280,14 +283,15 @@ int32 OS_FileSysFormatVolume_Impl (uint32 filesys_id) } /* end OS_FileSysFormatVolume_Impl */ -/*-------------------------------------------------------------------------------------- - Name: OS_mount - - Purpose: mounts a drive. - - Returns: OS_FS_SUCCESS if success ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysMountVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysMountVolume_Impl (uint32 filesys_id) { OS_filesys_internal_record_t *local = &OS_filesys_table[filesys_id]; @@ -327,16 +331,17 @@ int32 OS_FileSysMountVolume_Impl (uint32 filesys_id) return OS_SUCCESS; -}/* end OS_FileSysMountVolume_Impl */ - -/*-------------------------------------------------------------------------------------- - Name: OS_FileSysUnmountVolume_Impl - - Purpose: unmounts a drive. - - Returns: OS_FS_SUCCESS if success ----------------------------------------------------------------------------------------*/ +} /* end OS_FileSysMountVolume_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysUnmountVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysUnmountVolume_Impl (uint32 filesys_id) { OS_filesys_internal_record_t *local = &OS_filesys_table[filesys_id]; @@ -352,15 +357,17 @@ int32 OS_FileSysUnmountVolume_Impl (uint32 filesys_id) return OS_SUCCESS; -}/* end OS_umount */ - -/*-------------------------------------------------------------------------------------- - Name: OS_FileSysStatVolume_Impl - - Purpose: Returns stats about a volume +} /* end OS_FileSysUnmountVolume_Impl */ - Returns: OS_FS_SUCCESS or OS_FS_ERROR if the OS call failed ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysStatVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysStatVolume_Impl (uint32 filesys_id, OS_statvfs_t *result) { OS_filesys_internal_record_t *local = &OS_filesys_table[filesys_id]; @@ -376,22 +383,22 @@ int32 OS_FileSysStatVolume_Impl (uint32 filesys_id, OS_statvfs_t *result) result->total_blocks = stat_buf.f_blocks; return(OS_FS_SUCCESS); -}/* end OS_fsBlocksFree */ - - -/*-------------------------------------------------------------------------------------- - Name: OS_FileSysCheckVolume_Impl +} /* end OS_FileSysStatVolume_Impl */ - Purpose: Checks the drives for inconsisenties and either repairs it or not - Returns: OS_FS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysCheckVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysCheckVolume_Impl (uint32 filesys_id, bool repair) { - return OS_FS_UNIMPLEMENTED; -}/* end OS_FileSysCheckVolume_Impl */ - + return OS_ERR_NOT_IMPLEMENTED; +} /* end OS_FileSysCheckVolume_Impl */ diff --git a/src/os/rtems/osloader.c b/src/os/rtems/osloader.c index d8798dc50..887a8c12d 100644 --- a/src/os/rtems/osloader.c +++ b/src/os/rtems/osloader.c @@ -60,32 +60,34 @@ OS_impl_module_internal_record_t OS_impl_module_table[OS_MAX_MODULES]; /**************************************************************************************** INITIALIZATION FUNCTION ***************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_Rtems_ModuleAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_Rtems_ModuleAPI_Impl_Init(void) { #if (OS_MAX_MODULES > 0) memset(OS_impl_module_table, 0, sizeof(OS_impl_module_table)); #endif return(OS_SUCCESS); -} +} /* end OS_Rtems_ModuleAPI_Impl_Init */ /**************************************************************************************** Symbol table API ***************************************************************************************/ -/*-------------------------------------------------------------------------------------- - Name: OS_SymbolLookup - - Purpose: Find the Address of a Symbol - - Parameters: - - Returns: OS_SUCCESS if the symbol is found - The address of the symbol will be stored in the pointer that is passed in. - - Note this is compiled-in regardless of OS_MAX_MODULES or OS_INCLUDE_MODULE_LOADER, - because there is still value in being able to look up symbols in the base image even - if the application does not intend to load additional modules. - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SymbolLookup_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SymbolLookup_Impl( cpuaddr *SymbolAddress, const char *SymbolName ) { int32 status; @@ -127,25 +129,23 @@ int32 OS_SymbolLookup_Impl( cpuaddr *SymbolAddress, const char *SymbolName ) return status; -}/* end OS_SymbolLookup */ - -/*-------------------------------------------------------------------------------------- - Name: OS_SymbolTableDump_Impl +} /* end OS_SymbolLookup_Impl */ - Purpose: Dumps the system symbol table to a file - - Parameters: - - Returns: OS_ERROR if the symbol table could not be read or dumped - OS_INVALID_FILE if the file could not be opened or written - OS_SUCCESS if the symbol is found ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SymbolTableDump_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SymbolTableDump_Impl ( const char *filename, uint32 SizeLimit ) { return(OS_ERR_NOT_IMPLEMENTED); -}/* end OS_SymbolTableDump */ +} /* end OS_SymbolTableDump_Impl */ @@ -164,11 +164,17 @@ int32 OS_SymbolTableDump_Impl ( const char *filename, uint32 SizeLimit ) HELPER ROUTINES ***************************************************************************************/ -/* +/*---------------------------------------------------------------- + * + * Function: OS_rtems_rtl_check_unresolved + * + * Purpose: Local helper routine, not part of OSAL API. + * This callback checks symbols in the RTL unresolved record list - * Right now this considers any unresolved items to be a failure. + * NOTE: Right now this considers any unresolved items to be a failure. * This could be fine-tuned later. - */ + * + *-----------------------------------------------------------------*/ static bool OS_rtems_rtl_check_unresolved (rtems_rtl_unresolv_rec_t* rec, void* data) { @@ -187,22 +193,18 @@ static bool OS_rtems_rtl_check_unresolved (rtems_rtl_unresolv_rec_t* rec, break; } return false; -} - +} /* end OS_rtems_rtl_check_unresolved */ -/*-------------------------------------------------------------------------------------- - Name: OS_ModuleLoad - Purpose: Loads an object file into the running operating system - - Parameters: - - Returns: 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 - OS_SUCCESS if the module is loaded successfuly ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ModuleLoad_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ModuleLoad_Impl ( uint32 module_id, char *translated_path ) { int32 status = OS_ERROR; @@ -267,18 +269,17 @@ int32 OS_ModuleLoad_Impl ( uint32 module_id, char *translated_path ) return status; -}/* end OS_ModuleLoad */ - -/*-------------------------------------------------------------------------------------- - Name: OS_ModuleUnload +} /* end OS_ModuleLoad_Impl */ - Purpose: Unloads the module file from the running operating system - - Parameters: - - Returns: OS_ERROR if the module is invalid or cannot be unloaded - OS_SUCCESS if the module was unloaded successfuly ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ModuleUnload_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ModuleUnload_Impl ( uint32 module_id ) { int32 status = OS_ERROR; @@ -299,50 +300,51 @@ int32 OS_ModuleUnload_Impl ( uint32 module_id ) return status; -}/* end OS_ModuleUnload */ +} /* end OS_ModuleUnload_Impl */ #else -/* - * Note that for load/unload, "OS_SUCCESS" here is better - * than "OS_ERR_NOT_IMPLEMENTED". This is because: + +/*---------------------------------------------------------------- * - * If OS_MAX_MODULES is also zero, then these functions will never be - * called through the shared layer (i.e. upper layer already handles it). - * So it doesn't matter what this returns in that case. + * Function: OS_ModuleLoad_Impl * - * But if OS_MAX_MODULES is nonzero then this acts like a "fake" module - * loader for statically linked apps. When combined with the static - * symbol table, this means that apps like CFE that typically would - * use Module loading and symbol lookups can be linked statically and - * everything just works. - */ + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ModuleLoad_Impl ( uint32 module_id, char *translated_path ) { return OS_SUCCESS; -} - +} /* end OS_ModuleLoad_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_ModuleUnload_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ModuleUnload_Impl ( uint32 module_id ) { return OS_SUCCESS; -} +} /* end OS_ModuleUnload_Impl */ #endif -/*-------------------------------------------------------------------------------------- - Name: OS_ModuleInfo - - Purpose: Returns information about the loadable module - - Parameters: - - Returns: OS_ERR_INVALID_ID if the module id invalid - OS_INVALID_POINTER if the pointer to the ModuleInfo structure is invalid - OS_SUCCESS if the module info was filled out successfuly ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ModuleGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ModuleGetInfo_Impl ( uint32 module_id, OS_module_prop_t *module_prop ) { /* @@ -351,6 +353,6 @@ int32 OS_ModuleGetInfo_Impl ( uint32 module_id, OS_module_prop_t *module_prop ) */ return(OS_SUCCESS); -}/* end OS_ModuleInfo */ +} /* end OS_ModuleGetInfo_Impl */ diff --git a/src/os/rtems/osnetwork.c b/src/os/rtems/osnetwork.c index 61a791355..cf64d6e7a 100644 --- a/src/os/rtems/osnetwork.c +++ b/src/os/rtems/osnetwork.c @@ -42,21 +42,21 @@ const int OS_IMPL_SOCKET_FLAGS = O_NONBLOCK; /* Leverage the portable BSD sockets implementation */ #include "../portable/os-impl-bsd-sockets.c" -/*-------------------------------------------------------------------------------------- - Name: OS_NetworkGetID - - Purpose: Gets the ID of the current Network - - Returns: OS_ERROR if the host id could not be found - a 32 bit host id if success ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_NetworkGetID_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_NetworkGetID_Impl (int32 *IdBuf) { /* RTEMS does not have the GetHostId call - * it is deprecated in other OS's anyway and not a good idea to use it */ return OS_ERR_NOT_IMPLEMENTED; -}/* end OS_NetworkGetID */ +} /* end OS_NetworkGetID_Impl */ #else /* OS_INCLUDE_NETWORK */ diff --git a/src/os/rtems/ostimer.c b/src/os/rtems/ostimer.c index c671614a4..05154944a 100644 --- a/src/os/rtems/ostimer.c +++ b/src/os/rtems/ostimer.c @@ -70,18 +70,43 @@ typedef struct ***************************************************************************************/ OS_impl_timebase_internal_record_t OS_impl_timebase_table[OS_MAX_TIMEBASES]; - - + +/*---------------------------------------------------------------- + * + * Function: OS_TimeBaseLock_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_TimeBaseLock_Impl(uint32 local_id) { rtems_semaphore_obtain(OS_impl_timebase_table[local_id].handler_mutex, RTEMS_WAIT, RTEMS_NO_TIMEOUT); -} - +} /* end OS_TimeBaseLock_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_TimeBaseUnlock_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_TimeBaseUnlock_Impl(uint32 local_id) { rtems_semaphore_release(OS_impl_timebase_table[local_id].handler_mutex); -} +} /* end OS_TimeBaseUnlock_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_TimeBase_ISR + * + * Purpose: Local helper routine, not part of OSAL API. + * An ISR to service a timer tick interrupt, which in turn + * posts a semaphore so the user task can execute + * + *-----------------------------------------------------------------*/ static rtems_timer_service_routine OS_TimeBase_ISR(rtems_id rtems_timer_id, void *arg) { OS_U32ValueWrapper_t user_data; @@ -111,8 +136,17 @@ static rtems_timer_service_routine OS_TimeBase_ISR(rtems_id rtems_timer_id, void rtems_semaphore_release(local->tick_sem); } -} +} /* end OS_TimeBase_ISR */ + +/*---------------------------------------------------------------- + * + * Function: OS_TimeBase_WaitImpl + * + * Purpose: Local helper routine, not part of OSAL API. + * Pends on the semaphore for the next timer tick + * + *-----------------------------------------------------------------*/ static uint32 OS_TimeBase_WaitImpl(uint32 local_id) { OS_impl_timebase_internal_record_t *local; @@ -144,12 +178,20 @@ static uint32 OS_TimeBase_WaitImpl(uint32 local_id) return interval_time; -} +} /* end OS_TimeBase_WaitImpl */ /**************************************************************************************** INITIALIZATION FUNCTION ***************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_Rtems_TimeBaseAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_Rtems_TimeBaseAPI_Impl_Init ( void ) { /* @@ -184,19 +226,20 @@ int32 OS_Rtems_TimeBaseAPI_Impl_Init ( void ) OS_SharedGlobalVars.MicroSecPerTick = (RTEMS_GlobalVars.ClockAccuracyNsec + 500) / 1000; return(OS_SUCCESS); -} +} /* end OS_Rtems_TimeBaseAPI_Impl_Init */ /**************************************************************************************** INTERNAL FUNCTIONS ***************************************************************************************/ -/****************************************************************************** - ** Function: OS_UsecToTicks - ** - ** Purpose: Convert Microseconds to a number of ticks. - ** - */ +/*---------------------------------------------------------------- + * + * Function: OS_UsecsToTicks + * + * Purpose: Convert Microseconds to a number of ticks. + * + *-----------------------------------------------------------------*/ void OS_UsecsToTicks(uint32 usecs, rtems_interval *ticks) { uint32 result; @@ -218,7 +261,7 @@ void OS_UsecsToTicks(uint32 usecs, rtems_interval *ticks) } *ticks = (rtems_interval)result; -} +} /* end OS_UsecsToTicks */ @@ -229,15 +272,15 @@ void OS_UsecsToTicks(uint32 usecs, rtems_interval *ticks) /* The user may specify whether to use priority inheritance on mutexes via osconfig.h */ #define OSAL_TIMEBASE_MUTEX_ATTRIBS RTEMS_PRIORITY | RTEMS_BINARY_SEMAPHORE | RTEMS_INHERIT_PRIORITY -/****************************************************************************** - * Function: OS_TimeBaseCreate + +/*---------------------------------------------------------------- * - * Purpose: Create a new OSAL Time base + * Function: OS_TimeBaseCreate_Impl * - * Arguments: + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Return: - */ + *-----------------------------------------------------------------*/ int32 OS_TimeBaseCreate_Impl(uint32 timer_id) { int32 return_code; @@ -357,19 +400,17 @@ int32 OS_TimeBaseCreate_Impl(uint32 timer_id) } return return_code; -} +} /* end OS_TimeBaseCreate_Impl */ -/****************************************************************************** - * Function: OS_TimeBaseSet + +/*---------------------------------------------------------------- * - * Purpose: + * Function: OS_TimeBaseSet_Impl * - * Arguments: - * (none) + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Return: - * (none) - */ + *-----------------------------------------------------------------*/ int32 OS_TimeBaseSet_Impl(uint32 timer_id, int32 start_time, int32 interval_time) { OS_U32ValueWrapper_t user_data; @@ -444,20 +485,18 @@ int32 OS_TimeBaseSet_Impl(uint32 timer_id, int32 start_time, int32 interval_time local->reset_flag = 1; } return return_code; -} +} /* end OS_TimeBaseSet_Impl */ -/****************************************************************************** - * Function: OS_TimerDelete + +/*---------------------------------------------------------------- * - * Purpose: + * Function: OS_TimeBaseDelete_Impl * - * Arguments: - * (none) + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail * - * Return: - * (none) - */ + *-----------------------------------------------------------------*/ int32 OS_TimeBaseDelete_Impl(uint32 timer_id) { rtems_status_code rtems_sc; @@ -512,23 +551,22 @@ int32 OS_TimeBaseDelete_Impl(uint32 timer_id) } return return_code; -} +} /* end OS_TimeBaseDelete_Impl */ -/*************************************************************************************** - * Name: OS_TimerGetInfo + +/*---------------------------------------------------------------- * - * Purpose: This function will pass back a pointer to structure that contains - * all of the relevant info( name and creator) about the specified timer. + * Function: OS_TimeBaseGetInfo_Impl * - * Returns: OS_ERR_INVALID_ID if the id passed in is not a valid timer - * OS_INVALID_POINTER if the timer_prop pointer is null - * OS_SUCCESS if success - */ + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TimeBaseGetInfo_Impl (uint32 timer_id, OS_timebase_prop_t *timer_prop) { return OS_SUCCESS; -} /* end OS_TimerGetInfo */ +} /* end OS_TimeBaseGetInfo_Impl */ /**************************************************************************************** Other Time-Related API Implementation diff --git a/src/os/shared/os-impl.h b/src/os/shared/os-impl.h index 4a2ec5323..8e252bf5d 100644 --- a/src/os/shared/os-impl.h +++ b/src/os/shared/os-impl.h @@ -417,67 +417,326 @@ typedef bool (*OS_ObjectMatchFunc_t)(void *ref, uint32 local_id, const OS_common * Initialization functions for each of the common sub-layers * These functions may or may not do anything, but the hook is provided nonetheless. */ + +/*--------------------------------------------------------------------------------------- + Name: OS_API_Impl_Init + + Purpose: Initialize the OS-specific layer for the given object type + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_API_Impl_Init (uint32 idtype); + +/*--------------------------------------------------------------------------------------- + Name: OS_ObjectIdInit + + Purpose: Initialize the OS-independent layer for object ID management + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_ObjectIdInit (void); + +/*--------------------------------------------------------------------------------------- + Name: OS_TaskAPI_Init + + Purpose: Initialize the OS-independent layer for tasks + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_TaskAPI_Init (void); + +/*--------------------------------------------------------------------------------------- + Name: OS_QueueAPI_Init + + Purpose: Initialize the OS-independent layer for queues + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_QueueAPI_Init (void); + +/*--------------------------------------------------------------------------------------- + Name: OS_BinSemAPI_Init + + Purpose: Initialize the OS-independent layer for binary semaphores + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_BinSemAPI_Init (void); + +/*--------------------------------------------------------------------------------------- + Name: OS_CountSemAPI_Init + + Purpose: Initialize the OS-independent layer for counting semaphores + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_CountSemAPI_Init (void); + +/*--------------------------------------------------------------------------------------- + Name: OS_MutexAPI_Init + + Purpose: Initialize the OS-independent layer for mutex objects + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_MutexAPI_Init (void); + +/*--------------------------------------------------------------------------------------- + Name: OS_ModuleAPI_Init + + Purpose: Initialize the OS-independent layer for modules + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_ModuleAPI_Init (void); + +/*--------------------------------------------------------------------------------------- + Name: OS_TimeBaseAPI_Init + + Purpose: Initialize the OS-independent layer for timebase objects + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_TimeBaseAPI_Init (void); + +/*--------------------------------------------------------------------------------------- + Name: OS_TimerCbAPI_Init + + Purpose: Initialize the OS-independent layer for timer callback objects + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_TimerCbAPI_Init (void); + +/*--------------------------------------------------------------------------------------- + Name: OS_FileAPI_Init + + Purpose: Initialize the OS-independent layer for file resources + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_FileAPI_Init (void); + +/*--------------------------------------------------------------------------------------- + Name: OS_DirAPI_Init + + Purpose: Initialize the OS-independent layer for directory resources + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_DirAPI_Init (void); + +/*--------------------------------------------------------------------------------------- + Name: OS_NetworkAPI_Init + + Purpose: Initialize the OS-independent layer for network services + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_NetworkAPI_Init (void); + +/*--------------------------------------------------------------------------------------- + Name: OS_SocketAPI_Init + + Purpose: Initialize the OS-independent layer for network sockets + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_SocketAPI_Init (void); + +/*--------------------------------------------------------------------------------------- + Name: OS_FileSysAPI_Init + + Purpose: Initialize the OS-independent layer for file systems + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_FileSysAPI_Init (void); + +/*--------------------------------------------------------------------------------------- + Name: OS_ConsoleAPI_Init + + Purpose: Initialize the OS-independent layer for console service + + returns: OS_SUCCESS on success, or relevant error code +---------------------------------------------------------------------------------------*/ int32 OS_ConsoleAPI_Init (void); + +/**************************************************************************************** + IMPLEMENTATION FUNCTIONS + ***************************************************************************************/ + /* - * The "IdleLoop_Impl" is called by the main thread once - * everything is running and there is no more work to do. - * - * It should suspend the calling thread until a wakeup - * event happens. + * This functions implement a the OS-specific portion + * of various OSAL functions. They are defined in + * OS-specific source files. */ + + +/*---------------------------------------------------------------- + + Function: OS_IdleLoop_Impl + + Purpose: Block the "idle" thread until woken up + + The "IdleLoop_Impl" is called by the main thread once + everything is running and there is no more work to do. + + It should suspend the calling thread until a wakeup + event happens. + + ------------------------------------------------------------------*/ void OS_IdleLoop_Impl (void); -/* - * The "ApplicationShutdown_Impl" should wake up whatever - * task is currently suspended in "IdleLoop_Impl" and cause - * that thread to resume and return to its caller. - * - * NOTE: This should not block but it may cause the current - * thread to be preempted by the thread that was woken up, - * depending on priority levels. - */ +/*---------------------------------------------------------------- + + Function: OS_ApplicationShutdown_Impl + + Purpose: Wake up the idle task + + The "ApplicationShutdown_Impl" should wake up whatever + task is currently suspended in "IdleLoop_Impl" and cause + that thread to resume and return to its caller. + + NOTE: This should not block but it may cause the current + thread to be preempted by the thread that was woken up, + depending on priority levels. + + ------------------------------------------------------------------*/ void OS_ApplicationShutdown_Impl (void); /**************************************************************************************** ID MAPPING FUNCTIONS - ****************************************************************************************/ + ***************************************************************************************/ /* - * Function prototypes for routines implemented in common layers but private to OSAL - * - * These implement the basic OSAL ObjectID patterns - that is a 32-bit number that - * is opaque externally, but internally identifies a specific type of object and - * corresponding index within the local tables. + Function prototypes for routines implemented in common layers but private to OSAL + + These implement the basic OSAL ObjectID patterns - that is a 32-bit number that + is opaque externally, but internally identifies a specific type of object and + corresponding index within the local tables. */ + +/*---------------------------------------------------------------- + Function: OS_GetMaxForObjectType + + Purpose: Obtains the maximum number of objects for "idtype" in the global table + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ uint32 OS_GetMaxForObjectType(uint32 idtype); + +/*---------------------------------------------------------------- + Function: OS_GetBaseForObjectType + + Purpose: Obtains the base object number for "idtype" in the global table + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ uint32 OS_GetBaseForObjectType(uint32 idtype); + +/*---------------------------------------------------------------- + Function: OS_ObjectIdMap + + Purpose: Convert an object serial number into a 32-bit OSAL ID of the given type + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_ObjectIdMap(uint32 idtype, uint32 idvalue, uint32 *result); + +/*---------------------------------------------------------------- + Function: OS_ObjectIdUnMap + + Purpose: Convert a 32-bit OSAL ID of the expected type into an object serial number + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_ObjectIdUnMap(uint32 id, uint32 idtype, uint32 *idvalue); + +/*---------------------------------------------------------------- + Function: OS_ObjectIdFindByName + + Purpose: Finds an entry in the global resource table matching the given name + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_ObjectIdFindByName (uint32 idtype, const char *name, uint32 *object_id); + +/*---------------------------------------------------------------- + Function: OS_ObjectIdToArrayIndex + + Purpose: Convert a 32-bit OSAL ID into a zero-based array index + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_ObjectIdToArrayIndex(uint32 idtype, uint32 id, uint32 *ArrayIndex); + +/*---------------------------------------------------------------- + Function: OS_ObjectIdGetBySearch + + Purpose: Find and lock an entry in the global resource table + Search is performed using a user-specified match function + (Allows searching for items by arbitrary keys) + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_ObjectIdGetBySearch(OS_lock_mode_t lock_mode, uint32 idtype, OS_ObjectMatchFunc_t MatchFunc, void *arg, OS_common_record_t **record); + +/*---------------------------------------------------------------- + Function: OS_ObjectIdGetByName + + Purpose: Find and lock an entry in the global resource table + Search is performed using a name match function + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_ObjectIdGetByName (OS_lock_mode_t lock_mode, uint32 idtype, const char *name, OS_common_record_t **record); + +/*---------------------------------------------------------------- + Function: OS_ObjectIdGetById + + Purpose: Find and lock an entry in the global resource table + Lookup is performed by ID value (no searching required) + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_ObjectIdGetById(OS_lock_mode_t lock_mode, uint32 idtype, uint32 id, uint32 *array_index, OS_common_record_t **record); + +/*---------------------------------------------------------------- + Function: OS_ObjectIdAllocateNew + + Purpose: Issue a new object ID of the given type and associate with the given name + The array index (0-based) and global record pointers are output back to the caller + The table will be left in a "locked" state to allow further initialization + The OS_ObjectIdFinalizeNew() function must be called to complete the operation + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_ObjectIdAllocateNew(uint32 idtype, const char *name, uint32 *array_index, OS_common_record_t **record); + +/*---------------------------------------------------------------- + Function: OS_ObjectIdFinalizeNew + + Purpose: Completes the operation initiated by OS_ObjectIdAllocateNew() + If the operation was successful, the final OSAL ID is returned + If the operation was unsuccessful, the ID is deleted and returned to the pool. + The global table is unlocked for future operations + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_ObjectIdFinalizeNew(int32 operation_status, OS_common_record_t *record, uint32 *outid); + +/*---------------------------------------------------------------- + Function: OS_ObjectIdRefcountDecr + + Purpose: Decrement the reference count + This releases objects obtained with OS_LOCK_MODE_REFCOUNT mode + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_ObjectIdRefcountDecr(OS_common_record_t *record); @@ -485,30 +744,130 @@ int32 OS_ObjectIdRefcountDecr(OS_common_record_t *record); * Table locking and unlocking for global objects can be done at the shared code * layer but the actual implementation is OS-specific */ + + +/*---------------------------------------------------------------- + Function: OS_Lock_Global_Impl + + Purpose: Locks the global table identified by "idtype" + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_Lock_Global_Impl(uint32 idtype); + +/*---------------------------------------------------------------- + Function: OS_Unlock_Global_Impl + + Purpose: Unlocks the global table identified by "idtype" + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_Unlock_Global_Impl(uint32 idtype); /**************************************************************************************** TASK API LOW-LEVEL IMPLEMENTATION FUNCTIONS - ****************************************************************************************/ + ***************************************************************************************/ -/* - * The "OS_TaskEntryPoint" is a generic method implemented in the - * shared layer that performs housekeeping and then calls the user-specified - * entry point. It should be the first thing called in any new task. - */ +/*---------------------------------------------------------------- + Function: OS_TaskEntryPoint + + Purpose: Entry point for all newly created tasks + + The "OS_TaskEntryPoint" is a generic method implemented in the + shared layer that performs housekeeping and then calls the user-specified + entry point. It should be the first thing called in any new task. + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ void OS_TaskEntryPoint (uint32 global_task_id); +/*---------------------------------------------------------------- + Function: OS_TaskMatch_Impl + + Purpose: Determines if the caller matches the given task_id + + Returns: OS_SUCCESS on match, any other code on non-match + ------------------------------------------------------------------*/ int32 OS_TaskMatch_Impl (uint32 task_id); + +/*---------------------------------------------------------------- + + Function: OS_TaskCreate_Impl + + Purpose: Prepare/Allocate OS resources for a new task and start + running it, based on configuration in the global object + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_TaskCreate_Impl (uint32 task_id, uint32 flags); + +/*---------------------------------------------------------------- + Function: OS_TaskDelete_Impl + + Purpose: Free the OS resources associated with the specified task + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_TaskDelete_Impl (uint32 task_id); + +/*---------------------------------------------------------------- + Function: OS_TaskExit_Impl + + Purpose: Exits the calling task + + This function does not return + ------------------------------------------------------------------*/ void OS_TaskExit_Impl (void); + +/*---------------------------------------------------------------- + Function: OS_TaskDelay_Impl + + Purpose: Blocks the calling task for the specified number of milliseconds + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_TaskDelay_Impl (uint32 millisecond); + +/*---------------------------------------------------------------- + Function: OS_TaskSetPriority_Impl + + Purpose: Set the scheduling priority of the specified task + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_TaskSetPriority_Impl (uint32 task_id, uint32 new_priority); + +/*---------------------------------------------------------------- + Function: OS_TaskGetId_Impl + + Purpose: Obtain the OSAL task ID of the caller + + Returns: The OSAL ID of the calling task, or zero if not registered + ------------------------------------------------------------------*/ uint32 OS_TaskGetId_Impl (void); + +/*---------------------------------------------------------------- + Function: OS_TaskGetInfo_Impl + + Purpose: Obtain OS-specific information about a task + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_TaskGetInfo_Impl (uint32 task_id, OS_task_prop_t *task_prop); + +/*---------------------------------------------------------------- + + Function: OS_TaskRegister_Impl + + Purpose: Perform registration actions after new task creation + + NOTE: This is invoked via the OS_TaskEntryPoint() immediately + after new task creation, not through OS_TaskRegister() API + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_TaskRegister_Impl (uint32 global_task_id); @@ -516,49 +875,241 @@ int32 OS_TaskRegister_Impl (uint32 global_task_id); /**************************************************************************************** MESSAGE QUEUE API LOW-LEVEL IMPLEMENTATION FUNCTIONS - ****************************************************************************************/ - + ***************************************************************************************/ + +/*---------------------------------------------------------------- + Function: OS_QueueCreate_Impl + + Purpose: Prepare/Allocate OS resources for a message queue + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_QueueCreate_Impl (uint32 queue_id, uint32 flags); + +/*---------------------------------------------------------------- + Function: OS_QueueDelete_Impl + + Purpose: Free the OS resources associated with the message queue + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_QueueDelete_Impl (uint32 queue_id); + +/*---------------------------------------------------------------- + Function: OS_QueueGet_Impl + + Purpose: Receive a message on a message queue. + The calling task will be blocked if no message is immediately available + + Returns: OS_SUCCESS on success, or relevant error code + OS_QUEUE_TIMEOUT must be returned if the timeout expired and no message was received + OS_QUEUE_EMPTY must be returned if the queue is empty when polled (OS_CHECK) + OS_QUEUE_INVALID_SIZE must be returned if the supplied buffer is too small + ------------------------------------------------------------------*/ int32 OS_QueueGet_Impl (uint32 queue_id, void *data, uint32 size, uint32 *size_copied, int32 timeout); + +/*---------------------------------------------------------------- + Function: OS_QueuePut_Impl + + Purpose: Put a message into a message queue + + Returns: OS_SUCCESS on success, or relevant error code + OS_QUEUE_FULL must be returned if the queue is full. + ------------------------------------------------------------------*/ int32 OS_QueuePut_Impl (uint32 queue_id, const void *data, uint32 size, uint32 flags); + +/*---------------------------------------------------------------- + Function: OS_QueueGetInfo_Impl + + Purpose: Obtain OS-specific information about a message queue + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_QueueGetInfo_Impl (uint32 queue_id, OS_queue_prop_t *queue_prop); /**************************************************************************************** SEMAPHORE API LOW-LEVEL IMPLEMENTATION FUNCTIONS - ****************************************************************************************/ + ***************************************************************************************/ /* * Binary semaphores */ + +/*---------------------------------------------------------------- + Function: OS_BinSemCreate_Impl + + Purpose: Prepare/allocate OS resources for a binary semaphore + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_BinSemCreate_Impl (uint32 sem_id, uint32 sem_initial_value, uint32 options); + +/*---------------------------------------------------------------- + Function: OS_BinSemFlush_Impl + + Purpose: Unblock all tasks waiting on the binary semaphore. + Does not change the semaphore value. + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_BinSemFlush_Impl (uint32 sem_id); + +/*---------------------------------------------------------------- + Function: OS_BinSemGive_Impl + + Purpose: Release the semaphore + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_BinSemGive_Impl (uint32 sem_id); + +/*---------------------------------------------------------------- + Function: OS_BinSemTake_Impl + + Purpose: Acquire the semaphore + Block the calling task if the semaphore is 0. + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_BinSemTake_Impl (uint32 sem_id); + +/*---------------------------------------------------------------- + Function: OS_BinSemTimedWait_Impl + + Purpose: Acquire the semaphore, with a time limit + + Returns: OS_SUCCESS on success, or relevant error code + OS_SEM_TIMEOUT must be returned if the time limit was reached + ------------------------------------------------------------------*/ int32 OS_BinSemTimedWait_Impl (uint32 sem_id, uint32 msecs); + +/*---------------------------------------------------------------- + Function: OS_BinSemDelete_Impl + + Purpose: Free the OS resources associated with the binary semaphore + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_BinSemDelete_Impl (uint32 sem_id); + +/*---------------------------------------------------------------- + Function: OS_BinSemGetInfo_Impl + + Purpose: Obtain OS-specific information about the semaphore + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_BinSemGetInfo_Impl (uint32 sem_id, OS_bin_sem_prop_t *bin_prop); /* * Counting semaphores */ + +/*---------------------------------------------------------------- + Function: OS_CountSemCreate_Impl + + Purpose: Prepare/allocate OS resources for a counting semaphore + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_CountSemCreate_Impl (uint32 sem_id, uint32 sem_initial_value, uint32 options); + +/*---------------------------------------------------------------- + Function: OS_CountSemGive_Impl + + Purpose: Increment the semaphore value + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_CountSemGive_Impl (uint32 sem_id); + +/*---------------------------------------------------------------- + Function: OS_CountSemTake_Impl + + Purpose: Decrement the semaphore value + Block the calling task if the semaphore is 0. + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_CountSemTake_Impl (uint32 sem_id); + +/*---------------------------------------------------------------- + Function: OS_CountSemTimedWait_Impl + + Purpose: Decrement the semaphore value, with a time limit + + Returns: OS_SUCCESS on success, or relevant error code + OS_SEM_TIMEOUT must be returned if the time limit was reached + ------------------------------------------------------------------*/ int32 OS_CountSemTimedWait_Impl (uint32 sem_id, uint32 msecs); + +/*---------------------------------------------------------------- + Function: OS_CountSemDelete_Impl + + Purpose: Free the OS resources associated with the counting semaphore + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_CountSemDelete_Impl (uint32 sem_id); + +/*---------------------------------------------------------------- + Function: OS_CountSemGetInfo_Impl + + Purpose: Obtain OS-specific information about the semaphore + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_CountSemGetInfo_Impl (uint32 sem_id, OS_count_sem_prop_t *count_prop); /* * Mutex semaphores */ + +/*---------------------------------------------------------------- + Function: OS_MutSemCreate_Impl + + Purpose: Prepare/allocate OS resources for a mutex object + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_MutSemCreate_Impl (uint32 sem_id, uint32 options); + +/*---------------------------------------------------------------- + Function: OS_MutSemGive_Impl + + Purpose: Release the mutex, which must be owned by the caller + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_MutSemGive_Impl (uint32 sem_id); + +/*---------------------------------------------------------------- + Function: OS_MutSemTake_Impl + + Purpose: Acquire the mutex, blocking the caller as necessary + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_MutSemTake_Impl (uint32 sem_id); + +/*---------------------------------------------------------------- + Function: OS_MutSemDelete_Impl + + Purpose: Free the OS resources associated with a mutex object + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_MutSemDelete_Impl (uint32 sem_id); -int32 OS_MutSemGetIdByName_Impl (uint32 *sem_id, const char *sem_name); + +/*---------------------------------------------------------------- + Function: OS_MutSemGetInfo_Impl + + Purpose: Obtain OS-specific information about the mutex object + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_MutSemGetInfo_Impl (uint32 sem_id, OS_mut_sem_prop_t *mut_prop); @@ -571,19 +1122,95 @@ int32 OS_MutSemGetInfo_Impl (uint32 sem_id, OS_mut_sem_prop_t *mut_prop * no callbacks to user code here. All application callbacks are * done in the shared layer timer API. */ + +/*---------------------------------------------------------------- + Function: OS_TimeBaseCreate_Impl + + Purpose: Prepare OS resources for a time base + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_TimeBaseCreate_Impl (uint32 timebase_id); + +/*---------------------------------------------------------------- + Function: OS_TimeBaseSet_Impl + + Purpose: Configure the OS resources to provide a timer tick + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_TimeBaseSet_Impl (uint32 timebase_id, int32 start_time, int32 interval_time); + +/*---------------------------------------------------------------- + Function: OS_TimeBaseDelete_Impl + + Purpose: Free the OS resources associated with the time base + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_TimeBaseDelete_Impl (uint32 timebase_id); + + + +/**************************************************************************************** + INTERNAL FUNCTIONS +****************************************************************************************/ + + +/*---------------------------------------------------------------- + Function: OS_TimeBaseLock_Impl + + Purpose: Get exclusive access to the given timebase + Add/remove of application callbacks is prevented + ------------------------------------------------------------------*/ void OS_TimeBaseLock_Impl (uint32 timebase_id); + +/*---------------------------------------------------------------- + Function: OS_TimeBaseLock_Impl + + Purpose: Release exclusive access to the given timebase + Add/remove of application callbacks is allowed + ------------------------------------------------------------------*/ void OS_TimeBaseUnlock_Impl (uint32 timebase_id); + +/*---------------------------------------------------------------- + Function: OS_TimeBaseGetInfo_Impl + + Purpose: Obtain the OS-specific time base information, if any + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_TimeBaseGetInfo_Impl (uint32 timer_id, OS_timebase_prop_t *timer_prop); + +/*---------------------------------------------------------------- + Function: OS_TimeBase_CallbackThread + + Purpose: Implement the time base helper thread + This is the context for providing application callbacks + ------------------------------------------------------------------*/ void OS_TimeBase_CallbackThread (uint32 timebase_id); /* * Clock API low-level handlers * These simply get/set the kernel RTC (if it has one) */ + +/*---------------------------------------------------------------- + Function: OS_GetLocalTime_Impl + + Purpose: Get the time from the RTC + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_GetLocalTime_Impl(OS_time_t *time_struct); + +/*---------------------------------------------------------------- + Function: OS_SetLocalTime_Impl + + Purpose: Set the time in the RTC + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SetLocalTime_Impl(const OS_time_t *time_struct); @@ -593,10 +1220,51 @@ int32 OS_SetLocalTime_Impl(const OS_time_t *time_struct); MODULE LOADER API LOW-LEVEL IMPLEMENTATION FUNCTIONS ****************************************************************************************/ +/*---------------------------------------------------------------- + Function: OS_ModuleLoad_Impl + + Purpose: Loads an object file into the running operating system + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_ModuleLoad_Impl ( uint32 module_id, char *translated_path ); + +/*---------------------------------------------------------------- + + Function: OS_ModuleUnload_Impl + + Purpose: Unloads the module file from the running operating system + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_ModuleUnload_Impl ( uint32 module_id ); + +/*---------------------------------------------------------------- + Function: OS_ModuleGetInfo_Impl + + Purpose: Returns information about the loadable module + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_ModuleGetInfo_Impl ( uint32 module_id, OS_module_prop_t *module_prop ); + +/*---------------------------------------------------------------- + Function: OS_SymbolLookup_Impl + + Purpose: Find the Address of a Symbol + The address of the symbol will be stored in the pointer that is passed in. + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SymbolLookup_Impl ( cpuaddr *SymbolAddress, const char *SymbolName ); + +/*---------------------------------------------------------------- + Function: OS_SymbolTableDump_Impl + + Purpose: Dumps the system symbol table to a file + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SymbolTableDump_Impl ( const char *filename, uint32 size_limit ); @@ -606,27 +1274,39 @@ int32 OS_SymbolTableDump_Impl ( const char *filename, uint32 size_limit ); ****************************************************************************************/ +/*---------------------------------------------------------------- + Function: OS_ConsoleCreate_Impl + + Purpose: Prepare a console device for use + For Async devices, this sets up the background writer task + ------------------------------------------------------------------*/ int32 OS_ConsoleCreate_Impl(uint32 local_id); -/* - * Basic Console output implementation - * - * This function forwards the data from the console - * ring buffer into the actual output device/descriptor - */ +/*---------------------------------------------------------------- + Function: OS_ConsoleOutput_Impl + + Purpose: Basic Console output implementation + + This function forwards the data from the console + ring buffer into the actual output device/descriptor + + The data is already formatted, this just writes the characters. + ------------------------------------------------------------------*/ void OS_ConsoleOutput_Impl(uint32 local_id); -/* - * Console output data notification - * - * This is a notification API that is invoked whenever there - * is new data available in the console output buffer. - * - * For a synchronous console service, this may call - * OS_ConsoleWrite_Impl() directly. For an async console - * service, this should wakeup the actual console servicing - * thread. - */ +/*---------------------------------------------------------------- + Function: OS_ConsoleOutput_Impl + + Purpose: Console output data notification + + This is a notification API that is invoked whenever there + is new data available in the console output buffer. + + For a synchronous console service, this may call + OS_ConsoleWrite_Impl() directly. For an async console + service, this should wakeup the actual console servicing + thread. + ------------------------------------------------------------------*/ void OS_ConsoleWakeup_Impl(uint32 local_id); @@ -665,9 +1345,49 @@ void OS_ConsoleWakeup_Impl(uint32 local_id); * relevant for fifos or sockets. It should be set to OS_PEND for normal * behavior on regular files which is to wait forever. */ + +/*---------------------------------------------------------------- + Function: OS_GenericSeek_Impl + + Purpose: Seek to a given position in a file + + Returns: File position (non-negative) on success, or relevant error code (negative) + ------------------------------------------------------------------*/ int32 OS_GenericSeek_Impl (uint32 local_id, int32 offset, uint32 whence); + +/*---------------------------------------------------------------- + Function: OS_GenericRead_Impl + + Purpose: Read from a file descriptor + This may be a normal file or a socket/pipe + + Returns: Number of bytes read (non-negative) on success, or relevant error code (negative) + ------------------------------------------------------------------*/ int32 OS_GenericRead_Impl (uint32 local_id, void *buffer, uint32 nbytes, int32 timeout); + +/*---------------------------------------------------------------- + Function: OS_GenericWrite_Impl + + Purpose: Write to a file descriptor + This may be a normal file or a socket/pipe + + Returns: Number of bytes written (non-negative) on success, or relevant error code (negative) + ------------------------------------------------------------------*/ int32 OS_GenericWrite_Impl(uint32 local_id, const void *buffer, uint32 nbytes, int32 timeout); + +/**************************************************************************************** + Low Level Input/Output API + ***************************************************************************************/ + + +/*---------------------------------------------------------------- + Function: OS_GenericClose_Impl + + Purpose: Close a file descriptor + This may be a normal file or a socket/pipe + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_GenericClose_Impl(uint32 local_id); @@ -682,25 +1402,119 @@ int32 OS_GenericClose_Impl(uint32 local_id); * filename, so they require a different "open" method, but usually do use * the generic read/write/close pattern thereafter. */ + +/*---------------------------------------------------------------- + Function: OS_FileStat_Impl + + Purpose: Output stats on the file indicated by "local_path" + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_FileStat_Impl(const char *local_path, os_fstat_t *filestat); + +/*---------------------------------------------------------------- + Function: OS_FileRemove_Impl + + Purpose: Remove/Unlink the file indicated by "local_path" + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_FileRemove_Impl(const char *local_path); + +/*---------------------------------------------------------------- + Function: OS_FileRename_Impl + + Purpose: Rename "old_path" to "new_path" in the filesystem + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_FileRename_Impl(const char *old_path, const char *new_path); + +/*---------------------------------------------------------------- + Function: OS_FileOpen_Impl + + Purpose: Opens the file indicated by "local_path" with permission + indicated by "access". + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_FileOpen_Impl(uint32 local_id, const char *local_path, int32 flags, int32 access); + +/*---------------------------------------------------------------- + + Function: OS_FileChmod_Impl + + Purpose: Change permission on an existing file + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_FileChmod_Impl(const char *local_path, uint32 access); -/* - * Output a shell command to an existing open file ID - */ +/*---------------------------------------------------------------- + Function: OS_ShellOutputToFile_Impl + + Purpose: Takes a shell command in and writes the output of that command to the specified file + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_ShellOutputToFile_Impl(uint32 stream_id, const char* Cmd); /* * Directory API abstraction layer */ + +/*---------------------------------------------------------------- + Function: OS_DirCreate_Impl + + Purpose: Create a directory in the local filesystem + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_DirCreate_Impl(const char *local_path, uint32 access); + +/*---------------------------------------------------------------- + Function: OS_DirOpen_Impl + + Purpose: Open a directory and prepare to read the entries + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_DirOpen_Impl(uint32 local_id, const char *local_path); + +/*---------------------------------------------------------------- + Function: OS_DirClose_Impl + + Purpose: Close a directory + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_DirClose_Impl(uint32 local_id); + +/*---------------------------------------------------------------- + Function: OS_DirRead_Impl + + Purpose: Read the next entry from a directory handle + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_DirRead_Impl(uint32 local_id, os_dirent_t *dirent); + +/*---------------------------------------------------------------- + Function: OS_DirRewind_Impl + + Purpose: Rewind a directory handle back to the start + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_DirRewind_Impl(uint32 local_id); + +/*---------------------------------------------------------------- + Function: OS_DirRemove_Impl + + Purpose: Remove a directory in the local filesystem + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_DirRemove_Impl(const char *local_path); /* @@ -708,19 +1522,112 @@ int32 OS_DirRemove_Impl(const char *local_path); * Blocks until specified readable/writable conditions * are met on a file id or set of file ids */ + +/*---------------------------------------------------------------- + Function: OS_SelectSingle_Impl + + Purpose: Waits for activity on a single file descriptor + This wrapper is usable by the File or Socket API + The type of activity to wait for is indicated by "SelectFlags" + msecs indicates the timeout. Positive values will wait up to that many milliseconds. + Zero will not wait (poll) or negative values will wait forever (pend) + + Bits in "SelectFlags" will be unset according to activity + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SelectSingle_Impl(uint32 stream_id, uint32 *SelectFlags, int32 msecs); + +/*---------------------------------------------------------------- + + Function: OS_SelectMultiple_Impl + + Purpose: Waits for activity on multiple file descriptors + This wrapper is usable by the File or Socket API + Will wait for any file descriptor in "ReadSet" to be readable OR + any descriptor in "WriteSet" to be writable. + Time-Limited to "msecs" (negative to wait forever, zero to poll) + + Notes: It is not possible for this function to verify that the file descriptors + passed in are actually valid. In order to do so would require a different + approach to the OS_FdSet structure (this is currently just a bitmask so + the actual file descriptor value is lost in translation). + + Using an array of uint32's would solve the problem but make the structures + much bigger. + + File descriptors in sets be modified according to activity + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SelectMultiple_Impl(OS_FdSet *ReadSet, OS_FdSet *WriteSet, int32 msecs); /* * File system abstraction layer */ + +/*---------------------------------------------------------------- + Function: OS_FileSysStartVolume_Impl + + Purpose: Starts/Registers a file system on the target + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_FileSysStartVolume_Impl (uint32 filesys_id); + +/*---------------------------------------------------------------- + Function: OS_FileSysStopVolume_Impl + + Purpose: Stops/Unregisters a file system on the target + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_FileSysStopVolume_Impl (uint32 filesys_id); + +/*---------------------------------------------------------------- + Function: OS_FileSysFormatVolume_Impl + + Purpose: Formats a file system on the target to prepare it for use + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_FileSysFormatVolume_Impl (uint32 filesys_id); + +/*---------------------------------------------------------------- + Function: OS_FileSysCheckVolume_Impl + + Purpose: Checks the drives and optionally repairs inconsistencies + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_FileSysCheckVolume_Impl (uint32 filesys_id, bool repair); + +/*---------------------------------------------------------------- + Function: OS_FileSysStatVolume_Impl + + Purpose: Returns stats about a volume + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_FileSysStatVolume_Impl (uint32 filesys_id, OS_statvfs_t *result); + +/*---------------------------------------------------------------- + Function: OS_FileSysMountVolume_Impl + + Purpose: mounts a drive + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_FileSysMountVolume_Impl (uint32 filesys_id); + +/*---------------------------------------------------------------- + Function: OS_FileSysUnmountVolume_Impl + + Purpose: unmounts a drive. + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_FileSysUnmountVolume_Impl (uint32 filesys_id); @@ -728,24 +1635,155 @@ int32 OS_FileSysUnmountVolume_Impl (uint32 filesys_id); NETWORK / SOCKET API LOW-LEVEL IMPLEMENTATION FUNCTIONS ****************************************************************************************/ + +/*---------------------------------------------------------------- + + Function: OS_NetworkGetHostName_Impl + + Purpose: Gets the name of the current host + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_NetworkGetHostName_Impl (char *host_name, uint32 name_len); + +/*---------------------------------------------------------------- + Function: OS_NetworkGetID_Impl + + Purpose: Gets the ID of the host on the network + + Returns: the ID value on success, or -1 on error. + ------------------------------------------------------------------*/ int32 OS_NetworkGetID_Impl (int32 *IdBuf); /* * Sockets API abstraction layer */ + +/*---------------------------------------------------------------- + Function: OS_SocketOpen_Impl + + Purpose: Opens the OS socket indicated by the sock_id table entry + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SocketOpen_Impl(uint32 sock_id); + +/*---------------------------------------------------------------- + Function: OS_SocketBind_Impl + + Purpose: Binds the indicated socket table entry to the passed-in address + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SocketBind_Impl(uint32 sock_id, const OS_SockAddr_t *Addr); + +/*---------------------------------------------------------------- + Function: OS_SocketAccept_Impl + + Purpose: Accept an incoming connection on the indicated socket (must be a STREAM socket) + Will wait up to "timeout" milliseconds for an incoming connection + Will wait forever if timeout is negative + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SocketAccept_Impl(uint32 sock_id, uint32 connsock_id, OS_SockAddr_t *Addr, int32 timeout); + +/*---------------------------------------------------------------- + Function: OS_SocketConnect_Impl + + Purpose: Connects the socket to a remote address. + Socket must be of the STREAM variety. + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SocketConnect_Impl(uint32 sock_id, const OS_SockAddr_t *Addr, int32 timeout); + +/*---------------------------------------------------------------- + Function: OS_SocketRecvFrom_Impl + + Purpose: Receives a datagram from the specified socket (must be of the DATAGRAM type) + Stores the datagram in "buffer" which has a maximum size of "buflen" + Stores the remote address (sender of the datagram) in "RemoteAddr" + Will wait up to "timeout" milliseconds to receive a packet + (zero to poll, negative to wait forever) + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SocketRecvFrom_Impl(uint32 sock_id, void *buffer, uint32 buflen, OS_SockAddr_t *RemoteAddr, int32 timeout); + +/*---------------------------------------------------------------- + Function: OS_SocketSendTo_Impl + + Purpose: Sends a datagram from the specified socket (must be of the DATAGRAM type) + to the remote address specified by "RemoteAddr" + The datagram to send must be stored in "buffer" with a size of "buflen" + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SocketSendTo_Impl(uint32 sock_id, const void *buffer, uint32 buflen, const OS_SockAddr_t *RemoteAddr); + +/*---------------------------------------------------------------- + + Function: OS_SocketGetInfo_Impl + + Purpose: Get OS-specific information about a socket + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SocketGetInfo_Impl (uint32 sock_id, OS_socket_prop_t *sock_prop); - + +/*---------------------------------------------------------------- + + Function: OS_SocketAddrInit_Impl + + Purpose: Initializes an OSAL SockAddr structure to the given address domain + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SocketAddrInit_Impl(OS_SockAddr_t *Addr, OS_SocketDomain_t Domain); + +/*---------------------------------------------------------------- + Function: OS_SocketAddrToString_Impl + + Purpose: Converts a Socket Address structure to a printable string + Useful for including a dotted-decimal IP address in a message or log + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SocketAddrToString_Impl(char *buffer, uint32 buflen, const OS_SockAddr_t *Addr); + +/*---------------------------------------------------------------- + Function: OS_SocketAddrFromString_Impl + + Purpose: Sets the Address portion of the SockAddr structure according to the string + For IPV4 (SocketDomain_INET) this will parse the dotted decimal IP address. + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SocketAddrFromString_Impl(OS_SockAddr_t *Addr, const char *string); + +/*---------------------------------------------------------------- + Function: OS_SocketAddrGetPort_Impl + + Purpose: Retrieve the TCP/UDP port number from the SockAddr structure + + NOTE: The port number is output to the caller in native byte order + (the value is converted from network order before return) + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SocketAddrGetPort_Impl(uint16 *PortNum, const OS_SockAddr_t *Addr); + +/*---------------------------------------------------------------- + Function: OS_SocketAddrSetPort_Impl + + Purpose: Set the TCP/UDP port number in the SockAddr structure + + NOTE: The port number should be passed in native byte order + (this function will convert to network order) + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_SocketAddrSetPort_Impl(OS_SockAddr_t *Addr, uint16 PortNum); @@ -762,12 +1800,70 @@ int32 OS_SocketAddrSetPort_Impl(OS_SockAddr_t *Addr, uint16 PortNum); * VxWorks or RTEMS, but not Linux. As such they should not be * relied upon. */ + +/*---------------------------------------------------------------- + Function: OS_IntAttachHandler_Impl + + Purpose: The call associates a specified C routine to a specified interrupt + number.Upon occurring of the InterruptNumber the InerruptHandler + routine will be called and passed the parameter. + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_IntAttachHandler_Impl (uint32 InterruptNumber, osal_task_entry InterruptHandler, int32 parameter); + +/*---------------------------------------------------------------- + Function: OS_IntUnlock_Impl + + Purpose: Enable previous state of interrupts + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_IntUnlock_Impl (int32 IntLevel); + +/*---------------------------------------------------------------- + Function: OS_IntLock_Impl + + Purpose: Disable interrupts + + Returns: A key value that can be used to restore interrupts + ------------------------------------------------------------------*/ int32 OS_IntLock_Impl ( void ); + +/*---------------------------------------------------------------- + Function: OS_IntEnable_Impl + + Purpose: Enable previous state of interrupts + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_IntEnable_Impl(int32 Level); + +/*---------------------------------------------------------------- + Function: OS_IntDisable_Impl + + Purpose: Disable the corresponding interrupt number. + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_IntDisable_Impl(int32 Level); + +/*---------------------------------------------------------------- + Function: OS_IntSetMask_Impl + + Purpose: Set the cpu mask register for interrupts + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_IntSetMask_Impl ( uint32 MaskSetting ); + +/*---------------------------------------------------------------- + Function: OS_IntGetMask_Impl + + Purpose: Read and output the setting of the cpu mask register + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_IntGetMask_Impl ( uint32 * MaskSettingPtr ); /**************************************************************************************** @@ -782,7 +1878,23 @@ int32 OS_FPUExcAttachHandler_Impl(uint32 ExceptionNumber, void * ExceptionHandle int32 parameter); int32 OS_FPUExcEnable_Impl(int32 ExceptionNumber); int32 OS_FPUExcDisable_Impl(int32 ExceptionNumber); + +/*---------------------------------------------------------------- + Function: OS_FPUExcSetMask_Impl + + Purpose: This function sets the FPU exception mask + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_FPUExcSetMask_Impl(uint32 mask); + +/*---------------------------------------------------------------- + Function: OS_FPUExcGetMask_Impl + + Purpose: This function gets the FPU exception mask + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_FPUExcGetMask_Impl(uint32 *mask); @@ -794,6 +1906,14 @@ int32 OS_FPUExcGetMask_Impl(uint32 *mask); /* * This may also not be implementable on some platforms */ + +/*---------------------------------------------------------------- + Function: OS_HeapGetInfo_Impl + + Purpose: Return current info on the heap + + Returns: OS_SUCCESS on success, or relevant error code + ------------------------------------------------------------------*/ int32 OS_HeapGetInfo_Impl(OS_heap_prop_t *heap_prop); diff --git a/src/os/shared/osapi-binsem.c b/src/os/shared/osapi-binsem.c index 1c6da7854..4e72b5cab 100644 --- a/src/os/shared/osapi-binsem.c +++ b/src/os/shared/osapi-binsem.c @@ -66,30 +66,30 @@ OS_apiname_internal_record_t OS_bin_sem_table [LOCAL_NUM_OBJECTS]; Returns: OS_SUCCESS ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemAPI_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_BinSemAPI_Init(void) { memset(OS_bin_sem_table, 0, sizeof(OS_bin_sem_table)); return OS_SUCCESS; -} +} /* end OS_BinSemAPI_Init */ -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemCreate - - Purpose: Creates a binary semaphore with initial value specified by - sem_initial_value and name specified by sem_name. sem_id will be - returned to the caller - - Returns: 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 - OS_SUCCESS if success - - - Notes: options is an unused parameter ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemCreate + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemCreate (uint32 *sem_id, const char *sem_name, uint32 sem_initial_value, uint32 options) { @@ -126,21 +126,17 @@ int32 OS_BinSemCreate (uint32 *sem_id, const char *sem_name, uint32 sem_initial_ return return_code; -}/* end OS_BinSemCreate */ - -/*-------------------------------------------------------------------------------------- - Name: OS_BinSemDelete +} /* end OS_BinSemCreate */ - Purpose: Deletes the specified Binary Semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid binary semaphore - OS_SEM_FAILURE the OS call failed - OS_SUCCESS if success - - Notes: Since we can't delete a semaphore which is currently locked by some task - (as it may ber crucial to completing the task), the semaphore must be full to - allow deletion. ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemDelete + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemDelete (uint32 sem_id) { OS_common_record_t *record; @@ -164,25 +160,18 @@ int32 OS_BinSemDelete (uint32 sem_id) return return_code; -}/* end OS_BinSemDelete */ - - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemGive - - Purpose: The function unlocks the semaphore referenced by sem_id by performing - a semaphore unlock operation on that semaphore.If the semaphore value - resulting from this operation is positive, then no threads were blocked - waiting for the semaphore to become unlocked; the semaphore value is - simply incremented for this semaphore. +} /* end OS_BinSemDelete */ - Returns: 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 - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemGive + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemGive ( uint32 sem_id ) { OS_common_record_t *record; @@ -198,21 +187,17 @@ int32 OS_BinSemGive ( uint32 sem_id ) return return_code; -}/* end OS_BinSemGive */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemFlush - - Purpose: The function unblocks all tasks pending on the specified semaphore. However, - this function does not change the state of the semaphore. - - - Returns: 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 - OS_SUCCESS if success +} /* end OS_BinSemGive */ ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemFlush + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemFlush (uint32 sem_id) { OS_common_record_t *record; @@ -227,22 +212,17 @@ int32 OS_BinSemFlush (uint32 sem_id) } return return_code; -}/* end OS_BinSemFlush */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemTake - - Purpose: The locks the semaphore referenced by sem_id by performing a - semaphore lock operation on that semaphore.If the semaphore value - is currently zero, then the calling thread shall not return from - the call until it either locks the semaphore or the call is - interrupted by a signal. - - Return: OS_ERR_INVALID_ID the Id passed in is not a valid binary semaphore - OS_SEM_FAILURE if the OS call failed - OS_SUCCESS if success +} /* end OS_BinSemFlush */ -----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemTake + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemTake ( uint32 sem_id ) { OS_common_record_t *record; @@ -257,23 +237,17 @@ int32 OS_BinSemTake ( uint32 sem_id ) } return return_code; -}/* end OS_BinSemTake */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemTimedWait - - Purpose: The function locks the semaphore referenced by sem_id . However, - if the semaphore cannot be locked without waiting for another process - or thread to unlock the semaphore , this wait shall be terminated when - the specified timeout ,msecs, expires. +} /* end OS_BinSemTake */ - Returns: OS_SEM_TIMEOUT if semaphore was not relinquished in time - OS_SUCCESS if success - 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 - -----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemTimedWait + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemTimedWait ( uint32 sem_id, uint32 msecs ) { OS_common_record_t *record; @@ -288,19 +262,16 @@ int32 OS_BinSemTimedWait ( uint32 sem_id, uint32 msecs ) } return return_code; -} -/*-------------------------------------------------------------------------------------- - Name: OS_BinSemGetIdByName - - Purpose: This function tries to find a binary sem Id given the name of a bin_sem - The id is returned through sem_id - - Returns: 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 - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +} /* end OS_BinSemTimedWait */ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemGetIdByName + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemGetIdByName (uint32 *sem_id, const char *sem_name) { int32 return_code; @@ -313,19 +284,17 @@ int32 OS_BinSemGetIdByName (uint32 *sem_id, const char *sem_name) return_code = OS_ObjectIdFindByName(LOCAL_OBJID_TYPE, sem_name, sem_id); return return_code; -}/* end OS_BinSemGetIdByName */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info( name and creator) about the specified binary - semaphore. +} /* end OS_BinSemGetIdByName */ - Returns: 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 ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemGetInfo + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemGetInfo (uint32 sem_id, OS_bin_sem_prop_t *bin_prop) { OS_common_record_t *record; diff --git a/src/os/shared/osapi-clock.c b/src/os/shared/osapi-clock.c index faadd5978..14fcac60c 100644 --- a/src/os/shared/osapi-clock.c +++ b/src/os/shared/osapi-clock.c @@ -32,12 +32,15 @@ #include "common_types.h" #include "os-impl.h" -/*--------------------------------------------------------------------------------------- - * Name: OS_GetLocalTime + +/*---------------------------------------------------------------- * - * Purpose: This functions get the local time of the machine its on - * ------------------------------------------------------------------------------------*/ - + * Function: OS_GetLocalTime + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_GetLocalTime(OS_time_t *time_struct) { if (time_struct == NULL) @@ -47,14 +50,17 @@ int32 OS_GetLocalTime(OS_time_t *time_struct) return OS_GetLocalTime_Impl(time_struct); -}/* end OS_GetLocalTime */ +} /* end OS_GetLocalTime */ -/*--------------------------------------------------------------------------------------- - * Name: OS_SetLocalTime + +/*---------------------------------------------------------------- * - * Purpose: This functions set the local time of the machine its on - * ------------------------------------------------------------------------------------*/ - + * Function: OS_SetLocalTime + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SetLocalTime(OS_time_t *time_struct) { if (time_struct == NULL) @@ -64,5 +70,4 @@ int32 OS_SetLocalTime(OS_time_t *time_struct) return OS_SetLocalTime_Impl(time_struct); -} /*end OS_SetLocalTime */ - +} /* end OS_SetLocalTime */ diff --git a/src/os/shared/osapi-common.c b/src/os/shared/osapi-common.c index e339ea6fb..dde63d3b8 100644 --- a/src/os/shared/osapi-common.c +++ b/src/os/shared/osapi-common.c @@ -51,14 +51,15 @@ OS_SharedGlobalVars_t OS_SharedGlobalVars = */ -/*--------------------------------------------------------------------------------------- - Name: OS_API_Init - - Purpose: Initialize the tables that the OS API uses to keep track of information - about objects - - returns: OS_SUCCESS or OS_ERROR ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_API_Init + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_API_Init(void) { int32 return_code = OS_SUCCESS; @@ -161,21 +162,17 @@ int32 OS_API_Init(void) } return(return_code); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_ApplicationExit +} /* end OS_API_Init */ - Purpose: 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. - - Returns: None - - NOTES: This exits the entire process including tasks that have been created. - It does not return. Production code typically should not ever call this. - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ApplicationExit + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ void OS_ApplicationExit(int32 Status) { if (Status == OS_SUCCESS) @@ -186,7 +183,7 @@ void OS_ApplicationExit(int32 Status) { exit(EXIT_FAILURE); } -} +} /* end OS_ApplicationExit */ /*--------------------------------------------------------------------------------------- Name: OS_CleanUpObject @@ -197,6 +194,14 @@ void OS_ApplicationExit(int32 Status) Returns: None ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CleanUpObject + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ void OS_CleanUpObject(uint32 object_id, void *arg) { uint32 *ObjectCount; @@ -238,15 +243,17 @@ void OS_CleanUpObject(uint32 object_id, void *arg) default: break; } -} - -/*--------------------------------------------------------------------------------------- - Name: OS_DeleteAllObjects - - Purpose: Clean up routine, delete all resources created in OSAL. +} /* end OS_CleanUpObject */ - returns: no value ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_DeleteAllObjects + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ void OS_DeleteAllObjects(void) { uint32 ObjectCount; @@ -269,17 +276,17 @@ void OS_DeleteAllObjects(void) OS_TaskDelay(5); } while (ObjectCount > 0 && TryCount < 5); -} +} /* end OS_DeleteAllObjects */ -/*--------------------------------------------------------------------------------------- - Name: OS_IdleLoop - - Purpose: Should be called after all initialization is done - This thread may be used to wait for and handle external events - Typically just waits forever until "OS_shutdown" flag becomes true. - - returns: no value ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_IdleLoop + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ void OS_IdleLoop() { /* @@ -291,18 +298,18 @@ void OS_IdleLoop() { OS_IdleLoop_Impl(); } -} - - -/*--------------------------------------------------------------------------------------- - Name: OS_ApplicationShutdown +} /* end OS_IdleLoop */ - Purpose: Indicates that the OSAL application should perform an orderly shutdown - of ALL tasks, clean up all resources, and exit the application. - returns: none - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ApplicationShutdown + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ void OS_ApplicationShutdown(uint8 flag) { if (flag == true) @@ -316,5 +323,5 @@ void OS_ApplicationShutdown(uint8 flag) * should do whatever is needed to wake that task up. */ OS_ApplicationShutdown_Impl(); -} +} /* end OS_ApplicationShutdown */ diff --git a/src/os/shared/osapi-countsem.c b/src/os/shared/osapi-countsem.c index 3546140a2..b7e08f63c 100644 --- a/src/os/shared/osapi-countsem.c +++ b/src/os/shared/osapi-countsem.c @@ -59,39 +59,31 @@ OS_apiname_internal_record_t OS_count_sem_table [LOCAL_NUM_OBJECTS]; SEMAPHORE API ***************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemAPI_Init - - Purpose: Init function for OS-independent layer - - Returns: OS_SUCCESS - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemAPI_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * Init function for OS-independent layer + * + *-----------------------------------------------------------------*/ int32 OS_CountSemAPI_Init(void) { memset(OS_count_sem_table, 0, sizeof(OS_count_sem_table)); return OS_SUCCESS; -} - +} /* end OS_CountSemAPI_Init */ -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemCreate - Purpose: Creates a counting semaphore with initial value specified by - sem_initial_value and name specified by sem_name. sem_id will be - returned to the caller - - Returns: 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 - OS_SUCCESS if success - - - Notes: options is an unused parameter ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemCreate + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemCreate (uint32 *sem_id, const char *sem_name, uint32 sem_initial_value, uint32 options) { @@ -127,21 +119,17 @@ int32 OS_CountSemCreate (uint32 *sem_id, const char *sem_name, uint32 sem_initia return return_code; -}/* end OS_CountSemCreate */ +} /* end OS_CountSemCreate */ -/*-------------------------------------------------------------------------------------- - Name: OS_CountSemDelete - - Purpose: Deletes the specified Countary Semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid counting semaphore - OS_SEM_FAILURE the OS call failed - OS_SUCCESS if success - - Notes: Since we can't delete a semaphore which is currently locked by some task - (as it may be crucial to completing the task), the semaphore must be full to - allow deletion. ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemDelete + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemDelete (uint32 sem_id) { OS_common_record_t *record; @@ -165,25 +153,18 @@ int32 OS_CountSemDelete (uint32 sem_id) return return_code; -}/* end OS_CountSemDelete */ +} /* end OS_CountSemDelete */ -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemGive - - Purpose: The function unlocks the semaphore referenced by sem_id by performing - a semaphore unlock operation on that semaphore.If the semaphore value - resulting from this operation is positive, then no threads were blocked - waiting for the semaphore to become unlocked; the semaphore value is - simply incremented for this semaphore. - - - Returns: 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 - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemGive + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemGive ( uint32 sem_id ) { OS_common_record_t *record; @@ -199,22 +180,17 @@ int32 OS_CountSemGive ( uint32 sem_id ) return return_code; -}/* end OS_CountSemGive */ - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemTake - - Purpose: The locks the semaphore referenced by sem_id by performing a - semaphore lock operation on that semaphore.If the semaphore value - is currently zero, then the calling thread shall not return from - the call until it either locks the semaphore or the call is - interrupted by a signal. - - Return: OS_ERR_INVALID_ID the Id passed in is not a valid counting semaphore - OS_SEM_FAILURE if the OS call failed - OS_SUCCESS if success +} /* end OS_CountSemGive */ -----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemTake + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemTake ( uint32 sem_id ) { OS_common_record_t *record; @@ -229,23 +205,17 @@ int32 OS_CountSemTake ( uint32 sem_id ) } return return_code; -}/* end OS_CountSemTake */ +} /* end OS_CountSemTake */ -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemTimedWait - - Purpose: The function locks the semaphore referenced by sem_id . However, - if the semaphore cannot be locked without waiting for another process - or thread to unlock the semaphore , this wait shall be terminated when - the specified timeout ,msecs, expires. - - Returns: OS_SEM_TIMEOUT if semaphore was not relinquished in time - OS_SUCCESS if success - 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 - -----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemTimedWait + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemTimedWait ( uint32 sem_id, uint32 msecs ) { OS_common_record_t *record; @@ -260,20 +230,17 @@ int32 OS_CountSemTimedWait ( uint32 sem_id, uint32 msecs ) } return return_code; -} +} /* end OS_CountSemTimedWait */ -/*-------------------------------------------------------------------------------------- - Name: OS_CountSemGetIdByName - - Purpose: This function tries to find a counting sem Id given the name of a count_sem - The id is returned through sem_id - - Returns: 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 - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemGetIdByName + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemGetIdByName (uint32 *sem_id, const char *sem_name) { int32 return_code; @@ -286,20 +253,17 @@ int32 OS_CountSemGetIdByName (uint32 *sem_id, const char *sem_name) return_code = OS_ObjectIdFindByName(LOCAL_OBJID_TYPE, sem_name, sem_id); return return_code; -}/* end OS_CountSemGetIdByName */ - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info( name and creator) about the specified counting - semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid semaphore - OS_INVALID_POINTER if the count_prop pointer is null - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ +} /* end OS_CountSemGetIdByName */ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemGetInfo + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemGetInfo (uint32 sem_id, OS_count_sem_prop_t *count_prop) { OS_common_record_t *record; diff --git a/src/os/shared/osapi-dir.c b/src/os/shared/osapi-dir.c index f8a04dade..10d554321 100644 --- a/src/os/shared/osapi-dir.c +++ b/src/os/shared/osapi-dir.c @@ -75,34 +75,30 @@ typedef union DIRECTORY API ***************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_DirAPI_Init - - Purpose: Init function for OS-independent layer - - Returns: OS_SUCCESS - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_DirAPI_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * Init function for OS-independent layer + * + *-----------------------------------------------------------------*/ int32 OS_DirAPI_Init(void) { memset(OS_dir_table, 0, sizeof(OS_dir_table)); return OS_SUCCESS; -} - -/*-------------------------------------------------------------------------------------- - Name: OS_mkdir - - Purpose: makes a directory specified by path. - - Returns: OS_FS_ERR_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_FS_ERROR if the OS call fails - OS_FS_SUCCESS if success - - Note: The access parameter is currently unused. ----------------------------------------------------------------------------------------*/ +} /* end OS_DirAPI_Init */ + +/*---------------------------------------------------------------- + * + * Function: OS_mkdir + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_mkdir (const char *path, uint32 access) { int32 return_code; @@ -116,16 +112,17 @@ int32 OS_mkdir (const char *path, uint32 access) return return_code; -}/* end OS_mkdir */ - -/*-------------------------------------------------------------------------------------- - Name: OS_DirectoryOpen - - Purpose: opens a directory for searching, OSAL-style API - - Returns: OS_SUCCESS or error code +} /* end OS_mkdir */ ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_DirectoryOpen + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_DirectoryOpen(uint32 *dir_id, const char *path) { char local_path[OS_MAX_LOCAL_PATH_LEN]; @@ -161,15 +158,15 @@ int32 OS_DirectoryOpen(uint32 *dir_id, const char *path) } /* end OS_DirectoryOpen */ -/*-------------------------------------------------------------------------------------- - Name: OS_DirectoryClose - - Purpose: close a directory - - Returns: OS_FS_SUCCESS if success - OS_FS_ERROR if close failed ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_DirectoryClose + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_DirectoryClose(uint32 dir_id) { OS_common_record_t *record; @@ -195,13 +192,15 @@ int32 OS_DirectoryClose(uint32 dir_id) return return_code; } /* end OS_DirectoryClose */ -/*-------------------------------------------------------------------------------------- - Name: OS_DirectoryRead - - Purpose: obtains directory entry data for the next file from an open directory - - Returns: OS_SUCCESS or error code ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_DirectoryRead + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_DirectoryRead(uint32 dir_id, os_dirent_t *dirent) { OS_common_record_t *record; @@ -236,13 +235,15 @@ int32 OS_DirectoryRead(uint32 dir_id, os_dirent_t *dirent) } /* end OS_DirectoryRead */ -/*-------------------------------------------------------------------------------------- - Name: OS_DirectoryRewind - - Purpose: rewind a directory - - Returns: OS_SUCCESS or error code ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_DirectoryRewind + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_DirectoryRewind(uint32 dir_id) { OS_common_record_t *record; @@ -259,18 +260,15 @@ int32 OS_DirectoryRewind(uint32 dir_id) return return_code; } /* end OS_DirectoryRewind */ -/*-------------------------------------------------------------------------------------- - Name: OS_rmdir - - Purpose: removes a directory from the structure (must be an empty directory) - - Returns: OS_FS_ERR_INVALID_POINTER if path is NULL - OS_FS_ERR_PATH_INVALID if path cannot be parsed - OS_FS_ER_PATH_TOO_LONG - OS_FS_SUCCESS on success - OS_FS_ERROR if the directory remove operation failed ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_rmdir + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_rmdir (const char *path) { int32 return_code; @@ -284,23 +282,20 @@ int32 OS_rmdir (const char *path) return return_code; -}/* end OS_rmdir */ +} /* end OS_rmdir */ /* * Compatibility layers for old-style API */ #ifndef OSAL_OMIT_DEPRECATED -/*-------------------------------------------------------------------------------------- - Name: OS_opendir - - Purpose: opens a directory for searching - Backward-compatible API - - Returns: NULL if there is an error - a "pointer" to a directory if success - ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + + * Function: OS_opendir + * + * Purpose: Open a directory. Deprecated function. + * + *-----------------------------------------------------------------*/ os_dirp_t OS_opendir (const char *path) { OS_Dirp_Xltr_t dirdescptr; @@ -309,17 +304,16 @@ os_dirp_t OS_opendir (const char *path) OS_DirectoryOpen(&dirdescptr.dir_id, path); return dirdescptr.dirp; -} - -/*-------------------------------------------------------------------------------------- - Name: OS_closedir - - Purpose: closes a directory - - Returns: OS_FS_SUCCESS if success - OS_FS_ERROR if close failed ----------------------------------------------------------------------------------------*/ +} /* end OS_opendir */ + +/*---------------------------------------------------------------- + * + * Function: OS_closedir + * + * Purpose: closes a directory. Deprecated function. + * + *-----------------------------------------------------------------*/ int32 OS_closedir (os_dirp_t directory) { OS_Dirp_Xltr_t dirdescptr; @@ -331,21 +325,18 @@ int32 OS_closedir (os_dirp_t directory) dirdescptr.dirp = directory; return (OS_DirectoryClose(dirdescptr.dir_id)); -} - -/*-------------------------------------------------------------------------------------- - Name: OS_readdir - - Purpose: obtains directory entry data for the next file from an open directory - - Returns: a pointer to the next entry for success - NULL if error or end of directory is reached +} /* end OS_closedir */ - NOTE: this function is not thread-safe, and it cannot ever be thread-safe. - Whoever implemented this originally copied the old UNIX API which is also broken. - The problem is that the returned pointer might be overwritten by another - call to OS_readdir by another thread. ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_readdir + * + * Purpose: read a directory. Deprecated function. + * + * NOTE: this function is not thread-safe, and it cannot ever be thread-safe, + * which is one reason why this is deprecated. + * + *-----------------------------------------------------------------*/ os_dirent_t *OS_readdir (os_dirp_t directory) { OS_Dirp_Xltr_t dirdescptr; @@ -362,14 +353,15 @@ os_dirent_t *OS_readdir (os_dirp_t directory) } return tempptr; -} -/*-------------------------------------------------------------------------------------- - Name: OS_rewinddir +} /* end OS_readdir */ - Purpose: Rewinds the directory pointer - - Returns: N/A ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_rewinddir + * + * Purpose: Rewinds the directory pointer. Deprecated Function. + * + *-----------------------------------------------------------------*/ void OS_rewinddir (os_dirp_t directory ) { OS_Dirp_Xltr_t dirdescptr; @@ -377,7 +369,7 @@ void OS_rewinddir (os_dirp_t directory ) dirdescptr.dirp = directory; OS_DirectoryRewind(dirdescptr.dir_id); -} +} /* end OS_rewinddir */ #endif diff --git a/src/os/shared/osapi-errors.c b/src/os/shared/osapi-errors.c index 616acbc1e..7d985b0b8 100644 --- a/src/os/shared/osapi-errors.c +++ b/src/os/shared/osapi-errors.c @@ -83,9 +83,15 @@ static const OS_ErrorTable_Entry_t OS_GLOBAL_ERROR_NAME_TABLE[] = */ -/*--------------------------------------------------------------------------------------- - * Name: OS_GetErrorName() - *---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_GetErrorName + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_GetErrorName(int32 error_num, os_err_name_t* err_name) { uint32 return_code; @@ -125,5 +131,5 @@ int32 OS_GetErrorName(int32 error_num, os_err_name_t* err_name) (*err_name)[OS_ERROR_NAME_LENGTH - 1] = '\0'; return return_code; -} +} /* end OS_GetErrorName */ diff --git a/src/os/shared/osapi-file.c b/src/os/shared/osapi-file.c index 756af94da..ce14cf264 100644 --- a/src/os/shared/osapi-file.c +++ b/src/os/shared/osapi-file.c @@ -54,18 +54,16 @@ enum OS_stream_internal_record_t OS_stream_table[OS_MAX_NUM_OPEN_FILES]; -/* -------------------------------------------------------------------------------------- - Name: OS_check_name_length - - Purpose: Checks the length of the file name at the end of the path. - - Returns: OS_FS_ERROR if path is NULL, path is too long, there is no '/' in the path - name, the name is too long - OS_SUCCESS if success - - NOTE: This is only an internal function and is not intended for use by the user - ---------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_check_name_length + * + * Purpose: Local helper routine, not part of OSAL API. + * Validates that the path length is within spec and + * contains at least one directory separator (/) char. + * + *-----------------------------------------------------------------*/ static int32 OS_check_name_length(const char *path) { char* name_ptr; @@ -89,35 +87,37 @@ static int32 OS_check_name_length(const char *path) return OS_FS_SUCCESS; -}/* end OS_check_name_length */ +} /* end OS_check_name_length */ /**************************************************************************************** FILE API ***************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_StreamAPI_Init - - Purpose: Init function for OS-independent layer - - Returns: OS_SUCCESS - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileAPI_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * Init function for OS-independent layer + * + *-----------------------------------------------------------------*/ int32 OS_FileAPI_Init(void) { memset(OS_stream_table, 0, sizeof(OS_stream_table)); return OS_SUCCESS; -} - +} /* end OS_FileAPI_Init */ -/*--------------------------------------------------------------------------------------- - Name: OS_OpenCreate - Purpose: Local function to implement both "open" and "creat" - (The difference is a matter of what flags are passed in) - - returns: OS_SUCCESS or OS_ERROR ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_OpenCreate + * + * Purpose: Local helper routine, not part of OSAL API. + * Implements both "open" and "creat" file operations + * (The difference is a matter of what flags are passed in) + * + *-----------------------------------------------------------------*/ static int32 OS_OpenCreate(uint32 *filedes, const char *path, int32 flags, int32 access) { int32 return_code; @@ -157,25 +157,17 @@ static int32 OS_OpenCreate(uint32 *filedes, const char *path, int32 flags, int32 } return return_code; -} - -/*-------------------------------------------------------------------------------------- - Name: OS_creat - - Purpose: creates a file specified by const char *path, with read/write - permissions by access. The file is also automatically opened by the - create call. - - Returns: OS_FS_ERR_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_FS_ERROR if permissions are unknown or OS call fails - OS_FS_ERR_NO_FREE_FDS if there are no free file descripors left - OS_FS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +} /* end OS_OpenCreate */ + +/*---------------------------------------------------------------- + * + * Function: OS_creat + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_creat (const char *path, int32 access) { uint32 filedes; @@ -205,21 +197,15 @@ int32 OS_creat (const char *path, int32 access) return return_code; } /* end OS_creat */ -/*-------------------------------------------------------------------------------------- - Name: OS_open - - Purpose: Opens a file. access parameters are OS_READ_ONLY,OS_WRITE_ONLY, or - OS_READ_WRITE - - Returns: OS_FS_ERR_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_FS_ERROR if permissions are unknown or OS call fails - OS_FS_ERR_NO_FREE_FDS if there are no free file descriptors left - a file descriptor if success ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_open + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_open (const char *path, int32 access, uint32 mode) { uint32 filedes; @@ -249,16 +235,15 @@ int32 OS_open (const char *path, int32 access, uint32 mode) } /* end OS_open */ -/*-------------------------------------------------------------------------------------- - Name: OS_close - - Purpose: Closes a file. - - Returns: OS_FS_ERROR if file descriptor could not be closed - OS_FS_ERR_INVALID_FD if the file descriptor passed in is invalid - OS_FS_SUCCESS if success ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_close + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_close (uint32 filedes) { OS_common_record_t *record; @@ -283,16 +268,17 @@ int32 OS_close (uint32 filedes) return return_code; -}/* end OS_close */ - -/*-------------------------------------------------------------------------------------- - Name: OS_TimedRead +} /* end OS_close */ - Purpose: reads up to nbytes from a stream, and puts them into buffer. - Will wait up to the time specified in timeout (OS_PEND = forever) - - Returns: number of bytes read if success, <0 on error ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TimedRead + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_TimedRead(uint32 filedes, void *buffer, uint32 nbytes, int32 timeout) { OS_common_record_t *record; @@ -313,16 +299,17 @@ int32 OS_TimedRead(uint32 filedes, void *buffer, uint32 nbytes, int32 timeout) } return return_code; -}/* end OS_read */ - -/*-------------------------------------------------------------------------------------- - Name: OS_TimedWrite - - Purpose: writes to a stream up to a maximum of nbytes to the file described in filedes - Will wait up to the time specified in timeout (OS_PEND = forever) +} /* end OS_TimedRead */ - Returns: number of bytes written if success, <0 on error ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TimedWrite + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_TimedWrite(uint32 filedes, const void *buffer, uint32 nbytes, int32 timeout) { OS_common_record_t *record; @@ -343,47 +330,46 @@ int32 OS_TimedWrite(uint32 filedes, const void *buffer, uint32 nbytes, int32 ti } return return_code; -}/* end OS_write */ - -/*-------------------------------------------------------------------------------------- - Name: OS_read +} /* end OS_TimedWrite */ - Purpose: reads up to nbytes from a file, and puts them into buffer. - - Returns: OS_FS_ERR_INVALID_POINTER if buffer is a null pointer - OS_FS_ERROR if OS call failed - OS_FS_ERR_INVALID_FD if the file descriptor passed in is invalid - number of bytes read if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_read + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_read (uint32 filedes, void *buffer, uint32 nbytes) { return OS_TimedRead(filedes, buffer, nbytes, OS_PEND); -}/* end OS_read */ - -/*-------------------------------------------------------------------------------------- - Name: OS_write - - Purpose: writes to a file. copies up to a maximum of nbtyes of buffer to the file - described in filedes - - Returns: OS_FS_ERR_INVALID_POINTER if buffer is NULL - OS_FS_ERROR if OS call failed - OS_FS_ERR_INVALID_FD if the file descriptor passed in is invalid - number of bytes written if success ----------------------------------------------------------------------------------------*/ +} /* end OS_read */ + +/*---------------------------------------------------------------- + * + * Function: OS_write + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_write (uint32 filedes, const void *buffer, uint32 nbytes) { return OS_TimedWrite(filedes, buffer, nbytes, OS_PEND); -}/* end OS_write */ - - -/*-------------------------------------------------------------------------------------- - Name: OS_chmod +} /* end OS_write */ - Notes: This is not going to be implemented because there is no use for this function. ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_chmod + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_chmod (const char *path, uint32 access) { char local_path[OS_MAX_LOCAL_PATH_LEN]; @@ -399,21 +385,15 @@ int32 OS_chmod (const char *path, uint32 access) } /* end OS_chmod */ -/*-------------------------------------------------------------------------------------- - Name: OS_stat - - Purpose: returns information about a file or directory in a os_fs_stat structure - - Returns: OS_FS_ERR_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_FS_ERROR id the OS call failed - OS_FS_SUCCESS if success - - Note: The information returned is in the structure pointed to by filestats ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_stat + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_stat (const char *path, os_fstat_t *filestats) { int32 return_code; @@ -435,17 +415,15 @@ int32 OS_stat (const char *path, os_fstat_t *filestats) return return_code; } /* end OS_stat */ -/*-------------------------------------------------------------------------------------- - Name: OS_lseek - - Purpose: 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 - - Returns: the new offset from the beginning of the file - OS_FS_ERR_INVALID_FD if the file descriptor passed in is invalid - OS_FS_ERROR if OS call failed ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_lseek + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_lseek (uint32 filedes, int32 offset, uint32 whence) { OS_common_record_t *record; @@ -461,22 +439,17 @@ int32 OS_lseek (uint32 filedes, int32 offset, uint32 whence) } return return_code; -}/* end OS_lseek */ - -/*-------------------------------------------------------------------------------------- - Name: OS_remove - - Purpose: removes a given filename from the drive - - Returns: OS_FS_SUCCESS if the driver returns OK - OS_FS_ERROR if there is no device or the driver returns error - OS_FS_ERR_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 to be - stored locally ----------------------------------------------------------------------------------------*/ +} /* end OS_lseek */ + +/*---------------------------------------------------------------- + * + * Function: OS_remove + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_remove (const char *path) { int32 return_code; @@ -496,19 +469,15 @@ int32 OS_remove (const char *path) } /* end OS_remove */ -/*-------------------------------------------------------------------------------------- - Name: OS_rename - - Purpose: renames a file - - Returns: OS_FS_SUCCESS if the rename works - OS_FS_ERROR if the file could not be opened or renamed. - OS_FS_ERR_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 ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_rename + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_rename (const char *old, const char *new) { int i; @@ -552,22 +521,17 @@ int32 OS_rename (const char *old, const char *new) return return_code; -}/*end OS_rename */ - -/*-------------------------------------------------------------------------------------- - Name: OS_cp - - Purpose: Copies a single file from src to dest - - Returns: OS_FS_SUCCESS if the operation worked - OS_FS_ERROR if the file could not be accessed - OS_FS_ERR_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 - ----------------------------------------------------------------------------------------*/ +} /* end OS_rename */ + +/*---------------------------------------------------------------- + * + * Function: OS_cp + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_cp (const char *src, const char *dest) { int32 return_code; @@ -580,7 +544,7 @@ int32 OS_cp (const char *src, const char *dest) if (src == NULL || dest == NULL) { - return OS_FS_ERR_INVALID_POINTER; + return OS_INVALID_POINTER; } return_code = OS_FS_SUCCESS; @@ -635,21 +599,17 @@ int32 OS_cp (const char *src, const char *dest) return return_code; -}/*end OS_cp */ - -/*-------------------------------------------------------------------------------------- - Name: OS_mv - - Purpose: moves a single file from src to dest - - Returns: OS_FS_SUCCESS if the rename works - OS_FS_ERROR if the file could not be opened or renamed. - OS_FS_ERR_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 ----------------------------------------------------------------------------------------*/ +} /* end OS_cp */ + +/*---------------------------------------------------------------- + * + * Function: OS_mv + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_mv (const char *src, const char *dest) { int32 return_code; @@ -667,19 +627,19 @@ int32 OS_mv (const char *src, const char *dest) return (return_code); -}/*end OS_mv */ - - +} /* end OS_mv */ -/* -------------------------------------------------------------------------------------- -Name: OS_FDGetInfo -Purpose: Copies the information of the given file descriptor into a structure passed in - -Returns: OS_FS_ERR_INVALID_FD if the file descriptor passed in is invalid - OS_FS_SUCCESS if the copying was successfull - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FDGetInfo + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_FDGetInfo (uint32 filedes, OS_file_prop_t *fd_prop) { OS_common_record_t *record; @@ -706,16 +666,17 @@ int32 OS_FDGetInfo (uint32 filedes, OS_file_prop_t *fd_prop) return return_code; -}/* end OS_FDGetInfo */ +} /* end OS_FDGetInfo */ -/* -------------------------------------------------------------------------------------- - Name: OS_FileOpenCheck - - Purpose: Checks to see if a file is open - - Returns: OS_FS_ERROR if the file is not open - OS_FS_SUCCESS if the file is open - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileOpenCheck + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_FileOpenCheck(const char *Filename) { int32 return_code; @@ -744,20 +705,18 @@ int32 OS_FileOpenCheck(const char *Filename) OS_Unlock_Global_Impl(LOCAL_OBJID_TYPE); return return_code; -}/* end OS_FileOpenCheck */ - +} /* end OS_FileOpenCheck */ -/* -------------------------------------------------------------------------------------- - Name: OS_CloseFileByName - Purpose: Allows a file to be closed by name. - This will only work if the name passed in is the same name used to open - the file. - - Returns: OS_FS_ERR_PATH_INVALID if the file is not found - OS_FS_ERROR if the file close returned an error - OS_FS_SUCCESS if the file close suceeded - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CloseFileByName + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_CloseFileByName(const char *Filename) { int32 return_code; @@ -795,16 +754,17 @@ int32 OS_CloseFileByName(const char *Filename) return (return_code); -}/* end OS_CloseFileByName */ - -/* -------------------------------------------------------------------------------------- - Name: OS_CloseAllFiles - - Purpose: Closes All open files that were opened through the OSAL +} /* end OS_CloseFileByName */ - Returns: OS_FS_ERROR if one or more file close returned an error - OS_FS_SUCCESS if the files were all closed without error - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CloseAllFiles + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_CloseAllFiles(void) { int32 return_code; @@ -835,17 +795,17 @@ int32 OS_CloseAllFiles(void) return (return_code); -}/* end OS_CloseAllFiles */ - -/* -------------------------------------------------------------------------------------- - Name: OS_ShellOutputToFile +} /* end OS_CloseAllFiles */ - Purpose: Takes a shell command in and writes the output of that command to the specified file - - Returns: OS_FS_ERROR if the command was not executed properly - OS_FS_ERR_INVALID_FD if the file descriptor passed in is invalid - OS_SUCCESS if success - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ShellOutputToFile + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_ShellOutputToFile(const char* Cmd, uint32 filedes) { OS_common_record_t *record; @@ -866,5 +826,5 @@ int32 OS_ShellOutputToFile(const char* Cmd, uint32 filedes) } return return_code; -}/* end OS_ShellOutputToFile */ +} /* end OS_ShellOutputToFile */ diff --git a/src/os/shared/osapi-filesys.c b/src/os/shared/osapi-filesys.c index 14a1885b8..252074ba2 100644 --- a/src/os/shared/osapi-filesys.c +++ b/src/os/shared/osapi-filesys.c @@ -66,15 +66,18 @@ extern const OS_VolumeInfo_t OS_VolumeTable[]; #define OS_COMPAT_VOLTAB_SIZE 0 #endif -/*--------------------------------------------------------------------------------------- - Name: OS_FileSys_FindVirtMountPoint - - Purpose: Checks if the filesys table index matches the "virtual_mountpt" field. - Function is Compatible with the Search object lookup routine - - Returns: true if the entry matches, false if it does not match - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSys_FindVirtMountPoint + * + * Purpose: Local helper routine, not part of OSAL API. + * Checks if the filesys table index matches the "virtual_mountpt" field. + * Function is Compatible with the Search object lookup routine + * + * Returns: true if the entry matches, false if it does not match + * + *-----------------------------------------------------------------*/ static bool OS_FileSys_FindVirtMountPoint(void *ref, uint32 local_id, const OS_common_record_t *obj) { OS_filesys_internal_record_t *rec = &OS_filesys_table[local_id]; @@ -89,17 +92,20 @@ static bool OS_FileSys_FindVirtMountPoint(void *ref, uint32 local_id, const OS_c mplen = strlen(rec->virtual_mountpt); return (mplen > 0 && strncmp(target, rec->virtual_mountpt, mplen) == 0 && (target[mplen] == '/' || target[mplen] == 0)); -} +} /* end OS_FileSys_FindVirtMountPoint */ -/*--------------------------------------------------------------------------------------- - Name: OS_FileSys_InitLocalFromVolTable - - Purpose: Pre-populates a local filesys table entry from the classic OS_VolumeTable - This provides backward compatibility with existing PSP/BSP implementations. - - Returns: OS_SUCCESS on success or appropriate error code. - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSys_InitLocalFromVolTable + * + * Purpose: Local helper routine, not part of OSAL API. + * Pre-populates a local filesys table entry from the classic OS_VolumeTable + * This provides backward compatibility with existing PSP/BSP implementations. + * + * Returns: OS_SUCCESS on success or appropriate error code. + * + *-----------------------------------------------------------------*/ static int32 OS_FileSys_InitLocalFromVolTable(OS_filesys_internal_record_t *local, const OS_VolumeInfo_t *Vol) { int32 return_code = OS_SUCCESS; @@ -186,17 +192,20 @@ static int32 OS_FileSys_InitLocalFromVolTable(OS_filesys_internal_record_t *loca } return return_code; -} - -/* --------------------------------------------------------------------------------------- - Name: OS_FileSys_GetInitialParamsForDevice - - Purpose: Pre-populates a local filesys table entry from the classic OS_VolumeTable - This provides backward compatibility with existing PSP/BSP implementations. +} /* end OS_FileSys_InitLocalFromVolTable */ - Returns: OS_SUCCESS on success or appropriate error code. - - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSys_SetupInitialParamsForDevice + * + * Purpose: Local helper routine, not part of OSAL API. + * Pre-populates a local filesys table entry from the classic OS_VolumeTable + * This provides backward compatibility with existing PSP/BSP implementations. + * + * Returns: OS_SUCCESS on success or appropriate error code. + * + *-----------------------------------------------------------------*/ static int32 OS_FileSys_SetupInitialParamsForDevice(const char *devname, OS_filesys_internal_record_t *local) { const OS_VolumeInfo_t *Vol; @@ -217,17 +226,20 @@ static int32 OS_FileSys_SetupInitialParamsForDevice(const char *devname, OS_file } return return_code; -} - -/* --------------------------------------------------------------------------------------- - Name: OS_FileSys_Initialize +} /* end OS_FileSys_SetupInitialParamsForDevice */ - Purpose: Implements Common code between the mkfs and initfs calls - - mkfs passes the "should_format" as true and initfs passes as false. - - Returns: OS_FS_SUCCESS on creating the disk, or appropriate error code. - - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSys_Initialize + * + * Purpose: Local helper routine, not part of OSAL API. + * Implements Common code between the mkfs and initfs calls - + * mkfs passes the "should_format" as true and initfs passes as false. + * + * Returns: OS_FS_SUCCESS on creating the disk, or appropriate error code. + * + *-----------------------------------------------------------------*/ static int32 OS_FileSys_Initialize(char *address, const char *fsdevname, const char * fsvolname, uint32 blocksize, uint32 numblocks, bool should_format) { @@ -326,13 +338,21 @@ static int32 OS_FileSys_Initialize(char *address, const char *fsdevname, const c return return_code; -} /* end OS_FileSysInitialize */ +} /* end OS_FileSys_Initialize */ /**************************************************************************************** INITIALIZATION ***************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysAPI_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_FileSysAPI_Init(void) { uint32 i; @@ -390,12 +410,17 @@ int32 OS_FileSysAPI_Init(void) } return return_code; -} - -/**************************************************************************************** - FILE SYSTEM API - ***************************************************************************************/ +} /* end OS_FileSysAPI_Init */ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysAddFixedMap + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysAddFixedMap(uint32 *filesys_id, const char *phys_path, const char *virt_path) { OS_common_record_t *global; @@ -464,20 +489,17 @@ int32 OS_FileSysAddFixedMap(uint32 *filesys_id, const char *phys_path, const cha } return return_code; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_mkfs - - Purpose: Makes a file system on the target - - Returns: OS_FS_ERR_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 - ----------------------------------------------------------------------------------------*/ +} /* end OS_FileSysAddFixedMap */ + +/*---------------------------------------------------------------- + * + * Function: OS_mkfs + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_mkfs (char *address, const char *devname, const char * volname, uint32 blocksize, uint32 numblocks) { @@ -502,16 +524,15 @@ int32 OS_mkfs (char *address, const char *devname, const char * volname, uint32 } /* end OS_mkfs */ -/*--------------------------------------------------------------------------------------- - Name: OS_rmfs - - Purpose: Inititalizes a file system on the target - - Returns: OS_FS_ERR_INVALID_POINTER if devname is NULL - OS_FS_ERROR is the drive specified cannot be located - OS_FS_SUCCESS on removing the disk ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_rmfs + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_rmfs (const char *devname) { int32 return_code; @@ -564,20 +585,17 @@ int32 OS_rmfs (const char *devname) } return return_code; -}/* end OS_rmfs */ - -/*--------------------------------------------------------------------------------------- - Name: OS_initfs - - Purpose: Inititalizes a file system on the target +} /* end OS_rmfs */ - Returns: OS_FS_ERR_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 - OS_FS_SUCCESS on creating the disk - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_initfs + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_initfs (char *address,const char *devname, const char *volname, uint32 blocksize, uint32 numblocks) { @@ -600,15 +618,17 @@ int32 OS_initfs (char *address,const char *devname, const char *volname, return return_code; -}/* end OS_initfs */ - -/*-------------------------------------------------------------------------------------- - Name: OS_mount - - Purpose: mounts a drive. - ----------------------------------------------------------------------------------------*/ +} /* end OS_initfs */ + +/*---------------------------------------------------------------- + * + * Function: OS_mount + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_mount (const char *devname, const char* mountpoint) { int32 return_code; @@ -683,20 +703,17 @@ int32 OS_mount (const char *devname, const char* mountpoint) return return_code; -}/* end OS_mount */ - -/*-------------------------------------------------------------------------------------- - Name: OS_unmount - - Purpose: unmounts a drive. and therefore makes all file descriptors pointing into - the drive obsolete. - - Returns: OS_FS_ERR_INVALID_POINTER if name is NULL - OS_FS_ERR_PATH_TOO_LONG if the absolute path given is too long - OS_FS_ERROR if the OS calls failed - OS_FS_SUCCESS if success ----------------------------------------------------------------------------------------*/ +} /* end OS_mount */ + +/*---------------------------------------------------------------- + * + * Function: OS_unmount + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_unmount (const char *mountpoint) { int32 return_code; @@ -770,18 +787,17 @@ int32 OS_unmount (const char *mountpoint) } return return_code; -}/* end OS_umount */ - -/*-------------------------------------------------------------------------------------- - Name: OS_fsBlocksFree - - Purpose: Returns the number of free blocks in a volume +} /* end OS_unmount */ - Returns: OS_FS_ERR_INVALID_POINTER if name is NULL - OS_FS_ERR_PATH_TOO_LONG if the name is too long - OS_FS_ERROR if the OS call failed - The number of blocks free in a volume if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_fsBlocksFree + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_fsBlocksFree (const char *name) { int32 return_code; @@ -823,18 +839,17 @@ int32 OS_fsBlocksFree (const char *name) return return_code; -}/* end OS_fsBlocksFree */ +} /* end OS_fsBlocksFree */ -/*-------------------------------------------------------------------------------------- - Name: OS_fsBytesFree - - Purpose: Returns the number of free bytes in a volume - - Returns: OS_FS_ERR_INVALID_POINTER if name is NULL - OS_FS_ERR_PATH_TOO_LONG if the name is too long - OS_FS_ERROR if the OS call failed - OS_FS_SUCCESS if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_fsBytesFree + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_fsBytesFree (const char *name, uint64 *bytes_free) { int32 return_code; @@ -876,19 +891,18 @@ int32 OS_fsBytesFree (const char *name, uint64 *bytes_free) return return_code; -}/* end OS_fsBytesFree */ - +} /* end OS_fsBytesFree */ -/*-------------------------------------------------------------------------------------- - Name: OS_chkfs - Purpose: Checks the drives for inconsistencies and either repairs it or not - - Returns: OS_FS_ERR_INVALID_POINTER if name is NULL - OS_FS_SUCCESS if success - OS_FS_ERROR if the OS calls fail - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_chkfs + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_chkfs (const char *name, bool repair) { uint32 local_id; @@ -926,18 +940,17 @@ int32 OS_chkfs (const char *name, bool repair) return return_code; -}/* end OS_chkfs */ - -/*-------------------------------------------------------------------------------------- - Name: OS_FS_GetPhysDriveName +} /* end OS_chkfs */ - Purpose: Returns the name of the physical volume associated with the drive, - when given the OSAL mount point of the drive - - Returns: OS_FS_ERR_INVALID_POINTER if either parameter is NULL - OS_SUCCESS if success - OS_FS_ERROR if the mountpoint could not be found ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FS_GetPhysDriveName + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_FS_GetPhysDriveName(char * PhysDriveName, const char * MountPoint) { uint32 local_id; @@ -984,19 +997,18 @@ int32 OS_FS_GetPhysDriveName(char * PhysDriveName, const char * MountPoint) return return_code; -}/* end OS_FS_GetPhysDriveName */ - - -/*-------------------------------------------------------------------------------------- - Name: OS_GetFsInfo +} /* end OS_FS_GetPhysDriveName */ - Purpose: returns information about the file system in an os_fsinfo_t - Returns: OS_FS_ERR_INVALID_POINTER if filesys_info is NULL - OS_FS_SUCCESS if success - - Note: The information returned is in the structure pointed to by filesys_info - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_GetFsInfo + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_GetFsInfo(os_fsinfo_t *filesys_info) { int i; @@ -1039,15 +1051,17 @@ int32 OS_GetFsInfo(os_fsinfo_t *filesys_info) OS_Unlock_Global_Impl(OS_OBJECT_TYPE_OS_FILESYS); return(OS_FS_SUCCESS); -} +} /* end OS_GetFsInfo */ -/*------------------------------------------------------------------------------------- - * Name: OS_TranslatePath + +/*---------------------------------------------------------------- + * + * Function: OS_TranslatePath + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * Purpose: Because of the abstraction of the filesystem across OSes, we have to change - * the name of the {file, directory, drive} to be what the OS can actually - * accept ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_TranslatePath(const char *VirtualPath, char *LocalPath) { uint32 local_id; diff --git a/src/os/shared/osapi-fpu.c b/src/os/shared/osapi-fpu.c index 276087f62..4959b9ff2 100644 --- a/src/os/shared/osapi-fpu.c +++ b/src/os/shared/osapi-fpu.c @@ -31,8 +31,15 @@ */ #include "common_types.h" #include "os-impl.h" - - + +/*---------------------------------------------------------------- + * + * Function: OS_FPUExcAttachHandler + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_FPUExcAttachHandler (uint32 ExceptionNumber, void * ExceptionHandler , int32 parameter) { @@ -42,44 +49,60 @@ int32 OS_FPUExcAttachHandler (uint32 ExceptionNumber, void * ExceptionHandler } return OS_FPUExcAttachHandler_Impl(ExceptionNumber, ExceptionHandler, parameter); -} +} /* end OS_FPUExcAttachHandler */ -/* + +/*---------------------------------------------------------------- * - * Name: OS_FPUExcSetMask + * Function: OS_FPUExcSetMask * - * Purpose: This function sets the FPU exception mask + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * Notes: 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. - */ + *-----------------------------------------------------------------*/ int32 OS_FPUExcSetMask(uint32 mask) { return OS_FPUExcSetMask_Impl(mask); -} +} /* end OS_FPUExcSetMask */ -/* + +/*---------------------------------------------------------------- * - * Name: OS_FPUExcGetMask + * Function: OS_FPUExcGetMask * - * Purpose: This function gets the FPU exception mask + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * Notes: 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. - */ + *-----------------------------------------------------------------*/ int32 OS_FPUExcGetMask(uint32 *mask) { return OS_FPUExcGetMask_Impl(mask); -} - +} /* end OS_FPUExcGetMask */ + +/*---------------------------------------------------------------- + * + * Function: OS_FPUExcEnable + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_FPUExcEnable (int32 ExceptionNumber) { return OS_FPUExcEnable_Impl(ExceptionNumber); -} - +} /* end OS_FPUExcEnable */ + +/*---------------------------------------------------------------- + * + * Function: OS_FPUExcDisable + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_FPUExcDisable (int32 ExceptionNumber) { return OS_FPUExcDisable_Impl(ExceptionNumber); -} +} /* end OS_FPUExcDisable */ diff --git a/src/os/shared/osapi-heap.c b/src/os/shared/osapi-heap.c index 86fb53bc5..0cbda348f 100644 --- a/src/os/shared/osapi-heap.c +++ b/src/os/shared/osapi-heap.c @@ -33,14 +33,15 @@ #include "os-impl.h" -/*--------------------------------------------------------------------------------------- - Name: OS_HeapGetInfo - - Purpose: Return current info on the heap - - Parameters: - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_HeapGetInfo + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_HeapGetInfo (OS_heap_prop_t *heap_prop) { if (heap_prop == NULL) @@ -49,5 +50,5 @@ int32 OS_HeapGetInfo (OS_heap_prop_t *heap_prop) } return OS_HeapGetInfo_Impl(heap_prop); -} +} /* end OS_HeapGetInfo */ diff --git a/src/os/shared/osapi-idmap.c b/src/os/shared/osapi-idmap.c index 0bdc5ea6f..c328fb935 100644 --- a/src/os/shared/osapi-idmap.c +++ b/src/os/shared/osapi-idmap.c @@ -17,6 +17,19 @@ * in a generic/common manner. They are used internally within * OSAL by all the various modules. * + * In order to add additional verification capabilities, each class of fundamental + * objects will use its own ID space within the 32-bit integer ID value. This way + * one could not mistake a Task ID for a Queue ID or vice versa. Also, all IDs will + * become nonzero and an ID of zero is ALWAYS invalid. + * + * These functions provide a consistent way to validate a 32-bit OSAL ID as + * well as determine its internal type and index. + * + * The map/unmap functions are not part of the public API -- applications + * should be treating OSAL IDs as opaque objects. + * + * NOTE: The only exception is OS_ConvertToArrayIndex() as this is necessary to + * assist applications when storing OSAL IDs in a table. */ /**************************************************************************************** @@ -80,32 +93,28 @@ OS_common_record_t * const OS_global_console_table = &OS_common_table[OS_CONS ********************************************************************************* */ -/* - * Initialization function --- clears the entire table - * and brings it to a proper initial state - */ +/*---------------------------------------------------------------- + * + * Function: OS_ObjectIdInit + * + * Purpose: Local helper routine, not part of OSAL API. + * clears the entire table and brings it to a proper initial state + * + *-----------------------------------------------------------------*/ int32 OS_ObjectIdInit(void) { memset(OS_common_table, 0, sizeof(OS_common_table)); memset(OS_last_id_issued, 0, sizeof(OS_last_id_issued)); return OS_SUCCESS; -} +} /* end OS_ObjectIdInit */ -/* - * In order to add additional verification capabilities, each class of fundamental - * objects will use its own ID space within the 32-bit integer ID value. This way - * one could not mistake a Task ID for a Queue ID or vice versa. Also, all IDs will - * become nonzero and an ID of zero is ALWAYS invalid. +/*---------------------------------------------------------------- * - * These functions provide a consistent way to validate a 32-bit OSAL ID as - * well as determine its internal type and index. + * Function: OS_ObjectIdMap * - * The map/unmap functions are not part of the public API -- applications - * should be treating OSAL IDs as opaque objects. + * Purpose: Local helper routine, not part of OSAL API. * - * NOTE: The only exception is OS_ConvertToArrayIndex() as this is necessary to - * assist applications when storing OSAL IDs in a table. - */ + *-----------------------------------------------------------------*/ int32 OS_ObjectIdMap(uint32 idtype, uint32 idvalue, uint32 *result) { *result = (idtype << OS_OBJECT_TYPE_SHIFT) | idvalue; @@ -117,8 +126,16 @@ int32 OS_ObjectIdMap(uint32 idtype, uint32 idvalue, uint32 *result) } return OS_SUCCESS; -} +} /* end OS_ObjectIdMap */ + +/*---------------------------------------------------------------- + * + * Function: OS_ObjectIdUnMap + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_ObjectIdUnMap(uint32 id, uint32 idtype, uint32 *idvalue) { *idvalue = id & OS_OBJECT_INDEX_MASK; @@ -129,8 +146,16 @@ int32 OS_ObjectIdUnMap(uint32 id, uint32 idtype, uint32 *idvalue) } return OS_SUCCESS; -} +} /* end OS_ObjectIdUnMap */ + +/*---------------------------------------------------------------- + * + * Function: OS_GetMaxForObjectType + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ uint32 OS_GetMaxForObjectType(uint32 idtype) { switch(idtype) @@ -149,8 +174,16 @@ uint32 OS_GetMaxForObjectType(uint32 idtype) case OS_OBJECT_TYPE_OS_CONSOLE: return OS_MAX_CONSOLES; default: return 0; } -} +} /* end OS_GetMaxForObjectType */ + +/*---------------------------------------------------------------- + * + * Function: OS_GetBaseForObjectType + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ uint32 OS_GetBaseForObjectType(uint32 idtype) { switch(idtype) @@ -169,89 +202,98 @@ uint32 OS_GetBaseForObjectType(uint32 idtype) case OS_OBJECT_TYPE_OS_CONSOLE: return OS_CONSOLE_BASE; default: return 0; } -} +} /* end OS_GetBaseForObjectType */ /************************************************************** * LOCAL HELPER FUNCTIONS * (not used outside of this unit) **************************************************************/ -/*-------------------------------------------------------------------------------------- - Name: OS_ObjectNameMatch - - Purpose: A matching function to compare the name of the record against - a reference value (which must be a const char* string). - - This allows OS_ObjectIdFindByName() to be implemented using the - generic OS_ObjectIdSearch() routine. - - returns: true if match, false otherwise ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ObjectNameMatch + * + * Purpose: Local helper routine, not part of OSAL API. + * A matching function to compare the name of the record against + * a reference value (which must be a const char* string). + * + * This allows OS_ObjectIdFindByName() to be implemented using the + * generic OS_ObjectIdSearch() routine. + * + * returns: true if match, false otherwise + * + *-----------------------------------------------------------------*/ static bool OS_ObjectNameMatch(void *ref, uint32 local_id, const OS_common_record_t *obj) { return (obj->name_entry != NULL && strcmp((const char*)ref, obj->name_entry) == 0); -} +} /* end OS_ObjectNameMatch */ -/*-------------------------------------------------------------------------------------- - Name: OS_ObjectIdInitiateLock - - Purpose: - Initiate the locking process for the given mode and ID type, prior - to looking up a specific object. - - For any lock_mode other than OS_LOCK_MODE_NONE, this acquires the - global table lock for that ID type. - - Once the lookup operation is completed, the OS_ObjectIdConvertLock() - routine should be used to convert this global lock into the actual - lock type requested (lock_mode). - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ObjectIdInitiateLock + * + * Purpose: Local helper routine, not part of OSAL API. + * Initiate the locking process for the given mode and ID type, prior + * to looking up a specific object. + * + * For any lock_mode other than OS_LOCK_MODE_NONE, this acquires the + * global table lock for that ID type. + * + * Once the lookup operation is completed, the OS_ObjectIdConvertLock() + * routine should be used to convert this global lock into the actual + * lock type requested (lock_mode). + * + *-----------------------------------------------------------------*/ static void OS_ObjectIdInitiateLock(OS_lock_mode_t lock_mode, uint32 idtype) { if (lock_mode != OS_LOCK_MODE_NONE) { OS_Lock_Global_Impl(idtype); } -} - -/*-------------------------------------------------------------------------------------- - Name: OS_ObjectIdConvertLock - - Purpose: - Selectively convert the existing lock on a given resource, depending on the lock mode. - - For any lock_mode other than OS_LOCK_MODE_NONE, the global table lock **must** - already be held prior to entering this function. This function may or may - not unlock the global table, depending on the lock_mode and state of the entry. +} /* end OS_ObjectIdInitiateLock */ - For all modes, this verifies that the reference_id passed in and the active_id - within the record are a match. If they do not match, then OS_ERR_INVALID_ID - is returned. - - If lock_mode is set to either OS_LOCK_MODE_NONE or OS_LOCK_MODE_GLOBAL, - no additional operation is performed, as the existing lock (if any) is - sufficient and no conversion is necessary. - - If lock_mode is set to OS_LOCK_MODE_REFCOUNT, then this increments - the reference count within the object itself and releases the table lock, - so long as there is no "exclusive" request already pending. - - If lock_mode is set to OS_LOCK_MODE_EXCLUSIVE, then this verifies - that the refcount is zero, but also keeps the global lock held. - - For EXCLUSIVE and REFCOUNT style locks, if the state is not appropriate, - this may unlock the global table and re-lock it several times - while waiting for the state to change. - - Returns: OS_SUCCESS if operation was successful, - or suitable error code if operation was not successful. - - NOTE: Upon failure, the global table lock is always released for - all lock modes other than OS_LOCK_MODE_NONE. - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ObjectIdConvertLock + * + * Purpose: Local helper routine, not part of OSAL API. + * + * Selectively convert the existing lock on a given resource, depending on the lock mode. + * + * For any lock_mode other than OS_LOCK_MODE_NONE, the global table lock **must** + * already be held prior to entering this function. This function may or may + * not unlock the global table, depending on the lock_mode and state of the entry. + * + * For all modes, this verifies that the reference_id passed in and the active_id + * within the record are a match. If they do not match, then OS_ERR_INVALID_ID + * is returned. + * + * If lock_mode is set to either OS_LOCK_MODE_NONE or OS_LOCK_MODE_GLOBAL, + * no additional operation is performed, as the existing lock (if any) is + * sufficient and no conversion is necessary. + * + * If lock_mode is set to OS_LOCK_MODE_REFCOUNT, then this increments + * the reference count within the object itself and releases the table lock, + * so long as there is no "exclusive" request already pending. + * + * If lock_mode is set to OS_LOCK_MODE_EXCLUSIVE, then this verifies + * that the refcount is zero, but also keeps the global lock held. + * + * For EXCLUSIVE and REFCOUNT style locks, if the state is not appropriate, + * this may unlock the global table and re-lock it several times + * while waiting for the state to change. + * + * Returns: OS_SUCCESS if operation was successful, + * or suitable error code if operation was not successful. + * + * NOTE: Upon failure, the global table lock is always released for + * all lock modes other than OS_LOCK_MODE_NONE. + * + *-----------------------------------------------------------------*/ static int32 OS_ObjectIdConvertLock(OS_lock_mode_t lock_mode, uint32 idtype, uint32 reference_id, OS_common_record_t *obj) { int32 return_code = OS_ERROR; @@ -367,20 +409,22 @@ static int32 OS_ObjectIdConvertLock(OS_lock_mode_t lock_mode, uint32 idtype, uin return return_code; -} - -/*-------------------------------------------------------------------------------------- - Name: OS_ObjectIdGetBySearch - - Purpose: Locate an existing object using the supplied Match function. - Matching object ID is stored in the object_id pointer +} /* end OS_ObjectIdConvertLock */ - This is an internal function and no table locking is performed here. - Locking must be done by the calling function. - - returns: OS_ERR_NAME_NOT_FOUND if not found, OS_SUCCESS if match is found - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ObjectIdSearch + * + * Purpose: Local helper routine, not part of OSAL API. + * Locate an existing object using the supplied Match function. + * Matching object ID is stored in the object_id pointer + * + * This is an internal function and no table locking is performed here. + * Locking must be done by the calling function. + * + * returns: OS_ERR_NAME_NOT_FOUND if not found, OS_SUCCESS if match is found + * + *-----------------------------------------------------------------*/ static int32 OS_ObjectIdSearch(uint32 idtype, OS_ObjectMatchFunc_t MatchFunc, void *arg, OS_common_record_t **record) { int32 return_code; @@ -417,23 +461,25 @@ static int32 OS_ObjectIdSearch(uint32 idtype, OS_ObjectMatchFunc_t MatchFunc, vo } return return_code; -} - -/*-------------------------------------------------------------------------------------- - Name: OS_ObjectIdFindNext - - Purpose: Find the next available Object ID of the given type - Searches the global name/id table for an open entry of the given type. - The search will start at the location of the last-issued ID. +} /* end OS_ObjectIdSearch */ - Note: This is an internal helper function and no locking is performed. - The appropriate global table lock must be held prior to calling this. - - Outputs: *record is set to point to the global entry and active_id member is set - *array_index updated to the offset of the found entry (local_id) - - returns: OS_SUCCESS if an empty location was found. ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ObjectIdFindNext + * + * Purpose: Local helper routine, not part of OSAL API. + * Find the next available Object ID of the given type + * Searches the global name/id table for an open entry of the given type. + * The search will start at the location of the last-issued ID. + * + * Note: This is an internal helper function and no locking is performed. + * The appropriate global table lock must be held prior to calling this. + * + * Outputs: *record is set to point to the global entry and active_id member is set + * *array_index updated to the offset of the found entry (local_id) + * + * returns: OS_SUCCESS if an empty location was found. + *-----------------------------------------------------------------*/ static int32 OS_ObjectIdFindNext(uint32 idtype, uint32 *array_index, OS_common_record_t **record) { uint32 max_id; @@ -504,7 +550,7 @@ static int32 OS_ObjectIdFindNext(uint32 idtype, uint32 *array_index, OS_common_r } return return_code; -} +} /* end OS_ObjectIdFindNext */ /* @@ -516,17 +562,19 @@ static int32 OS_ObjectIdFindNext(uint32 idtype, uint32 *array_index, OS_common_r ********************************************************************************* */ -/*-------------------------------------------------------------------------------------- - Name: OS_ObjectIdToArrayIndex - - Purpose: Convert an object ID (which must be of the given type) to a number suitable - for use as an array index. The array index will be in the range of: - 0 <= ArrayIndex < OS_MAX_ - - returns: If the passed-in ID is not of the proper type, OS_ERROR is returned - Otherwise OS_SUCCESS is returned. - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ObjectIdToArrayIndex + * + * Purpose: Local helper routine, not part of OSAL API. + * Convert an object ID (which must be of the given type) to a number suitable + * for use as an array index. The array index will be in the range of: + * 0 <= ArrayIndex < OS_MAX_ + * + * returns: If the passed-in ID is not of the proper type, OS_ERROR is returned + * Otherwise OS_SUCCESS is returned. + * + *-----------------------------------------------------------------*/ int32 OS_ObjectIdToArrayIndex(uint32 idtype, uint32 id, uint32 *ArrayIndex) { uint32 max_id; @@ -546,22 +594,24 @@ int32 OS_ObjectIdToArrayIndex(uint32 idtype, uint32 id, uint32 *ArrayIndex) return return_code; } /* end OS_ObjectIdToArrayIndex */ -/*-------------------------------------------------------------------------------------- - Name: OS_ObjectIdFinalizeNew - - Purpose: Called when the initialization of a newly-issued object ID is fully complete, - to perform finalization of the object and record state. - - If the operation_status was successful (OS_SUCCESS) then the ID is exported - to the caller through the "outid" pointer. - - If the operation_status is unsuccessful, then the temporary id in the record - is cleared and an ID value of 0 is exported to the caller. - - returns: The same operation_status value passed-in, or OS_ERR_INVALID_ID if problems - were detected while validating the ID. - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ObjectIdFinalizeNew + * + * Purpose: Local helper routine, not part of OSAL API. + * Called when the initialization of a newly-issued object ID is fully complete, + * to perform finalization of the object and record state. + * + * If the operation_status was successful (OS_SUCCESS) then the ID is exported + * to the caller through the "outid" pointer. + * + * If the operation_status is unsuccessful, then the temporary id in the record + * is cleared and an ID value of 0 is exported to the caller. + * + * returns: The same operation_status value passed-in, or OS_ERR_INVALID_ID if problems + * were detected while validating the ID. + * + *-----------------------------------------------------------------*/ int32 OS_ObjectIdFinalizeNew(int32 operation_status, OS_common_record_t *record, uint32 *outid) { uint32 idtype = record->active_id >> OS_OBJECT_TYPE_SHIFT; @@ -599,21 +649,23 @@ int32 OS_ObjectIdFinalizeNew(int32 operation_status, OS_common_record_t *record, OS_Unlock_Global_Impl(idtype); return operation_status; -} - - -/*-------------------------------------------------------------------------------------- - Name: OS_ObjectIdGetBySearch - - Purpose: Locate an existing object using the supplied Match function. - Matching object ID is stored in the object_id pointer - - Global locking is performed according to the lock_mode - parameter. +} /* end OS_ObjectIdFinalizeNew */ - returns: OS_ERR_NAME_NOT_FOUND if not found, OS_SUCCESS if match is found ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ObjectIdGetBySearch + * + * Purpose: Local helper routine, not part of OSAL API. + * Locate an existing object using the supplied Match function. + * Matching object ID is stored in the object_id pointer + * + * Global locking is performed according to the lock_mode + * parameter. + * + * returns: OS_ERR_NAME_NOT_FOUND if not found, OS_SUCCESS if match is found + * + *-----------------------------------------------------------------*/ int32 OS_ObjectIdGetBySearch(OS_lock_mode_t lock_mode, uint32 idtype, OS_ObjectMatchFunc_t MatchFunc, void *arg, OS_common_record_t **record) { int32 return_code; @@ -643,34 +695,40 @@ int32 OS_ObjectIdGetBySearch(OS_lock_mode_t lock_mode, uint32 idtype, OS_ObjectM } return return_code; -} - +} /* end OS_ObjectIdGetBySearch */ -/*-------------------------------------------------------------------------------------- - Name: OS_ObjectIdGetByName - Purpose: Locate an existing object with matching name and type - Matching record is stored in the record pointer - - Global locking is performed according to the lock_mode - parameter. - - returns: OS_ERR_NAME_NOT_FOUND if not found, OS_SUCCESS if match is found ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ObjectIdGetByName + * + * Purpose: Local helper routine, not part of OSAL API. + * Locate an existing object with matching name and type + * Matching record is stored in the record pointer + * + * Global locking is performed according to the lock_mode + * parameter. + * + * returns: OS_ERR_NAME_NOT_FOUND if not found, OS_SUCCESS if match is found + * + *-----------------------------------------------------------------*/ int32 OS_ObjectIdGetByName (OS_lock_mode_t lock_mode, uint32 idtype, const char *name, OS_common_record_t **record) { return OS_ObjectIdGetBySearch(lock_mode, idtype, OS_ObjectNameMatch, (void*)name, record); -}/* end OS_ObjectIdGetByName */ - -/*-------------------------------------------------------------------------------------- - Name: OS_ObjectFindIdByName - - Purpose: Locate an existing object with matching name and type - Matching object ID is stored in the object_id pointer +} /* end OS_ObjectIdGetByName */ - returns: OS_ERR_NAME_NOT_FOUND if not found, OS_SUCCESS if match is found ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ObjectIdFindByName + * + * Purpose: Local helper routine, not part of OSAL API. + * Locate an existing object with matching name and type + * Matching object ID is stored in the object_id pointer + * + * returns: OS_ERR_NAME_NOT_FOUND if not found, OS_SUCCESS if match is found + * + *-----------------------------------------------------------------*/ int32 OS_ObjectIdFindByName (uint32 idtype, const char *name, uint32 *object_id) { int32 return_code; @@ -700,25 +758,26 @@ int32 OS_ObjectIdFindByName (uint32 idtype, const char *name, uint32 *object_id) return return_code; -}/* end OS_ObjectIdFindByName */ - - - -/*-------------------------------------------------------------------------------------- - Name: OS_ObjectIdGetById - - Purpose: Gets the resource record pointer and index associated with the given resource ID. - If successful, this returns with the item locked according to "lock_mode". +} /* end OS_ObjectIdFindByName */ - IMPORTANT: when this function returns OS_SUCCESS with lock_mode something - other than NONE, then the caller must take appropriate action to UN lock - after completing the respective operation. The OS_ObjectIdRelease() - function may be used to release the lock appropriately for the lock_mode. - If this returns something other than OS_SUCCESS then the global is NOT locked. - returns: status ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ObjectIdGetById + * + * Purpose: Local helper routine, not part of OSAL API. + * Gets the resource record pointer and index associated with the given resource ID. + * If successful, this returns with the item locked according to "lock_mode". + * + * IMPORTANT: when this function returns OS_SUCCESS with lock_mode something + * other than NONE, then the caller must take appropriate action to UN lock + * after completing the respective operation. The OS_ObjectIdRelease() + * function may be used to release the lock appropriately for the lock_mode. + * + * If this returns something other than OS_SUCCESS then the global is NOT locked. + * + *-----------------------------------------------------------------*/ int32 OS_ObjectIdGetById(OS_lock_mode_t lock_mode, uint32 idtype, uint32 id, uint32 *array_index, OS_common_record_t **record) { int32 return_code; @@ -764,14 +823,17 @@ int32 OS_ObjectIdGetById(OS_lock_mode_t lock_mode, uint32 idtype, uint32 id, uin } /* end OS_ObjectIdGetById */ -/*-------------------------------------------------------------------------------------- - Name: OS_ObjectIdRefcountDecr - - Purpose: Decrement the reference count on the resource record, which must have been - acquired (incremented) by the caller prior to this. - - returns: OS_SUCCESS if decremented successfully. ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ObjectIdRefcountDecr + * + * Purpose: Local helper routine, not part of OSAL API. + * Decrement the reference count on the resource record, which must have been + * acquired (incremented) by the caller prior to this. + * + * returns: OS_SUCCESS if decremented successfully. + * + *-----------------------------------------------------------------*/ int32 OS_ObjectIdRefcountDecr(OS_common_record_t *record) { int32 return_code; @@ -801,34 +863,36 @@ int32 OS_ObjectIdRefcountDecr(OS_common_record_t *record) return return_code; } /* end OS_ObjectIdRefcountDecr */ -/*-------------------------------------------------------------------------------------- - Name: OS_ObjectIdAllocateNew - - Purpose: Locks the global table for the indicated ID type and allocates a - new object of the given type with the given name. - - Inputs: last_alloc_id represents the previously issued ID of this type. - (The search for a free entry will start here +1 to avoid repeats). - - Outputs: *record is set to point to the global entry and active_id member is set - - returns: OS_SUCCESS if a NEW object was allocated and the table remains locked. - - IMPORTANT: The global table is remains in a locked state if this returns OS_SUCCESS, - so that additional initialization can be performed in an atomic manner. - - If this fails for any reason (i.e. a duplicate name or no free slots) - then the global table is unlocked inside this function prior to - returning to the caller. - - If OS_SUCCESS is returned, then the global lock MUST be either unlocked - or converted to a different style lock (see OS_ObjectIdConvertLock) once - the initialization of the new object is completed. - - For any return code other than OS_SUCCESS, the caller must NOT - manipulate the global lock at all. - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ObjectIdAllocateNew + * + * Purpose: Local helper routine, not part of OSAL API. + * Locks the global table for the indicated ID type and allocates a + * new object of the given type with the given name. + * + * Inputs: last_alloc_id represents the previously issued ID of this type. + * (The search for a free entry will start here +1 to avoid repeats). + * + * Outputs: *record is set to point to the global entry and active_id member is set + * + * returns: OS_SUCCESS if a NEW object was allocated and the table remains locked. + * + * IMPORTANT: The global table is remains in a locked state if this returns OS_SUCCESS, + * so that additional initialization can be performed in an atomic manner. + * + * If this fails for any reason (i.e. a duplicate name or no free slots) + * then the global table is unlocked inside this function prior to + * returning to the caller. + * + * If OS_SUCCESS is returned, then the global lock MUST be either unlocked + * or converted to a different style lock (see OS_ObjectIdConvertLock) once + * the initialization of the new object is completed. + * + * For any return code other than OS_SUCCESS, the caller must NOT + * manipulate the global lock at all. + * + *-----------------------------------------------------------------*/ int32 OS_ObjectIdAllocateNew(uint32 idtype, const char *name, uint32 *array_index, OS_common_record_t **record) { int32 return_code; @@ -884,17 +948,14 @@ int32 OS_ObjectIdAllocateNew(uint32 idtype, const char *name, uint32 *array_inde ********************************************************************************* */ -/*-------------------------------------------------------------------------------------- - Name: OS_ConvertToArrayIndex - - Purpose: Converts any abstract ID into a number suitable for use as an array index. - This is necessary for code that breaks when IDs are converted - to nonzero ranges. Note that this does NOT verify the validity of the ID, - that is left to the caller. This is only the conversion logic. - - returns: status - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ConvertToArrayIndex + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_ConvertToArrayIndex(uint32 object_id, uint32 *ArrayIndex) { uint32 max_id; @@ -914,14 +975,15 @@ int32 OS_ConvertToArrayIndex(uint32 object_id, uint32 *ArrayIndex) return return_code; } /* end OS_ConvertToArrayIndex */ -/*-------------------------------------------------------------------------------------- - Name: OS_ForEachObject - - Purpose: Loops through all defined OSAL objects and calls callback_ptr on each one - If creator_id is nonzero then only objects with matching creator id are processed. - - returns: None ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ForEachObject + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ void OS_ForEachObject (uint32 creator_id, OS_ArgCallback_t callback_ptr, void *callback_arg) { uint32 obj_index; @@ -956,17 +1018,18 @@ void OS_ForEachObject (uint32 creator_id, OS_ArgCallback_t callback_ptr, void *c OS_Unlock_Global_Impl(idtype); } } -} +} /* end OS_ForEachObject */ -/*--------------------------------------------------------------------------------------- - Name: OS_IdentifyObject - - Purpose: Given an arbitrary object ID, get the type of the object - - returns: The type of object that the ID represents ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_IdentifyObject + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ uint32 OS_IdentifyObject (uint32 object_id) { return (object_id >> OS_OBJECT_TYPE_SHIFT); -} +} /* end OS_IdentifyObject */ diff --git a/src/os/shared/osapi-interrupts.c b/src/os/shared/osapi-interrupts.c index b87187134..86ce5080d 100644 --- a/src/os/shared/osapi-interrupts.c +++ b/src/os/shared/osapi-interrupts.c @@ -32,31 +32,15 @@ #include "common_types.h" #include "os-impl.h" -/*--------------------------------------------------------------------------------------- - * Name: OS_IntAttachHandler + +/*---------------------------------------------------------------- * - * Purpose: - * The call associates a specified C routine to a specified interrupt - * number.Upon occurring of the InterruptNumber , the InerruptHandler - * routine will be called and passed the parameter. - * - * Assumptions and Notes: - * - * Parameters: - * InterruptNumber : The Interrupt Number that will cause the start of - * the ISR - * InerruptHandler : The ISR associatd with this interrupt - * parameter :The parameter that is passed to the ISR - * - * Global Inputs: None + * Function: OS_IntAttachHandler * - * Global Outputs: None + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * - * Return Values: - * OS_SUCCESS on success - * OS_INVALID_POINTER if the Interrupt handler pointer is NULL ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_IntAttachHandler (uint32 InterruptNumber, osal_task_entry InterruptHandler, int32 parameter) { if (InterruptHandler == NULL) @@ -65,145 +49,89 @@ int32 OS_IntAttachHandler (uint32 InterruptNumber, osal_task_entry InterruptHan } return OS_IntAttachHandler_Impl(InterruptNumber, InterruptHandler, parameter); -} +} /* end OS_IntAttachHandler */ -/*--------------------------------------------------------------------------------------- - * Name: OS_IntUnlock - * Purpose: - * Enable the interrupts. - * - * Assumptions and Notes: - * - * Parameters: + +/*---------------------------------------------------------------- * - * Global Inputs: None + * Function: OS_IntUnlock * - * Global Outputs: None + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * - * Return Values: - * OS_SUCCESS ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_IntUnlock (int32 IntFlags) { return OS_IntUnlock_Impl(IntFlags); -} +} /* end OS_IntUnlock */ -/*--------------------------------------------------------------------------------------- - * Name: OS_Intlock - * Purpose: - * Disable the interrupts. - * - * Assumptions and Notes: - * - * Parameters: + +/*---------------------------------------------------------------- * - * Global Inputs: None + * Function: OS_IntLock * - * Global Outputs: None + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * - * Return Values: - * OS_SUCCESS ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_IntLock ( void ) { return OS_IntLock_Impl(); -} +} /* end OS_IntLock */ -/*--------------------------------------------------------------------------------------- - * Name: OS_IntEnable - * Purpose: - * Enables interrupts through Level - * - * Assumptions and Notes: - * - * Parameters: - * Level - the interrupts to enable + +/*---------------------------------------------------------------- * - * Global Inputs: None + * Function: OS_IntEnable * - * Global Outputs: None + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * - * Return Values: - * OS_SUCCESS ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_IntEnable(int32 Level) { return OS_IntEnable_Impl(Level); -} +} /* end OS_IntEnable */ -/*--------------------------------------------------------------------------------------- - * Name: OS_IntDisable - * Purpose: - * Disables interrupts through Level - * - * Assumptions and Notes: - * - * Parameters: - * Level - the interrupts to disable + +/*---------------------------------------------------------------- * - * Global Inputs: None + * Function: OS_IntDisable * - * Global Outputs: None + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * - * Return Values: - * OS_SUCCESS ----------------------------------------------------------------------------------------*/ - + *-----------------------------------------------------------------*/ int32 OS_IntDisable(int32 Level) { return OS_IntDisable_Impl(Level); -} +} /* end OS_IntDisable */ -/*--------------------------------------------------------------------------------------- - * Name: OS_SetMask - * Purpose: - * Set the masking register to mask and unmask interrupts - * - * Assumptions and Notes: - * HW interrupt control is not supported from a user task + +/*---------------------------------------------------------------- * - * Parameters: - * MaskSetting :the value to be written into the mask register + * Function: OS_IntSetMask * - * Global Inputs: None + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * Global Outputs: None - * - * - * Return Values: - * ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_IntSetMask ( uint32 MaskSetting ) { return OS_IntSetMask_Impl(MaskSetting); -} +} /* end OS_IntSetMask */ -/*-------------------------------------------------------------------------------------- - * Name: OS_GetMask - * Purpose: - * Read and report the setting of the cpu mask register. - * - * Assumptions and Notes: - * HW interrupt control is not supported from a user task - * - * Parameters: - * MaskSettingPtr : pointer to a location where the function store the - * reading of the cpu mask register. - * - * Global Inputs: None - * - * Global Outputs: None + +/*---------------------------------------------------------------- * + * Function: OS_IntGetMask * - * Return Values: + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_IntGetMask ( uint32 * MaskSettingPtr ) { return OS_IntGetMask_Impl(MaskSettingPtr); -} +} /* end OS_IntGetMask */ diff --git a/src/os/shared/osapi-module.c b/src/os/shared/osapi-module.c index 853b207f3..4a10f3e21 100644 --- a/src/os/shared/osapi-module.c +++ b/src/os/shared/osapi-module.c @@ -81,13 +81,15 @@ extern OS_static_symbol_record_t OS_STATIC_SYMTABLE_SOURCE[]; /* there is no static symbol table, use NULL */ #define OS_STATIC_SYMTABLE_SOURCE NULL #endif /* OS_STATIC_SYMTABLE_SOURCE */ -/* - * Internal Helper function to implement the static symbol table lookup - * (not called externally - only used within OS_SymbolLookup()) + +/*---------------------------------------------------------------- * - * If OS_STATIC_LOADER is not defined then this returns OS_ERR_NOT_IMPLEMENTED - * Otherwise it searches the static symbol table for a match. - */ + * Function: OS_SymbolLookup_Static + * + * Purpose: Local helper routine, not part of OSAL API. + * Checks for a symbol name in the static symbol table + * + *-----------------------------------------------------------------*/ static int32 OS_SymbolLookup_Static(cpuaddr *SymbolAddress, const char *SymbolName) { int32 return_code = OS_ERR_NOT_IMPLEMENTED; @@ -115,8 +117,17 @@ static int32 OS_SymbolLookup_Static(cpuaddr *SymbolAddress, const char *SymbolNa } return return_code; -} +} /* end OS_SymbolLookup_Static */ + +/*---------------------------------------------------------------- + * + * Function: OS_ModuleLoad_Static + * + * Purpose: Local helper routine, not part of OSAL API. + * Checks for a module name in the static symbol table + * + *-----------------------------------------------------------------*/ static int32 OS_ModuleLoad_Static(const char *ModuleName) { int32 return_code = OS_ERR_NAME_NOT_FOUND; @@ -141,43 +152,38 @@ static int32 OS_ModuleLoad_Static(const char *ModuleName) } return return_code; -} +} /* end OS_ModuleLoad_Static */ /**************************************************************************************** Module API ***************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_ModuleAPI_Init - - Purpose: Init function for OS-independent layer - - Returns: OS_SUCCESS - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ModuleAPI_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * Init function for OS-independent layer + * + *-----------------------------------------------------------------*/ int32 OS_ModuleAPI_Init(void) { #if (OS_MAX_MODULES > 0) memset(OS_module_table, 0, sizeof(OS_module_table)); #endif return OS_SUCCESS; -} - +} /* end OS_ModuleAPI_Init */ -/*-------------------------------------------------------------------------------------- - Name: OS_ModuleLoad - Purpose: Loads an object file into the running operating system - - Parameters: - - Returns: 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 - OS_SUCCESS if the module is loaded successfuly ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ModuleLoad + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_ModuleLoad ( uint32 *module_id, const char *module_name, const char *filename ) { char translated_path[OS_MAX_LOCAL_PATH_LEN]; @@ -244,18 +250,16 @@ int32 OS_ModuleLoad ( uint32 *module_id, const char *module_name, const char *fi return(return_code); -}/* end OS_ModuleLoad */ - -/*-------------------------------------------------------------------------------------- - Name: OS_ModuleUnload - - Purpose: Unloads the module file from the running operating system - - Parameters: +} /* end OS_ModuleLoad */ - Returns: OS_ERROR if the module is invalid or cannot be unloaded - OS_SUCCESS if the module was unloaded successfuly ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ModuleUnload + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_ModuleUnload ( uint32 module_id ) { OS_common_record_t *record; @@ -281,19 +285,16 @@ int32 OS_ModuleUnload ( uint32 module_id ) } return return_code; -}/* end OS_ModuleUnload */ - -/*-------------------------------------------------------------------------------------- - Name: OS_ModuleInfo - - Purpose: Returns information about the loadable module - - Parameters: +} /* end OS_ModuleUnload */ - Returns: OS_ERR_INVALID_ID if the module id invalid - OS_INVALID_POINTER if the pointer to the ModuleInfo structure is invalid - OS_SUCCESS if the module info was filled out successfuly ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_ModuleInfo + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_ModuleInfo ( uint32 module_id, OS_module_prop_t *module_prop ) { OS_common_record_t *record; @@ -325,25 +326,17 @@ int32 OS_ModuleInfo ( uint32 module_id, OS_module_prop_t *module_prop ) return return_code; -}/* end OS_ModuleInfo */ - - -/*-------------------------------------------------------------------------------------- - Name: OS_SymbolLookup +} /* end OS_ModuleInfo */ - Purpose: Find the Address of a Symbol - This calls to the OS dynamic symbol lookup implementation, - and/or checks a static symbol table for a matching symbol name. - The static table is intended to support embedded targets that do - not have module loading capability or have it disabled. - - Parameters: - - Returns: OS_ERROR if the symbol could not be found - OS_SUCCESS if the symbol is found - OS_INVALID_POINTER if one of the pointers passed in are NULL ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_SymbolLookup + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SymbolLookup( cpuaddr *SymbolAddress, const char *SymbolName ) { int32 return_code; @@ -389,19 +382,16 @@ int32 OS_SymbolLookup( cpuaddr *SymbolAddress, const char *SymbolName ) return (return_code); -}/* end OS_SymbolLookup */ - -/*-------------------------------------------------------------------------------------- - Name: OS_SymbolTableDump +} /* end OS_SymbolLookup */ - Purpose: Dumps the system symbol table to a file - - Parameters: - - Returns: OS_ERROR if the symbol table could not be read or dumped - OS_INVALID_FILE if the file could not be opened or written - OS_SUCCESS if the symbol is found ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_SymbolTableDump + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SymbolTableDump ( const char *filename, uint32 SizeLimit ) { int32 return_code; @@ -442,7 +432,7 @@ int32 OS_SymbolTableDump ( const char *filename, uint32 SizeLimit ) return(return_code); -}/* end OS_SymbolTableDump */ +} /* end OS_SymbolTableDump */ diff --git a/src/os/shared/osapi-mutex.c b/src/os/shared/osapi-mutex.c index 71fc5ec22..f141b9945 100644 --- a/src/os/shared/osapi-mutex.c +++ b/src/os/shared/osapi-mutex.c @@ -59,34 +59,29 @@ OS_apiname_internal_record_t OS_mutex_table [LOCAL_NUM_OBJECTS]; MUTEX API ***************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_MutexAPI_Init - - Purpose: Init function for OS-independent layer - - Returns: OS_SUCCESS - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_MutexAPI_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * Init function for OS-independent layer + * + *-----------------------------------------------------------------*/ int32 OS_MutexAPI_Init(void) { memset(OS_mutex_table, 0, sizeof(OS_mutex_table)); return OS_SUCCESS; -} +} /* end OS_MutexAPI_Init */ -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemCreate - - Purpose: Creates a mutex semaphore initially full. - - Returns: 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 - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_MutSemCreate + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemCreate (uint32 *sem_id, const char *sem_name, uint32 options) { OS_common_record_t *record; @@ -121,21 +116,16 @@ int32 OS_MutSemCreate (uint32 *sem_id, const char *sem_name, uint32 options) return return_code; -}/* end OS_MutexSemCreate */ - -/*-------------------------------------------------------------------------------------- - Name: OS_MutSemDelete - - Purpose: Deletes the specified Mutex Semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid mutex - OS_SEM_FAILURE if the OS call failed - OS_SUCCESS if success - - Notes: The mutex must be full to take it, so we have to check for fullness - ----------------------------------------------------------------------------------------*/ +} /* end OS_MutSemCreate */ +/*---------------------------------------------------------------- + * + * Function: OS_MutSemDelete + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemDelete (uint32 sem_id) { OS_common_record_t *record; @@ -159,24 +149,17 @@ int32 OS_MutSemDelete (uint32 sem_id) return return_code; -}/* end OS_MutSemDelete */ - -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemGive - - Purpose: The function releases the mutex object referenced by sem_id.The - manner in which a mutex is released is dependent upon the mutex's type - attribute. If there are threads blocked on the mutex object referenced by - mutex when this function is called, resulting in the mutex becoming - available, the scheduling policy shall determine which thread shall - acquire the mutex. - - Returns: OS_SUCCESS if success - OS_SEM_FAILURE if the semaphore was not previously initialized - OS_ERR_INVALID_ID if the id passed in is not a valid mutex - ----------------------------------------------------------------------------------------*/ +} /* end OS_MutSemDelete */ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemGive + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemGive ( uint32 sem_id ) { OS_common_record_t *record; @@ -194,20 +177,15 @@ int32 OS_MutSemGive ( uint32 sem_id ) } /* end OS_MutSemGive */ -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemTake - - Purpose: The mutex object referenced by sem_id shall be locked by calling this - function. If the mutex is already locked, the calling thread shall - block until the mutex becomes available. This operation shall return - with the mutex object referenced by mutex in the locked state with the - calling thread as its owner. - - Returns: OS_SUCCESS if success - 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 ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemTake + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemTake ( uint32 sem_id ) { OS_common_record_t *record; @@ -223,19 +201,16 @@ int32 OS_MutSemTake ( uint32 sem_id ) return return_code; -} -/*-------------------------------------------------------------------------------------- - Name: OS_MutSemGetIdByName - - Purpose: This function tries to find a mutex sem Id given the name of a mut_sem - The id is returned through sem_id - - Returns: 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 - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +} /* end OS_MutSemTake */ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemGetIdByName + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemGetIdByName (uint32 *sem_id, const char *sem_name) { int32 return_code; @@ -249,20 +224,17 @@ int32 OS_MutSemGetIdByName (uint32 *sem_id, const char *sem_name) return return_code; -}/* end OS_MutSemGetIdByName */ - -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info( name and creator) about the specified mutex - semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid semaphore - OS_INVALID_POINTER if the mut_prop pointer is null - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ +} /* end OS_MutSemGetIdByName */ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemGetInfo + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemGetInfo (uint32 sem_id, OS_mut_sem_prop_t *mut_prop) { OS_common_record_t *record; diff --git a/src/os/shared/osapi-network.c b/src/os/shared/osapi-network.c index 52c0737f5..e508de36e 100644 --- a/src/os/shared/osapi-network.c +++ b/src/os/shared/osapi-network.c @@ -38,22 +38,28 @@ NETWORK API ***************************************************************************************/ -/* Initialization function */ +/*---------------------------------------------------------------- + * + * Function: OS_NetworkAPI_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_NetworkAPI_Init(void) { return OS_SUCCESS; -} - +} /* end OS_NetworkAPI_Init */ -/*-------------------------------------------------------------------------------------- - Name: OS_NetworkGetHostName - - Purpose: Gets the name of the current host - - Returns: OS_ERROR if the host name could not be found - OS_SUCCESS if the name was copied to host_name successfully ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_NetworkGetHostName + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_NetworkGetHostName (char *host_name, uint32 name_len) { uint32 return_code; @@ -79,21 +85,19 @@ int32 OS_NetworkGetHostName (char *host_name, uint32 name_len) } return(return_code); -}/* end OS_NetworkGetHostName */ - - - -/*-------------------------------------------------------------------------------------- - Name: OS_NetworkGetID +} /* end OS_NetworkGetHostName */ - Purpose: Gets the ID of the current Network - Returns: The ID or fixed value of -1 if the host id could not be found - Note this is _not_ an OS_ERROR code -- 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. ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_NetworkGetID + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_NetworkGetID (void) { int32 IdBuf; @@ -107,6 +111,6 @@ int32 OS_NetworkGetID (void) return IdBuf; -}/* end OS_NetworkGetID */ +} /* end OS_NetworkGetID */ diff --git a/src/os/shared/osapi-printf.c b/src/os/shared/osapi-printf.c index ec676bc77..6f1c782d0 100644 --- a/src/os/shared/osapi-printf.c +++ b/src/os/shared/osapi-printf.c @@ -94,6 +94,14 @@ OS_console_internal_record_t OS_console_table[OS_MAX_CONSOLES]; ********************************************************************************* */ + +/*---------------------------------------------------------------- + * + * Function: OS_ConsoleAPI_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_ConsoleAPI_Init(void) { OS_console_internal_record_t *console; @@ -133,7 +141,7 @@ int32 OS_ConsoleAPI_Init(void) } return OS_SUCCESS; -} +} /* end OS_ConsoleAPI_Init */ /* ********************************************************************************* @@ -141,17 +149,22 @@ int32 OS_ConsoleAPI_Init(void) ********************************************************************************* */ -/** - * Write into the console ring buffer +/*---------------------------------------------------------------- * - * The NextWritePos is an input-output and contains the position - * in the ring buffer to start writing into. This may or may not - * be the same as the value in the global. It is only updated - * if the string is written in its entirety. + * Function: OS_Console_CopyOut * - * The intent is to avoid truncating a string if it does not fit. - * Either the entire string should be written, or none of it. - */ + * Purpose: Local helper routine, not part of OSAL API. + * Write into the console ring buffer + * + * The NextWritePos is an input-output and contains the position + * in the ring buffer to start writing into. This may or may not + * be the same as the value in the global. It is only updated + * if the string is written in its entirety. + * + * The intent is to avoid truncating a string if it does not fit. + * Either the entire string should be written, or none of it. + * + *-----------------------------------------------------------------*/ static int32 OS_Console_CopyOut(OS_console_internal_record_t *console, const char *Str, uint32 *NextWritePos) { const char *pmsg; @@ -188,7 +201,7 @@ static int32 OS_Console_CopyOut(OS_console_internal_record_t *console, const cha } return return_code; -} +} /* end OS_Console_CopyOut */ /* ********************************************************************************* @@ -196,9 +209,15 @@ static int32 OS_Console_CopyOut(OS_console_internal_record_t *console, const cha ********************************************************************************* */ -/** - * Write into the console ring buffer - */ + +/*---------------------------------------------------------------- + * + * Function: OS_ConsoleWrite + * + * Purpose: Local helper routine, not part of OSAL API. + * Write into the console ring buffer + * + *-----------------------------------------------------------------*/ int32 OS_ConsoleWrite(uint32 console_id, const char *Str) { int32 return_code; @@ -253,16 +272,18 @@ int32 OS_ConsoleWrite(uint32 console_id, const char *Str) return return_code; -} +} /* end OS_ConsoleWrite */ -/* --------------------------------------------------------------------------- - * Name: OS_printf + +/*---------------------------------------------------------------- * - * Purpose: This function abstracts out the printf type statements. This is - * useful for using OS- specific thats that will allow non-polled - * print statements for the real time systems. - ---------------------------------------------------------------------------*/ + * Function: OS_printf + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ void OS_printf( const char *String, ...) { va_list va; @@ -316,27 +337,33 @@ void OS_printf( const char *String, ...) OS_ConsoleWrite(OS_SharedGlobalVars.PrintfConsoleId, msg_buffer); } -}/* end OS_printf*/ +} /* end OS_printf */ -/* --------------------------------------------------------------------------- - * Name: OS_printf_disable + +/*---------------------------------------------------------------- * - * Purpose: This function disables the output to the UART from OS_printf. + * Function: OS_printf_disable * - ---------------------------------------------------------------------------*/ + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ void OS_printf_disable(void) { OS_SharedGlobalVars.PrintfEnabled = false; -}/* end OS_printf_disable*/ +} /* end OS_printf_disable */ -/* --------------------------------------------------------------------------- - * Name: OS_printf_enable + +/*---------------------------------------------------------------- + * + * Function: OS_printf_enable * - * Purpose: This function enables the output to the UART through OS_printf. + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - ---------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ void OS_printf_enable(void) { OS_SharedGlobalVars.PrintfEnabled = true; -}/* end OS_printf_enable*/ +} /* end OS_printf_enable */ diff --git a/src/os/shared/osapi-queue.c b/src/os/shared/osapi-queue.c index dc9d1bb0b..010c556b0 100644 --- a/src/os/shared/osapi-queue.c +++ b/src/os/shared/osapi-queue.c @@ -61,35 +61,30 @@ OS_queue_internal_record_t OS_queue_table [LOCAL_NUM_OBJECTS]; MESSAGE QUEUE API ***************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_QueueAPI_Init - - Purpose: Init function for OS-independent layer - - Returns: OS_SUCCESS - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_QueueAPI_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * Init function for OS-independent layer + * + *-----------------------------------------------------------------*/ int32 OS_QueueAPI_Init(void) { memset(OS_queue_table, 0, sizeof(OS_queue_table)); return OS_SUCCESS; -} - - -/*--------------------------------------------------------------------------------------- - Name: OS_QueueCreate +} /* end OS_QueueAPI_Init */ - Purpose: Create a message queue which can be referred to by name or ID - Returns: 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 - OS_SUCCESS if success - - Notes: the flags parameter is unused. - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_QueueCreate + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueCreate (uint32 *queue_id, const char *queue_name, uint32 queue_depth, uint32 data_size, uint32 flags) { OS_common_record_t *record; @@ -126,20 +121,17 @@ int32 OS_QueueCreate (uint32 *queue_id, const char *queue_name, uint32 queue_dep return return_code; -}/* end OS_QueueCreate */ - -/*-------------------------------------------------------------------------------------- - Name: OS_QueueDelete - - Purpose: Deletes the specified message queue. - - Returns: OS_ERR_INVALID_ID if the id passed in does not exist - OS_ERROR if the OS call to delete the queue fails - OS_SUCCESS if success +} /* end OS_QueueCreate */ - Notes: 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 - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_QueueDelete + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueDelete (uint32 queue_id) { OS_common_record_t *record; @@ -165,17 +157,15 @@ int32 OS_QueueDelete (uint32 queue_id) } /* end OS_QueueDelete */ -/*--------------------------------------------------------------------------------------- - Name: OS_QueueGet - - Purpose: Receive a message on a message queue. Will pend or timeout on the receive. - Returns: 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 - OS_SUCCESS if success - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_QueueGet + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueGet (uint32 queue_id, void *data, uint32 size, uint32 *size_copied, int32 timeout) { OS_common_record_t *record; @@ -210,17 +200,15 @@ int32 OS_QueueGet (uint32 queue_id, void *data, uint32 size, uint32 *size_copied return return_code; } /* end OS_QueueGet */ -/*--------------------------------------------------------------------------------------- - Name: OS_QueuePut - - Purpose: Put a message on a message queue. - - Returns: 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 - OS_SUCCESS if SUCCESS - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_QueuePut + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_QueuePut (uint32 queue_id, const void *data, uint32 size, uint32 flags) { OS_common_record_t *record; @@ -245,19 +233,15 @@ int32 OS_QueuePut (uint32 queue_id, const void *data, uint32 size, uint32 flags) } /* end OS_QueuePut */ -/*-------------------------------------------------------------------------------------- - Name: OS_QueueGetIdByName - - Purpose: This function tries to find a queue Id given the name of the queue. The - id of the queue is passed back in queue_id - - Returns: 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 - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_QueueGetIdByName + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueGetIdByName (uint32 *queue_id, const char *queue_name) { int32 return_code; @@ -271,18 +255,17 @@ int32 OS_QueueGetIdByName (uint32 *queue_id, const char *queue_name) return return_code; -}/* end OS_QueueGetIdByName */ - -/*--------------------------------------------------------------------------------------- - Name: OS_QueueGetInfo +} /* end OS_QueueGetIdByName */ - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info (name and creator) about the specified queue. - - Returns: 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 ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_QueueGetInfo + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueGetInfo (uint32 queue_id, OS_queue_prop_t *queue_prop) { OS_common_record_t *record; diff --git a/src/os/shared/osapi-select.c b/src/os/shared/osapi-select.c index 78208d895..983ff64c5 100644 --- a/src/os/shared/osapi-select.c +++ b/src/os/shared/osapi-select.c @@ -44,6 +44,15 @@ * SELECT API ********************************************************************************* */ + +/*---------------------------------------------------------------- + * + * Function: OS_SelectSingle + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SelectSingle(uint32 objid, uint32 *StateFlags, int32 msecs) { int32 return_code; @@ -58,8 +67,16 @@ int32 OS_SelectSingle(uint32 objid, uint32 *StateFlags, int32 msecs) } return return_code; -} - +} /* end OS_SelectSingle */ + +/*---------------------------------------------------------------- + * + * Function: OS_SelectMultiple + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SelectMultiple(OS_FdSet *ReadSet, OS_FdSet *WriteSet, int32 msecs) { int32 return_code; @@ -73,14 +90,30 @@ int32 OS_SelectMultiple(OS_FdSet *ReadSet, OS_FdSet *WriteSet, int32 msecs) return_code = OS_SelectMultiple_Impl(ReadSet, WriteSet, msecs); return return_code; -} - +} /* end OS_SelectMultiple */ + +/*---------------------------------------------------------------- + * + * Function: OS_SelectFdZero + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SelectFdZero(OS_FdSet *Set) { memset(Set,0,sizeof(OS_FdSet)); return OS_SUCCESS; -} - +} /* end OS_SelectFdZero */ + +/*---------------------------------------------------------------- + * + * Function: OS_SelectFdAdd + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SelectFdAdd(OS_FdSet *Set, uint32 objid) { int32 return_code; @@ -93,8 +126,16 @@ int32 OS_SelectFdAdd(OS_FdSet *Set, uint32 objid) } return return_code; -} - +} /* end OS_SelectFdAdd */ + +/*---------------------------------------------------------------- + * + * Function: OS_SelectFdClear + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SelectFdClear(OS_FdSet *Set, uint32 objid) { int32 return_code; @@ -107,8 +148,16 @@ int32 OS_SelectFdClear(OS_FdSet *Set, uint32 objid) } return return_code; -} - +} /* end OS_SelectFdClear */ + +/*---------------------------------------------------------------- + * + * Function: OS_SelectFdIsSet + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ bool OS_SelectFdIsSet(OS_FdSet *Set, uint32 objid) { int32 return_code; @@ -121,6 +170,6 @@ bool OS_SelectFdIsSet(OS_FdSet *Set, uint32 objid) } return ((Set->object_ids[local_id >> 3] >> (local_id & 0x7)) & 0x1); -} +} /* end OS_SelectFdIsSet */ diff --git a/src/os/shared/osapi-sockets.c b/src/os/shared/osapi-sockets.c index d3192080d..8a874a9d3 100644 --- a/src/os/shared/osapi-sockets.c +++ b/src/os/shared/osapi-sockets.c @@ -47,6 +47,14 @@ enum Init Functions ***************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketAPI_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_SocketAPI_Init(void) { /* @@ -55,7 +63,7 @@ int32 OS_SocketAPI_Init(void) * cases where OS_INCLUDE_NETWORK is off */ return OS_SUCCESS; -} +} /* end OS_SocketAPI_Init */ #ifdef OS_INCLUDE_NETWORK @@ -63,6 +71,14 @@ int32 OS_SocketAPI_Init(void) Local Helper Functions ***************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_CreateSocketName + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ static void OS_CreateSocketName(OS_stream_internal_record_t *sock, const OS_SockAddr_t *Addr, const char *parent_name) { int32 len; @@ -86,12 +102,17 @@ static void OS_CreateSocketName(OS_stream_internal_record_t *sock, const OS_Sock snprintf(&sock->stream_name[len], sizeof(sock->stream_name) - len, "-%s", parent_name); sock->stream_name[sizeof(sock->stream_name) - 1] = 0; } -} - -/**************************************************************************************** - SOCKETS API - ***************************************************************************************/ +} /* end OS_CreateSocketName */ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketOpen + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketOpen(uint32 *sock_id, OS_SocketDomain_t Domain, OS_SocketType_t Type) { OS_common_record_t *record; @@ -122,8 +143,16 @@ int32 OS_SocketOpen(uint32 *sock_id, OS_SocketDomain_t Domain, OS_SocketType_t T } return return_code; -} - +} /* end OS_SocketOpen */ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketBind + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketBind(uint32 sock_id, const OS_SockAddr_t *Addr) { OS_common_record_t *record; @@ -167,8 +196,16 @@ int32 OS_SocketBind(uint32 sock_id, const OS_SockAddr_t *Addr) return return_code; -} - +} /* end OS_SocketBind */ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketAccept + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketAccept(uint32 sock_id, uint32 *connsock_id, OS_SockAddr_t *Addr, int32 timeout) { OS_common_record_t *record; @@ -255,8 +292,16 @@ int32 OS_SocketAccept(uint32 sock_id, uint32 *connsock_id, OS_SockAddr_t *Addr, } return return_code; -} - +} /* end OS_SocketAccept */ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketConnect + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketConnect(uint32 sock_id, const OS_SockAddr_t *Addr, int32 Timeout) { OS_common_record_t *record; @@ -304,8 +349,16 @@ int32 OS_SocketConnect(uint32 sock_id, const OS_SockAddr_t *Addr, int32 Timeout) return return_code; -} - +} /* end OS_SocketConnect */ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketRecvFrom + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketRecvFrom(uint32 sock_id, void *buffer, uint32 buflen, OS_SockAddr_t *RemoteAddr, int32 timeout) { OS_common_record_t *record; @@ -339,8 +392,16 @@ int32 OS_SocketRecvFrom(uint32 sock_id, void *buffer, uint32 buflen, OS_SockAddr } return return_code; -} - +} /* end OS_SocketRecvFrom */ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketSendTo + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketSendTo(uint32 sock_id, const void *buffer, uint32 buflen, const OS_SockAddr_t *RemoteAddr) { OS_common_record_t *record; @@ -369,20 +430,17 @@ int32 OS_SocketSendTo(uint32 sock_id, const void *buffer, uint32 buflen, const O } return return_code; -} - -/*-------------------------------------------------------------------------------------- - Name: OS_SocketGetIdByName +} /* end OS_SocketSendTo */ - Purpose: This function tries to find a socket id given the name of the socket - The id is returned through sock_id - - Returns: 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 - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketGetIdByName + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketGetIdByName (uint32 *sock_id, const char *sock_name) { int32 return_code; @@ -395,19 +453,17 @@ int32 OS_SocketGetIdByName (uint32 *sock_id, const char *sock_name) return_code = OS_ObjectIdFindByName(LOCAL_OBJID_TYPE, sock_name, sock_id); return return_code; -}/* end OS_SocketGetIdByName */ - -/*--------------------------------------------------------------------------------------- - Name: OS_SocketGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info( name and creator) about the specified socket - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid semaphore - OS_INVALID_POINTER if the count_prop pointer is null - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ +} /* end OS_SocketGetIdByName */ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketGetInfo + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketGetInfo (uint32 sock_id, OS_socket_prop_t *sock_prop) { OS_common_record_t *record; @@ -433,9 +489,16 @@ int32 OS_SocketGetInfo (uint32 sock_id, OS_socket_prop_t *sock_prop) } return return_code; -} /* end OS_CountSemGetInfo */ - - +} /* end OS_SocketGetInfo */ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketAddrInit + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketAddrInit(OS_SockAddr_t *Addr, OS_SocketDomain_t Domain) { if (Addr == NULL) @@ -444,8 +507,16 @@ int32 OS_SocketAddrInit(OS_SockAddr_t *Addr, OS_SocketDomain_t Domain) } return OS_SocketAddrInit_Impl(Addr, Domain); -} - +} /* end OS_SocketAddrInit */ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketAddrToString + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketAddrToString(char *buffer, uint32 buflen, const OS_SockAddr_t *Addr) { if (Addr == NULL || buffer == NULL || buflen == 0) @@ -454,8 +525,16 @@ int32 OS_SocketAddrToString(char *buffer, uint32 buflen, const OS_SockAddr_t *Ad } return OS_SocketAddrToString_Impl(buffer, buflen, Addr); -} - +} /* end OS_SocketAddrToString */ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketAddrFromString + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketAddrFromString(OS_SockAddr_t *Addr, const char *string) { if (Addr == NULL || string == NULL) @@ -464,8 +543,16 @@ int32 OS_SocketAddrFromString(OS_SockAddr_t *Addr, const char *string) } return OS_SocketAddrFromString_Impl(Addr, string); -} - +} /* end OS_SocketAddrFromString */ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketAddrGetPort + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketAddrGetPort(uint16 *PortNum, const OS_SockAddr_t *Addr) { if (PortNum == NULL || Addr == NULL) @@ -474,8 +561,16 @@ int32 OS_SocketAddrGetPort(uint16 *PortNum, const OS_SockAddr_t *Addr) } return OS_SocketAddrGetPort_Impl(PortNum, Addr); -} - +} /* end OS_SocketAddrGetPort */ + +/*---------------------------------------------------------------- + * + * Function: OS_SocketAddrSetPort + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_SocketAddrSetPort(OS_SockAddr_t *Addr, uint16 PortNum) { if (Addr == NULL) @@ -484,7 +579,7 @@ int32 OS_SocketAddrSetPort(OS_SockAddr_t *Addr, uint16 PortNum) } return OS_SocketAddrSetPort_Impl(Addr, PortNum); -} +} /* end OS_SocketAddrSetPort */ #endif diff --git a/src/os/shared/osapi-task.c b/src/os/shared/osapi-task.c index cd0835934..a0ec7ccc0 100644 --- a/src/os/shared/osapi-task.c +++ b/src/os/shared/osapi-task.c @@ -56,19 +56,22 @@ enum OS_task_internal_record_t OS_task_table [LOCAL_NUM_OBJECTS]; -/*--------------------------------------------------------------------------------------- - Name: OS_TaskPrepare - - Purpose: Helper function for registering new tasks in the global database. - This maps the given task_id back to the array entry (OS_task_internal_record_t) - so that the caller can call the real entry point. - - In the process, this also verifies that the task_id is valid and - it matches the expected entry, and this calls the implementation's - "Register" function to make sure that the appropriate thread-specific - variables are set - this guarantees that GetTaskId will work. - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_TaskPrepare + * + * Purpose: Local helper routine, not part of OSAL API. + * Helper function for registering new tasks in the global database. + * This maps the given task_id back to the array entry (OS_task_internal_record_t) + * so that the caller can call the real entry point. + * + * In the process, this also verifies that the task_id is valid and + * it matches the expected entry, and this calls the implementation's + * "Register" function to make sure that the appropriate thread-specific + * variables are set - this guarantees that GetTaskId will work. + * + * + *-----------------------------------------------------------------*/ static int32 OS_TaskPrepare(uint32 task_id, osal_task_entry *entrypt) { int32 return_code; @@ -111,18 +114,20 @@ static int32 OS_TaskPrepare(uint32 task_id, osal_task_entry *entrypt) } return return_code; -} - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskEntryPoint - - Purpose: The entry point for all OSAL tasks - This function is called from the OS-specific layers after a task is spawned - and is the first thing to run under the context of the task itself. - This will register the task appropriately in the global data structures and - call the user's intended entry point function. +} /* end OS_TaskPrepare */ ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_TaskEntryPoint + * + * Purpose: Local helper routine, not part of OSAL API. + * The entry point for all OSAL tasks + * This function is called from the OS-specific layers after a task is spawned + * and is the first thing to run under the context of the task itself. + * This will register the task appropriately in the global data structures and + * call the user's intended entry point function. + * + *-----------------------------------------------------------------*/ void OS_TaskEntryPoint(uint32 task_id) { osal_task_entry task_entry; @@ -137,7 +142,7 @@ void OS_TaskEntryPoint(uint32 task_id) /* If the function returns, treat as a normal exit and do the proper cleanup */ OS_TaskExit(); -} +} /* end OS_TaskEntryPoint */ /* ********************************************************************************* @@ -145,37 +150,30 @@ void OS_TaskEntryPoint(uint32 task_id) ********************************************************************************* */ -/*--------------------------------------------------------------------------------------- - Name: OS_TaskAPI_Init - - Purpose: Init function for OS-independent layer - - Returns: OS_SUCCESS - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_TaskAPI_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * Init function for OS-independent layer + * + *-----------------------------------------------------------------*/ int32 OS_TaskAPI_Init(void) { memset(OS_task_table, 0, sizeof(OS_task_table)); return OS_SUCCESS; -} +} /* end OS_TaskAPI_Init */ -/*--------------------------------------------------------------------------------------- - Name: OS_TaskCreate - - Purpose: Creates a task and starts running it. - - returns: 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 the operating system calls fail - OS_SUCCESS if success - - NOTES: task_id is passed back to the user as the ID. stack_pointer is usually null. - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskCreate + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskCreate (uint32 *task_id, const char *task_name, osal_task_entry function_pointer, uint32 *stack_pointer, uint32 stack_size, uint32 priority, uint32 flags) { @@ -226,18 +224,18 @@ int32 OS_TaskCreate (uint32 *task_id, const char *task_name, osal_task_entry fun return return_code; -}/* end OS_TaskCreate */ - +} /* end OS_TaskCreate */ -/*-------------------------------------------------------------------------------------- - Name: OS_TaskDelete - Purpose: Deletes the specified Task and removes it from the OS_task_table. - - returns: OS_ERR_INVALID_ID if the ID given to it is invalid - OS_ERROR if the OS delete call fails - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskDelete + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskDelete (uint32 task_id) { OS_common_record_t *record; @@ -277,16 +275,17 @@ int32 OS_TaskDelete (uint32 task_id) } return return_code; -}/* end OS_TaskDelete */ - -/*-------------------------------------------------------------------------------------- - Name: OS_TaskExit - - Purpose: Exits the calling task and removes it from the OS_task_table. - - returns: Nothing ----------------------------------------------------------------------------------------*/ +} /* end OS_TaskDelete */ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskExit + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ void OS_TaskExit() { OS_common_record_t *record; @@ -305,33 +304,32 @@ void OS_TaskExit() OS_TaskExit_Impl(); /* Impl function never returns */ -}/*end OS_TaskExit */ - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskDelay +} /* end OS_TaskExit */ - Purpose: Delay a task for specified amount of milliseconds - - returns: OS_ERROR if sleep fails or millisecond = 0 - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskDelay + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskDelay(uint32 millisecond) { /* just call the implementation */ return OS_TaskDelay_Impl(millisecond); -}/* end OS_TaskDelay */ - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskSetPriority +} /* end OS_TaskDelay */ - Purpose: Sets the given task to a new priority - - returns: 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 - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskSetPriority + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskSetPriority (uint32 task_id, uint32 new_priority) { OS_common_record_t *record; @@ -365,15 +363,15 @@ int32 OS_TaskSetPriority (uint32 task_id, uint32 new_priority) } /* end OS_TaskSetPriority */ -/*--------------------------------------------------------------------------------------- - Name: OS_TaskRegister - - Purpose: Obsolete function retained for compatibility purposes. Does Nothing. - Formerly this would register the task ID in the global table for later lookup, - but that function is now done automatically when the task is spawned. - - Returns: OS_SUCCESS ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskRegister + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskRegister (void) { OS_common_record_t *record; @@ -384,15 +382,17 @@ int32 OS_TaskRegister (void) * this will return NON success when called from a non-task context */ return OS_ObjectIdGetById(OS_LOCK_MODE_NONE, LOCAL_OBJID_TYPE, OS_TaskGetId_Impl(), &local_id, &record); -}/* end OS_TaskRegister */ - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskGetId +} /* end OS_TaskRegister */ - Purpose: This function returns the task id of the calling task - - Returns: Task ID, or zero if the operation failed (zero is never a valid ID for anything) ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskGetId + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ uint32 OS_TaskGetId (void) { OS_common_record_t *record; @@ -409,19 +409,17 @@ uint32 OS_TaskGetId (void) } return(task_id); -}/* end OS_TaskGetId */ - -/*-------------------------------------------------------------------------------------- - Name: OS_TaskGetIdByName - - Purpose: This function tries to find a task Id given the name of a task - - Returns: 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 - OS_SUCCESS if SUCCESS ----------------------------------------------------------------------------------------*/ +} /* end OS_TaskGetId */ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskGetIdByName + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskGetIdByName (uint32 *task_id, const char *task_name) { int32 return_code; @@ -435,20 +433,17 @@ int32 OS_TaskGetIdByName (uint32 *task_id, const char *task_name) return return_code; -}/* end OS_TaskGetIdByName */ - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info (creator, stack size, priority, name) about the - specified task. - - Returns: OS_ERR_INVALID_ID if the ID passed to it is invalid - OS_INVALID_POINTER if the task_prop pointer is NULL - OS_SUCCESS if it copied all of the relevant info over +} /* end OS_TaskGetIdByName */ ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskGetInfo + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskGetInfo (uint32 task_id, OS_task_prop_t *task_prop) { OS_common_record_t *record; @@ -484,14 +479,15 @@ int32 OS_TaskGetInfo (uint32 task_id, OS_task_prop_t *task_prop) } /* end OS_TaskGetInfo */ -/*-------------------------------------------------------------------------------------- - Name: OS_TaskInstallDeleteHandler - - Purpose: Installs a handler for when the task is deleted. - - returns: status ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_TaskInstallDeleteHandler + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskInstallDeleteHandler(osal_task_entry function_pointer) { OS_common_record_t *record; @@ -512,4 +508,4 @@ int32 OS_TaskInstallDeleteHandler(osal_task_entry function_pointer) } return return_code; -}/*end OS_TaskInstallDeleteHandler */ +} /* end OS_TaskInstallDeleteHandler */ diff --git a/src/os/shared/osapi-time.c b/src/os/shared/osapi-time.c index c915cece3..135adafa7 100644 --- a/src/os/shared/osapi-time.c +++ b/src/os/shared/osapi-time.c @@ -52,31 +52,34 @@ OS_timecb_internal_record_t OS_timecb_table [OS_MAX_TIMERS]; Timer API ***************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_TimeCbAPI_Init - - Purpose: Init function for OS-independent layer - - Returns: OS_SUCCESS - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_TimerCbAPI_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * Init function for OS-independent layer + * + *-----------------------------------------------------------------*/ int32 OS_TimerCbAPI_Init(void) { memset(OS_timecb_table, 0, sizeof(OS_timecb_table)); return OS_SUCCESS; -} +} /* end OS_TimerCbAPI_Init */ -/****************************************************************************** - * Function: OS_DoTimerAdd +/*---------------------------------------------------------------- * - * Purpose: Adds new OSAL Timer based on an existing timebase - * Internal function used by TimerCreate and TimerAdd API calls + * Function: OS_DoTimerAdd + * + * Purpose: Local helper routine, not part of OSAL API. + * Adds new OSAL Timer based on an existing timebase + * Internal function used by TimerCreate and TimerAdd API calls * * Arguments: flags to specify the internal bits to set in the created record * * Return: OS_SUCCESS or error code - */ + * + *-----------------------------------------------------------------*/ static int32 OS_DoTimerAdd(uint32 *timer_id, const char *timer_name, uint32 timebase_ref_id, OS_ArgCallback_t callback_ptr, void *callback_arg, uint32 flags) { OS_common_record_t *timebase; @@ -181,24 +184,31 @@ static int32 OS_DoTimerAdd(uint32 *timer_id, const char *timer_name, uint32 time } return return_code; -} +} /* end OS_DoTimerAdd */ -/****************************************************************************** - * Function: OS_TimerAdd + +/*---------------------------------------------------------------- * - * Purpose: Adds new OSAL Timer based on an existing timebase (external call) - * Just calls OS_DoTimerAdd with zero flags + * Function: OS_TimerAdd * - * Arguments: + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * Return: OS_SUCCESS or error code - */ + *-----------------------------------------------------------------*/ int32 OS_TimerAdd(uint32 *timer_id, const char *timer_name, uint32 timebase_ref_id, OS_ArgCallback_t callback_ptr, void *callback_arg) { return (OS_DoTimerAdd(timer_id, timer_name, timebase_ref_id, callback_ptr, callback_arg, 0)); -} +} /* end OS_TimerAdd */ + +/*---------------------------------------------------------------- + * + * Function: OS_Timer_NoArgCallback + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ static void OS_Timer_NoArgCallback(uint32 objid, void *arg) { OS_U32ValueWrapper_t Conv; @@ -209,21 +219,17 @@ static void OS_Timer_NoArgCallback(uint32 objid, void *arg) */ Conv.opaque_arg = arg; (*Conv.timer_callback_func)(objid); -} +} /* end OS_Timer_NoArgCallback */ -/****************************************************************************** - * Function: OS_TimerCreate - * - * Purpose: Creates new OSAL Timer AND associated timebase to go with it - * This function exists for API compatibility. It is a shortcut that - * creates both a software-driven timebase and a timer with the same - * interval. + +/*---------------------------------------------------------------- * + * Function: OS_TimerCreate * - * Arguments: + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * Return: - */ + *-----------------------------------------------------------------*/ int32 OS_TimerCreate(uint32 *timer_id, const char *timer_name, uint32 *accuracy, OS_TimerCallback_t callback_ptr) { int32 return_code; @@ -285,20 +291,18 @@ int32 OS_TimerCreate(uint32 *timer_id, const char *timer_name, uint32 *accuracy, } return return_code; -} +} /* end OS_TimerCreate */ -/****************************************************************************** - * Function: OS_TimerSet + +/*---------------------------------------------------------------- * - * Purpose: + * Function: OS_TimerSet * - * Arguments: - * (none) + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * Return: - * (none) - */ + *-----------------------------------------------------------------*/ int32 OS_TimerSet(uint32 timer_id, uint32 start_time, uint32 interval_time) { OS_common_record_t *record; @@ -313,6 +317,11 @@ int32 OS_TimerSet(uint32 timer_id, uint32 start_time, uint32 interval_time) { return OS_TIMER_ERR_INVALID_ARGS; } + + if (start_time == 0 && interval_time == 0) + { + return OS_ERROR; + } /* * Check our context. Not allowed to use the timer API from a timer callback. @@ -364,20 +373,18 @@ int32 OS_TimerSet(uint32 timer_id, uint32 start_time, uint32 interval_time) return_code = OS_TimeBaseSet(dedicated_timebase_id, start_time, interval_time); } return return_code; -} +} /* end OS_TimerSet */ -/****************************************************************************** - * Function: OS_TimerDelete + +/*---------------------------------------------------------------- * - * Purpose: + * Function: OS_TimerDelete * - * Arguments: - * (none) + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * Return: - * (none) - */ + *-----------------------------------------------------------------*/ int32 OS_TimerDelete(uint32 timer_id) { OS_timecb_internal_record_t *local; @@ -464,21 +471,17 @@ int32 OS_TimerDelete(uint32 timer_id) } return return_code; -} +} /* end OS_TimerDelete */ -/*********************************************************************************** - * - * Name: OS_TimerGetIdByName + +/*---------------------------------------------------------------- * - * Purpose: This function tries to find a Timer Id given the name - * The id is returned through timer_id + * Function: OS_TimerGetIdByName * - * Returns: 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 - * OS_SUCCESS if success + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - */ + *-----------------------------------------------------------------*/ int32 OS_TimerGetIdByName (uint32 *timer_id, const char *timer_name) { int32 return_code; @@ -503,18 +506,17 @@ int32 OS_TimerGetIdByName (uint32 *timer_id, const char *timer_name) return_code = OS_ObjectIdFindByName(OS_OBJECT_TYPE_OS_TIMECB, timer_name, timer_id); return return_code; -}/* end OS_TimerGetIdByName */ +} /* end OS_TimerGetIdByName */ -/*************************************************************************************** - * Name: OS_TimerGetInfo + +/*---------------------------------------------------------------- * - * Purpose: This function will pass back a pointer to structure that contains - * all of the relevant info( name and creator) about the specified timer. + * Function: OS_TimerGetInfo * - * Returns: OS_ERR_INVALID_ID if the id passed in is not a valid timer - * OS_INVALID_POINTER if the timer_prop pointer is null - * OS_SUCCESS if success - */ + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_TimerGetInfo (uint32 timer_id, OS_timer_prop_t *timer_prop) { OS_common_record_t *record; diff --git a/src/os/shared/osapi-timebase.c b/src/os/shared/osapi-timebase.c index 350be7390..e6cd7cad3 100644 --- a/src/os/shared/osapi-timebase.c +++ b/src/os/shared/osapi-timebase.c @@ -66,30 +66,30 @@ OS_timebase_internal_record_t OS_timebase_table [OS_MAX_TIMEBASES]; ***************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_TimeBaseAPI_Init - - Purpose: Init function for OS-independent layer - - Returns: OS_SUCCESS - ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_TimeBaseAPI_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * Init function for OS-independent layer + * + *-----------------------------------------------------------------*/ int32 OS_TimeBaseAPI_Init(void) { memset(OS_timebase_table, 0, sizeof(OS_timebase_table)); return OS_SUCCESS; -} +} /* end OS_TimeBaseAPI_Init */ -/****************************************************************************** - * Function: OS_TimeBaseCreate + +/*---------------------------------------------------------------- * - * Purpose: Create a new OSAL TimeBase + * Function: OS_TimeBaseCreate * - * Arguments: + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * Return: - */ + *-----------------------------------------------------------------*/ int32 OS_TimeBaseCreate(uint32 *timer_id, const char *timebase_name, OS_TimerSync_t external_sync) { OS_common_record_t *record; @@ -155,8 +155,16 @@ int32 OS_TimeBaseCreate(uint32 *timer_id, const char *timebase_name, OS_TimerSyn } return return_code; -} - +} /* end OS_TimeBaseCreate */ + +/*---------------------------------------------------------------- + * + * Function: OS_TimeBaseSet + * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_TimeBaseSet(uint32 timer_id, uint32 start_time, uint32 interval_time) { OS_common_record_t *record; @@ -207,19 +215,17 @@ int32 OS_TimeBaseSet(uint32 timer_id, uint32 start_time, uint32 interval_time) } return return_code; -} +} /* end OS_TimeBaseSet */ -/****************************************************************************** - * Function: OS_TimeBaseDelete + +/*---------------------------------------------------------------- * - * Purpose: + * Function: OS_TimeBaseDelete * - * Arguments: - * (none) + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * Return: - * (none) - */ + *-----------------------------------------------------------------*/ int32 OS_TimeBaseDelete(uint32 timer_id) { OS_common_record_t *record; @@ -252,21 +258,17 @@ int32 OS_TimeBaseDelete(uint32 timer_id) } return return_code; -} +} /* end OS_TimeBaseDelete */ -/*********************************************************************************** - * - * Name: OS_TimerGetIdByName + +/*---------------------------------------------------------------- * - * Purpose: This function tries to find a Timer Id given the name - * The id is returned through timer_id + * Function: OS_TimeBaseGetIdByName * - * Returns: 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 - * OS_SUCCESS if success + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - */ + *-----------------------------------------------------------------*/ int32 OS_TimeBaseGetIdByName (uint32 *timer_id, const char *timebase_name) { int32 return_code; @@ -291,18 +293,17 @@ int32 OS_TimeBaseGetIdByName (uint32 *timer_id, const char *timebase_name) return_code = OS_ObjectIdFindByName(OS_OBJECT_TYPE_OS_TIMEBASE, timebase_name, timer_id); return return_code; -}/* end OS_TimerGetIdByName */ +} /* end OS_TimeBaseGetIdByName */ -/*************************************************************************************** - * Name: OS_TimeBaseGetInfo + +/*---------------------------------------------------------------- * - * Purpose: This function will pass back a pointer to structure that contains - * all of the relevant info( name and creator) about the specified timebase. + * Function: OS_TimeBaseGetInfo * - * Returns: OS_ERR_INVALID_ID if the id passed in is not a valid timebase - * OS_INVALID_POINTER if the timebase_prop pointer is null - * OS_SUCCESS if success - */ + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_TimeBaseGetInfo (uint32 timebase_id, OS_timebase_prop_t *timebase_prop) { OS_common_record_t *record; @@ -344,16 +345,15 @@ int32 OS_TimeBaseGetInfo (uint32 timebase_id, OS_timebase_prop_t *timebase_prop) return return_code; } /* end OS_TimeBaseGetInfo */ -/*************************************************************************************** - * Name: OS_TimeBaseGetFreeRun + +/*---------------------------------------------------------------- * - * Purpose: Poll the timer "freerun" counter in a lightweight fashion. - * (Intentionally does not lock to avoid possible context switch) + * Function: OS_TimeBaseGetFreeRun * - * Returns: OS_ERR_INVALID_ID if the id passed in is not a valid timebase - * OS_INVALID_POINTER if the timebase_prop pointer is null - * OS_SUCCESS if success - */ + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail + * + *-----------------------------------------------------------------*/ int32 OS_TimeBaseGetFreeRun (uint32 timebase_id, uint32 *freerun_val) { OS_common_record_t *record; @@ -368,23 +368,27 @@ int32 OS_TimeBaseGetFreeRun (uint32 timebase_id, uint32 *freerun_val) } return return_code; -} +} /* end OS_TimeBaseGetFreeRun */ -/*************************************************************************************** - * Name: OS_TimeBase_CallbackThread +/*---------------------------------------------------------------- + * + * Function: OS_TimeBase_CallbackThread + * + * Purpose: Local helper routine, not part of OSAL API. + * Implementation of the time base "helper thread" * - * Purpose: This is executed in a dedicated thread context (typically elevated priority) - * and performs two basic functions: + * This is executed in a dedicated thread context (typically elevated priority) + * and performs two basic functions: * 1) call the BSP-specified delay routine to sync with the time reference (tick) * 2) process the requested Application callbacks each time the tick occurs * - * * Returns: None. * * Note: Application callbacks will be done under this thread context. * Doing callbacks directly as an ISR or signal handler can be dangerous, as the * available C library calls are very limited in that context. - */ + * + *-----------------------------------------------------------------*/ void OS_TimeBase_CallbackThread(uint32 timebase_id) { OS_TimerSync_t syncfunc; @@ -524,7 +528,7 @@ void OS_TimeBase_CallbackThread(uint32 timebase_id) OS_TimeBaseUnlock_Impl(local_id); } -} +} /* end OS_TimeBase_CallbackThread */ /**************************************************************************************** Other Time-Related API Implementation @@ -536,51 +540,29 @@ void OS_TimeBase_CallbackThread(uint32 timebase_id) * OS ticks directly. */ -/*--------------------------------------------------------------------------------------- - * Name: OS_Tick2Micros - * - * Purpose: - * This function returns the duration of a system tick in micro seconds. - * - * Assumptions and Notes: + +/*---------------------------------------------------------------- * - * Parameters: None + * Function: OS_Tick2Micros * - * Global Inputs: None + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * Global Outputs: None - * - * Return Values: duration of a system tick in microseconds - * - * Note - care is taken to ensure this does not return "0" since it is often used - * as the divisor in mathematical operations - * ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_Tick2Micros (void) { return (OS_SharedGlobalVars.MicroSecPerTick); -} +} /* end OS_Tick2Micros */ -/*--------------------------------------------------------------------------------------- - * Name: OS_Milli2Ticks - * - * Purpose: - * This function accepts a time interval in milliseconds, as an input and - * returns the tick equivalent for this time period. The tick value is - * rounded up. - * - * Assumptions and Notes: - * - * Parameters: - * milli_seconds : the time interval, in milliseconds, to be translated - * - * Global Inputs: None + +/*---------------------------------------------------------------- * - * Global Outputs: None + * Function: OS_Milli2Ticks * + * Purpose: Implemented per public OSAL API + * See description in API and header file for detail * - * Return Values: the number of ticks rounded up. ----------------------------------------------------------------------------------------*/ + *-----------------------------------------------------------------*/ int32 OS_Milli2Ticks(uint32 milli_seconds) { unsigned long num_of_ticks; @@ -590,7 +572,7 @@ int32 OS_Milli2Ticks(uint32 milli_seconds) num_of_ticks = (num_of_ticks + 999) / 1000; return((uint32)num_of_ticks); -} +} /* end OS_Milli2Ticks */ diff --git a/src/os/vxworks/osapi.c b/src/os/vxworks/osapi.c index 5f2dc9f24..d1dea6c3b 100644 --- a/src/os/vxworks/osapi.c +++ b/src/os/vxworks/osapi.c @@ -181,7 +181,15 @@ enum }; const OS_ErrorTable_Entry_t OS_IMPL_ERROR_NAME_TABLE[] = { { 0, NULL } }; - + +/*---------------------------------------------------------------- + * + * Function: OS_Lock_Global_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_Lock_Global_Impl(uint32 idtype) { VxWorks_GlobalMutex_t *mut; @@ -204,8 +212,16 @@ int32 OS_Lock_Global_Impl(uint32 idtype) } return OS_SUCCESS; -} - +} /* end OS_Lock_Global_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_Unlock_Global_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_Unlock_Global_Impl(uint32 idtype) { VxWorks_GlobalMutex_t *mut; @@ -228,7 +244,7 @@ int32 OS_Unlock_Global_Impl(uint32 idtype) } return OS_SUCCESS; -} +} /* end OS_Unlock_Global_Impl */ @@ -236,14 +252,14 @@ int32 OS_Unlock_Global_Impl(uint32 idtype) INITIALIZATION FUNCTION ****************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_API_Init - - Purpose: Initialize the tables that the OS API uses to keep track of information - about objects - - returns: OS_SUCCESS or OS_ERROR ----------------------------------------------------------------------------------------*/ +/*---------------------------------------------------------------- + * + * Function: OS_API_Impl_Init + * + * Purpose: Initialize the tables that the OS API uses to keep track of information + * about objects + * + *-----------------------------------------------------------------*/ int32 OS_API_Impl_Init(uint32 idtype) { int32 return_code = OS_SUCCESS; @@ -303,35 +319,37 @@ int32 OS_API_Impl_Init(uint32 idtype) return(return_code); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_IdleLoop - - Purpose: Wait for external events. +} /* end OS_API_Impl_Init */ - returns: no value ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_IdleLoop_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_IdleLoop_Impl() { TASK_ID tid = taskIdSelf(); OS_idle_task_id = tid; taskSuspend(tid); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_ApplicationShutdown_Impl +} /* end OS_IdleLoop_Impl */ - Purpose: Ensures that the thread waiting in OS_IdleLoop_Impl is waken up - - returns: no value - - NOTE: Might be called from an ISR/signal handler ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ApplicationShutdown_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_ApplicationShutdown_Impl() { taskResume(OS_idle_task_id); -} +} /* end OS_ApplicationShutdown_Impl */ @@ -347,7 +365,7 @@ static int OS_VxWorksEntry(int arg) { OS_TaskEntryPoint((uint32)arg); return 0; -} +} /* end OS_VxWorksEntry */ @@ -355,30 +373,29 @@ static int OS_VxWorksEntry(int arg) TASK API ****************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_VxWorks_TaskAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_VxWorks_TaskAPI_Impl_Init(void) { memset(OS_impl_task_table, 0, sizeof(OS_impl_task_table)); return (OS_SUCCESS); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskCreate - - Purpose: Creates a task and starts running it. - - returns: 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 the operating system calls fail - OS_SUCCESS if success - - NOTES: task_id is passed back to the user as the ID. stack_pointer is usually null. - - ----------------------------------------------------------------------------------------*/ +} /* end OS_VxWorks_TaskAPI_Impl_Init */ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskCreate_Impl (uint32 task_id, uint32 flags) { STATUS status; @@ -524,16 +541,15 @@ int32 OS_TaskCreate_Impl (uint32 task_id, uint32 flags) } /* end OS_TaskCreate_Impl */ -/*-------------------------------------------------------------------------------------- - Name: OS_TaskDelete - - Purpose: Deletes the specified Task and removes it from the OS_task_table. - - returns: OS_ERR_INVALID_ID if the ID given to it is invalid - OS_ERROR if the OS delete call fails - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_TaskDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskDelete_Impl (uint32 task_id) { /* @@ -551,28 +567,31 @@ int32 OS_TaskDelete_Impl (uint32 task_id) OS_impl_task_table[task_id].vxid = 0; return OS_SUCCESS; -}/* end OS_TaskDelete_Impl */ - -/*-------------------------------------------------------------------------------------- - Name: OS_TaskExit - - Purpose: Exits the calling task and removes it from the OS_task_table. +} /* end OS_TaskDelete_Impl */ - returns: Nothing ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskExit_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_TaskExit_Impl() { taskExit(0); -}/*end OS_TaskExit_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskDelay - - Purpose: Delay a task for specified amount of milliseconds +} /* end OS_TaskExit_Impl */ - returns: OS_ERROR if sleep fails - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskDelay_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskDelay_Impl (uint32 milli_second) { /* msecs rounded to the closest system tick count */ @@ -587,19 +606,17 @@ int32 OS_TaskDelay_Impl (uint32 milli_second) } return OS_SUCCESS; -}/* end OS_TaskDelay_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskSetPriority - - Purpose: Sets the given task to a new priority +} /* end OS_TaskDelay_Impl */ - returns: 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 - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskSetPriority_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskSetPriority_Impl (uint32 task_id, uint32 new_priority) { /* Set VxWorks Task Priority */ @@ -610,16 +627,17 @@ int32 OS_TaskSetPriority_Impl (uint32 task_id, uint32 new_priority) return OS_SUCCESS; -}/* end OS_TaskSetPriority_Impl */ +} /* end OS_TaskSetPriority_Impl */ -/*-------------------------------------------------------------------------------------- - Name: OS_TaskMatch - - Purpose: Determines if the caller matches the given task_id - - returns: OS_ERROR if not a match - OS_SUCCESS if match ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskMatch_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskMatch_Impl(uint32 task_id) { /* @@ -634,30 +652,29 @@ int32 OS_TaskMatch_Impl(uint32 task_id) return OS_SUCCESS; } /* end OS_TaskMatch_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_TaskRegister - - Purpose: Registers the calling task id with the task by adding the var to the tcb - - Returns: OS_ERR_INVALID_ID if there the specified ID could not be found - OS_ERROR if the OS call fails - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_TaskRegister_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskRegister_Impl (uint32 global_task_id) { return OS_SUCCESS; -}/* end OS_TaskRegister_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskGetId +} /* end OS_TaskRegister_Impl */ - Purpose: This function returns the OSAL task id of the calling task - - Notes: The OS_task_key is initialized by the task switch if AND ONLY IF the - OS_task_key has been registered via OS_TaskRegister(..). If this is not - called prior to this call, the value will be old and wrong. ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskGetId_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ uint32 OS_TaskGetId_Impl (void) { OS_impl_task_internal_record_t *lrec; @@ -678,20 +695,17 @@ uint32 OS_TaskGetId_Impl (void) return id; -}/* end OS_TaskGetId_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_TaskGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info (creator, stack size, priority, name) about the - specified task. +} /* end OS_TaskGetId_Impl */ - Returns: OS_ERR_INVALID_ID if the ID passed to it is invalid - OS_INVALID_POINTER if the task_prop pointer is NULL - OS_SUCCESS if it copied all of the relevant info over - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TaskGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TaskGetInfo_Impl (uint32 task_id, OS_task_prop_t *task_prop) { union @@ -718,27 +732,29 @@ int32 OS_TaskGetInfo_Impl (uint32 task_id, OS_task_prop_t *task_prop) MESSAGE QUEUE API ****************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_VxWorks_QueueAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_VxWorks_QueueAPI_Impl_Init(void) { memset(OS_impl_queue_table, 0, sizeof(OS_impl_queue_table)); return (OS_SUCCESS); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_QueueCreate - - Purpose: Create a message queue which can be refered to by name or ID - - Returns: 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 - OS_SUCCESS if success - - Notes: the flags parameter is unused. ----------------------------------------------------------------------------------------*/ +} /* end OS_VxWorks_QueueAPI_Impl_Init */ + +/*---------------------------------------------------------------- + * + * Function: OS_QueueCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueCreate_Impl (uint32 queue_id, uint32 flags) { MSG_Q_ID tmp_msgq_id; @@ -760,18 +776,15 @@ int32 OS_QueueCreate_Impl (uint32 queue_id, uint32 flags) } /* end OS_QueueCreate_Impl */ -/*-------------------------------------------------------------------------------------- - Name: OS_QueueDelete - - Purpose: Deletes the specified message queue. - - Returns: OS_ERR_INVALID_ID if the id passed in does not exist - OS_ERROR if the OS call to delete the queue fails - OS_SUCCESS if success - - Notes: 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 ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_QueueDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueDelete_Impl (uint32 queue_id) { /* Try to delete the queue */ @@ -787,18 +800,15 @@ int32 OS_QueueDelete_Impl (uint32 queue_id) } /* end OS_QueueDelete_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_QueueGet - - Purpose: Receive a message on a message queue. Will pend or timeout on the receive. - Returns: OS_ERR_INVALID_ID if the given ID does not exist - OS_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 passed in may be too small for the message - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_QueueGet_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueGet_Impl (uint32 queue_id, void *data, uint32 size, uint32 *size_copied, int32 timeout) { @@ -847,23 +857,17 @@ int32 OS_QueueGet_Impl (uint32 queue_id, void *data, uint32 size, uint32 *size_c } return return_code; -}/* end OS_QueueGet_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_QueuePut - - Purpose: Put a message on a message queue. - - Returns: 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 - OS_SUCCESS if SUCCESS - - Notes: The flags parameter is not used. The message put is always configured to - immediately return an error if the receiving message queue is full. ----------------------------------------------------------------------------------------*/ +} /* end OS_QueueGet_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_QueuePut_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_QueuePut_Impl (uint32 queue_id, const void *data, uint32 size, uint32 flags) { int32 return_code; @@ -884,19 +888,17 @@ int32 OS_QueuePut_Impl (uint32 queue_id, const void *data, uint32 size, uint32 f return return_code; -}/* end OS_QueuePut_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_QueueGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info (name and creator) about the specified queue. - - Returns: 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 ----------------------------------------------------------------------------------------*/ +} /* end OS_QueuePut_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_QueueGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_QueueGetInfo_Impl (uint32 queue_id, OS_queue_prop_t *queue_prop) { /* No extra info for queues in the OS implementation */ @@ -917,6 +919,14 @@ int32 OS_QueueGetInfo_Impl (uint32 queue_id, OS_queue_prop_t *queue_prop) * Therefore all semaphore actions can just invoke these generic actions * ----------------------------------- */ + +/*---------------------------------------------------------------- + * + * Function: OS_VxWorks_GenericSemGive + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ static int32 OS_VxWorks_GenericSemGive(SEM_ID vxid) { /* Give VxWorks Semaphore */ @@ -926,8 +936,16 @@ static int32 OS_VxWorks_GenericSemGive(SEM_ID vxid) return OS_SEM_FAILURE; } return OS_SUCCESS; -} +} /* end OS_VxWorks_GenericSemGive */ + +/*---------------------------------------------------------------- + * + * Function: OS_VxWorks_GenericSemTake + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ static int32 OS_VxWorks_GenericSemTake(SEM_ID vxid, int sys_ticks) { int vx_status; @@ -951,35 +969,34 @@ static int32 OS_VxWorks_GenericSemTake(SEM_ID vxid, int sys_ticks) } return OS_SUCCESS; -} +} /* end OS_VxWorks_GenericSemTake */ /**************************************************************************************** BINARY SEMAPHORE API ****************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_VxWorks_BinSemAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_VxWorks_BinSemAPI_Impl_Init(void) { memset(OS_impl_bin_sem_table, 0, sizeof(OS_impl_bin_sem_table)); return (OS_SUCCESS); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemCreate - - Purpose: Creates a binary semaphore with initial value specified by - sem_initial_value and name specified by sem_name. sem_id will be - returned to the caller - - Returns: 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 - OS_SUCCESS if success - - - Notes: options is an unused parameter ----------------------------------------------------------------------------------------*/ +} /* end OS_VxWorks_BinSemAPI_Impl_Init */ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemCreate_Impl (uint32 sem_id, uint32 sem_initial_value, uint32 options) { SEM_ID tmp_sem_id; @@ -998,20 +1015,18 @@ int32 OS_BinSemCreate_Impl (uint32 sem_id, uint32 sem_initial_value, uint32 opti OS_impl_bin_sem_table[sem_id].vxid = tmp_sem_id; return OS_SUCCESS; -}/* end OS_BinSemCreate_Impl */ - - -/*-------------------------------------------------------------------------------------- - Name: OS_BinSemDelete +} /* end OS_BinSemCreate_Impl */ - Purpose: Deletes the specified Binary Semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid binary semaphore - OS_SEM_FAILURE the OS call failed - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemDelete_Impl (uint32 sem_id) { /* @@ -1020,44 +1035,32 @@ int32 OS_BinSemDelete_Impl (uint32 sem_id) OS_impl_bin_sem_table[sem_id].vxid = 0; return OS_SUCCESS; -}/* end OS_BinSemDelete_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemGive - - Purpose: The function unlocks the semaphore referenced by sem_id by performing - a semaphore unlock operation on that semaphore.If the semaphore value - resulting from this operation is positive, then no threads were blocked - waiting for the semaphore to become unlocked; the semaphore value is - simply incremented for this semaphore. - - - Returns: 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 - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +} /* end OS_BinSemDelete_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemGive_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemGive_Impl (uint32 sem_id) { /* Use common routine */ return OS_VxWorks_GenericSemGive(OS_impl_bin_sem_table[sem_id].vxid); -}/* end OS_BinSemGive_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemFlush - - Purpose: The function releases all the tasks pending on this semaphore. Note - that the state of the semaphore is not changed by this operation. - - Returns: 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 - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +} /* end OS_BinSemGive_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemFlush_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemFlush_Impl (uint32 sem_id) { /* Flush VxWorks Semaphore */ @@ -1068,63 +1071,47 @@ int32 OS_BinSemFlush_Impl (uint32 sem_id) } return OS_SUCCESS; -}/* end OS_BinSemFlush_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemTake - - Purpose: The locks the semaphore referenced by sem_id by performing a - semaphore lock operation on that semaphore.If the semaphore value - is currently zero, then the calling thread shall not return from - the call until it either locks the semaphore or the call is - interrupted by a signal. - - Return: OS_ERR_INVALID_ID : the semaphore was not previously initialized - or is not in the array of semaphores defined by the system - OS_SEM_FAILURE if the OS call failed and the semaphore is not obtained - OS_SUCCESS if success - -----------------------------------------------------------------------------------------*/ +} /* end OS_BinSemFlush_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemTake_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemTake_Impl (uint32 sem_id) { /* Use common routine */ return OS_VxWorks_GenericSemTake(OS_impl_bin_sem_table[sem_id].vxid, WAIT_FOREVER); -}/* end OS_BinSemTake_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemTimedWait - - Purpose: The function locks the semaphore referenced by sem_id . However, - if the semaphore cannot be locked without waiting for another process - or thread to unlock the semaphore , this wait shall be terminated when - the specified timeout ,msecs, expires. - - Returns: OS_SEM_TIMEOUT if semaphore was not relinquished in time - OS_SUCCESS if success - 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 -----------------------------------------------------------------------------------------*/ +} /* end OS_BinSemTake_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemTimedWait_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemTimedWait_Impl (uint32 sem_id, uint32 msecs) { return OS_VxWorks_GenericSemTake(OS_impl_bin_sem_table[sem_id].vxid, OS_Milli2Ticks(msecs)); -}/* end OS_BinSemTimedWait_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_BinSemGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info( name and creator) about the specified binary - semaphore. - - Returns: 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 ----------------------------------------------------------------------------------------*/ +} /* end OS_BinSemTimedWait_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_BinSemGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_BinSemGetInfo_Impl (uint32 sem_id, OS_bin_sem_prop_t *bin_prop) { /* VxWorks has no API for obtaining the current value of a semaphore */ @@ -1136,30 +1123,30 @@ int32 OS_BinSemGetInfo_Impl (uint32 sem_id, OS_bin_sem_prop_t *bin_prop) COUNTING SEMAPHORE API ****************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_VxWorks_CountSemAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_VxWorks_CountSemAPI_Impl_Init(void) { memset(OS_impl_count_sem_table, 0, sizeof(OS_impl_count_sem_table)); return (OS_SUCCESS); -} - - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemCreate - - Purpose: Creates a countary semaphore with initial value specified by - sem_initial_value and name specified by sem_name. sem_id will be - returned to the caller - - Returns: 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 countary semaphore - OS_SEM_FAILURE if the OS call failed - OS_SUCCESS if success +} /* end OS_VxWorks_CountSemAPI_Impl_Init */ - Notes: options is an unused parameter ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemCreate_Impl (uint32 sem_id, uint32 sem_initial_value, uint32 options) { SEM_ID tmp_sem_id; @@ -1178,19 +1165,17 @@ int32 OS_CountSemCreate_Impl (uint32 sem_id, uint32 sem_initial_value, uint32 op OS_impl_count_sem_table[sem_id].vxid = tmp_sem_id; return OS_SUCCESS; -}/* end OS_CountSemCreate_Impl */ - -/*-------------------------------------------------------------------------------------- - Name: OS_CountSemDelete - - Purpose: Deletes the specified Counting Semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid countary semaphore - OS_SEM_FAILURE the OS call failed - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +} /* end OS_CountSemCreate_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemDelete_Impl (uint32 sem_id) { /* @@ -1199,121 +1184,97 @@ int32 OS_CountSemDelete_Impl (uint32 sem_id) OS_impl_count_sem_table[sem_id].vxid = 0; return OS_SUCCESS; -}/* end OS_CountSemDelete_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemGive - - Purpose: The function unlocks the semaphore referenced by sem_id by performing - a semaphore unlock operation on that semaphore.If the semaphore value - resulting from this operation is positive, then no threads were blocked - waiting for the semaphore to become unlocked; the semaphore value is - simply incremented for this semaphore. - - - Returns: 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 countary semaphore - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +} /* end OS_CountSemDelete_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemGive_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemGive_Impl (uint32 sem_id) { /* Give VxWorks Semaphore */ return OS_VxWorks_GenericSemGive(OS_impl_count_sem_table[sem_id].vxid); -}/* end OS_CountSemGive_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemTake - - Purpose: The locks the semaphore referenced by sem_id by performing a - semaphore lock operation on that semaphore.If the semaphore value - is currently zero, then the calling thread shall not return from - the call until it either locks the semaphore or the call is - interrupted by a signal. - - Return: 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 the Id passed in is not a valid countar semaphore - OS_SEM_FAILURE if the OS call failed - OS_SUCCESS if success - -----------------------------------------------------------------------------------------*/ +} /* end OS_CountSemGive_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemTake_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemTake_Impl (uint32 sem_id) { return OS_VxWorks_GenericSemTake(OS_impl_count_sem_table[sem_id].vxid, WAIT_FOREVER); -}/* end OS_CountSemTake_Impl */ - - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemTimedWait +} /* end OS_CountSemTake_Impl */ - Purpose: The function locks the semaphore referenced by sem_id . However, - if the semaphore cannot be locked without waiting for another process - or thread to unlock the semaphore , this wait shall be terminated when - the specified timeout ,msecs, expires. - - Returns: OS_SEM_TIMEOUT if semaphore was not relinquished in time - OS_SUCCESS if success - 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 -----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemTimedWait_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemTimedWait_Impl (uint32 sem_id, uint32 msecs) { return OS_VxWorks_GenericSemTake(OS_impl_count_sem_table[sem_id].vxid, OS_Milli2Ticks(msecs)); -}/* end OS_CountSemTimedWait_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_CountSemGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info( name and creator) about the specified countary - semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid semaphore - OS_INVALID_POINTER if the count_prop pointer is null - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ +} /* end OS_CountSemTimedWait_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_CountSemGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_CountSemGetInfo_Impl (uint32 sem_id, OS_count_sem_prop_t *count_prop) { /* VxWorks does not provide an API to get the value */ return OS_SUCCESS; -} /* end OS_CountSemGetInfo */ +} /* end OS_CountSemGetInfo_Impl */ /**************************************************************************************** MUTEX API ****************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_VxWorks_MutexAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_VxWorks_MutexAPI_Impl_Init(void) { memset(OS_impl_mut_sem_table, 0, sizeof(OS_impl_mut_sem_table)); return (OS_SUCCESS); -} - -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemCreate - - Purpose: Creates a mutex semaphore initially full. - - Returns: 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 - OS_SUCCESS if success - - Notes: the options parameter is not used in this implementation - ----------------------------------------------------------------------------------------*/ +} /* end OS_VxWorks_MutexAPI_Impl_Init */ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemCreate_Impl (uint32 sem_id, uint32 options) { SEM_ID tmp_sem_id; @@ -1330,19 +1291,17 @@ int32 OS_MutSemCreate_Impl (uint32 sem_id, uint32 options) OS_impl_mut_sem_table[sem_id].vxid = tmp_sem_id; return OS_SUCCESS; -}/* end OS_MutSemCreate_Impl */ - -/*-------------------------------------------------------------------------------------- - Name: OS_MutSemDelete - - Purpose: Deletes the specified Mutex Semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid mutex - OS_SEM_FAILURE if the OS call failed - OS_SUCCESS if success - ----------------------------------------------------------------------------------------*/ +} /* end OS_MutSemCreate_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemDelete_Impl (uint32 sem_id) { /* @@ -1351,63 +1310,48 @@ int32 OS_MutSemDelete_Impl (uint32 sem_id) OS_impl_mut_sem_table[sem_id].vxid = 0; return OS_SUCCESS; -}/* end OS_MutSemDelete_Impl */ +} /* end OS_MutSemDelete_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemGive - - Purpose: The function releases the mutex object referenced by sem_id.The - manner in which a mutex is released is dependent upon the mutex's type - attribute. If there are threads blocked on the mutex object referenced by - mutex when this function is called, resulting in the mutex becoming - available, the scheduling policy shall determine which thread shall - acquire the mutex. - - Returns: OS_SUCCESS if success - OS_SEM_FAILURE if the semaphore was not previously initialized - OS_ERR_INVALID_ID if the id passed in is not a valid mutex - ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemGive_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemGive_Impl (uint32 sem_id) { /* Give VxWorks Semaphore */ return OS_VxWorks_GenericSemGive(OS_impl_mut_sem_table[sem_id].vxid); -}/* end OS_MutSemGive_Impl */ +} /* end OS_MutSemGive_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemTake - - Purpose: The mutex object referenced by sem_id shall be locked by calling this - function. If the mutex is already locked, the calling thread shall - block until the mutex becomes available. This operation shall return - with the mutex object referenced by mutex in the locked state with the - calling thread as its owner. - - Returns: OS_SUCCESS if success - 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 ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemTake_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemTake_Impl (uint32 sem_id) { /* Take VxWorks Semaphore */ return OS_VxWorks_GenericSemTake(OS_impl_mut_sem_table[sem_id].vxid, WAIT_FOREVER); -}/* end OS_MutSemTake_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_MutSemGetInfo - - Purpose: This function will pass back a pointer to structure that contains - all of the relevant info( name and creator) about the specified mutex - semaphore. - - Returns: OS_ERR_INVALID_ID if the id passed in is not a valid semaphore - OS_INVALID_POINTER if the mut_prop pointer is null - OS_SUCCESS if success ----------------------------------------------------------------------------------------*/ +} /* end OS_MutSemTake_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_MutSemGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_MutSemGetInfo_Impl (uint32 sem_id, OS_mut_sem_prop_t *mut_prop) { /* VxWorks provides no additional info */ @@ -1423,19 +1367,15 @@ int32 OS_MutSemGetInfo_Impl (uint32 sem_id, OS_mut_sem_prop_t *mut_prop) INT API ****************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_IntAttachHandler - - Purpose: The call associates a specified C routine to a specified interrupt - number.Upon occurring of the InterruptNumber the InerruptHandler - routine will be called and passed the parameter. - - Parameters: - InterruptNumber : The Interrupt Number that will cause the start of the ISR - InerruptHandler : The ISR associatd with this interrupt - parameter :The parameter that is passed to the ISR - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_IntAttachHandler_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_IntAttachHandler_Impl (uint32 InterruptNumber, osal_task_entry InterruptHandler, int32 parameter) { /* The Xenomai-VxWorks emulation layer does not support interrupt control */ @@ -1446,47 +1386,46 @@ int32 OS_IntAttachHandler_Impl (uint32 InterruptNumber, osal_task_entry Interru } return OS_SUCCESS; -}/* end OS_IntAttachHandler_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_IntUnlock - - Purpose: Enable previous state of interrupts - - Parameters: - IntLevel : The Interrupt Level to be reinstated ----------------------------------------------------------------------------------------*/ - +} /* end OS_IntAttachHandler_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_IntUnlock_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_IntUnlock_Impl (int32 IntLevel) { intUnlock(IntLevel); return(OS_SUCCESS); -}/* end OS_IntUnlock_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_IntLock - - Purpose: Disable interrupts. - - Parameters: - - Returns: Interrupt level ----------------------------------------------------------------------------------------*/ +} /* end OS_IntUnlock_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_IntLock_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_IntLock_Impl (void) { return (int32)intLock(); -}/* end OS_IntLock_Impl */ +} /* end OS_IntLock_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_IntEnable - - Purpose: Enable previous state of interrupts - - Parameters: - IntLevel : The Interrupt Level to be reinstated ----------------------------------------------------------------------------------------*/ - + +/*---------------------------------------------------------------- + * + * Function: OS_IntEnable_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_IntEnable_Impl (int32 Level) { int32 RetCode; @@ -1504,18 +1443,17 @@ int32 OS_IntEnable_Impl (int32 Level) } return RetCode; -}/* end OS_IntEnable_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_IntDisable - - Purpose: Disable the corresponding interrupt number. - - Parameters: - - Returns: Interrupt level before OS_IntDisable Call ----------------------------------------------------------------------------------------*/ +} /* end OS_IntEnable_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_IntDisable_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_IntDisable_Impl (int32 Level) { int32 RetCode; @@ -1533,16 +1471,17 @@ int32 OS_IntDisable_Impl (int32 Level) } return RetCode; -}/* end OS_IntDisable_Impl */ - -/*--------------------------------------------------------------------------------------- - Name: OS_HeapGetInfo - - Purpose: Return current info on the heap +} /* end OS_IntDisable_Impl */ - Parameters: - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_HeapGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_HeapGetInfo_Impl (OS_heap_prop_t *heap_prop) { MEM_PART_STATS stats; @@ -1562,56 +1501,43 @@ int32 OS_HeapGetInfo_Impl (OS_heap_prop_t *heap_prop) return (OS_SUCCESS); } /* end OS_HeapGetInfo_Impl */ -/*--------------------------------------------------------------------------------------- -** Name: OS_SetMask -** Purpose: -** Set the masking register to mask and unmask interrupts -** -** Assumptions and Notes: -** HW interrupt control is not supported from a user task -** -** Parameters: -** MaskSetting :the value to be written into the mask register -** -** Global Inputs: None -** -** Global Outputs: None -** -** -** Return Values: -** ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_IntSetMask_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_IntSetMask_Impl ( uint32 MaskSetting ) { return(OS_ERR_NOT_IMPLEMENTED); } /* end OS_IntSetMask_Impl */ -/*-------------------------------------------------------------------------------------- -** Name: OS_GetMask -** Purpose: -** Read and report the setting of the cpu mask register. -** -** Assumptions and Notes: -** HW interrupt control is not supported from a user task -** -** Parameters: -** MaskSettingPtr : pointer to a location where the function store the -** reading of the cpu mask register. -** -** Global Inputs: None -** -** Global Outputs: None -** -** -** Return Values: -** ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_IntGetMask_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_IntGetMask_Impl ( uint32 * MaskSettingPtr ) { *MaskSettingPtr = 0; return(OS_ERR_NOT_IMPLEMENTED); } /* end OS_IntGetMask_Impl */ - + +/*---------------------------------------------------------------- + * + * Function: OS_FPUExcAttachHandler_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FPUExcAttachHandler_Impl(uint32 ExceptionNumber, void * ExceptionHandler, int32 parameter) { @@ -1620,7 +1546,15 @@ int32 OS_FPUExcAttachHandler_Impl(uint32 ExceptionNumber, void * ExceptionHandle */ return(OS_ERR_NOT_IMPLEMENTED); } /* end OS_FPUExcAttachHandler_Impl */ - + +/*---------------------------------------------------------------- + * + * Function: OS_FPUExcEnable_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FPUExcEnable_Impl(int32 ExceptionNumber) { /* @@ -1628,7 +1562,15 @@ int32 OS_FPUExcEnable_Impl(int32 ExceptionNumber) */ return(OS_SUCCESS); } /* end OS_FPUExcEnable_Impl */ - + +/*---------------------------------------------------------------- + * + * Function: OS_FPUExcDisable_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FPUExcDisable_Impl(int32 ExceptionNumber) { /* @@ -1637,15 +1579,15 @@ int32 OS_FPUExcDisable_Impl(int32 ExceptionNumber) return(OS_SUCCESS); } /* end OS_FPUExcDisable_Impl */ -/* -** -** Name: OS_FPUExcSetMask -** -** Purpose: This function sets the FPU exception mask -** -** Notes: 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. -*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FPUExcSetMask_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FPUExcSetMask_Impl(uint32 mask) { int32 Status; @@ -1664,15 +1606,15 @@ int32 OS_FPUExcSetMask_Impl(uint32 mask) return Status; } /* end OS_FPUExcSetMask_Impl */ -/* -** -** Name: OS_FPUExcGetMask -** -** Purpose: This function gets the FPU exception mask -** -** Notes: 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. -*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FPUExcGetMask_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FPUExcGetMask_Impl(uint32 *mask) { int32 Status; @@ -1691,13 +1633,15 @@ int32 OS_FPUExcGetMask_Impl(uint32 *mask) /********************************************************************/ -/* - * Name: OS_ConsoleOutput_Impl + +/*---------------------------------------------------------------- * - * Purpose: Transfer output data to the real console. + * Function: OS_ConsoleOutput_Impl * - * The data is already formatted, this just writes the characters. - */ + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_ConsoleOutput_Impl(uint32 local_id) { uint32 StartPos; @@ -1721,7 +1665,15 @@ void OS_ConsoleOutput_Impl(uint32 local_id) /* Update the global with the new read location */ console->ReadPos = StartPos; } /* end OS_ConsoleOutput_Impl */ - + +/*---------------------------------------------------------------- + * + * Function: OS_ConsoleWakeup_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_ConsoleWakeup_Impl(uint32 local_id) { OS_impl_console_internal_record_t *local = &OS_impl_console_table[local_id]; @@ -1741,6 +1693,14 @@ void OS_ConsoleWakeup_Impl(uint32 local_id) } } /* end OS_ConsoleWakeup_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_ConsoleTask_Entry + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ static void OS_ConsoleTask_Entry(int arg) { uint32 local_id = arg; @@ -1757,7 +1717,15 @@ static void OS_ConsoleTask_Entry(int arg) } } } /* end OS_ConsoleTask_Entry */ - + +/*---------------------------------------------------------------- + * + * Function: OS_ConsoleCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ConsoleCreate_Impl(uint32 local_id) { OS_impl_console_internal_record_t *local = &OS_impl_console_table[local_id]; diff --git a/src/os/vxworks/osfileapi.c b/src/os/vxworks/osfileapi.c index 31bddc6dd..09b1b291a 100644 --- a/src/os/vxworks/osfileapi.c +++ b/src/os/vxworks/osfileapi.c @@ -95,6 +95,15 @@ const int OS_IMPL_REGULAR_FILE_FLAGS = 0; * defines the e.g. mkdir() system calls differently. */ + +/*---------------------------------------------------------------- + * + * Function: OS_DirCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_DirCreate_Impl(const char *local_path, uint32 access) { int32 return_code; @@ -109,8 +118,16 @@ int32 OS_DirCreate_Impl(const char *local_path, uint32 access) } return return_code; -} - +} /* end OS_DirCreate_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_DirOpen_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_DirOpen_Impl(uint32 local_id, const char *local_path) { OS_impl_dir_table[local_id] = opendir(local_path); @@ -119,15 +136,31 @@ int32 OS_DirOpen_Impl(uint32 local_id, const char *local_path) return OS_FS_ERROR; } return OS_FS_SUCCESS; -} - +} /* end OS_DirOpen_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_DirClose_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_DirClose_Impl(uint32 local_id) { closedir(OS_impl_dir_table[local_id]); OS_impl_dir_table[local_id] = NULL; return OS_FS_SUCCESS; -} - +} /* end OS_DirClose_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_DirRead_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_DirRead_Impl(uint32 local_id, os_dirent_t *dirent) { struct dirent *de; @@ -151,14 +184,30 @@ int32 OS_DirRead_Impl(uint32 local_id, os_dirent_t *dirent) dirent->FileName[OS_MAX_PATH_LEN - 1] = 0; return OS_FS_SUCCESS; -} - +} /* end OS_DirRead_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_DirRewind_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_DirRewind_Impl(uint32 local_id) { rewinddir(OS_impl_dir_table[local_id]); return OS_FS_SUCCESS; -} - +} /* end OS_DirRewind_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_DirRemove_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_DirRemove_Impl(const char *local_path) { if ( rmdir(local_path) < 0 ) @@ -167,7 +216,7 @@ int32 OS_DirRemove_Impl(const char *local_path) } return OS_FS_SUCCESS; -} +} /* end OS_DirRemove_Impl */ /**************************************************************************************** @@ -181,6 +230,14 @@ int32 OS_DirRemove_Impl(const char *local_path) #define OS_SHELL_CMD_TASK_PRIORITY 250 + +/*---------------------------------------------------------------- + * + * Function: OS_VxWorks_StreamAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_VxWorks_StreamAPI_Impl_Init(void) { uint32 local_id; @@ -195,24 +252,32 @@ int32 OS_VxWorks_StreamAPI_Impl_Init(void) } return OS_SUCCESS; -} +} /* end OS_VxWorks_StreamAPI_Impl_Init */ + +/*---------------------------------------------------------------- + * + * Function: OS_VxWorks_DirAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_VxWorks_DirAPI_Impl_Init(void) { memset(OS_impl_dir_table, 0, sizeof(OS_impl_dir_table)); return OS_SUCCESS; -} - +} /* end OS_VxWorks_DirAPI_Impl_Init */ -/* -------------------------------------------------------------------------------------- - Name: OS_ShellOutputToFile - Purpose: Takes a shell command in and writes the output of that command to the specified file - - Returns: OS_FS_ERROR if the command was not executed properly - OS_FS_ERR_INVALID_FD if the file descriptor passed in is invalid - OS_SUCCESS if success - ---------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ShellOutputToFile_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ShellOutputToFile_Impl(uint32 file_id, const char *Cmd) { int32 ReturnCode = OS_FS_ERROR; @@ -259,5 +324,5 @@ int32 OS_ShellOutputToFile_Impl(uint32 file_id, const char *Cmd) return ReturnCode; -}/* end OS_ShellOutputToFile */ +} /* end OS_ShellOutputToFile_Impl */ diff --git a/src/os/vxworks/osfilesys.c b/src/os/vxworks/osfilesys.c index 53f91bce6..510e38b58 100644 --- a/src/os/vxworks/osfilesys.c +++ b/src/os/vxworks/osfilesys.c @@ -61,14 +61,15 @@ OS_impl_filesys_internal_record_t OS_impl_filesys_table[OS_MAX_FILE_SYSTEMS]; Filesys API ****************************************************************************************/ -/*--------------------------------------------------------------------------------------- - Name: OS_FileSysStartVolume_Impl - - Purpose: Starts/Registers a file system on the target - - Returns: OS_FS_SUCCESS on creating the disk - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysStartVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysStartVolume_Impl (uint32 filesys_id) { OS_filesys_internal_record_t *local = &OS_filesys_table[filesys_id]; @@ -171,14 +172,15 @@ int32 OS_FileSysStartVolume_Impl (uint32 filesys_id) } /* end OS_FileSysStartVolume_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_FileSysStopVolume_Impl - - Purpose: Stops/Unregisters a file system on the target - - Returns: OS_FS_SUCCESS on creating the disk - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysStopVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysStopVolume_Impl (uint32 filesys_id) { OS_impl_filesys_internal_record_t *impl = &OS_impl_filesys_table[filesys_id]; @@ -199,14 +201,15 @@ int32 OS_FileSysStopVolume_Impl (uint32 filesys_id) } /* end OS_FileSysStopVolume_Impl */ -/*--------------------------------------------------------------------------------------- - Name: OS_FileSysFormatVolume_Impl - - Purpose: Formats a file system on the target to prepare it for use - - Returns: OS_FS_SUCCESS on creating the disk - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysFormatVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysFormatVolume_Impl (uint32 filesys_id) { OS_filesys_internal_record_t *local = &OS_filesys_table[filesys_id]; @@ -224,17 +227,18 @@ int32 OS_FileSysFormatVolume_Impl (uint32 filesys_id) return OS_SUCCESS; -} /* end OS_FileSysStartVolume_Impl */ - - -/*-------------------------------------------------------------------------------------- - Name: OS_mount +} /* end OS_FileSysFormatVolume_Impl */ - Purpose: mounts a drive. - - Returns: OS_FS_SUCCESS if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysMountVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysMountVolume_Impl (uint32 filesys_id) { OS_filesys_internal_record_t *local = &OS_filesys_table[filesys_id]; @@ -258,16 +262,17 @@ int32 OS_FileSysMountVolume_Impl (uint32 filesys_id) return status; -}/* end OS_mount */ - -/*-------------------------------------------------------------------------------------- - Name: OS_FileSysUnmountVolume_Impl - - Purpose: unmounts a drive. - - Returns: OS_FS_SUCCESS if success ----------------------------------------------------------------------------------------*/ - +} /* end OS_FileSysMountVolume_Impl */ + + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysUnmountVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysUnmountVolume_Impl (uint32 filesys_id) { OS_filesys_internal_record_t *local = &OS_filesys_table[filesys_id]; @@ -298,15 +303,17 @@ int32 OS_FileSysUnmountVolume_Impl (uint32 filesys_id) return status; -}/* end OS_umount */ - -/*-------------------------------------------------------------------------------------- - Name: OS_FileSysStatVolume_Impl - - Purpose: Returns stats about a volume - - Returns: OS_FS_SUCCESS or OS_FS_ERROR if the OS call failed ----------------------------------------------------------------------------------------*/ +} /* end OS_FileSysUnmountVolume_Impl */ + + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysStatVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysStatVolume_Impl (uint32 filesys_id, OS_statvfs_t *result) { OS_filesys_internal_record_t *local = &OS_filesys_table[filesys_id]; @@ -328,17 +335,18 @@ int32 OS_FileSysStatVolume_Impl (uint32 filesys_id, OS_statvfs_t *result) return return_code; -}/* end OS_FileSysStatVolume_Impl */ - - -/*-------------------------------------------------------------------------------------- - Name: OS_FileSysCheckVolume_Impl - - Purpose: Checks the drives for inconsisenties and either repairs it or not +} /* end OS_FileSysStatVolume_Impl */ - Returns: OS_FS_SUCCESS if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_FileSysCheckVolume_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_FileSysCheckVolume_Impl (uint32 filesys_id, bool repair) { OS_filesys_internal_record_t *local = &OS_filesys_table[filesys_id]; @@ -375,7 +383,7 @@ int32 OS_FileSysCheckVolume_Impl (uint32 filesys_id, bool repair) return OS_FS_SUCCESS; -}/* end OS_FileSysCheckVolume_Impl */ +} /* end OS_FileSysCheckVolume_Impl */ diff --git a/src/os/vxworks/osloader.c b/src/os/vxworks/osloader.c index 1256778ee..b95d7a7f1 100644 --- a/src/os/vxworks/osloader.c +++ b/src/os/vxworks/osloader.c @@ -81,26 +81,30 @@ extern SYMTAB_ID sysSymTbl; /**************************************************************************************** INITIALIZATION FUNCTION ***************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_VxWorks_ModuleAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_VxWorks_ModuleAPI_Impl_Init(void) { memset(&OS_impl_module_global, 0, sizeof(OS_impl_module_global)); return(OS_SUCCESS); -} - - -/*-------------------------------------------------------------------------------------- - Name: OS_SymbolLookup - - Purpose: Find the Address of a Symbol - - Parameters: - - Returns: OS_ERROR if the symbol could not be found - OS_SUCCESS if the symbol is found - OS_INVALID_POINTER if the pointer passed in is invalid - - The address of the symbol will be stored in the pointer that is passed in. ----------------------------------------------------------------------------------------*/ +} /* end OS_VxWorks_ModuleAPI_Impl_Init */ + + + +/*---------------------------------------------------------------- + * + * Function: OS_SymbolLookup_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SymbolLookup_Impl( cpuaddr *SymbolAddress, const char *SymbolName ) { STATUS vxStatus; @@ -149,26 +153,28 @@ int32 OS_SymbolLookup_Impl( cpuaddr *SymbolAddress, const char *SymbolName ) return(OS_SUCCESS); -}/* end OS_SymbolLookup */ - - -/*-------------------------------------------------------------------------------------- - Name: OS_SymTableIterator ( local function, not part of the public API ) - - Purpose: Function called by vxWorks to iterate the vxworks symbol table - - Parameters: - name - The symbol name - val - The symbol address value - type - The vxWorks symbol type ( not used ) - max_size - The maximum size of the file that is written to. - group - The vxWorks symbol group ( not used ) - - Returns: true to tell vxWorks to continue to iterate the symbol table - false to tell vxWorks to stop iterating the symbol table - - The address of the symbol will be stored in the pointer that is passed in. ----------------------------------------------------------------------------------------*/ +} /* end OS_SymbolLookup_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_SymTableIterator_Impl + * + * Purpose: Local helper routine, not part of OSAL API. + * Function called by vxWorks to iterate the vxworks symbol table + * + * Parameters: + * name - The symbol name + * val - The symbol address value + * type - The vxWorks symbol type ( not used ) + * max_size - The maximum size of the file that is written to. + * group - The vxWorks symbol group ( not used ) + * + * Returns: true to tell vxWorks to continue to iterate the symbol table + * false to tell vxWorks to stop iterating the symbol table + * + * The address of the symbol will be stored in the pointer that is passed in. + * + *-----------------------------------------------------------------*/ static BOOL OS_SymTableIterator_Impl ( char *name, SYM_VALUE val, SYM_TYPE type, _Vx_usr_arg_t arg, SYM_GROUP group ) { SymbolRecord_t symRecord; @@ -231,20 +237,17 @@ static BOOL OS_SymTableIterator_Impl ( char *name, SYM_VALUE val, SYM_TYPE typ ** It's OK to continue */ return(true); -} - -/*-------------------------------------------------------------------------------------- - Name: OS_SymbolTableDump - - Purpose: Dumps the system symbol table to a file - - Parameters: - - Returns: OS_ERROR if the symbol table could not be read or dumped - OS_INVALID_POINTER if the filename is NULL - OS_FS_ERR_PATH_INVALID if the filename/path is invalid - OS_SUCCESS if the symbol is found ----------------------------------------------------------------------------------------*/ +} /* end OS_SymTableIterator_Impl */ + + +/*---------------------------------------------------------------- + * + * Function: OS_SymbolTableDump_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_SymbolTableDump_Impl ( const char *local_filename, uint32 SizeLimit ) { SymbolDumpState_t *state; @@ -279,26 +282,21 @@ int32 OS_SymbolTableDump_Impl ( const char *local_filename, uint32 SizeLimit ) return(state->StatusCode); -}/* end OS_SymbolTableDump */ +} /* end OS_SymbolTableDump_Impl */ /**************************************************************************************** Module Loader API ****************************************************************************************/ -/*-------------------------------------------------------------------------------------- - Name: OS_ModuleLoad - - Purpose: Loads an object file into the running operating system - - Parameters: - - Returns: 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 - OS_SUCCESS if the module is loaded successfuly - ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_ModuleLoad_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ModuleLoad_Impl ( uint32 local_id, char *translated_path ) { int32 return_code; @@ -344,18 +342,17 @@ int32 OS_ModuleLoad_Impl ( uint32 local_id, char *translated_path ) return(return_code); -}/* end OS_ModuleLoad */ - -/*-------------------------------------------------------------------------------------- - Name: OS_ModuleUnload - - Purpose: Unloads the module file from the running operating system - - Parameters: - - Returns: OS_ERROR if the module is invalid or cannot be unloaded - OS_SUCCESS if the module was unloaded successfuly ----------------------------------------------------------------------------------------*/ +} /* end OS_ModuleLoad_Impl */ + + +/*---------------------------------------------------------------- + * + * Function: OS_ModuleUnload_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ModuleUnload_Impl ( uint32 local_id ) { STATUS vxStatus; @@ -372,19 +369,17 @@ int32 OS_ModuleUnload_Impl ( uint32 local_id ) return(OS_SUCCESS); -}/* end OS_ModuleUnload */ - -/*-------------------------------------------------------------------------------------- - Name: OS_ModuleInfo - - Purpose: Returns information about the loadable module - - Parameters: - - Returns: OS_ERR_INVALID_ID if the module id invalid - OS_INVALID_POINTER if the pointer to the ModuleInfo structure is invalid - OS_SUCCESS if the module info was filled out successfuly ----------------------------------------------------------------------------------------*/ +} /* end OS_ModuleUnload_Impl */ + + +/*---------------------------------------------------------------- + * + * Function: OS_ModuleGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_ModuleGetInfo_Impl ( uint32 local_id, OS_module_prop_t *module_prop ) { MODULE_INFO vxModuleInfo; @@ -414,5 +409,5 @@ int32 OS_ModuleGetInfo_Impl ( uint32 local_id, OS_module_prop_t *module_prop ) return(OS_SUCCESS); -}/* end OS_ModuleInfo */ +} /* end OS_ModuleGetInfo_Impl */ diff --git a/src/os/vxworks/osnetwork.c b/src/os/vxworks/osnetwork.c index 4f42dd30e..259d79615 100644 --- a/src/os/vxworks/osnetwork.c +++ b/src/os/vxworks/osnetwork.c @@ -47,14 +47,15 @@ typedef u_short in_port_t; #include "../portable/os-impl-bsd-sockets.c" -/*-------------------------------------------------------------------------------------- - Name: OS_NetworkGetID - - Purpose: Gets the ID of the current Network - - Returns: OS_ERROR if the host id could not be found - a 32 bit host id if success ----------------------------------------------------------------------------------------*/ + +/*---------------------------------------------------------------- + * + * Function: OS_NetworkGetID_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_NetworkGetID_Impl (int32 *IdBuf) { int host_id; @@ -78,7 +79,7 @@ int32 OS_NetworkGetID_Impl (int32 *IdBuf) return status; -}/* end OS_NetworkGetID */ +} /* end OS_NetworkGetID_Impl */ #endif diff --git a/src/os/vxworks/ostimer.c b/src/os/vxworks/ostimer.c index 7ef020ce3..ee4b63ac8 100644 --- a/src/os/vxworks/ostimer.c +++ b/src/os/vxworks/ostimer.c @@ -90,16 +90,41 @@ static uint32 OS_ClockAccuracyNsec; INTERNAL FUNCTIONS ****************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_TimeBaseLock_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_TimeBaseLock_Impl(uint32 local_id) { semTake(OS_impl_timebase_table[local_id].handler_mutex, WAIT_FOREVER); -} - +} /* end OS_TimeBaseLock_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_TimeBaseUnlock_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ void OS_TimeBaseUnlock_Impl(uint32 local_id) { semGive(OS_impl_timebase_table[local_id].handler_mutex); -} +} /* end OS_TimeBaseUnlock_Impl */ + +/*---------------------------------------------------------------- + * + * Function: OS_Impl_UsecToTimespec + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ static void OS_Impl_UsecToTimespec(uint32 usecs, struct timespec *time_spec) { if ( usecs < 1000000 ) @@ -112,8 +137,17 @@ static void OS_Impl_UsecToTimespec(uint32 usecs, struct timespec *time_spec) time_spec->tv_sec = usecs / 1000000; time_spec->tv_nsec = (usecs % 1000000) * 1000; } -} +} /* end OS_Impl_UsecToTimespec */ + +/*---------------------------------------------------------------- + * + * Function: OS_VxWorks_SigWait + * + * Purpose: Local helper routine, not part of OSAL API. + * Blocks the calling task until the timer tick arrives + * + *-----------------------------------------------------------------*/ static uint32 OS_VxWorks_SigWait(uint32 local_id) { OS_impl_timebase_internal_record_t *local; @@ -161,8 +195,16 @@ static uint32 OS_VxWorks_SigWait(uint32 local_id) } return interval_time; -} +} /* end OS_VxWorks_SigWait */ + +/*---------------------------------------------------------------- + * + * Function: OS_VxWorks_RegisterTimer + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ static void OS_VxWorks_RegisterTimer(uint32 local_id) { OS_impl_timebase_internal_record_t *local; @@ -198,11 +240,19 @@ static void OS_VxWorks_RegisterTimer(uint32 local_id) { local->timer_state = OS_TimerRegState_SUCCESS; } -} +} /* end OS_VxWorks_RegisterTimer */ /**************************************************************************************** Entry point for helper thread ****************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_VxWorks_TimeBaseTask + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ static int OS_VxWorks_TimeBaseTask(int arg) { uint32 local_id; @@ -214,7 +264,7 @@ static int OS_VxWorks_TimeBaseTask(int arg) } return 0; -} +} /* end OS_VxWorks_TimeBaseTask */ @@ -222,6 +272,14 @@ static int OS_VxWorks_TimeBaseTask(int arg) /**************************************************************************************** INITIALIZATION FUNCTION ****************************************************************************************/ + +/*---------------------------------------------------------------- + * + * Function: OS_VxWorks_TimeBaseAPI_Impl_Init + * + * Purpose: Local helper routine, not part of OSAL API. + * + *-----------------------------------------------------------------*/ int32 OS_VxWorks_TimeBaseAPI_Impl_Init ( void ) { int clockRate; @@ -257,21 +315,21 @@ int32 OS_VxWorks_TimeBaseAPI_Impl_Init ( void ) OS_SharedGlobalVars.MicroSecPerTick = (OS_ClockAccuracyNsec + 500) / 1000; return(OS_SUCCESS); -} +} /* end OS_VxWorks_TimeBaseAPI_Impl_Init */ /**************************************************************************************** Time Base API ****************************************************************************************/ -/****************************************************************************** -** Function: OS_TimeBaseCreate -** -** Purpose: Create a new OSAL Time base -** -** Arguments: -** -** Return: -*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TimeBaseCreate_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TimeBaseCreate_Impl(uint32 timer_id) { /* @@ -443,19 +501,17 @@ int32 OS_TimeBaseCreate_Impl(uint32 timer_id) return return_code; -} +} /* end OS_TimeBaseCreate_Impl */ -/****************************************************************************** -** Function: OS_TimeBaseSet -** -** Purpose: -** -** Arguments: -** (none) -** -** Return: -** (none) -*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TimeBaseSet_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TimeBaseSet_Impl(uint32 timer_id, int32 start_time, int32 interval_time) { OS_impl_timebase_internal_record_t *local; @@ -495,20 +551,18 @@ int32 OS_TimeBaseSet_Impl(uint32 timer_id, int32 start_time, int32 interval_time } return return_code; -} +} /* end OS_TimeBaseSet_Impl */ -/****************************************************************************** -** Function: OS_TimerDelete -** -** Purpose: -** -** Arguments: -** (none) -** -** Return: -** (none) -*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TimeBaseDelete_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TimeBaseDelete_Impl(uint32 timer_id) { OS_impl_timebase_internal_record_t *local; @@ -533,23 +587,22 @@ int32 OS_TimeBaseDelete_Impl(uint32 timer_id) local->handler_task = 0; return return_code; -} +} /* end OS_TimeBaseDelete_Impl */ -/*************************************************************************************** -** Name: OS_TimerGetInfo -** -** Purpose: This function will pass back a pointer to structure that contains -** all of the relevant info( name and creator) about the specified timer. -** -** Returns: OS_ERR_INVALID_ID if the id passed in is not a valid timer -** OS_INVALID_POINTER if the timer_prop pointer is null -** OS_SUCCESS if success -*/ + +/*---------------------------------------------------------------- + * + * Function: OS_TimeBaseGetInfo_Impl + * + * Purpose: Implemented per internal OSAL API + * See prototype in os-impl.h for argument/return detail + * + *-----------------------------------------------------------------*/ int32 OS_TimeBaseGetInfo_Impl (uint32 timer_id, OS_timebase_prop_t *timer_prop) { return OS_SUCCESS; -} /* end OS_TimerGetInfo */ +} /* end OS_TimeBaseGetInfo_Impl */ /**************************************************************************************** Other Time-Related API Implementation diff --git a/src/unit-test-coverage/shared/src/coveragetest-time.c b/src/unit-test-coverage/shared/src/coveragetest-time.c index 733beb974..e55aaf4ad 100644 --- a/src/unit-test-coverage/shared/src/coveragetest-time.c +++ b/src/unit-test-coverage/shared/src/coveragetest-time.c @@ -156,15 +156,18 @@ void Test_OS_TimerSet(void) * Test Case For: * int32 OS_TimerSet(uint32 timer_id, uint32 start_time, uint32 interval_time) */ - int32 expected = OS_SUCCESS; + int32 expected = OS_ERROR; int32 actual = OS_TimerSet(1, 0, 0); + UtAssert_True(actual == expected, "OS_TimerSet() (%ld) == OS_ERROR", (long)actual); + expected = OS_SUCCESS; + actual = OS_TimerSet(1, 0, 1); UtAssert_True(actual == expected, "OS_TimerSet() (%ld) == OS_SUCCESS", (long)actual); OS_timecb_table[2].timebase_ref = 0; OS_timecb_table[2].flags = TIMECB_FLAG_DEDICATED_TIMEBASE; OS_global_timebase_table[0].active_id = 2; - actual = OS_TimerSet(2, 0, 0); + actual = OS_TimerSet(2, 0, 1); UtAssert_True(actual == expected, "OS_TimerSet() (%ld) == OS_SUCCESS", (long)actual); memset(OS_timecb_table, 0, sizeof(OS_timecb_table)); @@ -172,10 +175,9 @@ void Test_OS_TimerSet(void) actual = OS_TimerSet(2, 1 << 31, 1 << 31); UtAssert_True(actual == expected, "OS_TimerSet() (%ld) == OS_TIMER_ERR_INVALID_ARGS", (long)actual); - UT_SetForceFail(UT_KEY(OS_TaskGetId_Impl), 1 | (OS_OBJECT_TYPE_OS_TIMEBASE << OS_OBJECT_TYPE_SHIFT)); expected = OS_ERR_INCORRECT_OBJ_STATE; - actual = OS_TimerSet(2, 0, 0); + actual = OS_TimerSet(2, 0, 1); UtAssert_True(actual == expected, "OS_TimerSet() (%ld) == OS_ERR_INCORRECT_OBJ_STATE", (long)actual); UT_ClearForceFail(UT_KEY(OS_TaskGetId_Impl)); } diff --git a/src/unit-test-coverage/ut-stubs/src/osapi-base-impl-stubs.c b/src/unit-test-coverage/ut-stubs/src/osapi-base-impl-stubs.c index c7e0274a1..78a681061 100644 --- a/src/unit-test-coverage/ut-stubs/src/osapi-base-impl-stubs.c +++ b/src/unit-test-coverage/ut-stubs/src/osapi-base-impl-stubs.c @@ -105,7 +105,6 @@ UT_DEFAULT_STUB(OS_MutSemCreate_Impl,(uint32 sem_id, uint32 options)) UT_DEFAULT_STUB(OS_MutSemGive_Impl,(uint32 sem_id)) UT_DEFAULT_STUB(OS_MutSemTake_Impl,(uint32 sem_id)) UT_DEFAULT_STUB(OS_MutSemDelete_Impl,(uint32 sem_id)) -UT_DEFAULT_STUB(OS_MutSemGetIdByName_Impl,(uint32 *sem_id, const char *sem_name)) UT_DEFAULT_STUB(OS_MutSemGetInfo_Impl,(uint32 sem_id, OS_mut_sem_prop_t *mut_prop)) /* diff --git a/src/unit-tests/oscore-test/ut_oscore_test.c b/src/unit-tests/oscore-test/ut_oscore_test.c index 68b239568..6961a7930 100644 --- a/src/unit-tests/oscore-test/ut_oscore_test.c +++ b/src/unit-tests/oscore-test/ut_oscore_test.c @@ -29,9 +29,9 @@ extern UT_OsLogInfo_t g_logInfo; **--------------------------------------------------------------------------------*/ int32 g_skipTestCase = -1; -char* g_skipTestCaseResult = " "; +const char* g_skipTestCaseResult = " "; -char* g_task_names[UT_OS_TASK_LIST_LEN]; +const char* g_task_names[UT_OS_TASK_LIST_LEN]; char g_long_task_name[OS_MAX_API_NAME+5]; /*--------------------------------------------------------------------------------* @@ -49,6 +49,7 @@ void UT_os_setup_install_delete_handler_test(void); void UT_os_init_task_exit_test(void); void UT_os_init_task_delay_test(void); void UT_os_init_task_set_priority_test(void); +void UT_os_init_task_register_test(void); void UT_os_init_task_get_id_test(void); void UT_os_init_task_get_id_by_name_test(void); void UT_os_init_task_get_info_test(void); diff --git a/src/unit-tests/osfile-test/ut_osfile_dirio_test.c b/src/unit-tests/osfile-test/ut_osfile_dirio_test.c index 2274bcd4d..ff723a992 100644 --- a/src/unit-tests/osfile-test/ut_osfile_dirio_test.c +++ b/src/unit-tests/osfile-test/ut_osfile_dirio_test.c @@ -40,7 +40,7 @@ char g_dirName[UT_OS_SM_TEXT_LEN]; char g_fileName[UT_OS_SM_TEXT_LEN]; char g_subdirNames[UT_OS_FILE_MAX_DIRS][UT_OS_SM_TEXT_LEN]; -char* g_tgtSubdirs[UT_OS_FILE_MAX_DIRS] = {"subdir1", "subdir2"}; +const char* g_tgtSubdirs[UT_OS_FILE_MAX_DIRS] = {"subdir1", "subdir2"}; char g_dirItems[UT_OS_FILE_MAX_DIRS][UT_OS_SM_TEXT_LEN]; @@ -520,7 +520,6 @@ void UT_os_readdir_test() { int32 idx=0; uint32 dirh; - os_dirent_t* dirEntry=NULL; UT_OsApiInfo_t apiInfo; const char* testDesc=NULL; diff --git a/src/unit-tests/osfile-test/ut_osfile_fileio_test.c b/src/unit-tests/osfile-test/ut_osfile_fileio_test.c index 2ac6d87ff..4e4bca577 100644 --- a/src/unit-tests/osfile-test/ut_osfile_fileio_test.c +++ b/src/unit-tests/osfile-test/ut_osfile_fileio_test.c @@ -2091,7 +2091,7 @@ void UT_os_outputtofile_test() { int32 idx=0; UT_OsApiInfo_t apiInfo; - char* cmd=NULL; + const char* cmd=NULL; const char* testDesc=NULL; UT_OS_CLEAR_API_INFO_MACRO(apiInfo, idx) @@ -2236,7 +2236,7 @@ void UT_os_getfdinfo_test() UT_OsApiInfo_t apiInfo; OS_file_prop_t fdProps; const char* testDesc=NULL; - char* fileName="GetInfo_Nom.txt"; + const char* fileName="GetInfo_Nom.txt"; UT_OS_CLEAR_API_INFO_MACRO(apiInfo, idx) diff --git a/src/unit-tests/osfile-test/ut_osfile_test.c b/src/unit-tests/osfile-test/ut_osfile_test.c index 9d5f5baef..2e4c9278a 100644 --- a/src/unit-tests/osfile-test/ut_osfile_test.c +++ b/src/unit-tests/osfile-test/ut_osfile_test.c @@ -31,14 +31,14 @@ extern UT_OsLogInfo_t g_logInfo; char* g_fsAddrPtr = NULL; int32 g_skipTestCase = -1; -char* g_skipTestCaseResult = " "; +const char* g_skipTestCaseResult = " "; char g_longPathName[OS_MAX_PATH_LEN+5]; char g_longFileName[OS_MAX_PATH_LEN]; char g_invalidPath[OS_MAX_PATH_LEN]; -char* g_devName = "/ramdev3"; -char* g_mntName = "/drive3"; +const char* g_devName = "/ramdev3"; +const char* g_mntName = "/drive3"; /*--------------------------------------------------------------------------------* ** External function prototypes diff --git a/src/unit-tests/osfilesys-test/ut_osfilesys_test.c b/src/unit-tests/osfilesys-test/ut_osfilesys_test.c index f3e916083..e95e8336a 100644 --- a/src/unit-tests/osfilesys-test/ut_osfilesys_test.c +++ b/src/unit-tests/osfilesys-test/ut_osfilesys_test.c @@ -37,7 +37,7 @@ int32 g_blkSize = UT_OS_FS_BLOCK_SIZE; int32 g_blkCnt = UT_OS_FS_MAX_BLOCKS; int32 g_skipTestCase = -1; -char* g_skipTestCaseResult = " "; +const char* g_skipTestCaseResult = " "; char g_fsLongName[OS_MAX_PATH_LEN+5]; char g_physDriveName[OS_MAX_PATH_LEN]; diff --git a/src/unit-tests/ostimer-test/ut_ostimer_test.c b/src/unit-tests/ostimer-test/ut_ostimer_test.c index 145386ad4..709f56c9b 100644 --- a/src/unit-tests/ostimer-test/ut_ostimer_test.c +++ b/src/unit-tests/ostimer-test/ut_ostimer_test.c @@ -29,9 +29,9 @@ extern UT_OsLogInfo_t g_logInfo; **--------------------------------------------------------------------------------*/ int32 g_skipTestCase = -1; -char* g_skipTestCaseResult = " "; +const char* g_skipTestCaseResult = " "; -char* g_timerNames[UT_OS_TIMER_LIST_LEN]; +const char* g_timerNames[UT_OS_TIMER_LIST_LEN]; char g_longTimerName[OS_MAX_API_NAME+5]; uint32 g_cbLoopCntMax = 5;