www.beck-ipc.com

@CHIP-RTOS - RTOS API


    IPC@CHIP® Documentation Index

RTOS API

Here is the documentation for the RTOS API.   This interface provides access to the RTOS of the IPC@CHIP®.

All RTOS API functions listed here are reentrant.

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.

For some useful comments see also the programming notes.

Topics

Task control functions

  • 0x00:_RTX_SLEEP_TIME, Sleep for a specified time
  • 0x01:_RTX_TASK_CREATE, Create and start a task
  • 0x11:_RTX_TASK_CREATE_WITHOUT_RUN, Create a task
  • 0x02:_RTX_TASK_KILL, Stop and kill specified task.
  • 0x03:_RTX_TASK_DELETE, Remove a task from the system
  • 0x04:_RTX_GET_TASKID, Get ID of the current task
  • 0x05:_RTX_SLEEP_REQ, Sleep until wake request
  • 0x06:_RTX_WAKEUP_TASK, Wake up a task
  • 0x07:_RTX_END_EXEC, End execution of task
  • 0x08:_RTX_CHANGE_PRIO, Change priority of a task
  • 0x09:_RTX_ACCESS_FILESYSTEM, Reserve file access context
  • 0x0A:_RTX_GET_TASK_STATE, Get state of a task
  • 0x0B:_RTX_GET_TASK_LIST, Get list of tasks
  • 0x0C:_RTX_START_TASK_MONITOR, Enable task monitoring
  • 0x0D:_RTX_STOP_TASK_MONITOR, Disable task monitoring
  • 0x0E:_RTX_SUSPEND_TASK, Suspend a task
  • 0x0F:_RTX_RESUME_TASK, Resume a task
  • 0x10:_RTX_RESTART_TASK, Start task
  • 0x12:_RTX_GET_TASK_STATE_EXT, Get task state
  • 0x13:_RTX_COUNT_RESOURCES, Check resources available.
  • 0x1D:_RTX_SLEEP_FINE, Sleep for RTI count
  • 0x20:_RTX_DISABLE_TASK_SCHEDULING, Task Lock
  • 0x21:_RTX_ENABLE_TASK_SCHEDULING, Release Task Lock
  • 0x27:_Install dynamic link, then call function

  • Semaphore services

  • 0x14:_RTX_CREATE_SEM, Create a semaphore
  • 0x15:_RTX_DELETE_SEM, Delete a semaphore
  • 0x16:_RTX_FREE_RES, Free a resource semaphore
  • 0x17:_RTX_GET_SEM, Get semaphore (no wait)
  • 0x18:_RTX_RELEASE_SEM, Release a resource semaphore
  • 0x19:_RTX_RESERVE_RES, Get use of a resource semaphore
  • 0x1A:_RTX_SIGNAL_SEM, Signal a counting semaphore
  • 0x1B:_RTX_WAIT_SEM, Wait on a semaphore
  • 0x1C:_RTX_FIND_SEM, Find semaphore by name
  • 0x1E:_RTX_WAIT_SEM_PRIO, Wait on a a semaphore

  • Time/Date functions

  • 0x28:_RTX_GET_TIMEDATE, Get system time and date
  • 0x29:_RTX_SET_TIMEDATE, Set system time and date
  • 0x2A:_RTX_GET_TICKS, Get tick count of system clock
  • 0x2B:_RTX_RTI_COUNT, Get real-time interrupt count.

  • Timer procedures

  • 0x2F:_RTX_TIMER_FINE, Install a fine precision timer procedure
  • 0x30:_RTX_INSTALL_TIMER, Install a timer procedure
  • 0x31:_RTX_REMOVE_TIMER, Remove a timer procedure
  • 0x32:_RTX_START_TIMER, Start periodic timer procedure
  • 0x33:_RTX_STOP_TIMER, Stop execution of a timer procedure
  • 0x34:_RTX_TIMER_DELAY, Set timer delay
  • 0x35:_RTX_SET_RTI_HOOK, Install Real-Time Interrupt hook

  • Event group manager

  • 0x40:_RTX_CREATE_EVENTGROUP, Create an event group
  • 0x41:_RTX_DELETE_EVENTGROUP, Delete an event group
  • 0x42:_RTX_SIGNAL_EVENTS, Signal event(s) in a group
  • 0x43:_RTX_WAIT_EVENTS, Wait for events in a group
  • 0x44:_RTX_GET_EVENTGROUP_STATE, Read the event states
  • 0x45:_RTX_GET_EVENT_FLAGS, Get the saved event flags
  • 0x46:_RTX_FIND_EVENTGROUP, Find an event group

  • Message exchange manager

  • 0x50:_RTX_CREATE_MSG, Create a Message Exchange
  • 0x51:_RTX_DELETE_MSG, Delete a Message Exchange
  • 0x52:_RTX_SEND_MSG, Send message
  • 0x53:_RTX_GET_MSG, Poll Message Exchange
  • 0x54:_RTX_WAIT_MSG, Wait for a message
  • 0x55:_RTX_FIND_MSG, Find a Message Exchange


  • RTX Interrupt 0xAD Services

    The RTOS API uses interrupt 0xAD with a service selector in the high order byte of the AX register (AH) as specified here:
    At return from most of the API calls, the DX-Register is used for error checking as follows:
      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


    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.

    These software interrupt API are used by the RTX Beck C-Library functions.   Normally there will never be a need for the user to call invoke these interrupts directly.


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

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

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

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x11:     RTX_TASK_CREATE_WITHOUT_RUN, Create a task

    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

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x02:     RTX_TASK_KILL, Stop and kill specified task.

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x03:     RTX_TASK_DELETE, Remove a task from the system

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x04:     RTX_GET_TASKID, Get ID of the current task

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x05:     RTX_SLEEP_REQ, Sleep until wake request

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x06:     RTX_WAKEUP_TASK, Wake up a task

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x07:     RTX_END_EXEC, End execution of task

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x08:     RTX_CHANGE_PRIO, Change priority of a task

    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

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x09:     RTX_ACCESS_FILESYSTEM, Reserve file access context

    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/SC2x) 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

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x0A:     RTX_GET_TASK_STATE, Get state of a task

    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

    The task monitoring mode must be enabled in order to obtain the taskCount member.
    The alternative function, RTX_GET_TASK_STATE_EXT provides a faster method, useful when only the task's state is required.

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x0B:     RTX_GET_TASK_LIST, Get list of tasks

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x0C:     RTX_START_TASK_MONITOR, Enable task monitoring

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x0D:     RTX_STOP_TASK_MONITOR, Disable task monitoring

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x0E:     RTX_SUSPEND_TASK, Suspend a task

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x0F:     RTX_RESUME_TASK, Resume a task

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x10:     RTX_RESTART_TASK, Start task

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x12:     RTX_GET_TASK_STATE_EXT, Get task state

    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

      SC12SC13SC11SC1x3SC2x
      V1.01V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x13:     RTX_COUNT_RESOURCES, Check resources available.

    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

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V0.91V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x14:     RTX_CREATE_SEM, Create a semaphore

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x15:     RTX_DELETE_SEM, Delete a semaphore

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x16:     RTX_FREE_RES, Free a resource semaphore

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x17:     RTX_GET_SEM, Get semaphore (no wait)

    Attempt acquisition of a counting or resource type 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.

    Note:>    On RTOS versions prior to SC1x version 1.27 and SC1x3/SC2x version 1.41, this function was restricted to counting semaphores.   This restriction has been removed.

    Beck C-Library Usage

    RTX_Get_Sem()

    Related Topics

    RTX_WAIT_SEM Wait for semaphore access
    RTX_SIGNAL_SEM Signal counting semaphore
    RTX_RELEASE_SEM Release a resource semaphore
    RTOS Semaphore Services

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.27V1.27V1.27V1.41V1.41

    Top of list
    Index page
    Interrupt 0xAD service 0x18:     RTX_RELEASE_SEM, Release a resource semaphore

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x19:     RTX_RESERVE_RES, Get use of a resource semaphore

    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.

    Implementation Note:    Internally, this API and the RTX_WAIT_SEM API execute the same function.   So although the convention would be to use this other function for counting semaphores, this API here will also work for counting semaphores.

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x1A:     RTX_SIGNAL_SEM, Signal a counting semaphore

    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 semaphore without waiting
    RTOS Semaphore Services

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x1B:     RTX_WAIT_SEM, Wait on a semaphore

    Wait up to a specified time for access to a 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.

    Implementation Note:    Internally, this API and the RTX_RESERVE_RES API execute the same function.   So although the convention would be to use this other function for resource semaphores, this API here will also work for resource type semaphores.

    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 semaphore without waiting
    RTOS Semaphore Services

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x1C:     RTX_FIND_SEM, Find semaphore by name

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x1D:     RTX_SLEEP_FINE, Sleep for RTI count

    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

      SC12SC13SC11SC1x3SC2x
      1.201.201.20V1.05V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x1E:     RTX_WAIT_SEM_PRIO, Wait on a a semaphore

    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 semaphore without waiting
    RTOS Semaphore Services

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      V1.22V1.22V1.22V1.11V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x20:     RTX_DISABLE_TASK_SCHEDULING, Task Lock

    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

      SC12SC13SC11SC1x3SC2x
      V1.02V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x21:     RTX_ENABLE_TASK_SCHEDULING, Release Task Lock

    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

      SC12SC13SC11SC1x3SC2x
      V1.02V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x27:     Install dynamic link, then call function

    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

    This API service is intended to be used by the RTOS C-Library exclusively.
    It should not be used directly within user applications.

    Supported since or modified in @CHIP-RTOS version

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.35V1.35

    Top of list
    Index page
    Interrupt 0xAD service 0x28:     RTX_GET_TIMEDATE, Get system time and date

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x29:     RTX_SET_TIMEDATE, Set system time and date

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x2A:     RTX_GET_TICKS, Get tick count of system clock

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x2B:     RTX_RTI_COUNT, Get real-time interrupt count.

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.05V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x2F:     RTX_TIMER_FINE, Install a fine precision timer procedure

    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.05V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x30:     RTX_INSTALL_TIMER, Install a timer procedure

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x31:     RTX_REMOVE_TIMER, Remove a timer procedure

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x32:     RTX_START_TIMER, Start periodic timer procedure

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x33:     RTX_STOP_TIMER, Stop execution of a timer procedure

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x34:     RTX_TIMER_DELAY, Set timer delay

    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

      SC12SC13SC11SC1x3SC2x
      V1.20V1.20V1.20V1.05V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x35:     RTX_SET_RTI_HOOK, Install Real-Time Interrupt hook

    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:


    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

      SC12SC13SC11SC1x3SC2x
      n/an/an/aV1.11V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x40:     RTX_CREATE_EVENTGROUP, Create an event group

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x41:     RTX_DELETE_EVENTGROUP, Delete an event group

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x42:     RTX_SIGNAL_EVENTS, Signal event(s) in a group

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x43:     RTX_WAIT_EVENTS, Wait for events in a group

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x44:     RTX_GET_EVENTGROUP_STATE, Read the event states

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x45:     RTX_GET_EVENT_FLAGS, Get the saved event flags

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x46:     RTX_FIND_EVENTGROUP, Find an event group

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x50:     RTX_CREATE_MSG, Create a Message Exchange

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x51:     RTX_DELETE_MSG, Delete a Message Exchange

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x52:     RTX_SEND_MSG, Send message

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x53:     RTX_GET_MSG, Poll Message Exchange

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x54:     RTX_WAIT_MSG, Wait for a message

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page
    Interrupt 0xAD service 0x55:     RTX_FIND_MSG, Find a Message Exchange

    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

      SC12SC13SC11SC1x3SC2x
      V1.00V1.00V1.00V0.90V1.00

    Top of list
    Index page


    End of document