RTOS API - SC12 @CHIP-RTOS V1.10

IPC@CHIP Documentation Index RTOS API News

Here is the documentation for the RTOS API. This interface provides access to the RTOS of the IPC@CHIP.
For a general introduction about multitasking with the @CHIP-RTOS see Multitasking introduction. Please note that we cannot explain in detail all principles of a multitasking system in this document.
A good book for understanding the architecture of Real-Time-Kernels is "MicroC/OS" from Jean.J.Labrosse.

Topics

API Functions

The RTOS API uses interrupt 0xAD with a service number in the high order byte of the AX register (AH). The implemented RTOS services are listed below.

For some useful comments see also Programming notes.

Interrupt_0xAD_function_0x00:_RTX_SLEEP_TIME, Sleep for a specified time

Interrupt_0xAD_function_0x01:_RTX_TASK_CREATE, Create and start a task

Interrupt_0xAD_function_0x11:_RTX_TASK_CREATE_WITHOUT_RUN, Create a task

Interrupt_0xAD_function_0x02:_RTX_TASK_KILL, Stop and kill specified task.

Interrupt_0xAD_function_0x03:_RTX_TASK_DELETE, Remove a task from the system

Interrupt_0xAD_function_0x04:_RTX_GET_TASKID, Get ID of the current task

Interrupt_0xAD_function_0x05:_RTX_SLEEP_REQ, Sleep until wake request

Interrupt_0xAD_function_0x06:_RTX_WAKEUP_TASK, Wake up a task

Interrupt_0xAD_function_0x07:_RTX_END_EXEC, End execution of task

Interrupt_0xAD_function_0x08:_RTX_CHANGE_PRIO, Change priority of a task

Interrupt_0xAD_function_0x14:_RTX_CREATE_SEM, Create a semaphore

Interrupt_0xAD_function_0x15:_RTX_DELETE_SEM, Delete a semaphore

Interrupt_0xAD_function_0x16:_RTX_FREE_RES, Free a resource semaphore

Interrupt_0xAD_function_0x17:_RTX_GET_SEM, Get counting semaphore (no wait)

Interrupt_0xAD_function_0x18:_RTX_RELEASE_SEM, Release a resource semaphore

Interrupt_0xAD_function_0x19:_RTX_RESERVE_RES, Get use of a resource semaphore

Interrupt_0xAD_function_0x1A:_RTX_SIGNAL_SEM, Signal a counting semaphore

Interrupt_0xAD_function_0x1B:_RTX_WAIT_SEM, Wait on a counting semaphore

Interrupt_0xAD_function_0x1C:_RTX_FIND_SEM, Find semaphore by name

Interrupt_0xAD_function_0x28:_RTX_GET_TIMEDATE, Get system time and date

Interrupt_0xAD_function_0x29:_RTX_SET_TIMEDATE, Set system time and date

Interrupt_0xAD_function_0x2A:_RTX_GET_TICKS, Get tick count of system clock

Interrupt_0xAD_function_0x09:_RTX_ACCESS_FILESYSTEM, Enable file access in task

Interrupt_0xAD_function_0x0A:_RTX_GET_TASK_STATE, Get state of a task

Interrupt_0xAD_function_0x0B:_RTX_GET_TASK_LIST, Get list of tasks

Interrupt_0xAD_function_0x0C:_RTX_START_TASK_MONITOR, Enable task monitoring

Interrupt_0xAD_function_0x0D:_RTX_STOP_TASK_MONITOR, Disable task monitoring

Interrupt_0xAD_function_0x0E:_RTX_SUSPEND_TASK, Suspend a task

Interrupt_0xAD_function_0x0F:_RTX_RESUME_TASK, Resume a task

Interrupt_0xAD_function_0x10:_RTX_RESTART_TASK, Start task

Interrupt_0xAD_function_0x12:_RTX_GET_TASK_STATE_EXT, Get task state

Interrupt_0xAD_function_0x20:_RTX_DISABLE_TASK_SCHEDULING, Task Lock

