UTS6710/aps/include/gsl/gl_task.h

#ifndef __GL_TASK_H__
#define __GL_TASK_H__

#include "gl_types.h"

/******************************************************************************/
/*!
 * @brief	To create a task.
 *
 * @param	szName String identifier for the task. Limit to 16 characters. Used wherever supported.
 * @param	pEntryPoint Function address from which the task starts executing.
 * @param	pTaskArg parameter passed to entry function.
 * @param	dPriority Task priority ranging from 0-31, with 0 being the lowest priority (see restrictions).
 * @param	dStackSize Task stack size in bytes.
 * @param	fTaskRun If DTV_TRUE, the task is scheduled for execution immediately. If DTV_FALSE, the task is suspended upon creation, and GL_TaskActivateResume() has to be explicitly invoked to start the task.
 * @param	pTaskId Task object identifier returned by the API (on success)
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR/DSR. It supports only 32 priority levels.
 *******************************************************************************/
GL_Status_t GL_TaskCreate(char *szName, void (*pEntryPoint)(void *pArg),
	void *pTaskArg, GL_UINT32 dPriority, GL_UINT32 dStackSize, GL_BOOL fTaskRun, GL_Task_t *pTaskId);

/******************************************************************************/
/*!
 * @brief	To self-delete a task.
 *
 * @return	@a GL_SUCCESS if task is successfully deleted.
 * @return	@a GL_FAILURE if the task was not created by GSL.
 *
 * @note	Cannot be used from ISR/DSR. It supports only 32 priority levels. Use @a GL_TaskPoolSelfDelete is the task is created by taskpool.
 *******************************************************************************/
GL_Status_t GL_TaskSelfDelete(void);

/******************************************************************************/
/*!
 * @brief	To activate a task that was immediately suspended upon creation (by setting fTaskRun=DTV_FALSE).
 * @param	taskId Task object identifier
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	None
 *******************************************************************************/
GL_Status_t GL_TaskActivate(GL_Task_t taskId);

/******************************************************************************/
/*!
 * @brief	To suspend a task, not remember task status in Task_t
 * @param	taskId Task object identifier
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	None
 *******************************************************************************/
GL_Status_t GL_TaskSuspend(GL_Task_t taskId);

/******************************************************************************/
/*!
 * @brief	To put a task to sleep for a finite period of time.
 *
 * @param	sdTimeout timeout period to suspend task. Measured in milliseconds. Set to any value between 1-2147483647 for finite wait.
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_TaskSleep(GL_UINT32 sdTimeout);

/******************************************************************************/
/*!
 * @brief	Used to yield processor time to other tasks of same priority, i.e., if any other task of same priority is ready to run, the other tasks will run before the current task gets a chance to run again. If no other task of same priority is ready, the current task will continue running. Please note that this API only affects scheduling among tasks of same priority. By default, a higher priority task will automatically preempt a lower priority task.
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_TaskYield(void);

/******************************************************************************/
/*!
 * @brief	To change a task's priority.
 *
 * @param	taskId Task object identifier
 * @param	dNewPriority Changes the tasks priority to specified value.
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_TaskSetPriority(GL_Task_t taskId, GL_UINT32 dNewPriority);

/******************************************************************************/
/*!
 * @brief	To query a tasks priority.
 *
 * @param	taskId Task object identifier
 * @param	pdPriority Returns with the task priority
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_TaskGetPriority(GL_Task_t taskId, GL_UINT32 *pdPriority);

/******************************************************************************/
/*!
 * @brief	Used to lock the scheduler and prevents the current task from being preempted by any other task, irrespective of priority. However, interrupts are enabled and an ISR can preempt the task. This API is used in conjunction with GL_TaskGlobalUnlock() to protect critical code in a task.
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_TaskGlobalLock(void);

/******************************************************************************/
/*!
 * @brief	Used to unlock the scheduler and enable normal task preemption. This API is used in conjuction with GL_TaskGlobalLock() to protect critical code in a task. This call does not affect enabling/disabling of interrupts in any way.
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_TaskGlobalUnlock(void);

/******************************************************************************/
/*!
 * @brief	To get the current task's gsl handle.
 *
 * @return	the current task's gsl handle
 *
 * @note	Cannot be used from ISR/DSR. Use @a GL_TaskPoolCurTask is the task is created by taskpool.
 *
 *******************************************************************************/
GL_Task_t GL_CurrentTask(void);

/******************************************************************************/
/*!
 * @brief	To get the current task's handle of OS.
 *
 * @return	the current task's handle of OS
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_UINT32 GL_CurrentTaskDebug(void);

/******************************************************************************/
/*!
 * @brief	To destroy a GL_Task_t, for some specical usage. GL_TaskSelfDelete would be safer.
 *
 * @param	taskId Task object identifier
 *
 * @return	@a GL_SUCCESS on success
 * @return	@a GL_FAILURE on failure
 *
 * @note	Cannot be used from ISR/DSR.
 *******************************************************************************/
GL_Status_t GL_TaskDestroyOne(GL_Task_t taskId);

char *GL_TaskName(GL_Task_t taskId);

#endif // __GL_TASK_H__