@CHIP-RTOS - RTOS API

RTOS API

Topics

RTOS API C-Library
RTOS API Overview
RTOS API Error Codes
RTOS API Developer Notes
RTOS API Examples Available
RTOS API Data Structures
IPC@CHIP® System Tasks

Task control functions

Semaphore services

Time/Date functions

Timer procedures

Event group manager

Message exchange manager

RTX Interrupt 0xAD Services

DX:    0   RTX_ENOERROR ... success
DX:   -1   RTX_ERROR ... error, AX contains error code
DX:   -2   RTX_NOT_SUPPORTED ... service is not supported by the API

Parameters

AH

0 (=RTX_SLEEP_TIME)

BX

Sleep time in milliseconds.   A value of zero is rounded up to 1.

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.

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).

Beck C-Library Usage

RTX_Sleep_Time()

Related Topics

RTOS Task Control Services

RTX_SLEEP_REQ Sleep until wake up call

RTX_WAKEUP_TASK Wake up a task

RTX_SLEEP_FINE Sleep for specified RTI ticks.

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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 TASK_PARAM_DEF type data structure.   (The deprecated TaskDefBlock structure may also be used here.)

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 TASK_PARAM_DEF 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.

Beck C-Library Usage

RTX_Create_Task()

RTX_Param_Task()

Related Topics

IPC@CHIP® System Tasks

RTOS Task Control Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V1.05	V1.00

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 TASK_PARAM_DEF type data structure.   (The deprecated TaskDefBlock structure may also be used here.)

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 TASK_PARAM_DEF 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.

Beck C-Library Usage

RTX_Create_Task_Without_Run()

RTX_Param_Task_Without_Run()

Related Topics

IPC@CHIP® System Tasks

RTOS Task Control Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V1.05	V1.00

Terminate a specified task, but do not remove it from system.

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.

Beck C-Library Usage

RTX_Kill_Task()

Related Topics

RTOS Task Control Services

RTX_TASK_DELETE Remove task from system

RTX_END_EXEC Task terminates itself

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Remove specified task from system.

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.

CAUTION:

Any memory allocated from the system by the task which is being deleted here will be released.

Beck C-Library Usage

RTX_Delete_Task()

Related Topics

RTOS Task Control Services

RTX_TASK_KILL Terminate task execution

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Returns ID of the calling task.

Parameters

AH

0x04 (= RTX_GET_TASKID)

Return Value

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

Beck C-Library Usage

RTX_Get_TaskID()

Related Topics

RTOS Task Control Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

The calling task will be suspended until some other task issues a RTX_WAKEUP_TASK call to awake this calling task.

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.

Beck C-Library Usage

RTX_Sleep_Request()

Related Topics

RTOS Task Control Services

RTX_WAKEUP_TASK Wake up a task

RTX_SLEEP_TIME Timed sleep

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

To wake up a task known to be waiting because of a RTX_SLEEP_REQ or RTX_SLEEP_TIME call.

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.

Beck C-Library Usage

RTX_Wakeup()

Related Topics

RTOS Task Control Services

RTX_SLEEP_REQ Sleep until wake up call

RTX_SLEEP_TIME Timed sleep

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

This call terminates the calling task.

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.

Beck C-Library Usage

RTX_End_Execution()

Related Topics

RTOS Task Control Services

RTX_TASK_KILL Kill specified task

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Parameters

AH

0x08 (= RTX_CHANGE_PRIO)

BX

taskID or zero for current task

CX

Priority, range 2 to 127 inclusive (2 is highest priority).
Or set to PRIORITY_READ_ONLY flag (=0x5ABC) to indicate that only a read out of the existing task priority is desired.

Return Value

DX =0 success

AX: 0,
CX: existing task priority (before any change)

DX!=0 failure AX: contains error code

Comments

The existing task priority is reported in the CX register.   This is what the task priority was before any change made by this call.   This function can be used to read out the existing task priority without modifying the priority by setting the CX register to the special flag setting 0x5ABC.  

A task can read/modify its own priority by setting the taskID in BX register to zero.   The AMXK kernel task's priority cannot be changed.

An out of range priority value (CX) will be limited to range 2..127 inside this function.   (CX = 0x5ABC is an exception for which no priority change is performed.)

Note:

Internally all tasks have a unique priority.  When a task is created or its priority is changed, that task is given a lower internal task priority than any other task in the system with the same user task priority.

Beck C-Library Usage

RTX_Change_TaskPrio()

RTX_Task_Priority()

Related Topics

RTOS Task Control Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V1.05	V1.00

Reserve file access context space for the calling task.

Parameters

AH

0x09 (= RTX_ACCESS_FILESYSTEM)

Return Value

DX =0, AX =0:   Success
DX = -1, AX = -1:   Failure   (Too many tasks with file access)

Comments

This API is deprecated.   (However, it may still have some diagnostic value to determine why file accesses are failing or could be used to acquire the file access context space ahead of time to assure the task's future file accesses will succeed.)

It is no longer necessary that a task use this API to gain access to the file system.   A task is automatically granted file system access when the file system API is used, provided that the system has not ran out of file access context space.

The file system supports registration of up to 15 tasks (35 tasks on SC1x3/SC23) at a time.   Each DOS program's main task is registered with the file system regardless of whether or not that program uses the file system.   A task's reservation on the file system access context space remains in effect until that task is deleted from the system.   The DOS program main tasks are deleted when the program terminates (or terminates and stays resident).

Once a successful call to this API has been made, any further calls perform no operation (at most one context slot is assigned per task).

If this API returns a failure indication, then the number of tasks registered with the file system has reached the limit and this calling task is consequently not being granted access to the file system.

Beck C-Library Usage

RTX_Access_Filesystem()

Related Topics

RTOS Task Control Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V1.05	V1.00

Get state information for a specified task.

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:

DX = 0
AX = taskID
Task_StateData structure at [DS:SI] contains the current task state data

Failure:

DX = -1
IF AX is zero THEN
    "Task Monitoring is not enabled".
ELSE
    "Specified task not found".
ENDIF

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.

Beck C-Library Usage

RTX_Get_Task_State()

Related Topics

Task_StateData structure definition

RTOS Task Control Services

Start Task Monitor API

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Get list of current tasks in the system.

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.

Beck C-Library Usage

RTX_Get_Task_List()

Related Topics

TaskList structure definition

RTOS Task Control Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Installs an alternate 1000 Hz timer interrupt which monitors task execution.

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.

Beck C-Library Usage

RTX_Start_Task_Monitor()

Related Topics

Get Task state

Stop Task Monitor API call

RTOS Task Control Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Remove special 1000 Hz timer interrupt service used by Task Monitor function and restore original handler.

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).

Beck C-Library Usage

RTX_Stop_Task_Monitor()

Related Topics

RTOS Task Control Services

Start Task Monitor API call

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Suspend the execution of a specified task until RTX_RESUME_TASK is called to resume the task.

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).

Beck C-Library Usage

RTX_Suspend_Task()

Related Topics

RTOS Task Control Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Re-enables the execution of a suspended task.

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.

Beck C-Library Usage

RTX_Resume_Task()

Related Topics

RTOS Task Control Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Start execution of a specified task which was in the "Trigger Wait" state.

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.

Beck C-Library Usage

RTX_Restart_Task()

Related Topics

RTOS Task Control Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Get state of specified task without task monitoring mode active.

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:

DX = 0
AX = taskID
BX = task state bit field

Failure (task not found)

DX != 0

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.

Beck C-Library Usage

RTX_Get_Task_State_Ext()

Related Topics

API function RTX_GET_TASK_STATE - Get state of a task

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.01	V1.00	V1.00	V0.90	V1.00

Read out the number of RTX resources available and optionally obtain detailed data about resources in use.

Parameters

AH

0x13 (= RTX_COUNT_RESOURCES)

ES:DI

Two related functions:

1) ES non-zero   Output Parameter:   Pointer to an RTX_COUNTS data structure that will be filled by this API.

2) ES zero:   Input Parameter:   DI contains the RTX object handle for a semaphore, Event Group or Message Exchange for which the queue of tasks awaiting this object will be reported.   (This supports the Beck C-Library RTX_Wait_Queue() function.)

BX:SI

Optional Output parameter:   Pointer to a buffer which will receive objects which can be referenced with the RTX_DETAILS union of structure pointers.   This API will report various details for each RTX object to this buffer.   This parameter can be set to NULL if no detailed RTX object data is desired.