Interrupt_0xAD_function_0x21:_RTX_ENABLE_TASK_SCHEDULING, Release Task Lock

Interrupt_0xAD_function_0x30:_RTX_INSTALL_TIMER, Install a timer procedure

Interrupt_0xAD_function_0x31:_RTX_REMOVE_TIMER, Remove a timer procedure

Interrupt_0xAD_function_0x32:_RTX_START_TIMER, Start periodic timer procedure

Interrupt_0xAD_function_0x33:_RTX_STOP_TIMER, Stop execution of a timer procedure

Interrupt_0xAD_function_0x40:_RTX_CREATE_EVENTGROUP, Create an event group

Interrupt_0xAD_function_0x41:_RTX_DELETE_EVENTGROUP, Delete an event group

Interrupt_0xAD_function_0x42:_RTX_SIGNAL_EVENTS, Signal event(s) in a group

Interrupt_0xAD_function_0x43:_RTX_WAIT_EVENTS, Wait for events in a group

Interrupt_0xAD_function_0x44:_RTX_GET_EVENTGROUP_STATE, Read the event states

Interrupt_0xAD_function_0x45:_RTX_GET_EVENT_FLAGS, Get the saved event flags

Interrupt_0xAD_function_0x46:_RTX_FIND_EVENTGROUP, Find an event group

Interrupt_0xAD_function_0x50:_RTX_CREATE_MSG, Create a Message Exchange

Interrupt_0xAD_function_0x51:_RTX_DELETE_MSG, Delete a Message Exchange

Interrupt_0xAD_function_0x52:_RTX_SEND_MSG, Send message

Interrupt_0xAD_function_0x53:_RTX_GET_MSG, Poll Message Exchange

Interrupt_0xAD_function_0x54:_RTX_WAIT_MSG, Wait for a message

Interrupt_0xAD_function_0x55:_RTX_FIND_MSG, Find a Message Exchange

At return from most of the API calls, the DX-Register is used for error checking as follows:

All needed constants and data structures for use with the RTOS API are defined in header file rtxapi.h. For a better understanding of the RTOS API, some example programs written in C are provided. The user should read these example and modify them for your own applications.

Interrupt 0xAD service 0x00: RTX_SLEEP_TIME, Sleep for a specified time

Parameters

AH: 0 (=RTX_SLEEP_TIME)
BX: Sleep time in milliseconds in range 1 to 32767, inclusive. Note this 16 bit value is treated as signed. Any non-positive values are translated within this API to 1 millisecond.

Return Value

DX = 0 success AX: 0
DX != 0 failure AX: contains error code

Comments

The RTX_WAKEUP_TASK API (service 0x06) can wake up a sleeping task before its sleep timer has expired. In this case this API returns with error code -5 in AX.

The system maintains a "Task Wakeup Pending " flag for each task. This flag is set when RTX_WAKEUP_TASK is called for a task which is not currently awaiting wakeup (i.e. when bit 7 in Task State is zero). In the case where "Task Wakeup Pending " flag had been set, this RTX_SLEEP_TIME API clears this flag and returns immediately with error code -5 in AX.

Developer Notes

A sleep call with BX parameter 1 millisecond sleeps for less than or equal to one millisecond. If a user needs a minimum sleep time of 1 millisecond they must call RTX_SLEEP_TIME with value 2 in BX. In general with BX sleep time specified to be N milliseconds, the resulting sleep time will range from N-1 milliseconds up to N milliseconds (inclusive).

Top of list
Index page

Interrupt 0xAD service 0x01: RTX_TASK_CREATE, Create and start a task

Parameters

AH: 0x01 (= RTX_TASK_CREATE)
BX:SI: Pointer to 16 bit storage for the taskID, allocated by the caller
ES:DI: Pointer to a TaskDefBlock type data structure

Return Value

DX =0 success AX: 0, task is running, location [BX:SI] contains the 16 bit taskID
DX!=0 failure AX: contains error code

