RTOS Overview - SC12 @CHIP-RTOS V1.10

RTOS Overview

Task Control Services

RTX_TASK_CREATE          Create and start a task
RTX_TASK_CREATE_WITHOUT_RUN        Create a task
RTX_END_EXEC             End execution of a task by itself
RTX_TASK_KILL            Kill a task
RTX_RESTART_TASK         Trigger start of task execution
RTX_TASK_DELETE          Remove a task from the system
RTX_GET_TASKID           Get ID of the current task
RTX_CHANGE_PRIO          Change the priority of a task
RTX_SLEEP_TIME           Sleep for a specified time
RTX_SLEEP_REQ            Sleep until a wake request
RTX_WAKEUP_TASK          Wake a task which is sleeping
RTX_SUSPEND_TASK         Suspend a task
RTX_RESUME_TASK          Resume a task
RTX_ACCESS_FILESYSTEM    Enable file access for the calling task
RTX_GET_TASK_STATE       Get state of a task (task monitoring)
RTX_GET_TASK_STATE_EXT      Get state of a task (without task monitoring)
RTX_GET_TASK_LIST        Get list of tasks in system
RTX_START_TASK_MONITOR   Start task monitoring
RTX_STOP_TASK_MONITOR    Stop task monitoring

Semaphore Services

Semaphores are used to guarantee a task mutually exclusive access to a critical resource.   Semaphores synchronize asynchronous occurring activities. They are an essential part of a multitasking system.   A good description of multitasking systems and semaphores is available in the book "Operating systems" from Andrew Tanenbaum.

The @CHIP-RTOS API provides two types of semaphores:



• A counting semaphore is a semaphore with an associated counter, which can be incremented (signal) and decremented (wait).   The resource controlled by the semaphore is free (available) when the counter is greater than 0.
  
  
• A resource semaphore is a counting semaphore with a maximum of count of one.   It can be used to provide mutually exclusive access to a single resource.   A resource semaphore is also called a binary semaphore.   It differs from a counting semaphore in one significant feature: The resource ownership is tied to a specific task.   No other task except the task owning the resource is allowed to signal the associated semaphore to release the resource.

The counting and resource semaphores provide automatic timeout.   Tasks can specify the maximum time for waiting on a semaphore.   The tasks wait in FIFO order for a resource.   A semaphore is created with RTX_CREATE_SEM service call.   The @CHIP-RTOS needs a unique four byte semaphore name and on success returns a new semaphore ID (or handle) to the caller.   This handle is needed for the other semaphore services.

Using a counting semaphore:

A counting semaphore is created by specifying an initial count greater or equal to zero in the call to RTX_CREATE_SEM.   If a semaphore is initialized with a value n, it can be used to control access to n resources, e.g. a counting semaphore with the initial value three assures that no more than three tasks can own a resource at any one time.   Access to a resource controlled by a counting semaphore is acquired with a call to RTX_WAIT_SEM or RTX_GET_SEM.   If the resource is available the @CHIP-RTOS gives it to the task immediately.   When the task is finished using the resource, it signals its release by calling RTX_SIGNAL_SEM.

Using a resource semaphore:

A resource semaphore is created by specifying an initial count of -1 in the call of RTX_CREATE_SEM.   The @CHIP-RTOS creates a resource semaphore and automatically gives it an initial value of one indicating that the resource is free.   A resource is reserved by calling RTX_RESERVE_RES with the semaphore ID returned by RTX_CREATE_SEM.   The resource is released with a call of RTX_RELEASE_SEM.  

Semaphore Services:

RTX_CREATE_SEM          Create a semaphore
RTX_DELETE_SEM          Delete a semaphore
RTX_FREE_RES            Free a resource semaphore
RTX_GET_SEM             Get use of a counting semaphore(no wait)
RTX_RELEASE_SEM         Release a resource semaphore
RTX_RESERVE_RES         Reserve a resource semaphore
RTX_SIGNAL_SEM          Signal a counting semaphore
RTX_WAIT_SEM            Wait on a counting semaphore (optional timeout)

Time / Date Services

The following Time/Date services are available.

RTX_GET_TIMEDATE       Get system time and date
RTX_SET_TIMEDATE       Set system time and date
RTX_GET_TICKS          Get tick count of system clock

Related Topics

TimeDate_Structure type definition

Timer Procedures

The @CHIP-RTOS API provides four calls for the usage of timer procedures:


RTX_INSTALL_TIMER       Install a timer procedure
RTX_REMOVE_TIMER        Remove a timer procedure from the system
RTX_START_TIMER         Start periodic execution of a installed timer procedure
RTX_STOP_TIMER          Stop periodic execution of a timer procedure


