www.beck-ipc.com

@CHIP-RTOS - Data Structures used in RTOS API


    IPC@CHIP® Documentation Index

Data Structures

Here are the data structures used by the RTOS API.   All constants and data structures are defined in the header file rtxapi.h

Notes:
  • Byte alignment is required for all data structures used within the API.

Content :

  • RTX_COUNTS
  • RTX_DETAILS
  • RTX_DETAIL_EVENT
  • RTX_DETAIL_MSGXCHG
  • RTX_DETAIL_SEM
  • RTX_DETAIL_TASK
  • RTX_DETAIL_TMR
  • RTX_Msg
  • RTX_Wait_Event
  • RTX_Wait_Msg
  • sTASK_INFO
  • TaskDefBlock
  • TASK_PARAM_DEF
  • TaskList
  • Task_StateData
  • TimeDate_Structure
  • TimeDateFineS
  • TimerProc_Structure


  • RTX_COUNTS


                
    typedef struct tag_rtx_counts
    {
        unsigned int    nTask_Avail ;       // Tasks control blocks available.
        unsigned int    nTask_In_Use ;      // Tasks control blocks in use.
    
        unsigned int    nObj_Avail ;        // RTX objects available.
        unsigned int    nSem_In_Use ;       // Number of semaphores existing.
        unsigned int    nTimer_In_Use ;     // Number of timers existing.
        unsigned int    nEventGrp_In_Use ;  // Number of Event Groups existing.
    
        unsigned int    nMsg_Xchg_Avail ;   // Number of Msg Exchanges available.
        unsigned int    nMsg_Xchg_In_Use ;  // Number of Msg Exchanges in use.
    
        unsigned int    nEnvelop_Avail ;    // Number of Msg Envelopes available.
        unsigned int    nEnvelop_In_Use ;   // Number of Msg Envelopes in use.
    
        unsigned int    nReport_Cnt ;       // Number of objects report if all
                                            // unfiltered objects were reported.
        unsigned int    nReport_Bytes ;     // Size in bytes report would be if all
                                            // unfiltered objects were reported.
        unsigned int    Internal_Err ;      // Should be zero, else RTX unhealthy.
        unsigned int    TCB_Q_Offset ;      // Wait Q offset in Task Control Block
        unsigned int    RTX_Data_Segment ;  // Segment where TCB reside
    
    } RTX_COUNTS ;

    Comments

    This structure is defined in the header file rtxapi.h.   A data structure of this form provided by the user is filled with data by the RTX_Count_Resources() API.

    nTask_Avail

      Number of task control blocks which are available to the task creation API, RTX_Param_Task().

    nTask_In_Use
      The current number of tasks present in system.

    nObj_Avail


    nSem_In_Use
      The current number of semaphores present in the system.

    nTimer_In_Use
      The current number of RTX timers present in the system.

    nEventGrp_In_Use

      The current number of Event Groups present in the system.

    nMsg_Xchg_Avail
    nMsg_Xchg_In_Use
      The current number of Message Exchanges present in system.

    nEnvelop_Avail

      Number of message envelopes available for the RTX_Send_Msg() API.   These containers are required for storing the message at the exchange in the case that no task is waiting for the message.

    nEnvelop_In_Use
      The current number of message envelopes awaiting pick up at the Message Exchanges.

    nReport_Cnt
      Total number of system objects which would be reported in the nReport_Bytes report when sufficient buffer space is provided.

    nReport_Bytes
      Total number of bytes required to report all the RTX_DETAILS objects that the RTX_Count_Resources() API would report, given sufficient space in the details buffer.   If this API is called with list_size greater or equal to this count, then all requested data has been reported.

    Internal_Err
      This value should always remain zero.   A non-zero value indicates that an internal inconsistency was found inside the RTX private data.

    TCB_Q_Offset
      This constant is the offset into the Task Control Blocks (TCB) at which the wait queues reside.   These circularly linked list are used to queue tasks awaiting a Message Exchange, Semaphore or Event Group.   This constant is reported here since it is subject to change in future @Chip-RTOS releases.

    RTX_Data_Segment
      This is the data segment at which the RTX has its private data. This segment should not be accessed by user applications.

    Related Topics

    API function RTX_Count_Resources() - Count RTX resources

    Top of list
    Index page

    RTX_DETAILS


                
    typedef union tag_rtx_detail
    {
        void                 *pBuf ;
        RTX_DETAIL_SEM       *pSem ;           // Semaphore details
        RTX_DETAIL_TMR       *pTimer ;         // Timer details
        RTX_DETAIL_EVENT     *pEvent ;         // Event details
        RTX_DETAIL_TASK      *pTask ;          // Task details
        RTX_DETAIL_MSGXCHG   *pMsgXchg ;       // Message Exchange details
    
    } RTX_DETAILS ;
    
     /////////////////////////////////////////////////////
     // Example usage of RTX_DETAILS union
     /////////////////////////////////////////////////////
    void Analyze_RTX_Usage (unsigned int list_size, unsigned int filter)
    {
        void *buffer = malloc(list_size) ;
        if (buffer)
        {
            int entries = RTX_Count_Resources(&Counts,
                                              buffer,
                                              list_size,
                                              filter) ;
            RTX_DETAILS details.pBuf = buffer ;     // For scanning
            for (i = 0 ; i < entries ; i++)
            {
                switch (details.pSem->Type)
                {
                case KRTX_SEM_TYPE:
                    Process_Sem(details.pSem) ;
                    details.pSem++ ;
                    break ;
                case KRTX_TIMER_TYPE:
                    Process_Timer(details.pTimer) ;
                    details.pTimer++ ;
                    break ;
                case KRTX_EVENT_GROUP_TYPE:
                    Process_Event_Group(details.pEvent) ;
                    details.pEvent++ ;
                    break ;
                case KRTX_MSG_XCHG_TYPE:
                    Process_Msg_Xchg(details.pMsgXchg) ;
                    details.pMsgXchg++ ;
                    break ;
                case KRTX_TASK_TYPE:
                    Process_Task(details.pTask) ;
                    details.pTask++ ;
                    break ;
                default:
                    i = entries ;
                    printf("ERROR: Invalid Type - 0x%02X\r\n",
                            details.pSem->Type) ;
                    break ;
                }   // End switch
            }       // End FOR loop
    
            free (buffer) ;
        }
    }

    Comments

    This union is defined in the header file rtxapi.h.   It can be used to parse the buffer output by the RTX_Count_Resources() API.

    In the example code shown above, the RTX_DETAILS union of pointers is used to scan the sequence of data structures of varying size output by the RTX_Count_Resources() API.   The number of bytes that the buffer pointer is advanced on each pass through the while loop depends on the data structure type recognized.

    Each of the non-void data structures referenced by the pointers in this union have a Type member located at a common offset within the structures.   This member is an enumerator which has one of the following values to indicate the type data structure present.

      0     KRTX_SEM_TYPE for semaphore details
      1     KRTX_TIMER_TYPE for RTX timer details
      2     KRTX_EVENT_GROUP_TYPE for Event Group details
      3     KRTX_MSG_XCHG_TYPE for Message Exchange details
      4     KRTX_TASK_TYPE for task details

    Related Topics

    API function RTX_Count_Resources() - Count RTX resources

    Top of list
    Index page

    RTX_DETAIL_EVENT


                
    typedef struct tag_rtx_detail_event
    {
        unsigned int  Handle ;          // Event Group "ID"
        char          szName[5] ;       // Nil terminated 4 char name
        char          Type ;            // Enumerator = KRTX_EVENT_GROUP_TYPE
        unsigned int  TaskQHead ;       // Task ID of task awaiting msg.
        unsigned int  Current_Events ;  // Event Group bits state
    
    } RTX_DETAIL_EVENT ;

    Comments

    This data structure is defined in the header file rtxapi.h.   The RTX_Count_Resources() API uses this structure type to report details about an Event Group that is in use within the system.

    Handle
    szName
      Zero terminated 4 character name.   This may not necessarily be ASCII.   Event Groups are not required to have a name.

    Type
      Set to KRTX_EVENT_GROUP_TYPE to distinguish data structure types within the RTX_DETAILS union.

    TaskQHead
      If no tasks are waiting on this Event Group, then this value matches Handle (an empty circularly linked list).   Otherwise this references a linked list node within the Task Control Block of the first task waiting on this Event Group.   Subtracting the TCB_Q_Offset value reported in the RTX_COUNTS data structure yields the task ID of the waiting task.

    Current_Events
      The current state of the Event Group.

    Related Topics

    API function RTX_Count_Resources() - Count RTX resources
    RTOS Event Manager

    Top of list
    Index page

    RTX_DETAIL_MSGXCHG


                
    typedef struct tag_rtx_detail_msgxchg
    {
        unsigned int  Handle ;      // Message Exchange "ID"
        char          szName[5] ;   // Nil terminated 4 char name
        char          Type ;        // Enumerator = KRTX_MSG_XCHG_TYPE
        unsigned int  TaskQHead ;   // Task ID of task awaiting msg.
        unsigned char Busy ;        // xchg busy flag
        unsigned char AvailFlags ;  // Message available flags
        // Following arrays have an entry for each message priority
        unsigned int  Slots[4];     // Msg slots available
        unsigned int  MaxMsg[4] ;   // Maximum number of messages
    } RTX_DETAIL_MSGXCHG ;

    Comments

    This data structure is defined in the header file rtxapi.h.   The RTX_Count_Resources() API uses this structure type to report details about a Message Exchange that is in use within the system.

    Handle
    szName
      Zero terminated 4 character name.   This may not necessarily be ASCII.   Event Groups are not required to have a name.

    Type
      Set to KRTX_MSG_XCHG_TYPE to distinguish data structure types within the RTX_DETAILS union.

    TaskQHead
      If no tasks are waiting on this Message Exchange, then this value matches Handle (an empty circularly linked list).   Otherwise this references a linked list node within the Task Control Block of the first task waiting on this Message Exchange.   Subtracting the TCB_Q_Offset value reported in the RTX_COUNTS data structure yields the task ID of the waiting task.

    Busy
      Counter non-zero when kernel is currently manipulating the Message Exchange object.

    AvailFlags
      This is a bit field indicating a message is available at each of the four priorities.  BN is set if there is a message available at priority N, where N is in range 0..3.

    Slots
      This array has an entry for each message priority in the range 0..3.   This count indicates the number of remaining message slots at the respective priority.   When this count reaches zero, the RTX_Send_Msg() API will fail due to "mailbox full" condition.

    MaxMsg
      This array has an entry for each message priority in the range 0..3.   This count indicates the maximum number of message slots available at the respective message priority.   Note that the number of messages currently posted on the exchange at priority 'i' can be computed as:

      unsigned int msg_cnt = MaxMsg[i] - Slots[i] ;

    Related Topics

    API function RTX_Count_Resources() - Count RTX resources
    RTOS Message Exchange Manager

    Top of list
    Index page

    RTX_DETAIL_SEM


                
    typedef struct tag_rtx_detail_sem
    {
        unsigned int  Handle ;      // Semaphore "ID"
        char          szName[5] ;   // Nil terminated 4 char name
        char          Type ;        // Enumerator = KRTX_SEM_TYPE
        unsigned int  TaskQHead ;   // Task ID of task awaiting msg.
        unsigned char Use_Count ;   // Semaphore use counter
        unsigned char Attribute ;   // B0=1 if resource type semaphore
        int           Value ;       // Semaphore up/down counter
        unsigned int  Owner ;       // ID of task owning this semaphore
    
    } RTX_DETAIL_SEM ;

    Comments

    This data structure is defined in the header file rtxapi.h.   The RTX_Count_Resources() API uses this structure type to report details about a semaphore that is in use within the system.

    Handle
    szName
      Zero terminated 4 character name.   This may not necessarily be ASCII.   Semaphores are not required to have a name.

    Type
      Set to KRTX_SEM_TYPE to distinguish data structure types within the RTX_DETAILS union.

    TaskQHead
      If no tasks are waiting on this semaphore, then this value matches Handle (an empty circularly linked list).   Otherwise this references a linked list node within the Task Control Block of the first task waiting on this semaphore.   Subtracting the TCB_Q_Offset value reported in the RTX_COUNTS data structure yields the task ID of the waiting task.

    Use_Count
      Resource semaphore's use up/down counter.   For resource semaphores this count is set to 1 when a task first acquires the semaphore and is incremented on each additional reservation made by that task. This count is positive when the semaphore is in use.   For resource type semaphores, this count is set to 1 when the semaphore is in use.  

    Attribute
      This is a bit field with two bits defined:

        0x1 - KRTX_RESOURCE_SEM A resource type semaphore
        0x2 - KRTX_SEM_BUSY Semaphore in use by system

    Value
      This is an up down counter used to represent the semaphore's state.   For counting semaphores this count is positive when the semaphore has been signaled and is available.   The count decrements with each RTX_Wait_Sem() or RTX_Get_Sem() call.   N tasks are waiting on this counting semaphore when the value is negative N.

      For resource type semaphores this value is 1 when semaphore is available and zero when it is in use.

    Owner
      For resource type semaphores this is the task ID of the RTX task which currently owns the semaphore, if non-zero.

    Related Topics

    API function RTX_Count_Resources() - Count RTX resources
    RTOS Semaphore Services

    Top of list
    Index page

    RTX_DETAIL_TASK


                
    typedef struct tag_rtx_detail_task
    {
        unsigned int  Handle ;      // Task "ID"
        char          szName[5] ;   // Nil terminated 4 char name
        char          Type ;        // Enumerator = KRTX_TASK_TYPE
        unsigned int  WaitQ ;       // Node in list of tasks awaiting an object.
        unsigned int  Status ;      // Task status
        unsigned int  WaitParam ;   // Semaphore handle, if awaiting semaphore.
        unsigned int  WaitParam2 ;  // Msg Xchg handle, if awaiting message.
    
    } RTX_DETAIL_TASK ;

    Comments

    This data structure is defined in the header file rtxapi.h.   The RTX_Count_Resources() API uses this structure type to report details about a task within the system.

    Handle
    szName
      Zero terminated 4 character name.   This may not necessarily be ASCII.   Tasks are not required to have a name, although it is the convention.

    WaitQ
      If this task is currently waiting on an RTX object, then this vector references the next task in the queue.   This linked list forms a circular queue which eventually leads back to the object on which the task is waiting (semaphore, Event Group or Message Exchange).   When this value refers to a task in the queue, then the TCB_Q_Offset value reported in the RTX_COUNTS data structure must be subtracted from this value to obtain that task's ID.   No offset is subtracted out if the next object in list is the semaphore, Event Group or Message Exchange.

    Status
      This is the task state bit field, same as reported for the RTX_Get_Task_State() API.   Refer to the taskState specification for detailed definition.

    WaitParam
      This RTX internal data can mean different things at different times.   When the task is parked at a semaphore, this will be the handle to that semaphore.

    WaitParam2
      This RTX internal data can mean different things at different times.   When the task is parked at a Message Exchange, this will be the handle to that Message Exchange.

    Related Topics

    API function RTX_Count_Resources() - Count RTX resources

    Top of list
    Index page

    RTX_DETAIL_TMR


                
    typedef struct tag_rtx_detail_tmr
    {
        unsigned int  Handle ;         // Timer "ID"
        // Note: @Chip-RTOS timers have no 4 letter name.
        RTX_TIMER_CALLBACK Callback ;  // Vector to timer's callback.
        char          fStopped ;       // Timer stopped
        char          Type ;           // Enumerator = KRTX_TIMER_TYPE
        unsigned long Period ;         // [ms]
        unsigned long Param ;          // Timer procedures parameter
    
    } RTX_DETAIL_TMR ;

    Comments

    This data structure is defined in the header file rtxapi.h.   The RTX_Count_Resources() API uses this structure type to report details about a RTX timer that is in use within the system.

    Handle
    Callback
      Far vector to timer's user callback function.

    fStopped
      Boolean, zero if timer is currently running.   Set to 1 if timer is stopped.

    Type
      Set to KRTX_TIMER_TYPE to distinguish data structure types within the RTX_DETAILS union.

    Period
      Timers interval in milliseconds.  

    Param
      The optional long parameter passed to the callback procedure.

    Related Topics

    API function RTX_Count_Resources() - Count RTX resources

    Top of list
    Index page

    RTX_Msg


                
    typedef struct tag_rtx_msg
    {
      unsigned int  msgID;    // Unique Message Exchange ID
      char name[4];           // 4 characters, not null terminated
      int  mb0;               // Numbers of message envelopes which can reside
      int  mb1;               //  in each of the four exchange mailboxes.
      int  mb2;
      int  mb3;
    
    } RTX_Msg;

    Comments

    This structure is defined in the header file rtxapi.h.

    Prior to making the RTX_Create_Msg() call, the caller must set the following members of the RTX_Msg data structure.

    name
      Here you can give the Message Exchange a unique four character name.   This field is optional.   If you plan to use the RTX_Find_Msg() API then you should provide a unique name here for all Message Exchanges.

    mb0 through mb3
      State here the maximum number of message envelopes to be queued at each of this Message Exchange's four priority mailboxes.   The system's total number of available messages envelopes is 64 (since @CHIP-RTOS version 1.02B, else 32).   For SC1x3/SC2x the total message envelopes is extended to 128.

    The msgID member is an output parameter from the RTX_Create_Msg() API call.

    Related Topics

    RTOS Message Exchange Manager

    Top of list
    Index page

    RTX_Wait_Event


                
    typedef struct tag_rtx_event_wait
    {
      unsigned int mask;   // 16-Bit mask identifying the flags of interest of the group.
      unsigned int value;  // 16 Bit value, which specifies the states of interest
                           //  for each flag selected by the mask.
      int match;           // event match requirements, 0: only one flag must match
                           //  with value, !=0: all by mask specified flags must match
      long timeout;        // Maximum time (milliseconds) for waiting for an event match
    
    } RTX_Wait_Event;

    Comments

    This structure is defined in the header file rtxapi.h.

    Prior to making the RTX_Wait_For_Event() call, the caller must set the members of the RTX_Wait_Event data structure.

    mask
      Event bits set to '1' in this mask indicate the events in value which will be matched.   All other event bits in the group are ignored.

    value
      The desired event state for the event bits set to '1' in mask are stated here.   User may wait on an event bit transition to either '1' or '0', as specified here.

    match
      This is a Boolean value which indicates whether you require all indicated events to match (AND, match != 0), or whether it is sufficient that only a single event of those specified match (OR, match =0).

    timeout
      Maximum time to wait for events, specified in milliseconds.   Zero here indicates wait forever.   Negative values indicate to return immediately with a timed out indication if the events are not ready (event polling).

    Related Topics

    API function RTX_Wait_For_Event() - Wait for events in a group
    RTOS Event Manager

    Top of list
    Index page

    RTX_Wait_Msg


                
    typedef struct tag_rtx_wait_msg
    {
      unsigned int msgID; // ID of the Message Exchange
      unsigned int prio;  // Priority for wait [0 .. 0xFFFF], 0 = highest
      void far *msg;      // Pointer to user buffer to store the arrived message
      long  timeout;      // Maximum time (milliseconds) for waiting for a message
    
    } RTX_Wait_Msg;

    Comments

    This structure is defined in the header file rtxapi.h.

    Prior to calling the RTX_Wait_For_Msg() ALI, the caller must set the following members of the RTX_Wait_Msg structure.

    msgID
    prio
      Specify here the priority of the calling task's access to the messages.   To wait in FIFO order, have all RTX_Wait_For_Msg() API callers use the same value here.   A task can cut in line ahead of other waiting tasks by setting this field to a higher priority (lower number) than used by the other tasks.   (Note that this priority has no connection to either task priority or Message send mailbox priority.)

    msg
      Put here a far pointer to a 12 byte buffer allocated in your application program memory.   The Message Exchange Manager will copy the message to this buffer if a message is available.   The format of the 12 byte object referenced by msg is user defined.

    timeout
      Here you can specify the maximum number of milliseconds you are willing to wait for a message.   A value of zero indicates you will wait forever.   Negative values are not permitted.

    Related Topics

    API function RTX_Wait_For_Msg() - Wait for a message from a Message Exchange
    RTOS Message Exchange Manager

    Top of list
    Index page

    sTASK_INFO


                
    typedef struct tTASK_INFO
    {
        unsigned int    tiTaskState;
        unsigned int    tiTaskID;
        char            tiName[5] ;
        unsigned char   tiTaskPriority;
        unsigned char   tiProgIdx ;
        unsigned char   tiTaskMonStatus ;
        unsigned long   tiDutyTime ;
        unsigned long   tiElapsedTime ;
        unsigned long   tiRunTime ;
        unsigned long   tiExistTime ;
        unsigned int    tiStackUsed;
        unsigned int    tiStackSize;
    
    } sTASK_INFO;

    Comments

    This data structure is defined in the header file rtxapi.h.   The RTX_Task_Info() and RTX_Task_Info_By_Id() API outputs to this structure type to report details about a specified task.

    tiTaskState
    tiTaskID
      Task handle.

    tiName
      Zero terminated 4 character name given to task when it was created.

    tiTaskPriority
      Task's priority.

    tiProgIdx
      Not applicable to this system. (Exists for compatibility with other Beck systems.)

    tiTaskMonStatus
      Bit field:

        0x2 RTX_MON_READY -> Task Monitor's 10 second data collection cycle has completed at least one time. The tiDutyTime and tiElapsedTime members are not valid until this flag comes up.
      The RTX_MON_RUNNING and RTX_MON_READY bit definition macros are defined in header file rtxapi.h.

    tiDutyTime
      This value is only meaningful when both the RTX_MON_RUNNING and RTX_MON_READY flags are set in the tiTaskMonStatus member of this report.   In this case, this is the count of the number times where this task was executing at the time of the one millisecond sampling.   This count is the same as appears at the console tasks command for the respective task.   This can provide a very rough indication of the task's duty cycle, where a count of 10000 would correspond to a 100% duty cycle.

    tiElapsedTime
      Always set to 10000, which is the number of milliseconds per 10 second task duty cycle measurement period used by the system's task monitor.

    tiRunTime
      Not applicable to this system. (Exists for compatibility with other Beck systems.)

    tiExistTime
      Not applicable to this system. (Exists for compatibility with other Beck systems.)

    tiStackUsed
      Number of bytes stack space used (worst case high water mark) by this task. This member is set to zero unless the measureStack Boolean passed to the RTX_Task_Info() or RTX_Task_Info_By_Id() API was set.

    tiStackSize
      Number of bytes total stack space available for this task.

    Related Topics

    API function RTX_Task_Info() - Get task info by name.
    API function RTX_Task_Info_By_Id() - Get task info by task handle.

    Top of list
    Index page

    TaskDefBlock


                
    typedef struct tag_taskdefblock
    {
       void     (far *proc)();      // Task entry vector (far)
       char           name[4];      // Task name, 4 characters not null terminated
       unsigned int far *stackptr;  // Task stack pointer (far)
       unsigned int   stacksize;    // size of stack (bytes)
       unsigned short attrib;       // task attributes, TA_SAVE_STACK bit
       short int      priority;     // task priority,  range: 2..127 inclusive
       unsigned short time_slice;   // 0: none, !=0: number of milliseconds before task
                                    //  is forced to relinquish processor
       short       mailboxlevel1;   // First parameter passed to task
       short       mailboxlevel2;   // Second parameter passed to task
       short       mailboxlevel3;   // not used
       short       mailboxlevel4;   // not used
    
    } TaskDefBlock;

    Comments

    This data structure is deprecated. Please use the TASK_PARAM_DEF data structure instead.

    This structure definition remains in the C-library header file rtxapi.h for compatibility with older code.   If you do not need your task to accept any input parameters then you are still free to use this compatible data structure with the RTX_Create_Task() API-call, however at a slight additional cost due to the larger data structure.

    The new and old task definition data structures are identical up to the mailboxlevel1 field, which was previously unused.   Refer to the TASK_PARAM_DEF documentation for descriptions of the member fields.

    If you use the new TASK_PARAM_DEF structure with the old RTX_Create_Task() API-call, you have to use a cast to suppress warnings that the compiler will generate due to the diffrent type.

    TASK_PARAM_DEF taskParameters;
    .
    .
    .
    RTX_Create_Task( &taskId, (TaskDefBlock *)&taskParameters );

    Related Topics

    API function RTX_Create_Task() - Create and start a task
    TASK_PARAM_DEF - Alternate data structure

    Top of list
    Index page

    TASK_PARAM_DEF


                
    typedef void huge (far *PARAM_TASK)(unsigned short Param1, unsigned short Param2) ;
    
    typedef struct tag_TASK_PARAM_DEF
    {
            PARAM_TASK    proc ;            // task procedure pointer
            char    name[4];                // name 4 characters not null terminated
            unsigned int far * stackptr;    // task stack pointer (Top of stack)
            unsigned int stacksize;         // size of task stack (bytes)
            unsigned short int attrib;      // task attributes, TA_SAVE_STACK bit
            short int priority;             // task priority,  range: 2 <= priority <= 127
            unsigned short int time_slice;  // 0: none, !=0: number of milliseconds before task
                                            //  force to relinquish processor
            unsigned short Param1 ;         // FP_OFF portion if a far pointer is used
            unsigned short Param2 ;         // FP_SEG portion if a far pointer is used
    
    } TASK_PARAM_DEF ;

    Comments

    This structure is defined in the header file rtxapi.h.

    Prior to making the RTX_Param_Task() API call, the caller must set each of the TASK_PARAM_DEF structure members.

    proc
      Here you must set the far vector to your task's entry point.   The task's main procedure should be declared (depending on compiler used) as:

        Borland/Paradigm C:    void huge taskfunc(...)
        Microsoft C:   void far _saveregs _loadds taskfunc(...)

      These declarations assure that the data segment register (DS) is loaded on entry into your task.   Where the three dots are shown in these prototypes, you must replace these with your desired parameters to be passed to your task by the system.   You are free to choose void parameters.   Here are a few possible parameter passing options you could use:

        taskfuncA(void)
        taskfuncB(unsigned int param1, unsigned int param2)
        taskfuncC(void far *this_object)
        taskfuncD(struct MY_STRUC_TYPE far *this_object)
        taskfuncE(struct MY_STRUC_TYPE near *this_object)
        taskfuncF(unsigned long combined_param)

      All above examples except for taskfuncB() would need to be cast to PARAM_TASK type as they are assigned to the proc member.   The parameters cannot exceed 32 bits in total, which is the amount of data that the system pushes onto the stack for task input parameters.   See Param1 and Param2 members.

    name
      Make up a four letter name for your task by which it can be uniquely identified.   Avoid names already occupied by the system tasks.

    stackptr
      This far pointer should point to the top of you task's stack space (highest address).   Your tasks stack pointer will be initialized to this value, which points to the first byte of memory following your actual stack space.   (Note that x86 CPU decrements the stack pointer prior to pushing data onto the stack.)   The stack memory space resides within your application program.

    stacksize
      Here you specify the size of your task's stack space in bytes.   The amount of stack space required for your task depends on the nature of your task.   If large automatic objects are declared in your task's procedures, a large amount of stack space will be needed.

      Caution:

        Some of the system's interrupts use your task's stack.   Consequently we recommend a minimum stack space of 1024 bytes per task.  

      Since the problems resulting from stack overflow are often difficult to diagnose and analyze, the following design steps are recommended:

      1. Initially allocate way more stack space then you believe you will need.
      2. When you have your task performing what it was designed to do, measure the amount of stack space being used by your task.   The RTX_Get_Task_State() API can be used to obtain this measurement.
      3. Refine your stack allocation based on this measurement, arriving at a compromise between the conflicting requirements:   efficiency on the one hand (small stack desired) and program maintainability and reliability on the other hand (big stack desired).  

      Software maintainability becomes an issue here if you have the stack space wired so tight that the slightest code change will lead to stack overflow.   Reliability is an issue when paths in your task (or interrupts) are executed that did not execute during your stack space measurement trials.

    attrib
      This is a bit field with currently one option attribute defined.   The amount of user task stack space used by the system prior to calling the task procedure can be reduced by 20 bytes by setting the B0 bit to 1 (see TA_SAVE_STACK define).   This setting is recommended here unless your task requires backwards compatibility to older @Chip-RTOS versions (not very likely) with respect to this user stack preparation done by the system prior to calling your task entry procedure.

      On entry into the task from the system, the stack situation will be as follows:

        Stack Fence WORD 2 = 0x5555    Highest address
        Stack Fence WORD 1 = 0x5555
        Task name characters 3 & 4
        Task name characters 1 & 2
        Pad bytes (20 bytes if TA_SAVE_STACK bit == 0, else 0 bytes)
        Param2 16 bit WORD
        Param1 16 bit WORD
        FP_SEG(return address)
        FP_OFF(return address) <-- SS:SP pointing here

    priority
      Application program tasks can range in priority from 2 to 127 (inclusive), where 2 is higher priority.   Generally, task priorities between 20 and 30 are recommended.   This recommendation is based on the priority assignments of the built-in system tasks.   Too high a priority for an application task may block important system tasks: e.g. the Ethernet receiver task.   However, in some cases higher priority application tasks are appropriate design, but in these cases you must keep the execution dwell of these high priority task very short.   User DOS applications are started at priority 25.

      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.

    time_slice
      Set this value to zero if you do not want round-robin time slicing between this task and others at the same priority level.   If you do want round-robin switching, then specify here the number of milliseconds of CPU time that this task should receive before the system switches to the next task at this same priority.   System timing granularity is one millisecond.   Time slicing is disabled on all DOS application main tasks.

      SC1x3/SC2x Note:
        If the RTI rate has been configured for rates higher than 1000 Hz, than this time-slice count will be translated to RTI ticks from milliseconds within the @Chip-RTOS task creation API.   Any time-slice values in milliseconds exceeding 65535 real-time interrupts will be limited to 65535 RTI ticks.

    Param1
      This will be the left most parameter declared in your task procedure if two 16 bit values are used as input parameters.   This would be the FP_OFF() portion of a far pointer input parameter or least significant half of a long 32 bit input parameter.

    Param2
      This will be the right most parameter declared in your task procedure if two 16 bit values are used as input parameters.   This would be the FP_SEG() portion of a far pointer input parameter or most significant half of a long 32 bit input parameter.

    Related Topics

    API function RTX_Param_Task() - Create and start a task
    TaskDefBlock - Legacy data structure

    Top of list
    Index page

    TaskList


                
    typedef struct tagtasklist
    {
         unsigned int taskID;         // Task handle
         char         taskname[5];    // Four character string terminated with zero.
    
    } TaskList;

    Comments

    This structure is defined in the header file rtxapi.h

    Related Topics

    API function RTX_Get_Task_List() - Get list of current tasks in the system

    Top of list
    Index page

    Task_StateData


                
    typedef struct tag_task_statedata
    {
        unsigned int taskID;      // Task handle
        unsigned int taskPrio;    // Task priority
        unsigned int taskState;   // Bit field
        unsigned int taskCount;   // Duty cycle indicator
        unsigned int stackused;   // Percentage of stack space used
        unsigned int stacksize;   // Task's total stack size, in bytes
    
    } Task_StateData;

    Comments

    This structure is defined in the header file rtxapi.h.

    taskID

      Task handle used for the RTX API functions.

    taskPrio

    taskState

      This bit field is zero for active tasks.   The reasons for an inactive task waiting are coded in B0..B7 as follows. B8 is a status flag.

        B0: Timer wait (used in combination with other bits: B2, B3, B4, B7)
        B1: Trigger wait (i.e. idle, see note)
        B2: Semaphore wait
        B3: Event Group wait
        B4: Message Exchange wait
        B5: -- not implemented --
        B6: Suspended (waiting for resume)
        B7: Asleep waiting for wakeup
        B8: Task has access to File System
        B9 - B15 internal use only
      Notes:
      • A task is in "trigger wait" state prior to starting (e.g. RTX_Create_Task_Without_Run()) or after termination.   A RTX_Restart_Task() call exits this state.

      • Where as B1, B2, B3, B4 and B7 are mutually exclusive wait conditions, B6 "Suspended" condition can be added (OR'ed in) to these other wait conditions.

    taskCount
      The task Monitoring mode must be enabled in order for this value to be meaningful.   This value, ranging from 0 to 10000, provides a rough indication of the amount load placed on the system by this task.   At each execution of the @CHIP-RTOS real-time interrupt handler (1000 Hz rate by default), this count is incremented if this particular task is either currently executing or if the CPU is idle and this task was the most recent task to be executed.   The running count is recorded at 10 second intervals (assuming 1000 Hz operation), so a task which is active 100% of the time would score a taskCount of 10000.

    stackused
      This value is the percentage of the task's stack space used.   The system presets stack space to all zeroes prior to starting tasks.   The deepest (lowest address) non-zero value on the stack indicates the "high water mark".   This value is only meaningful for tasks created within application programs.   DOS programs normally switch stacks on entry, so this the stack space usage measurement is defeated.

    stacksize
      This is the total number of bytes in the task's stack space.   This value is only meaningful for tasks created within application programs, due to that DOS programs normally switch stacks on entry.

    Related Topics

    API function RTX_Get_Task_State() - Get state of a task

    Top of list
    Index page

    TimeDate_Structure


                
    typedef struct tag_time
    {
        unsigned char sec;      // Seconds (0-59)
        unsigned char min;      // Minutes (0-59)
        unsigned char hr;       // Hours   (0-23)
        unsigned char dy;       // Day  (1-31)
        unsigned char mn;       // Month   (1-12)
        unsigned char yr;       // Year (0-99)
        unsigned char dow;      // Day of week (Mon=1 to Sun=7)
        unsigned char dcen;     // Century (19 or 20)
    
    } TimeDate_Structure;

    Comments

    This structure is defined in the header file rtxapi.h.

    The dow Day of Week index is strictly an output parameter from both the RTX_Get_TimeDate() and RTX_Set_TimeDate() API.

    Related Topics

    API function RTX_Get_TimeDate() - Get system time and date
    API function RTX_Set_TimeDate() - Set system time and date

    Top of list
    Index page

    TimeDateFineS


                
    typedef struct TimeDateFineT
    {
        unsigned short usec;    // Microseconds [0-999]
        unsigned short msec;    // Milliseconds [0-999]
        unsigned char sec;      // Seconds (0-59)
        unsigned char min;      // Minutes (0-59)
        unsigned char hr;       // Hours   (0-23)
        unsigned char dy;       // Day  (1-31)
        unsigned char mn;       // Month   (1-12)
        unsigned char yr;       // Year (0-99)
        unsigned char dow;      // Day of week (Mon=1 to Sun=7)
        unsigned char dcen;     // Century (19 or 20)
    
    } TimeDateFineS;

    Comments

    This structure is defined in the header file rtxapi.h.

    The dow Day of Week index is strictly an output parameter from both the RTX_Get_TimeDate() and RTX_Set_TimeDate() API.

    Related Topics

    API function RTX_Get_TimeDate_us() - Get system time and date
    API function RTX_Set_TimeDate_us() - Set system time and date

    Top of list
    Index page

    TimerProc_Structure


                
    typedef struct tag_timer_proc
    {
       unsigned int  far *timerID;  // pointer to storage the unique timerID
       void (far *proc)();          // pointer to the procedure to be executed
       void  far *dummyptr;         // Optional parameter to timer procedure
       char  name[4];               // -- Field not used --
       long  interval;              // timer execution interval in milliseconds
                                    //  (or RTI ticks if RTX_TIMER_FINE API is used)
    } TimerProc_Structure;

    Comments

    This structure is defined in the header file rtxapi.h.

    Before calling the RTX_Install_Timer() API function the caller must allocate a TimerProc_Structure with the following members set as specified here:

    timerID
      Put here a far pointer to a 16 bit location in your program's memory space.   The RTX_Install_Timer() API function will output a Timer ID to this referenced location.   This Timer ID value is used as handle for this new timer procedure within the other Timer Procedure API functions.

    proc
      This is a far vector to your timer procedure.   This routine will be called periodically from the kernel.   Your timer procedure should be declared (depending on compiler used) as:

        Borland/Paradigm C:    void huge MyTimerProc(void)
        Microsoft C:   void far _saveregs _loadds MyTimerProc(void)
        Turbo Pascal:
            procedure Timer1_Proc;interrupt;
            begin
            
            [... your code ...]
            
            (************************************************)
            (* This is needed at the end of the Timer Proc. *)
                 asm
                 POP BP
                 POP ES
                 POP DS
                 POP DI
                 POP SI
                 POP DX
                 POP CX
                 POP BX
                 POP AX
                 RETF
                 end;
            (************************************************)
            end;

      so that the compiler will generate code to set the CPU's DS register, enabling access to your program's data.   Have also a look to some important notes concerning Timer Procedures.

    dummyptr
      This four byte value is pushed onto the stack by the system as an input parameter to your timer procedure.   You are free to ignore this parameter as suggested by the above MyTimerProc(void) declarations.   Alternatively you could also use, for example, either of the following timer procedure declarations (Borland/Paradigm):

              void huge MyTimerProc(unsigned int timer_id,
                               unsigned long lParam) ;


          or

              void huge MyTimerProc(unsigned int timer_id, void far *ptr) ;

      The timer_id parameter will be the same as output to timerID location in this data structure.   In either case, the second parameter is a copy of the four byte dummyptr.

    name
      This provisional field is not used by the system.

    interval
      Specify here the interval at which you want your timer procedure to be called.   For the RTX_Install_Timer() API this interval is specified in milliseconds.   For the SC1x3/SC2x RTX_Fine_Timer() API this count is specified in Real-Time Interrupt (RTI) ticks, which differs from milliseconds when the RTI rate is configured for frequencies above 1000 Hz.

    Related Topics

    API function RTX_Install_Timer() - Install a timer procedure
    API function RTX_Fine_Timer() - Install a high resolution timer procedure
    RTOS Timer Procedures

    Top of list
    Index page


    End of document