Comments

The caller must fill in portions of the TaskDefBlock structure prior to making this call.

The new task is immediately placed in the system's task ready queue. Execution begins if the task is higher priority than any other task currently ready (including task which called RTX_TASK_CREATE). The alternate API RTX_TASK_CREATE_WITHOUT_RUN can be used if it is not desired that the task be free to run immediately on creation.

Parameters

AH: 0x11 (= RTX_TASK_CREATE_WITHOUT_RUN)
BX:SI: Pointer to 16 bit storage for the taskID, allocated by the caller
ES:DI: Pointer to a TaskDefBlock type data structure

Return Value

DX =0 success AX: 0, task is running, location [BX:SI] contains the 16 bit taskID
DX!=0 failure AX: contains error code

Comments

The caller must fill in portions of the TaskDefBlock structure prior to making this call.

Unlike the alternative RTX_TASK_CREATE API, this API call does not start the new task. The new task can be started with a RTX_RESTART_TASK call.

Parameters

AH: 0x02 (= RTX_TASK_KILL)
BX: taskID

Return Value

DX =0 success AX: 0, task is terminated
DX!=0 failure AX: contains error code

Comments

You should not kill a task which is waiting for a semaphore, an event in an event group, or a message from a message exchange. Failure to observe this restriction can lead to unpredictable results.

This function does not remove the task from the system. The task can be restarted by calling RTX_RESTART_TASK API function.

Parameters

AH: 0x03 (= RTX_TASK_DELETE)
BX: taskID

Return Value

DX =0 success AX: 0, task is removed
DX!=0 failure AX: contains error code

Comments

You should not delete a task which is waiting for a semaphore, an event in an event group, or a message from a message exchange. Failure to observe this restriction can lead to unpredictable results.

After making this call, the taskID is no longer valid. A task can delete itself.

Parameters

AH: 0x04 (= RTX_GET_TASKID)

Return Value

DX=0 (success always) AX: contains the TaskID

Parameters

AH: 0x05 (= RTX_SLEEP_REQ)

Return Value

DX=0 (always success) AX: 0

Comments

The system maintains a "Task Wakeup Pending " flag for each task. This flag is set when RTX_WAKEUP_TASK is called for a task which is not currently awaiting wakeup (i.e. when bit 7 in Task State is zero). In the case where "Task Wakeup Pending " flag had been set, this RTX_SLEEP_REQ API clears this flag and returns immediately.

Parameters

AH: 0x06 (= RTX_WAKEUP_TASK)
BX: taskID

Return Value

DX =0 success
DX!=0 failure AX: contains error code

Comments

An immediate task switch will occur if the task being wakened is of higher priority than the current task.

If this API is called for a task which is not currently awaiting wakeup, error code -6 is returned. In this case a wakeup is left pending such that when the specified task eventually makes a call to RTX_SLEEP_REQ or RTX_SLEEP_TIME API, it will react (once) to this pending wakeup and return immediately without a sleep period.

Parameters

AH: 0x07 (= RTX_END_EXEC)

Return Value

There is no return from this function

Comments

This call is equivalent to returning to the system from a task's main procedure.

The task can later be restarted with the RTX_RESTART_TASK API.

Parameters

AH: 0x08 (= RTX_CHANGE_PRIO)
BX: taskID
CX: priority, range 3 to 127 inclusive (3 is highest priority)

Return Value

DX =0 success AX: 0 DX!=0 failure AX: contains error code

Comments

An out of range priority value (CX) will be limited to range 3..127 inside this function.

Note:

created

Parameters

AH: 0x14 (= RTX_CREATE_SEM)
BX:SI: Pointer to 16 bit storage allocated by caller where this API will output a semaphoreID
CX: Initial value:
Set to -1 for resource semaphore
Set in range [0 .. 32767] (inclusive) for counting semaphore
ES:DI: Pointer to 4 character unique name tag for the new semaphore, which need not be null terminated but must contain four bytes.

Return Value