CX

Number of bytes in buffer at [BX:SI].   If either this value or BX is zero, then no RTX_DETAILS reporting is done.

DX

Optional output listing filter.   This bit field selects which type RTX objects are listed in detailed report at [BX:SI].   Set this to zero to report all object types.   When calling with ES set to zero, this parameter is required to be one of the masks RTX_FILT_SEM , RTX_FILT_EVENT_GROUP or RTX_FILT_MSGXCHG to identify the RTX object type whose handle is passed in DI.

Return Value

AX < 0:   Minus the number of bytes required at [BX:SI] to report task queue information for case where ES was zero and either BX was zero (NULL pointer) or CX was not large enough.   This reported size can be used to allocate sufficient memory for a subsequent call.

AX >= 0:   Number of RTX_DETAILS unions output to array at BX:SI.   This object count will be limited to assure that the byte count limit value specified by CX input parameter is not exceeded.   All data has been reported if this value matches the nReport_Cnt vallue reported in the RTX_COUNTS data structure (for ES != 0 case).   When ES was set to 0 to read out task list waiting at a queue, a positive AX return value indicates that all the data has been reported.

Comments

The primary purpose for this API is to allow the user to determine the number of RTX resources that are available.   For this limited purpose, only the RTX_COUNTS data structure is required at [ES:DI] and BX or CX can be set to zero to indicate that no RTX_DETAILS reporting is desired.

When more detailed information about the various RTX objects in use is desired, a buffer of sufficent length must be provided by the caller at [BX:SI].   This buffer will receive a sequence of various size data structures which can be accessed with the assistance of the RTX_DETAILS union of pointers.   The length of your buffer in bytes is indicated by the CX register contents.   This API will not exceed this space.

The report filter parameter in DX allows you to focus the detailed reporting on particular types of RTX objects.   This can simplify your memory management problem by reducing the size of the RTX_DETAILS array at BX:SI required to report all the objects of the type you are interested in.   Bits set to one in this bit field inhibit the reporting of the RTX object type associated with that bit.   The filter bit assignments are as follows:

0x01 - Inhibits semaphore detail reporting
0x02 - Inhibits timer detail reporting
0x04 - Inhibits Event Group detail reporting
0x08 - Inhibits Message Exchange detail reporting
0x10 - Inhibits task detail reporting

When calling with ES = 0 for wait queue information, the filter value in DX should have only the single zero bit, the ones complement of above one bit values, to indicate the type of RTX object.

One possible strategy for allocating the details buffer at [BX:SI] would be to first call this API with BX set to zero only to discover how large a buffer will be required to collect the desired detailed information.   The number of bytes required in the array is reported by the API in the nReport_Bytes member of the RTX_COUNTS data structure.   This reported count is influenced by what ever reporting filter you had specified in the DX register.

Inside this API, the RTX data is collected with the task switching locked.   Interrupts are enabled after inhibiting task switching.   The interrupt mask is restored to the state on entry prior to re-enabling the task switching on return.   Nevertheless, a task switch can occur at the moment task switching is re-enabled here, thereby defeating any interrupt mask set by the caller.

Beck C-Library Usage

RTX_Count_Resources()

RTX_Wait_Queue()

Related Topics

API function RTX_GET_TASK_STATE - Get state of a task

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V0.91	V1.00

Create a resource or counting semaphore.

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.

Beck C-Library Usage

RTX_Create_Sem()

Related Topics

RTOS Semaphore Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Removes specified semaphore from system.

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.

Beck C-Library Usage

RTX_Delete_Sem()

Related Topics

RTOS Semaphore Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

The resource semaphore's use count is set to zero which unconditionally frees the resource.

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.

Beck C-Library Usage

RTX_Free_Sem()

Related Topics

RTX_RESERVE_RES Reserve resource semaphore

RTX_RELEASE_SEM Release resource semaphore

RTOS Semaphore Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Attempt acquisition of a counting semaphore without waiting.

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.

Beck C-Library Usage

RTX_Get_Sem()

Related Topics

RTX_WAIT_SEM Wait for counting semaphore access

RTX_SIGNAL_SEM Signal counting semaphore

RTOS Semaphore Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Down count (unwind) a resource semaphore's "use count".

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.

