COrnell Miniature ATmel Operating System (COMATOS)

Application Programmer's Interface

C Version


General Words of Wisdom

Several OS calls have been implemented for initialization, message passing, debugging, and task management. There is nothing special about these calls; they are standard C functions. Each function is listed with the action it performs. In order to access them, you must include the comatos8515.c file at the beginning of your source code as follows:

#include <90s8515.h>
#include "comatos8515.c"



Index of OS Calls
OS Initialization, Task Management, Scheduling Message Passing
UART OS Initialization, Task Management, General Application

OSInit

Initializes the OS Memory, system clock, and possibly the UART.

Prototype:
void OSInit(unsigned maxTimeout, unsigned char debug)
Arguments:
  • OSMaxTimeout: Number of milliseconds allotted to a task before it is determined to have crashed
  • Debug: 0 or 1. If 1 is specified, the UART is initialized to 9600 baud. If 0 is specified, the UART is not initialized.
Example:
OSInit(0x0cff, 1)
Initializes the OS with the UART and a timeout interval of 3 seconds


OSStart

Starts the scheduler, beginning normal operation

Prototype:
void OSStart(void)
Arguments: None


OSCreateTask

Sets up the PCB for a new task and increments OSNumTasks

Prototype:
void OSCreateTask(int (*entry_pt_a)(void),unsigned char timeout, unsigned char messageMask, unsigned char state)
Arguments:
  • Entry Point: A pointer to the function which serves as this task. To pass a function to this call, simply use the function's name.
  • Timeout: If periodic scheduling is desired, this value specifies the interval at which the task is scheduled (in milliseconds). If periodic scheduling is not desired, this value should be specified as 0.
  • MessageMask: Specifies the tasks upon which this new one will wait. Once messages have been received from every specified task, this process can be run. For details, see the scheduler documentation. To indicate that a task is being waited for, set the bit corresponding to that task's number. For example, a mask of 0x03 (0b00000011) means that this task will wait for messages from tasks 0 and 1.
  • State: Initial value for the task's PCB state value.
Example:
OSCreateTask(TestTaskName, 20, 0x05, 0x01);
Creates the PCB for a new task whose code is located at the label "TestTaskLabel". This task will run every 20 milliseconds or when a message is received from tasks 0 and 2. It has an initial state of 0x01.


OSSetTimeout

Changes the periodicity properties of the currently running task

Prototype:
void OSSetTimeout(unsigned char timeout);
Arguments:
  • timeout: The interval at which this task is to be run (in milliseconds). A value of 0 indicates that this task will not run periodically.