DX =0 success AX: 0, Location referenced by [BX:SI] contains the unique semaphoreID
DX!=0 failure AX: contains error code

Comments

A resource semaphore is created by setting CX = -1. A non-negative value in CX creates a counting semaphore.

A resource semaphore is created in the free state, ready for use.

A counting semaphore is initially available the number of times specified in CX. The RTX_SIGNAL_SEM API increments this count and semaphore access via RTX_GET_SEM or RTX_WAIT_SEM decrements the count. A counting semaphore is not available when its count reaches zero.

Parameters

AH: 0x15 (= RTX_DELETE_SEM)
BX: ID of the semaphore acquired by RTX_CREATE_SEM

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code

Comments

You must be certain that no other task, Interrupt Service Routine or Timer procedure is in any way using or about to use this semaphore. Failure to observe this restriction can lead to unpredictable faults.

Parameters

AH: 0x16 (= RTX_FREE_RES)
BX: ID of the resource semaphore acquired from RTX_CREATE_SEM

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code

Comments

Only the task owning the resource semaphore can make this call successfully.  Error code -12 is returned if the calling task does not own the semaphore (or if the semaphore is a counting semaphore type which are not owned by tasks).

This API is useful to unwind in one stroke N calls made to RTX_RESERVE_RES.   Alternatively, the RTX_RELEASE_SEM API could be called N times to release the resource semaphore.

After being freed, the resource will immediately be given to the task (if any) which is waiting at the head of this resource semaphore's wait queue.   An immediate task switch occurs if this waiting task is higher priority than the calling task that just gave up ownership of this semaphore.

Parameters

AH: 0x17 (= RTX_GET_SEM)
BX: ID of the semaphore acquired from RTX_CREATE_SEM

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code, semaphore is in use

Comments

This call returns an error code -51, "semaphore busy", if the semaphore is not available.

This function must not be called for resource type semaphores, as this will foul up the operation of the resource semaphore.

Parameters

AH: 0x18 (= RTX_RELEASE_SEM)
BX: ID of the resource semaphore acquired from RTX_CREATE_SEM

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code

Comments

The resource's use count is decremented by one if the calling task presently owns this resource semaphore (otherwise error code -12, "not owner").   The resource is not freed until the use count reaches zero, at which point the caller no longer "owns" this semaphore.

Once freed, the resource will immediately be given to the task (if any) which is waiting at the head of this resource semaphore's wait queue.   An immediate task switch occurs if this waiting task is higher priority than the calling task that just gave up ownership of this semaphore.

Note:   Attempting to use this function on a counting semaphore will fail with error code -12.

Parameters

AH: 0x19 (= RTX_RESERVE_RES)
BX: ID of the semaphore acquired from RTX_CREATE_SEM
ES:DI: Pointer to signed long buffer containing the timeout in milliseconds
if timeout == 0, the caller waits forever for the resource
if timeout < 0, value is illegal resulting in error code -48

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code, semaphore is in use

Comments

This call waits for a defined time to reserve a semaphore and returns with an error code -27 if the semaphore is still in use by another task after the timeout period expires.

The callers wait in FIFO order for the semaphore.

On success, the calling task then owns the resource semaphore. A task which owns the semaphore is free to call here repeated times, reserving the same semaphore more than once. Each such call increments a "use count" internal to the semaphore. This use count must be restored to zero before any other task can be granted ownership of this resource semaphore.

Parameters

AH: 0x1A (= RTX_SIGNAL_SEM)
BX: ID of the semaphore acquired from RTX_CREATE_SEM

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code

Comments

Use this function to either surrender access to a counting semaphore, or to indicate that some resource guarded by this semaphore has become available.

Upon this signal, the semaphore will be given to the task (if any) which is waiting at the head of this semaphore's wait queue. This can result in an immediate task switch if this waiting task is higher priority than the calling task.

This function must not be called for resource semaphores, as this will cause the resource semaphore to malfunction.

Parameters

