CSE4352

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
==== Background Information ====
=== μC/OS-II Overview ===
μC/OS-II (read as MicroC/OS-II) is the second generation of μC/OS which is a priority-based, preemptive and real-time multitasking operating system written mainly in the C programming language. It is originally published in a book by Jean J. Labrosse, μC/OS The Real-Time Kernel, which purpose was to describe the internals of a portable operating system with a small footprint. It is now a product which is maintained by Micrium Inc. and licenses are issued per product or royalty free for non-commercial educational uses. Even though the source code of μC/OS is available, it is not by any means considered free or open source software.

μC/OS-II is an extremely detailed and highly readable design study which is particularly useful to the embedded systems student. While documenting the design and implementation of the kernel, the book also walks through the many related development issues such as how to adapt the kernel for a new microprocessor, how to install the kernel, and how to structure the applications that run on the kernel.

=== μC/OS-II Important Features ===
Important features of μC/OS-II are ((Based on a presentation by Enric Pastor http://studies.ac.upc.edu/EPSC/SED/Apuntes/uCOSII.pdf)):
  * Highly portable, scalable and preemptive real-time multitasking kernel that you only build what you need.
  * It can manage a predefined maximum number of tasks.
  * It can be expanded and connected to addons such as μC/GUI and μC/FS which are GUI and File Systems for μC/OS-II
  * It supports all type of processors from 8-bit to 64-bit

μC/OS-II like most modern operating systems has the following components:
  * Task Management (i.e. Create, Delete, Change Priority and Suspend/Resume tasks)
  * Time and Timer Management
  * Fixed Sized Memory Block management.
  * Inter-Task Communication (i.e. Message Mailboxes and Message Queues)
  * Semaphores, Mutual Exclusion Semaphores
  * Many external modules are available as the real-time addons to the core (μC/GUI, μC/FS, μC/CAN, μC/USB, μC/TCP-IP and many more).

μC/OS-II allows one to create new tasks and check the existing status of the tasks stack. Tasks can be deleted or their priority can be changed. Also μC/OS-II provides general information about a specific task and allows one to suspend or resume operation as well on a task.

The current version of μC/OS-II can manage up to 64 tasks. The four highest priority tasks and the four lowest priority tasks are reserved for the OS itself. The lower the value of the priority, the higher the priority of the task. The task priority number also serves as the task identifier μC/OS-II uses rate preemptive monotonic scheduling such that the highest rate of execution is given to the highest priority task which is ready. Tasks are periodic and do not synchronize with one another and 

=== μC/OS-II Frequently Used Functions ===
== OSInit ==
OSInit function is used to initialize the internals of μC/OS-II and MUST be called prior to creating any μC/OS-II object and, prior to calling OSStart().

== OSStart ==
OSStart function is used to start the multitasking process which lets μC/OS-II manages the task that you have created. Before you can call OSStart(), you MUST have called OSInit() and you MUST have created at least one task.

== OSIntEnter ==
OSIntEnter function is used to notify μC/OS-II that you are about to service an interrupt service routine (ISR). This allows μC/OS-II to keep track of interrupt nesting and thus only perform rescheduling at the last nested ISR. You are allowed to nest interrupts up to 255 levels deep.

== OSIntExit ==
OSIntExit function is used to notify μC/OS-II that you have completed servicing an ISR. When the last nested ISR has completed, μC/OS-II will call the scheduler to determine whether a new, high-priority task, is ready to run.

You MUST invoke OSIntEnter() and OSIntExit() in pairs. In other words, for every call to OSIntEnter() at the beginning of the ISR you MUST have a call to OSIntExit() at the end of the ISR.

Please note that rescheduling is prevented when the scheduler is locked (see OSSchedLock)

== OSTaskCreate ==
OSTaskCreate function is used to have μC/OS-II manage the execution of a task. Tasks can either be created prior to the start of multitasking or by a running task. A task cannot be created by an ISR.

Signature:
<code>INT8U OSTaskCreate (void (*task)(void *p_arg), void *p_arg, OS_STK *ptos, INT8U prio)</code>

Arguments:
  * Task argument is a pointer to the task's code
  * P_arg argument is a pointer to an optional data area which can be used to pass parameters to the task when the task first executes. Where the task is concerned it thinks it was invoked and passed the argument 'p_arg' as follows:
<code>void Task (void *p_arg)
{
   for (;;)
   {
      Task code;
   }
}
</code>

  * Ptos argument is a pointer to the task's top of stack. If the configuration constant OS_STK_GROWTH is set to 1, the stack is assumed to grow downward (i.e. from high memory to low memory). 'pstk' will thus point to the highest (valid) memory location of the stack. If OS_STK_GROWTH is set to 0, 'pstk' will point to the lowest memory location of the stack and the stack will grow with increasing memory locations.
  * Prio argument is the task's priority. A unique priority MUST be assigned to each task and the lower the number, the higher the priority.

Returns:
  * OS_ERR_NONE: if the function was successful.
  * OS_PRIO_EXIT: if the task priority already exist (each task MUST have a unique priority).
  * OS_ERR_PRIO_INVALID: if the priority you specify is higher that the maximum allowed (i.e. >= OS_LOWEST_PRIO)
  * OS_ERR_TASK_CREATE_ISR: if you tried to create a task from an ISR.

== OSTaskDel ==
OSTaskDel function allows you to delete a task. The calling task can delete itself by its own priority number. The deleted task is returned to the dormant state and can be re-activated by creating the deleted task again.

Signature:
<code>INT8U OSTaskDel (INT8U prio)</code>
Arguments:
  * prio argument is the priority of the task to delete. Note that you can explicitely delete the current task without knowing its priority level by setting 'prio' to OS_PRIO_SELF.

Returns:
  * OS_ERR_NONE: if the call is successful
  * OS_ERR_TASK_DEL_IDLE: if you attempted to delete μC/OS-II's idle task
  * OS_ERR_PRIO_INVALID: if the priority you specify is higher that the maximum allowed (i.e.>= OS_LOWEST_PRIO) or, you have not specified OS_PRIO_SELF.
  * OS_ERR_TASK_DEL: if the task is assigned to a Mutex PIP.
  * OS_ERR_TASK_NOT_EXIST: if the task you want to delete does not exist.
  * OS_ERR_TASK_DEL_ISR : if you tried to delete a task from an ISR.

Please note:
  * To reduce interrupt latency, OSTaskDel() 'disables' the task:
  * by making it not ready
  * by removing it from any wait lists
  * by preventing OSTimeTick() from making the task ready to run. The task can then be 'unlinked' from the miscellaneous structures in μC/OS-II.
  * The function OS_Dummy() is called after OS_EXIT_CRITICAL() because, on most processors, the next instruction following the enable interrupt instruction is ignored.
  * An ISR cannot delete a task.
  * The lock nesting counter is incremented because, for a brief instant, if the current task is being deleted, the current task would not be able to be rescheduled because it is removed from the ready list. Incrementing the nesting counter prevents another task from being scheduled. This means that an ISR would return to the current task which is being deleted. The rest of the deletion would thus be able to be completed.

== OSTaskDelReq ==
OSTaskDelReq function is used to notify a task to delete itself and to see if a task requested that the current task delete itself. This function is a little tricky to understand. Basically, you have a task that needs to be deleted however, this task has resources that it has allocated (memory buffers, semaphores, mailboxes, queues etc.). The task cannot be deleted otherwise these resources would not be freed. The requesting task calls OSTaskDelReq() to indicate that the task needs to be deleted. Deleting of the task is however, deferred to the task to be deleted. For example, suppose that task #10 needs to be deleted. The requesting task example, task #5, would call OSTaskDelReq(10). When task #10 gets to execute, it calls this function by specifying OS_PRIO_SELF and monitors the returned value. If the return value is OS_ERR_TASK_DEL_REQ, another task requested a task delete. Task #10 would look like this:
<code>
void Task(void *p_arg)
{
   .
   .
   .
   while (1)
   {
      OSTimeDly(1);
      if (OSTaskDelReq(OS_PRIO_SELF) == OS_ERR_TASK_DEL_REQ)
      {
         Release any owned resources;
         De-allocate any dynamic memory;
         OSTaskDel(OS_PRIO_SELF);
      }
   }
}
</code>

Arguments:
  * Prio argument is the priority of the task to request the delete from

Returns :
  * OS_ERR_NONE: if the task exist and the request has been registered
  * OS_ERR_TASK_NOT_EXIST: if the task has been deleted. This allows the caller to know whether the request has been executed.
  * OS_ERR_TASK_DEL: if the task is assigned to a Mutex.
  * OS_ERR_TASK_DEL_IDLE: if you requested to delete μC/OS-II's idle task
  * OS_ERR_PRIO_INVALID: if the priority you specify is higher that the maximum allowed (i.e. >= OS_LOWEST_PRIO) or, you have not specified OS_PRIO_SELF.
  * OS_ERR_TASK_DEL_REQ: if a task (possibly another task) requested that the running task be deleted.

== OSTaskSuspend ==
OSTaskSuspend function is called to suspend a task. The task can be the calling task if the priority passed to OSTaskSuspend() is the priority of the calling task or OS_PRIO_SELF. You should use this function with great care. If you suspend a task that is waiting for an event (i.e. a message, a semaphore, a queue ...) you will prevent this task from running when the event arrives. 

Arguments:
  * Prio arguments is the priority of the task to suspend. If you specify OS_PRIO_SELF, the calling task will suspend itself and rescheduling will occur.

Returns:
  * OS_ERR_NONE: if the requested task is suspended
  * OS_ERR_TASK_SUSPEND_IDLE: if you attempted to suspend the idle task which is not allowed.
  * OS_ERR_PRIO_INVALID: if the priority you specify is higher that the maximum allowed (i.e. >= OS_LOWEST_PRIO) or, you have not specified OS_PRIO_SELF.
  * OS_ERR_TASK_SUSPEND_PRIO: if the task to suspend does not exist
  * OS_ERR_TASK_NOT_EXITS: if the task is assigned to a Mutex PIP

== OSTaskResume ==
OSTaskResume function is called to resume a previously suspended task. This is the only call that will remove an explicit task suspension.

Returns:
  * OS_ERR_NONE: if the requested task is resumed
  * OS_ERR_PRIO_INVALID: if the priority you specify is higher that the maximum allowed (i.e.>= OS_LOWEST_PRIO)
  * OS_ERR_TASK_RESUME_PRIO: if the task to resume does not exist
  * OS_ERR_TASK_NOT_EXIST: if the task is assigned to a Mutex PIP
  * OS_ERR_TASK_NOT_SUSPENDED: if the task to resume has not been suspended

== OSTaskChangePrio ==
OSTaskChangePrio function allows you to change the priority of a task dynamically. Note that the new priority MUST be available.

Returns:
  * OS_ERR_NONE: is the call was successful
  * OS_ERR_PRIO_INVALID: if the priority you specify is higher that the maximum allowed (i.e. >= OS_LOWEST_PRIO)
  * OS_ERR_PRIO_EXIST: if the new priority already exist.
  * OS_ERR_PRIO: there is no task with the specified OLD priority (i.e. the OLD task does not exist.
  * OS_ERR_TASK_NOT_EXIST: if the task is assigned to a Mutex PIP.

== OSSchedLock ==
OSSchedLock function is used to prevent rescheduling to take place. This allows your application to prevent context switches until you are ready to permit context switching. You MUST invoke OSSchedLock() and OSSchedUnlock() in pair. In other words, for every call to OSSchedLock() you MUST have a call to OSSchedUnlock().

== OSSchedUnlock ==
OSSchedUnlock function is used to re-allow rescheduling. You MUST invoke OSSchedLock() and OSSchedUnlock() in pair. In other words, for every call to OSSchedLock() you MUST have a call to OSSchedUnlock().

== OSTimeDly ==
OSTimeDly function is called to delay execution of the currently running task until the specified number of system ticks expires. This, of course, directly equates to delaying the current task for some time to expire. No delay will result If the specified delay is 0. If the specified delay is greater than 0 then, a context switch will result.

Arguments:
  * "ticks" is the time delay that the task will be suspended in number of clock 'ticks'. Note that by specifying 0, the task will not be delayed.

== OSTimeDlyHMSM ==
OSTimeDlyHMSM function is called to delay execution of the currently running task until some time expires. This call allows you to specify the delay time in HOURS, MINUTES, SECONDS and
MILLISECONDS instead of ticks.

== OS_ENTER_CRITICAL ==
OS_ENTER_CRITICAL() is a macro inserts the machine instruction into your code to block all interrupts.

== OS_EXIT_CRITICAL ==
OS_EXIT_CRITICAL() is a macro inserts the machine instruction to enable interrupts.

== OSSemCreate ==
OSSemCreate function creates a semaphore.

Arguments:
  * "cnt" is the initial value for the semaphore. If the value is 0, no resource is available (or no event has occurred). You initialize the semaphore to a non-zero value to specify how many resources are available (e.g. if you have 10 resources, you would initialize the semaphore to 10). 

Returns:
  * (void *)0 if no event control blocks were available. Otherwise return is a pointer to the event control block (OS_EVENT) associated with the created semaphore.

== OSSemPost ==
OSSemPost function signals a semaphore Argument pevent is a pointer to the event control block associated with the desired semaphore.

Returns:
  * OS_ERR_NONE: The call was successful and the semaphore was signaled.
  * OS_ERR_SEM_OVF: If the semaphore count exceeded its limit. In other words, you have signalled the semaphore more often than you waited on it with either OSSemAccept() or OSSemPend().
  * OS_ERR_EVENT_TYPE: If you didn't pass a pointer to a semaphore.
  * OS_ERR_PEVENT_NULL: If 'pevent' is a NULL pointer.

== OSSemPendAbort ==
OSSemPendAbort function aborts & readies any tasks currently waiting on a semaphore. This function should be used to fault-abort the wait on the semaphore, rather than to normally signal the semaphore via OSSemPost().