The @CHIP-RTOS implements timer procedures using kernel objects, of which there are 60 total.   The sum of semaphores + event groups + timer procedures is limited to 60, since all three of these require use of a kernel object.



The kernel can execute periodic user timer procedures at a specified time interval.   Your timer procedure must be as short as practical without any waiting or endless loops.   Avoid the usage of large C-library functions such as printf().   However, any of the following kernel services are reasonable to call from within a timer procedure:


• RTX_REMOVE_TIMER        Service 0x31
  
• RTX_START_TIMER            Service 0x32
  
• RTX_STOP_TIMER            Service 0x33
  
• RTX_WAKEUP_TASK        Service 0x06
  
• RTX_SIGNAL_SEM            Service 0x1A
  
• RTX_SIGNAL_EVENTS    Service 0x42
  
• RTX_SEND_MESSAGE    Service 0x52
  
• RTX_SUSPEND_TASK        Service 0x0E
  
• RTX_RESUME_TASK        Service 0x0F
  

Event Manager

The internal @CHIP-RTOS Event Manager provides a convenient mechanism for coordinating tasks waiting for events with tasks and/or timer procedures which can signal the events.   The Event Manager allows more than one task to simultaneously wait for a particular event.   Tasks can also wait for a particular combination of events or for any one in a set of events.

The Event Manager provides a set of event flags which can be associated with specific events in your system.   These event flags are provided in groups with 16 event flags per group.   The number of event groups which can be created is limited by the 60 kernel objects available.   One kernel object is expended to create a semaphore, event group or timer procedure.

The Event Manager is useful when two or more tasks will wait for the same event, e.g. waiting for the start of a motor.   An event flag is defined to represent the state of the motor (off or on).   When tasks must wait for the motor, they do so by calling the Event Manager requesting a wait until the motor control event flag indicates that the motor is on.   When the motor control task or timer procedure detects that the motor is on, it signals the event with a call to the Event Manager.   The Event Manger wakes up all tasks which are waiting for the motor to be on.   For further explanations read the function description in the API call specifications.  

Event Services:

RTX_CREATE_EVENTGROUP      Create an event group
RTX_DELETE_EVENTGROUP      Delete an event group
RTX_SIGNAL_EVENTS          Signal one or more events in a group
RTX_WAIT_EVENTS            Wait for all/any of a set of events in a group
RTX_GET_EVENTGROUP_STATE   Read current state of events in a group
RTX_GET_EVENT_FLAGS        Get saved event flags
RTX_FIND_EVENTGROUP        Find the group ID of an group with a specific name

Message Exchange Manager

The internal @CHIP-RTOS Message Exchange Manager provides a mechanism for interprocess communication and synchronization.   In particular, it offers an instant solution to a common producer/consumer problem:


One or more processes (producers) having to asynchronously deliver requests for service to one or more servers (consumers) whose identity is unknown to the producer.


An often cited example of using message exchange is a print request queue.   Assume that there are two different server tasks (consumers), each of which is connected to a different printer.   There are some other tasks (producers) which want to asynchronously use one of the two servers for printing and they don't care which of the two printers is used.   The solution is to synchronize those requests: The producer tasks send their requests (messages) to the Message Exchange Manager.   The two server tasks waiting for messages take a message (if any) from the message queue and execute the requested print job.

The internal Message Exchange Manager uses a message exchange to deliver messages.   A message exchange consists of four mailboxes into which messages can be deposited.   The mailboxes are ordered according to priority (0-3), where mailbox 0 has the highest priority.  Maximum depth of a mailbox is four.

Messages are delivered to the mailboxes of the message exchange in message envelopes.   The system's maximum number of available messages envelopes is 64.   The maximum number of message exchanges is ten.   The maximum message length is 12 bytes.   (Note: Larger messages can be implemented with a pointer and a length parameter in the message.)   Any task or timer procedure can send a message to a Message Exchange.   The sender indicates the priority of its message (0-3), thereby identifying the mailbox into which it will be delivered.

Any task or timer procedure can request a message from a Message Exchange, but only tasks are allowed to wait for the arrival of a message, if none is available.   A task can specify the priority at which it is willing to wait and the maximum time.  

Message Exchange Services:

RTX_CREATE_MSG        Create a message exchange
RTX_DELETE_MSG        Delete a message exchange
RTX_SEND_MSG          Send a message to a message exchange
RTX_GET_MSG           Get a message, if any (no wait)
RTX_WAIT_MSG          Wait for message to arrive (optional timeout)
RTX_FIND_MSG          Find a message exchange, specified by name