Data Structures used in RTOS API - SC12 @CHIP-RTOS V1.10

Data Structures

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

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;               //  maximum 4 envelopes.

  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 number of message envelopes for each of this Message Exchange's four priority mailboxes.   These counts are truncated to a maximum of 4 envelopes per mailbox inside this API.   The system's maximum number of available messages envelopes is 64 (since @CHIP-RTOS version 1.02B, else 32).

The msgID member is an output parameter from the RTX_CREATE_MSG API call.

Related Topics

API function RTX_CREATE_MSG - Create a Message Exchange

RTOS Message Exchange Manager

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_EVENTS 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.   This signed value must be non-negative.

Related Topics

API function RTX_WAIT_EVENTS - Wait for events in a group

RTOS Event Manager

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

  char 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_MSG ALI, the caller must set the following members of the RTX_Wait_Msg structure.

msgID

Here you put the message exchange ID acquired by the RTX_CREATE_MSG call.

prio

Specify here the priority of the calling task's access to the messages.   To wait in FIFO order, have all RTX_WAIT_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.

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_MSG - Wait for a message from a message exchange

RTOS Message Exchange Manager

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 (not supported by the RTOS API)

        short int      priority;     // task priority,  range: 3..127 inclusive


        unsigned short time_slice;   // 0: none, !=0: number of milliseconds before task

                                     // is forced to relinquish processor

        short       mailboxlevel1;   // not used

        short       mailboxlevel2;   // not used

        short       mailboxlevel3;   // not used

        short       mailboxlevel4;   // not used



} TaskDefBlock;

Comments

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

Prior to making the RTX_TASK_CREATE API call, the caller must set the following members of the TaskDefBlock structure.

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 C:    void huge taskfunc(void)
Microsoft C:   void far _saveregs _loadds taskfunc(void)

These assure that the data segment register (DS) is loaded on entry into your task.

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.

priority

Application program tasks can range in priority from 3 to 127 (inclusive), where 3 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.

mailboxlevelN

These provisional four values are not used in the current implementation.

Related Topics

API function RTX_TASK_CREATE - Create and start a task

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

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

Current task priority.

taskState

This bit field is zero for active tasks.   The reasons for an inactive task waiting are coded as follows:


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 - B15 internal use only

Notes:

• A task is in "trigger wait" state prior to starting (e.g. RTX_TASK_CREATE_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

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 1000 Hz real-time interrupt handler, 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, so a task which is active 100% of the time would score a taskCount of 10000.   (Same true if the task had been sleeping for the last 10 seconds, but it was the most recently active task ... oh well.)

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

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 if time/date is correct



} TimeDate_Structure;

Comments

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

Related Topics

API function RTX_GET_TIMEDATE - Get system time and date

API function RTX_SET_TIMEDATE - Set system time and date

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



} 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 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):

        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, in milliseconds, at which you want your timer procedure to be called.

Related Topics

API function RTX_INSTALL_TIMER - Install a timer procedure

RTOS Timer Procedures