Beck C-Library Usage

RTX_Release_Sem()

Related Topics

RTX_FREE_RES Free resource semaphore

RTX_RESERVE_RES Reserve resource semaphore

RTOS Semaphore Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Reserves a resource semaphore.

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, the function will return immediately (polling mode). The AX register will be set to error code -27 if the semaphore was not available.

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.

Beck C-Library Usage

RTX_Reserve_Sem()

Related Topics

RTX_FREE_RES Free resource semaphore

RTX_RELEASE_SEM Release resource semaphore

RTX_WAIT_SEM_PRIO Wait in with specific priority

RTOS Semaphore Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Make semaphore access available to one additional task.

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.

Beck C-Library Usage

RTX_Signal_Sem()

Related Topics

RTX_WAIT_SEM Wait for counting semaphore access

RTX_GET_SEM Get counting semaphore without waiting

RTOS Semaphore Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Wait up to a specified time for access to a counting semaphore.

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, the function will return immediately (polling mode). The AX register will be set to error code -27 if the semaphore was not available.

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.

Beck C-Library Usage

RTX_Wait_Sem()

Related Topics

RTX_SIGNAL_SEM Signal counting semaphore

RTX_WAIT_SEM_PRIO Wait with specific priority

RTX_GET_SEM Get counting semaphore without waiting

RTOS Semaphore Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Get Semaphore ID using 4-char name.

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.

Beck C-Library Usage

RTX_Find_Sem()

Related Topics

RTOS Semaphore Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Parameters

AH

0x1D (=RTX_SLEEP_FINE)

DX:BX

32 bit signed sleep time specified as a Real-Time Interrupt (RTI) count.   This count must be positive.

Return Value

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

Comments

Refer to the the RTX_SLEEP_TIME API description for information concerning the sleep.

SC1x Comments

For SC1x targets which have a fixed 1 kHz real-time interrupt rate this API is nearly identical to the RTX_SLEEP_TIME API.   The only significant difference is that this API accepts a 31 bit sleep count allowing longer sleep periods to be specified.

SC1x3/SC2x Comments

This API differs from the RTX_SLEEP_TIME API when the Real-Time Interrupt (RTI) rate is configured for greater than 1000 Hz operation.

Beck C-Library Usage

RTX_Sleep_Fine()

RTX_Sleep_Long()

Related Topics

RTOS Task Control Services

RTX_SLEEP_TIME Sleep for specified milliseconds.

RTX_SLEEP_REQ Sleep until wake up call

RTX_WAKEUP_TASK Wake up a task

CHIP.INI RTI rate selection

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
1.20	1.20	1.20	V1.05	V1.00

Wait up to a specified time for access to a semaphore.

Parameters

AH

0x1E (= RTX_WAIT_SEM_PRIO)

CX

ID of the semaphore acquired from RTX_CREATE_SEM

ES:BX

Signed long value containing the timeout in milliseconds
if timeout == 0, the caller waits forever for the resource
If timeout < 0, the function will return immediately (polling mode). The AX register will be set to error code -27 if the semaphore was not available.

DX

The priority at which the caller wishes to wait (0 = highest).   To wait in FIFO order, have all callers use the same value.   (Note that this priority has no connection to task priorities.)

Return Value

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

Comments

This function may be used with either counting or resource type semaphores.

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

The callers with higher wait priority (lower number in DX register) cut in line ahead of other tasks waiting for the same semaphore at a lower wait priority (higher number in DX).

Beck C-Library Usage

RTX_Wait_Sem()

Related Topics

RTX_SIGNAL_SEM Signal counting semaphore

RTX_RESERVE_RES Wait in FIFO order

RTX_WAIT_SEM Wait in FIFO order

RTX_GET_SEM Get counting semaphore without waiting

RTOS Semaphore Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.22	V1.22	V1.22	V1.11	V1.00

Task switching is inhibited until follow up call(s) to RTX_ENABLE_TASK_SCHEDULER is made.   Interrupt service routines continue to execute, however Timer procedures will be delayed until task switching is re-enabled.

Parameters

AH

0x20 (= RTX_DISABLE_TASK_SCHEDULING)

Comments

