COrnell Miniature ATmel Operating System (COMATOS)

Application Programmer's Interface

General Words of Wisdom

Several OS calls have been implemented for initialization, message passing, debugging, and task management. They are all layed out as macros which call various subroutines. As a result, they are called with the following format:

*Name of OS Call* [Argument 1], [Argument 2], .....

Also note that while all of these calls preserve the registers, the way this is done requires that r16, r17, r18, and Z not be used as destination registers in these calls.

Index of OS Calls
OS Initialization, Task Management, Scheduling

OSInit
OSStart
OSCreateTask
OSReturn
OSSetTimeout
OSSetMessMask
OSSetEntryPt
OSPCBZ

Message Passing

OSSendMess
OSGetMess
ISRSendMess
OSGetMessageSrc
OSGetAck
OSSendAck
OSSetOwnAck
OSSetState
OSGetState

Debugging and UART

OSHextoAscY
OSUARTWait
OSRegDump

OS Initialization, Task Management, General Application

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

OSMaxTimeout (2 byte constant): Number of milliseconds allotted to a task before it is determined to have crashed
Debug (constant): One of the two predefined constants OSDebug or OSNoDebug. If OSDebug is specified, the UART is initialized to 9600 baud. If OSNoDebug is specified, the UART is not initialized.

Example:
OSInit 0x0cff, OSDebug
Initializes the OS with the UART and a timeout interval of 3 seconds

Starts the scheduler, beginning normal operation

Arguments: None

Sets up the PCB for a new task and increments OSNumTasks

Entry Point (2 byte address): The program memory address at which execution of the task begins (may also be a label, see example)
Timeout (1 byte constant): 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 (1 byte constant): 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.

Example:
OSCreateTask TestTaskLabel, 20, 0b00000101
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.

Returns control from a task to the scheduler

Return Code (constant): A value to be returned to the scheduler. A non-zero value will cause the system to halt. See scheduler documentation for details.

Example:
OSReturn 0
Returns execution to the scheduler and indicates that all is well.

Changes the periodicity properties of the currently running task

Rs (register): 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)
ldi r19, 25
OSSetTimeout r19
Sets task 2 to be run every 25 milliseconds

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!

Mask (constant): 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 0b00000110
Cause task 3 to wait for messages from tasks 1 and 2 before running again.

Sets the address at which the current task will resume execution for subsequent runs of the task

entryPt (2 byte constant): the address at which execution will resume

Example:
(Task is created with the entry point at the label TaskStart)
TaskStart:
...
OSSetEntryPt TaskResume
OSReturn 0
TaskResume:
...
The next time the task is scheduled, it will start running at TaskResume, not TaskStart.

Used INTERNALLY by many OS calls. Places the address of the currently running task's PCB into the Z register

Arguments: None

Message Passing

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

Rs (Source Register): Register containing the message
Target (constant): Task number of the recipient of the message

Example:
(Within task 3)
ldi r20, 0xf3
OSSendMess r20, 1
Sends the message 0xf3 to task 1.

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.

Rd (destination register): Register in which to place the message
Sender (constant): Number of the task which sent the message

Example:
(Within task 1)
OSGetMess r14, 3
Places the message sent by task 3 into r14.

Called by an ISR to send a message to a task

Rs (source register): Register containing the message
Target (constant): Number of the task being sent the message
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.

Example:
(Within an ISR designated as task 6)
ldi r25, 0x34
ISRSendMess r25, 3, 6
Sends the message 0x34 to task 3.

OSGetMessageSrc

Loads the current task's message source byte into a register and clears it in memory.

Rd (destination register): Register in which to place the message source

Example:
OSGetMessageSrc r14
Places the current task's message source byte into r14, then clears the byte in memory

Returns the PCBAck byte of the currently running process.

Rd (destination register): Register in which to place the ack byte

Example:
(Within task 1)
OSGetAck r24
Places task 1's ack byte in r24.

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.

Target (constant): 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

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

Rs (source register): Register containing the value to place in the PCBAck byte

Example:
(Within task 1)
ldi r23, 0x01
OSSetOwnAck r23
Places the value of 0x01 into task 1's PCBAck byte

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

Rs (source register): Register containing the value to place in the PCBState byte

Example:
(Within task 1)
ldi r23, 0x53
OSSetState r23
Places the value of 0x53 into task 1's PCBState byte

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

Rd (source register): Register into which to place the PCBState byte

Example:
(Within task 1)
OSGetState r26
Places task 1's PCBState value into r26

Debugging and UART

Converts a specified byte into an ascii string representing its hex value and stores that string at the location pointed to by the Y register.
NOTE: Y ends up pointing to the byte beyond the end of the string

Rs (source register): Register containing the value to convert

Example:
ldi r26, 0x3f
ldi YL, low(USRBase)
ldi YH, high(USRBase)
OSHextoAscY r26
Places the characters '3' and 'f' at USRBase and USRBase+1 respectively

Begins transmission of a specified number of characters and returns when transmission is complete.
The number of characters is specified in OSUARTCharCnt and the second character of string is pointed to by Z. The first is passed to this call as an argument.

Rs (source register): Contains the first character to be sent

Example:
ldi ZL, low(USRBase+1)
ldi ZH, high(USRBase+1)
ldi r26, 4
sts OSBase+OSUARTCharCnt, r26
ldi r25, 'a'
OSUARTWait r25
Sends 4 characters starting with 'a' to the UART

Sends the values of all the registers to the UART
NOTE: Requires that DinkyBug be running on the PC

Arguments: None