AH: 0x1B (= RTX_WAIT_SEM)
BX: ID of the semaphore acquired from RTX_CREATE_SEM
ES:DI: Pointer to signed long buffer containing the timeout in milliseconds
if timeout == 0, the caller waits forever for the resource
if timeout < 0, value is illegal resulting in error code -48

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code

Comments

This call waits for a defined time to acquire a counting semaphore and returns with an error code -27 if the semaphore is still not available after the timeout period expires.

The callers wait in FIFO order for the semaphore.

Parameters

AH: 0x1C (= RTX_FIND_SEM)
ES:DI: Pointer to 4 character name tag (no zero terminator needed)

Return Value

DX =0 success AX: contains the semaphore ID
DX!=0 failure AX: contains error code

Comments

The semaphore ID obtained here is the handle required for the semaphore API functions.
A semaphore created in some other program can be accessed in this manner.

If more than one semaphore was created with the same tag, you will get back the semaphore ID of one with this tag. But which one is not certain.

Parameters

AH: 0x28 (= RTX_GET_TIMEDATE)
BX:SI: Output parameter: Pointer to TimeDate_Structure type allocated by user.

Return Value

DX=0 success AX: 0, Location at [BX:SI] contains system date and time

Parameters

AH: 0x29 (= RTX_SET_TIMEDATE)
BX:SI: Pointer to TimeDate_Structure type filled in by user.

Return Value

DX=0 success AX: 0

Comments

The Day Of Week field (.dow) in TimeDate_Structure need not be set by caller. This API function computes this field based on the other member data.

Caution: Values for time/date supplied by the caller are not checked for validity.

Parameters

AH: 0x2A (= RTX_GET_TICKS)
BX:SI: Output Parameter: Pointer to an unsigned long where the tick count will be stored.

Return Value

Caller's unsigned long at [BX:SI] contains system tick count.

Comments

The system clock runs at 1000 Hz. So each tick represents 1 millisecond.

Parameters

AH: 0x09 (= RTX_ACCESS_FILESYSTEM)

Return Value

DX =0 success AX: 0
DX!=0 failure (Mostly to many processes with file access)

Comments

This API call is only necessary for tasks created within applications with the RTX_TASK_CREATE or RTX_TASK_CREATE_WITHOUT_RUN API. DOS applications' main tasks already have access to the file system, so this call is not necessary for them.

If DX is -3 then file access is enabled, but reserving a data entry for findfirst/findnext failed.

Parameters

AH: 0x0A (= RTX_GET_TASK_STATE)
ES:DI: Pointer to 4 character unique name tag of the task whose state information is desired. This need not be a null terminated, but must be four bytes.
DS:SI: Output parameter: Pointer to Task_StateData type structure allocated by the user to be filled by this API

Return Value

On Success:

Task_StateData

structure

Failure:

Monitoring

Comments

Task monitoring mode must first be enabled in order for this API to work.

The alternative function, RTX_GET_TASK_STATE_EXT, can be used without starting the Task Monitor, but offers less information about the task.

Parameters

AH: 0x0B (= RTX_GET_TASK_LIST)
ES:DI: Output Parameter: Pointer to array of TaskList type structures allocated by user.
CX: Length of the list, number of data structures in user's array at [ES:DI].

Return Value

DX=0
BX = number of tasks listed in [ES:DI] output array.

Comments

For a full report, the caller must allocate sufficient buffer space at [ES:DI] to allow all tasks to be reported including those created by the system. At most, CX tasks will be reported.

Parameters

AH: 0x0C (= RTX_START_TASK_MONITOR)

Return Value

DX=0, AX=0

Comments

This function installs a task timing function in the 0x13 timer interrupt which will poll at 1000 Hz to check which task is currently executing (or most recently if system is idle). Data collected by this timing function provides a coarse indication of which tasks are occupying the CPU.

Note that the Task Monitor places a considerable load on the system.

Parameters

AH: 0x0D (= RTX_STOP_TASK_MONITOR)

Return Value

DX=0, AX=0

