===================
uCOS Task Functions
===================

OSTaskCreate
============

.. code-block:: c

    UBYTE OSTaskCreate(void (*task)(void *pd),
                       void *pdata, 
                       OS_STK *pstk, 
                       INT8U prio);

* Parameters

  * task - function pointer to task to run.
  * pdata - optional pointer to data for the task.
  * pstk - pointer to stack space for task.
  * prio - the task's priority level.

* Returns

  * status, OS_NO_ERR == OK

* Creates a task so it can be managed by UCOS-II.
* Priorities must be unique.
* Calls OSTaskStkInit() to initial the task stack.
* Calls OS_TCBInit() which takes a TCB from the TCB 
  free list and initializes it with the task's data.
* Increments OSTaskCtr, the count of the number of tasks created.
* If OSRunning is true, it calls the scheduler.

Task Parameter Function Pointer
-------------------------------

.. code-block:: c

    void (*task)(void *pd);

* This parameter in the API prototype indicates that you are passing-

  * A pointer to a function (\*task)
  * The function has one parameter (void \*pd)
  * And does not return anything (void).
  
* The void * indicates a pointer to a void.
 
  * This pointer can be cast by the user to the actual type of the data.
  
* In the example above, task may actually take a structure as its parameter.

  * Since the API does not want to restrict what is passed into the task function, it defines the interface generically as pointer to a void.
  
* The code in the task would cast the void pointer into the appropriate structure, such as:

  * pData = (struct mystruct \*)pd;
  * ptr - abbreviation for pointer.
  * return - status, OS_NO_ERR == OK.
  
* This indicates the return value from the API.
* In this case the API returns a status code. If the status code is the define


OSTaskCreateExt
===============
.. code-block:: c
    
    INT8U OSTaskCreateExt(void(*task)(void *p_arg), 
                          void *p_arg, OS_STK *ptos,
    		              INT8U prio, 
    		              INT16U id, 
    		              OS_STK *pbos, 
    		              INT32U stk_size, 
    		              void *pext,
    		              INT16U opt);

* Same first four parameters as OSTaskCreate()
* Extra parameters:

  * Id - set id for the task. Not currently used by this version.
  * \*pbos - Pointer to the bottom of the stack.
  * stk_size - size of the stack
  * \*pext - pointer to user defined block of data.
  * opt - option flags, see uCOS-II.h for full list.
  
    * OS_TASK_OPT_STK_CHK - check stack.
    * OS_TASK_OPT_STK_CLR - clear stack area.
    * OS_TASK_OPT_SAVE_FP - save floating point context.


OSTaskDel
=========

.. code-block:: c

    INT8U OSTaskDel(INT8U prio);

* Parameters

  * prio - Priority of task to delete or OS_PRIO_SELF

* Returns

  * Status
  * OS_NO_ERR == OK

 
* Removes the task from all lists.
* Does not actually delete any memory
* Task will not be scheduled again.
* A task can delete itself by using OS_PRIO_SELF.
* Set delay to zero.
* The task's TCB is move to the TCB free list.
* Calls the scheduler
* If the task is holding any resources such as memory
  or semaphores they will be lost. Caller is responsible
  for releasing those resources.

OSTaskDelReq
============

.. code-block:: c

    INT8U OSTaskDelReq(INT8U prio);

* Parameters

  * prio - priority of task to delete

* Returns

  * status
  * if 'prio' is OS_PRIO_SELF: 
  
    * returns OS_TASK_DEL_REQ if a task requested to delete itself. 
    * returns OS_NO_ERR if no task requested to delete SELF
    
  * if 'prio' is other than OS_PRIO_SELF: 
  
    * request that the task be deleted

* Helps delete a task when the task needs to release resources.
* The task that is making the request should spin until the 
  delete is completed.
* The task that is being deleted has to call OSTaskDelReq() 
  to check if it should delete itself.
* This is really just a request. The task being deleted need 
  to have the check and honor the request.

.. code-block:: c

  void requestor() {
    while(1) {
        if (deleteTask == TRUE) {
            while(OSTaskDelReq(prio) != OS_TASK_NOT_EXIST) {
                OSTimeDly(1);
            }
        }
    }
    
    void task(void *pdata) {
        while(1) {
            if (OSTaskDelReq(OS_PRIO_SELF) == OS_TASK_DEL_REQ) {
                OSTaskDel(OS_PRIO_SELF);
            }
        }
    }



OSTaskChangePrio
================

.. code-block:: c

    INT8U OSTaskChangePrio(INT8U oldprio, INT8U newprio);

* Parameters

  * oldprio - old priority
  * newprio - new priority

* Returns

  * status
  * OS_NO_ERR == OK 

* Task can change its own priority by using OS_PRIO_SELF as the 
  old priority.
* New priority must be available.
* Frees the old priority.
* The priority is changes in all the wait lists the task might be in.
* Calls the scheduler.



OSTaskSuspend
=============

.. code-block:: c

    INT8U OSTaskSuspend(INT8U prio);

* Parameters

  * prio - priority of thread to suspend
  
* Returns 

  * status
  * OS_NO_ERR == OK
  * OS_TASK_SUSPEND_PRIO task to suspend does not exist

* Suspends the task the that priority level.
* Suspends all the task's timeouts until the continue
  when the task resume.
* Task can only resumed with OSTaskResume().
* The OS_STAT_SUSPEND flag is set in its TCB.
* Calls the scheduler only if the caller is suspending itself.


OSTaskResume
============

.. code-block:: c

    INT8U OSTaskResume(INT8U prio);

* Paramters

  * prio - priority of thread to resume.

* Returns

  * status
  * OS_NO_ERR - requested task is resumed   
  * OS_TASK_RESUME_PRIO - task to resume does not exist
  * OS_TASK_NOT_SUSPENDED - task to resume has not been suspended

* Resumes a task suspended with OSTaskSuspend().
* The resumed the task run only if it would be the highest ready task.
* Calls scheduler if the resumed is higher priority then the caller.


OSTaskStkChk
============
.. code-block:: c

    INT8U OSTaskStkChk(INT8U prio, OS_STK_DATA *p_stk_data);

* Used to get a measurement of how much stask a task has used
  when running.
* Run a task for a while, then call OSTaskStkChk().  
* Returns current high water mark.
* Sets OSFree or OSUsed in OS_STK_DATA.
* Task must be created with OSTaskCreateExt().
* Task's stack must be cleared first.
* Stack use is calculated by walking the stack from low to high
  until there is a nonzero value.
* The difference between low and the first used stack location 
  is the used value.
* A Task can call it on itself or on another task.


OSTaskNameSet
=============
.. code-block:: c

    void OSTaskNameSet(INT8U prio, INT8U *pname, INT8U *perr);


OSTaskNameGet
=============
.. code-block:: c

    INT8U OSTaskNameGet(INT8U prio, INT8U *pname, INT8U *perr);


OSTaskQuery
===========
.. code-block:: c

    INT8U OSTaskQuery(INT8U prio, OS_TCB *p_task_data);

* Caller allocates a TCB and passes a pointer to the structure
  in the call.
* It copies all the data in the task's TCB into the passed in TCB.