This function locks the processor to the current task, preventing further task switching until either RTX_ENABLE_TASK_SCHEDULER or a sleep API function is called.   Entering any sleep API defeats the task lock.   In this case the task lock condition is released until the task resumes execution.   During the sleep, the system automatically releases the lock condition to allow other tasks to execute.

During the task lock condition, interrupts still execute provided that the user leaves interrupts enabled.   Installed Timer procedures will not be executed.   After making this call, the task must follow up with a call to RTX_ENABLE_TASK_SCHEDULER.

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.

Beck C-Library Usage

RTX_Disable_Task_Scheduling()

Related Topics

RTOS Task Control Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.02	V1.00	V1.00	V0.90	V1.00

Unwinds the task switching spin lock to re-enable task switching.

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.

Beck C-Library Usage

RTX_Enable_Task_Scheduling()

Related Topics

API function RTX_DISABLE_TASK_SCHEDULER

RTOS Task Control Services

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.02	V1.00	V1.00	V0.90	V1.00

This function installs a far JMP opcode in the vicinity of the return instruction pointer to enter a specified API function directly from the user code. This function is provided for efficiency in real-time applications.

Parameters

AH

0x27

AL

Index for RTX dynamic linked function that is to be linked.

Return Value

Instruction Pointer is moved back 10 bytes so that newly installed far JMP will execute immediately.