Comments

This function installs the system's normal timer 0x13 interrupt handler. This action is performed irrespective of whether or not the alternate 1000 Hz Task Monitor handler had been installed (RTX_START_TASK_MONITOR API).

This API performs a reset of the 1000 Hz Timer #2 count which extends the period of the current one millisecond real-time interrupt period by up to one millisecond.

Parameters

AH: 0x0E (= RTX_SUSPEND_TASK)
BX: taskID (value from RTX_TASK_CREATE call)

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code, invalid taskID

Comments

Note that the @CHIP-RTOS implementation maintains a separate Boolean representing "Suspended" for each task. Consequently, to suspend a task which is already waiting for some other reason (Trigger, Semaphore, Event Group, Message, or Sleep) means that the task will remain inactive after the other wait condition is released (e.g. after the task is granted a semaphore).

Parameters

AH: 0x0F (= RTX_RESUME_TASK)
BX: taskID (value from RTX_TASK_CREATE call)

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code, invalid taskID

Comments

This can result in an immediate task switch if the suspended task is higher priority than the calling task.

Parameters

AH: 0x10 (= RTX_RESTART_TASK)
BX: taskID

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code, invalid taskID

Comments

A task is in the "Trigger Wait" state either before it has been started for the first time after being created by the RTX_TASK_CREATE_WITHOUT_RUN API, or after termination.

A task termination results from either returning to the system from a task's entry procedure or due to API calls RTX_TASK_KILL or RTX_END_EXEC.

Parameters

AH: 0x12 (= RTX_GET_TASK_STATE_EXT)
ES:DI: Pointer to 4 character unique name tag of the task whose state information is desired

Return Value

Success:

field

Failure (task not found)

Comments

The task name is not a null terminated string. It must contain four bytes (not necessarily ASCII).

The task state returned in BX is a bit field coded same as taskState member of the Task_StateData data structure.

Parameters

AH: 0x20 (= RTX_DISABLE_TASK_SCHEDULING)

Comments

After making this call, the task must remain compute bound until it follows up with a call to RTX_ENABLE_TASK_SCHEDULER. The task must not call any API which waits or ends the task.

Note that this is implemented as a spin lock, such that if for some reason the task calls here N times then N calls to RTX_ENABLE_TASK_SCHEDULER are required to unwind the spin lock and re-enable the task switching.

Caution: This call must be followed by a call to RTX_ENABLE_TASK_SCHEDULER as soon as possible to re-enable the task switching. Should the task lock period be excessive, the system watchdog must be triggered by the user until the task switching is re-enabled.

Parameters

AH: 0x21 (= RTX_ENABLE_TASK_SCHEDULING)

Comments

This API reverses the affect of the RTX_DISABLE_TASK_SCHEDULER API.

When task switching is re-enabled, an immediate task switch may result if there is an active task with higher priority than the task making this API call.

Parameters

AH: 0x30 (= RTX_INSTALL_TIMER)
ES:DI: Pointer to a TimerProc_Structure type

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code, no free timer available

Comments

See the TimerProc_Structure type description for instructions on how to call this function.

A timer ID is output to the 16 bit location referenced by timerID member of your TimerProc_Structure.

You must call the RTX_START_TIMER API function to get the kernel to start calling your new timer procedure.

Important:

printf()

Parameters

AH: 0x31 (= RTX_REMOVE_TIMER)
BX: timerID produced by the RTX_INSTALL_TIMER call

Return Value

DX =0 success AX: 0
DX!=0, failure AX contains error code, invalid timerID.

Comments

It is safe to call this API from within the timer procedure being removed.

It is possible to reinstall a timer procedure after removing it from the system.

Parameters

AH: 0x32 (= RTX_START_TIMER)
BX: timerID produced by the RTX_INSTALL_TIMER call

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code, invalid timerID.

Comments

The first execution of this timer procedure will occur within one millisecond of this call, after the subsequent @CHIP-RTOS 1000 Hz real-time interrupt.

