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

RTX_Param_Task()

nTask_In_Use

nObj_Avail

RTX_Install_Timer()

RTX_Create_Sem()

RTX_Create_EventGroup()

nSem_In_Use

nTimer_In_Use

nEventGrp_In_Use

nMsg_Xchg_Avail

Message Exchanges

RTX_Create_Msg()

nMsg_Xchg_In_Use

nEnvelop_Avail

RTX_Send_Msg()

nEnvelop_In_Use

nReport_Cnt

nReport_Bytes

nReport_Bytes

RTX_DETAILS

RTX_Count_Resources()

details

list_size

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

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.

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

RTX_Create_EventGroup()

szName

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

RTX_DETAILS

TaskQHead

Handle

TCB_Q_Offset

RTX_COUNTS

Current_Events

The current state of the Event Group.

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

RTX_Create_Msg()

szName

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

RTX_DETAILS

TaskQHead

Handle

TCB_Q_Offset

RTX_COUNTS

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

RTX_Send_Msg()

MaxMsg

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

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

RTX_Create_Sem()

szName

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

RTX_DETAILS

TaskQHead

Handle

TCB_Q_Offset

RTX_COUNTS

Use_Count

reservation

Attribute

KRTX_RESOURCE_SEM

KRTX_SEM_BUSY

Value

signaled

RTX_Wait_Sem()

RTX_Get_Sem()

Owner

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

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

RTX_TASK_CREATE

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

TCB_Q_Offset

RTX_COUNTS

Status

RTX_Get_Task_State()

taskState

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.

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

RTX_Install_Timer()

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

RTX_DETAILS

Period

Timers interval in milliseconds.
Param

The optional long parameter passed to the callback procedure.

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

RTX_Find_Msg()

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.

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

value

value

mask

match

match

timeout

timed out

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

msg

msg

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.

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

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

void huge taskfunc(...)

void far _saveregs _loadds taskfunc(...)

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)

taskfuncB()

PARAM_TASK

proc

Param1

Param2

members

name

system

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

Caution:

Initially allocate way more stack space then you believe you will need.
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.
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).

attrib

TA_SAVE_STACK

priority

system

Note:

created

changed

time_slice

SC1x3/SC2x Note:

RTI

configured

Param1

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.

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

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. Task Monitoring mode must be enabled to obtain all the data listed here.

taskID

Task handle used for the RTX API functions.
taskPrio

priority

taskState

access

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

rate

taskCount

stackused

stacksize

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.

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.

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

RTX_Install_Timer()

functions

proc

void huge MyTimerProc(void)

void far _saveregs _loadds MyTimerProc(void)

    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;

some important notes

dummyptr

MyTimerProc(void)

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

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

timer_id

timerID

dummyptr

name

This provisional field is not used by the system.
interval

@CHIP-RTOS - Data Structures used in RTOS API

RTX_COUNTS

Comments

Related Topics

RTX_DETAILS

Comments

Related Topics

RTX_DETAIL_EVENT

Comments

Related Topics

RTX_DETAIL_MSGXCHG

Comments

Related Topics

RTX_DETAIL_SEM

Comments

Related Topics

RTX_DETAIL_TASK

Comments

Related Topics

RTX_DETAIL_TMR

Comments

Related Topics

RTX_Msg

Comments

Related Topics

RTX_Wait_Event

Comments

Related Topics

RTX_Wait_Msg

Comments

Related Topics

TaskDefBlock

Comments

Related Topics

TASK_PARAM_DEF

Comments

Related Topics

TaskList

Comments

Related Topics

Task_StateData

Comments

Related Topics

TimeDate_Structure

Comments

Related Topics

TimeDateFineS

Comments

Related Topics

TimerProc_Structure

Comments

Related Topics