(Refer to respective linked function's documention for further return value information.)

Note: All dynamically linked functions are free to use all registers except for DS, SI, DI, and BP registers which are preserved. This matches Paradigm C, Borland C++ 5.02 and Microsoft Visual C 1.52 calling conventions.

Comments

Dynamic linking is only implemented for a few of the RTX API functions!

Generally the user has no need to know how this dynamic linking is implemented. The discussion here is only provided for reference.

A JMP FAR instruction will be written 10 bytes before the user's return instruction pointer. This far jump will transfer control directly into the RTOS from the user code when executed. This new far JMP will execute immediately upon return from this software interrupt due to the instruction pointer adjustment performed within the call.

Interrupts are masked and restored to their state on entry.

Since the code at calling site will be patched by this RTOS call, it is important that it has exactly the following form. The link index carried in AL register will vary. Refer to the Beck C-Library source files for a complete list of legal indexes for AL register.

JMP SHORT over_patch  ; Occupies 2 bytes of instruction code here
NOP    ; Never executed (1 byte)
NOP    ; Never executed (1 byte)
NOP    ; never executed (1 byte)
over_patch:  ; Linker overwrites above 5 bytes with JMP FAR instruction
MOV AX,02700h  ; AH = 0x27, AL = 0x00 = index for RTX_Get_TimeDate_us()
INT 0ADh

Developer Notes

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.35	V1.35

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

Beck C-Library Usage

RTX_Get_TimeDate()

Related Topics

Set Time/Date

RTOS Time/Date Services

TimeDate_Structure type definition

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

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.

Beck C-Library Usage

RTX_Set_TimeDate()

Related Topics

Get Time/Date

RTOS Time/Date Services

TimeDate_Structure type definition

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Reads out the system millisecond clock tick count.

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.

SC1x3/SC2x Comments

Optionally, the system's real-time interrupt can be run at rates higher than 1000 Hz.   Nevertheless, this function will return a count representing the number milliseconds that the system has been executing.

Beck C-Library Usage

RTX_Get_System_Ticks() - Uses output parameter pointer

RTX_GetTickCount() - Returns the 32 bit tick count

Related Topics

RTOS Time/Date Services

RTX_RTI_COUNT Get Real-Time Interrupt count

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Reads out the system real-time interrupt (RTI) tick count.

Parameters

AH

0x2B (= RTX_RTI_COUNT)

Return Value

DX:AX contains the unsigned long Real-Time Interrupt count.
CX = RTI ticks per millisecond (= kHz rate of RTI)

SC1x3/SC2x Comments

The SC1x3/SC2x system clock can optionally be run at rates above 1000 Hz.   This API returns the 32 bit count on this interrupt driven clock in the DX:AX register pair.   This count rolls over back to zero at 2**32 counts.

The configured interrupt rate in kHz is indicated in the returned CX register.   Total elapsed time in milliseconds can be computed by multiplying the RTI count in DX:AX by the rate in CX.

Beck C-Library Usage

RTX_Get_RTI_Ticks()

RTX_Get_RTI_Rate()

Related Topics

Concerning RTI rate adjustments

CHIP.INI RTI configuration

RTX_GET_TICKS Get millisecond count

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.05	V1.00

Install a fine resolution timer procedure that will be periodically executed by the kernel.

Parameters

AH

0x2F (= RTX_TIMER_FINE)

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

This API is only available for SC1x3/SC2x systems.

The interval here is specified in Real-Time Interrupt (RTI) count, which can differ from milliseconds when the RTI rate has been configured for higher than 1000 Hz operation.

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:

Timer procedures are executed on the stack of the kernel task at a high priority, so they should be as short as possible.   Avoid calling large functions like printf().

Beck C-Library Usage

RTX_Fine_Timer() - Timer defined in a structure

RTX_Fine_TimerP() - Parameters passed directly

Related Topics

TimerProc_Structure definition

RTOS Timer Procedures

Install Timer with millisecond interval

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.05	V1.00

Install a timer procedure that will be periodically executed by the kernel.

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:

Timer procedures are executed on the stack of the kernel task at a high priority, so they should be as short as possible.   Avoid calling large functions like printf().

Beck C-Library Usage

RTX_Install_Timer() - Timer defined in a structure

RTX_Install_TimerP() - Parameters passed directly

Related Topics

TimerProc_Structure definition

RTOS Timer Procedures

Install Timer with fine resolution

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Stop execution and remove a timer procedure.

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.

Beck C-Library Usage

RTX_Remove_Timer()

Related Topics

RTOS Timer Procedures

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Starts the periodic execution of a timer procedure.

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.

Beck C-Library Usage

RTX_Start_Timer()

Related Topics

RTOS Timer Procedures

Start Timer with Delay

Stop Timer

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Stops execution of a timer procedure.

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.

Beck C-Library Usage

RTX_Stop_Timer()

Related Topics

RTOS Timer Procedures

Start Timer

Start Timer with Delay

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Set specified timer's delay period until next callback.

Parameters

AH

0x34 (= RTX_TIMER_DELAY)

DX

timerID produced by the RTX_INSTALL_TIMER call

ES:BX

32 bit delay period count.    A zero delay period will stop the timer.

SC1x3/SC2x Parameters

CX

Boolean flag, set non-zero if the delay count in ES:BX is Real-Time Interrupt (RTI) ticks instead of milliseconds.

Return Value

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

Comments

The value in ES:BX is not a pointer.   This is a 32 bit count with MSH carried in ES register and LSH in BX register.

This function can be used on periodic timers to set the interval to the next call, thereby providing a phase control.

For non-periodic timers this function can be called with varying delay values.

When the delay period in ES:BX is set to '1', this function is identical to the RTX_START_TIMER API.

When the delay period in ES:BX is set to '0', this function is identical the RTX_STOP_TIMER API.

SC1x3/SC2x Comments

When the Real-Time Interrupt rate is configured for operation above 1000 Hz, the Boolean flag carried in CX becomes relevant.

Beck C-Library Usage

RTX_Timer_Delay()

RTX_Timer_Delay_RTI()

Related Topics

RTOS Timer Procedures

Start Timer

Stop Timer

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.20	V1.20	V1.20	V1.05	V1.00

This function installs a callback function which executes perioidically within the 1000 Hz (default rate) Real-Time Interrupt (RTI).

Parameters

AH

0x35 (= RTX_SET_RTI_HOOK)

ES:BX

Far vector to callback function.   Set ES to null to remove the current callback.

CL

Number of ticks before first call.
If this value is zero (special case), then the initial delay will be 256 ticks.  Set to 1 to execute on next RTI.

Return Value

-- none --

Comments

Interrupts are disabled and then restored to their state at the time of the call.

The term 'tick' used here refers to a 1 millisecond period when the system timer RTI is operated at its default rate of 1000 Hz.   Note that this RTI rate can be configured to higher rates with the [TIMER] RTI setting in the CHIP.INI, in which case tick time will be under 1 millisecond.

This API was provided for applications which require a precise and variable timing for high frequency front end hardware sampling, for example.

The callback function is free to use any register except for the DS and DI registers.  These two registers must be preserved.  The value returned in AL from the callback function will be used as the delay count in milliseconds to the next callback.  For example, return 1 to execute again on very next RTI.  Return zero for a delay of 256 ticks.

The system supports only a single RTI hook.   Installing a second overwrites the first.   Unlike with the RTX_INSTALL_TIMER timer callback functions, which execute after a task switch to the kernel task, this RTI hook executes in the context of the interrupt.   No task switch occurs prior to the callback and execution proceeds on the stack of what ever task was interrupted.   Consequently the callback should be conservative with its stack space usage.

This interrupt has been registers with the RTX kernel, so the user is free to use the task triggering RTX API functions from within the callback, such as:

RTX_WAKEUP_TASK
RTX_RESUME_TASK
RTX_SIGNAL_SEM
RTX_SIGNAL_EVENTS
RTX_SEND_MSG

However any time consuming activity must be avoided and it is not legal to call any RTOS API which could block or result in current task being suspended.   As a rough guideline, the dwell within this callback should be held to under 50 us.   Either very carefully written C code, or assembly code is recommended here.

As true for any installed callback function, it is essential that an application program remove its RTI hook callback (ES set to zero) before program termination.

Beck C-Library Usage

RTX_Install_RTI_Hook()

Related Topics

RTOS API RTX Timers

CHIP.INI RTI configuration

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
n/a	n/a	n/a	V1.11	V1.00

Creates a new event group of 16 user definable event flags.

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.

Beck C-Library Usage

RTX_Create_EventGroup()

Related Topics

RTOS Event Manager

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Deletes specified event group.

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.

Beck C-Library Usage

RTX_Delete_EventGroup()

Related Topics

RTOS Event Manager

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Set or clear up to 16 events under a mask in a group.

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.

Beck C-Library Usage

RTX_Signal_Events()

Related Topics

RTOS Event Manager

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

The calling task waits for up to a specified number of milliseconds for event(s) in an event group to assume specified value(s).

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.

Beck C-Library Usage

RTX_Wait_For_Event() - Uses pointer to data structure

RTX_Wait_For_EventP() - Passes direct parameters

Related Topics

RTX_Wait_Event type definition

RTOS Event Manager

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Returns the current state of the 16 event flags (bits) of a specified event group.

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.

Beck C-Library Usage

RTX_Get_EventGroup_State()

Related Topics

RTOS Event Manager

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Return the state of the 16 event flags as they were at the time the calling task most recently completed a RTX_WAIT_EVENTS call.

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.

Beck C-Library Usage

RTX_Get_Saved_Events()

Related Topics

RTOS Event Manager

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Find an event group by specified name tag and return the unique event group ID.

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.

Beck C-Library Usage

RTX_Find_EventGroup()

Related Topics

RTOS Event Manager

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Creates a new Message Exchange.  

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.

For SC1x @CHIP-RTOS versions, the maximum number of Message Exchanges supported by the system is ten.   The SC1x3/SC2x @CHIP-RTOS support up to 32 Message Exchanges.

Beck C-Library Usage

RTX_Create_Msg()

Related Topics

RTX_Msg type definition

RTOS Message Exchange Manager

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Deletes specified Message Exchange.

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.

Beck C-Library Usage

RTX_Delete_Msg()

Related Topics

RTOS Message Exchange Manager

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Send provided message to a specified Message Exchange.

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.

Beck C-Library Usage

RTX_Send_Msg()

Related Topics

RTOS Message Exchange Manager

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Get an available message from a specified Message Exchange without waiting.  

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.

Beck C-Library Usage

RTX_Get_Msg()

Related Topics

RTOS Message Exchange Manager

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Wait up to a specified number of milliseconds for a message from a Message Exchange.

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.

Beck C-Library Usage

RTX_Wait_For_Msg() - Uses pointer to a data structure

RTX_Wait_For_MsgP() - Passes parameters directly

Related Topics

RTX_Wait_Msg type definition

RTOS Message Exchange Manager

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00

Find a Message Exchange by specified name. tag and return the unique exchange ID.

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.

Beck C-Library Usage

RTX_Find_Msg()

Related Topics

RTOS Message Exchange Manager

Supported since or modified in @CHIP-RTOS version

SC12	SC13	SC11	SC1x3	SC2x
V1.00	V1.00	V1.00	V0.90	V1.00