The user is free to make this call on a timer which has already been started, the affect being that the phase of the periodic timer callback is shifted to within one millisecond of the call to this API.

Parameters

AH: 0x33 (= RTX_STOP_TIMER)
BX: timerID produced by the RTX_INSTALL_TIMER call

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code, invalid timerID.

Comments

The timer procedure can later be restarted.

Parameters

AH: 0x40 (= RTX_CREATE_EVENTGROUP)
BX: Initial value of the 16 event flags of the group.
ES:DI: Output Parameter: Pointer to 16 bit storage where Event Group ID is output by this API.
DS:SI: Pointer to unique four character tag, which need not be a zero terminated string but must consists of four bytes.

Return Value

DX = 0 success AX: 0 , location at [ES:DI] contains the unique group ID.
DX != 0 failure AX: contains error code, no free event group entry available

Comments

Each event group provides 16 Boolean event flags, encoded in a 16 bit word. Users are free to assign any meaning to these Booleans that suites their application.

Event groups can provide control and communicate between programs. One program creates the event group and the other programs must know the event group's unique 4 character tag. The other programs can then obtain the handle to this event group following its creation using the RTX_FIND_EVENTGROUP API.

Parameters

AH: 0x41 (= RTX_DELETE_EVENTGROUP)
BX: Event group ID acquired by RTX_CREATE_EVENTGROUP call.

Return Value

DX = 0 success AX: 0
DX != 0 failure AX: contains error code, event group still in use or invalid group ID

Comments

You must not delete an event group which is in use by another task or timer procedure, as this can lead to unpredictable results.

Parameters

AH: 0x42 (= RTX_SIGNAL_EVENTS)
BX: Event group ID acquired by RTX_CREATE_EVENTGROUP call.
CX: 16-Bit event group editing mask. The '1' bits here mark event flags to be set or cleared based on the corresponding bit value supplied in DX. Other flags in the event group are unaffected.
DX: New event values for the 16 event flags. Only the bits marked '1' in the CX mask are relevant here.

Return Value

DX = 0 success AX: 0
DX != 0 failure AX: contains error code

Comments

The Event Manager wakes up any tasks that are waiting on these events and satisfied with the resulting collection of event states (in case of AND waiting condition). This can lead to an immediate task switch if any of these released tasks are higher priority than the signaling task.

Parameters

AH: 0x43 (= RTX_WAIT_EVENTS)
BX: Event group ID acquired by RTX_CREATE_EVENTGROUP call.
ES:DI: Pointer to user RTX_Wait_Event type structure filled in by caller.

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code

Comments

The user must fill in the RTX_Wait_Event structure before making this call.

The caller can select whether to await all specified events or a single event.

Parameters

AH: 0x44 (= RTX_GET_EVENTGROUP_STATE)
BX: Event group ID acquired by RTX_CREATE_EVENTGROUP call.
ES:DI: Output Parameter: Pointer to 16 bit location to receive the current state of the event flags

Return Value

DX = 0 success AX: 0, Location at [ES:DI] contains the event states of the specified group
DX != 0 failure AX: contains error code, invalid group ID

Comments

Note that this API accesses the current event group states.

If instead the states recorded at return from the most recent RTX_WAIT_EVENTS call are desired, the alternate RTX_GET_EVENT_FLAGS API can be used.

Parameters

AH: 0x45 (= RTX_GET_EVENT_FLAGS)

Return Value

DX =0 success AX: contains the saved event states

Comments

The returned event flags apply to this task's most recent event wait wake up or timeout.

Parameters

AH: 0x46 (= RTX_FIND_EVENTGROUP)
ES:DI: Pointer to 4 character name tag. This string need not be zero terminated but most be four bytes length.

Return Value

DX = 0 success AX: contains the event group ID
DX != 0 failure AX: contains error code, not found

Comments

This function allows event groups to be accessed by another program which knows the agreed upon name for the group, thereby providing a communication and control mechanism between programs.

Parameters