Example:
(Taking place within task 2's code)
OSSetTimeout(25);
Sets task 2 to be run every 25 milliseconds


OSSetMessMask

Specifies which messages the currently running task will be waiting for before it is eligible to run again.
Note that this does not cause the task to exit!

Prototype:
void OSSetMessMask(unsigned char mask)
Arguments:
  • Mask: Specifies the tasks being waited on. To wait for a task, set the bit in the mask corresponding to that task's number. For more information, see the scheduler documentation.
Example:
(Within task 3's code)
OSSetMessMask(0x06);
Cause task 3 to wait for messages from tasks 1 and 2 before running again.


Message Passing

OSSendMess

Sends a message to the specified task. Sets the bit in the target task's PCBMessSrc corresponding to the sender's task number.

Prototype:
void OSSendMess(unsigned char recipTask, unsigned char message)
Arguments:
  • recipTask: The number of the task for which the message is intended
  • message: A one byte value sent as the message to the specified task
Example:
(Within task 3)
OSSendMess(1, 0xf3);
Sends the message 0xf3 to task 1.


OSGetMess

Retrieves message for the currently running task that was sent using OSSendMess
NOTE: The bit in the current task's PCBMessageSrc corresponding to the sender's task number is cleared when this function is called. Returns the message as an unsigned char.

Prototype:
unsigned char OSGetMess(unsigned char senderTask)
Arguments:
  • senderTask: Number of the task which sent the message
Example:
(Within task 1)
unsigned char x;
x=OSGetMess(3)
Places the message sent by task 3 into x.


ISRSendMess

Called by an ISR to send a message to a task

Prototype:
void ISRSendMess(unsigned char recipTask, unsigned sendTask, unsigned char message)
Arguments:
  • recipTask: The number of the task for which the message is intended task
  • Sender (constant): Identifies the ISR with a task number. This task number must not conflict with an actual task. For more information, see the note on ISR message passing.
  • message: A one byte value sent as the message to the specified
Example:
(Within an ISR designated as task 6)
ISRSendMess(3,6,0x34);
Sends the message 0x34 to task 3.


OSGetMessSrc

Returns thecurrent task's message source byte and clears it in memory.

Prototype:
unsigned char OSGetMessSrc(void)
Arguments: none
Example:
unsigned char x;
x=OSGetMessageSrc()
Places the current task's message source byte into x, then clears the byte in memory


OSGetAck

Returns the PCBAck byte of the currently running process.

Prototype:
unsigned char OSGetAck(void)
Arguments: none
Example:
(Within task 1)
unsigned char x;
x=OSGetAck();
Places task 1's ack byte in x.


OSSendAck

Sends an acknowledgement of a message to the specified task.
Sets the bit corresponding to the currently running task in the recipient's PCBAck byte.

Prototype:
void OSSendAck(unsigned char task);
Arguments:
  • task: Number of the task to which to send the acknowlegement
Example:
(Within task 1)
OSSendAck(3)
Sets bit 1 of task 3's PCBAck byte


OSSetOwnAck

Places the specified value into the currently running task's PCBAck byte.

Prototype:
void OSSetOwnAck(unsigned char val);
Arguments:
  • val: The value to place in the PCBAck byte
Example:
(Within task 1)
OSSetOwnAck(0x01);
Places the value of 0x01 into task 1's PCBAck byte


OSSetState

Place the specified value into the current task's PCBState byte.

Prototype:
void OSSetState(unsigned char val)
Arguments:
  • val: The value to place in the PCBState byte
Example:
(Within task 1)
OSSetState(0x53);
Places the value of 0x53 into task 1's PCBState byte


OSGetState

Reads the current task's PCBState byte into the specified register

Prototype:
unsigned char OSGetState(void)
Arguments: none
Example:
(Within task 1)
unsigned char x;
x=OSGetState();
Places task 1's PCBState value into x


UART


OSInitUART

Sets the UART baud rate, activates the receive interrupt, and initializes the pointers to the UART ring buffer. For details, see the C UART features page.

Prototype:
void OSInitUART(unsigned char baudrate)
Arguments:
  • baudrate: The value to place in the UBRR register, as specified in the Atmel documentation.
Example:
(Within the initialization code before OSStart)
OSInitUART(25);
Initializes the UART with a baudrate of 9600 bps.


OSUARTReceiveByte

Returns one character received on the UART and removes it from the ring buffer. Note that if no character is available, it will wait for one to arrive. For details, see the C UART features page.

Prototype:
unsigned char OSUARTReceiveByte(void)
Arguments: none
Example:
unsigned char c;
c=OSUARTReceiveByte();


OSUARTReceiveBytes

Reads the specified number of characters from the UART. Returns the number of characters read. If the desired number of characters are not available, simply transfers as many as are in the buffer. For details, see the C UART features page.

Prototype:
unsigned int OSUARTReceiveBytes(char *data, unsigned int n)
Arguments:
  • data: Pointer to the memory location into which you desire the data to be transferred.
  • n: The number of bytes to transfer
Example:
char buf[10];
c=OSUARTReceiveBytes(&buf[0],5);
Reads up to five characters into the buf[] array.


OSUARTTransmitByte

Places the specified character in the UART ring buffer for transmission. If space is unavailable within the buffer, waits for it to become available. The actual transmission is interrupt based and not blocking. For details, see the C UART features page.

Prototype:
void OSUARTTransmitByte(unsigned char data)
Arguments:
  • data: Character to send
Example:
OSUARTTransmitByte('B');
Sends the letter B.


OSUARTTransmitBytes

Places the specified characters in the UART ring buffer for transmission. If space is unavailable within the buffer, waits for it to become available. The actual transmission is interrupt based and not blocking. For details, see the C UART features page.

Prototype:
void OSUARTTransmitBytes(unsigned char *data, unsigned int n)
Arguments:
  • data: Pointer to the characters to send
  • n: Number of characters to send
Example:
char buf[]={"Hello",0x00}; OSUARTTransmitBytes(&buf[0],6);
Sends the word Hello with a null character at the end.