uCOS Task Functions

OSTaskCreate

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

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

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

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

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.

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

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

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

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

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

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

OSTaskNameGet

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

OSTaskQuery

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.