AH: 0x50 (= RTX_CREATE_MSG)
ES:DI: Pointer to user RTX_Msg type structure

Return Value

DX = 0 success AX: 0, RTX_Msg structure contains the new msgID
DX != 0 failure AX: contains error code

Comments

The user must fill in portions of the RTX_Msg structure prior to calling here.

The Message Exchange Manager returns a 16-Bit unique ID to the caller.

You can provide a unique 4 character tag to identify the Message Exchange, thereby allowing other programs access to it by name.

The maximum number of Message Exchanges supported by the system is ten.

Parameters

AH: 0x51 (= RTX_DELETE_MSG)
BX: Message Exchange ID acquired by RTX_CREATE_MSG call.

Return Value

DX =0 success AX: 0
DX!=0 failure AX: contains error code, Message Exchange still in use or invalid ID

Comments

You must not delete a Message Exchange which is in use by another task or timer procedure, as this may result in unpredictable faults.

Parameters

AH: 0x52 (= RTX_SEND_MSG)
BX: Message Exchange ID acquired by RTX_CREATE_MSG call.
CX: Message priority (mailbox) 0 - 3 where 0 is highest priority
ES:DI: Pointer to a 12 byte message to be sent

Return Value

DX = 0 success AX: 0
DX != 0 failure AX: contains error code

Comments

If one or more tasks are waiting at the exchange for a message, the message will be immediately given to the task waiting at the head of the exchange's wait queue.   This will result in an immediate task switch if the task receiving the message is higher priority than the task that is sending the message.

The format of the 12 byte message being sent is defined by the application program.   These 12 bytes can contain a pointer to further data, if required.   This API copies these 12 bytes into an internal message envelope, so the message at [ES:DI] need not persist beyond the call to this API.   (However, any data referenced by pointers contained in the message would, of course, need to be maintained until the message is received by some task.)

The message mailbox priority in CX is applicable for cases where messages are accumulating on the exchange for which there are no immediate waiting message consumer tasks.   In this case, a message from the highest priority non-empty mailbox FIFO queue will be given to the next caller of either RTX_GET_MSG or RTX_WAIT_MSG.

Parameters

AH: 0x53 (= RTX_GET_MSG)
BX: Message Exchange ID acquired by RTX_CREATE_MSG call.
ES:DI: Output Parameter: Pointer to a 12 byte user buffer for storing the message (if any).

Return Value

DX = 0 success AX: 0, Location at [ES:DI] holds the message
DX != 0 failure AX: contains error code, invalid ID or -28: no message available

Comments

This function always returns immediately. If no message is currently available, DX is non-zero and AX = -28.

On success, a message from the highest priority non-empty FIFO mailbox is copied into the 12 byte store at [ES:DI] and then this delivered message is removed from the mailbox.

Parameters

AH: 0x54
ES:DI: Pointer to user RTX_Wait_Msg type structure

Return Value

DX = 0 success AX: 0
DX != 0 failure AX: contains error code

Comments

The user must fill in the RTX_Wait_Msg structure prior to calling here.

On success, the highest priority message available on the exchange is copied into your message container at location specified by the msg member of the RTX_Wait_Msg structure. Then the message is removed from the Message Exchange.

Each caller to this API can specify their priority for access to messages. To wait in FIFO order, all callers have to wait with the same priority.

Parameters

AH: 0x55 (= RTX_FIND_MSG)
ES:DI: Pointer to 4 character name tag (no zero terminator needed)

Return Value

DX = 0 success AX: contains the Message Exchange ID
DX != 0 failure AX: contains error code, not found

Comments

This API can be used to access a Message Exchange created with an agreed upon name by another program, thereby providing a communication path between programs.

If more than one message exchange was created with the same tag, you will get back the message exchange ID of one with this tag, but which one is not certain.

RTOS API - SC12 @CHIP-RTOS V1.10

Topics

Parameters

Return Value

Comments

Related Topics

Developer Notes

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value

Comments

Related Topics

Parameters

Return Value