RTX-166 Real-Time Multitasking Executive for the 80C166 Microcontroller Family User s Guide 07.96

Transcription

1 RTX-166 Real-Time Multitasking Executive for the 80C166 Microcontroller Family User s Guide Keil Elektronik GmbH Keil Software, Inc. Bretonischer Ring Dallas Parkway, Suite 120 D Grasbrunn b. München Dallas, Texas (49) (089) Phone (800) Sales (49) (089) Fax (214) Phone (214) Fax

2 Contents CONTENTS III 1. Overview Summary of the Major System Features Tasks Interrupt System System Clock Operating Resources Program Example Installation Software Requirements Backing Up Your Disks Installing the Software Directory Structure Programming Concepts Task Management Task States Task Switching Task Classes Task Declaration Task Instances Interrupt Management Methods for Interrupt Handling Handling of the 80C166 Interrupt H/W Declaration of C166 Interrupt procedures Task Communication Signals Wait for a Signal Send Signal Clear Signal Mailboxes Mailbox Types Mailbox Lists Send a Message to a Mailbox Read a Message from a Mailbox Semaphores Initialize Semaphore Wait for Token Send Token Dynamic Memory Management Generate Memory Pool Request Memory Block from Pool Return Memory Block to Pool Check Number of free Blocks in Pool Time Management Set Time Slice... 16

3 IV RTX Delay a Task Wait Loop Time-out Cyclic Task Activation Read System Time-Base Exception Handling Install User-Written Error-Handler Un-install User-Written Error-Handler Get last Error Code Specific C166 Support Use of the C166 Runtime Library Support of C166 Memory Models Programmer s Reference Name Conventions Return Values INCLUDE Files RTX Type Definitions Object Handles Overview Initialize and Start the System...6 Function Call Overview... 6 os_start_system... 9 os_heap_use...16 os_heap_use_far Task Management...20 Function Call Overview...20 os_create_task...21 os_delete_task...24 os_change_prio...26 os_pass_task...27 os_running_task_prio...29 os_running_task_id Interrupt Management...31 Function Call Overview...31 os_attach_interrupt...32 os_detach_interrupt...35 os_enable_isr...37 os_disable_isr...39 os_wait_interrupt General Wait Function...43 Function Call Overview...43 os_wait Signal Functions...49 Function Call Overview...49 os_send_signal...50 os_clear_signal...52 os_wait_signal...53 isr_clear_signal...55 isr_send_signal Message Functions...57

4 Contents V Function Call Overview...57 os_create_mailbox...62 os_delete_mailbox...65 os_check_mailbox...67 os_send_message...69 isr_send_message...72 isr_recv_message...74 os_wait_message Semaphore Functions Function Call Overview...78 os_create_semaphore...79 os_delete_semaphore...81 os_send_token...82 os_wait_token Memory Management Function Call Overview...86 Example for a Buffer Pool Application...86 os_create_pool...88 os_get_block...91 os_free_block...93 os_check_pool Time Management Function Call Overview...97 os_set_slice...98 os_delay_task...99 os_set_timeout os_check_timeout os_set_interval os_wait_interval os_get_timebase Exception Handling Function Call Overview os_set_error_handler rtx_default_error_handler os_get_error_code Configuration Graphical Configuration Utility Graphical Configuration Utility Running the Configuration Utility Configuration Options Memory Assignment System- and Context-Heap System Stack User Stack Task Workspace Register Bank Summary of the User-Configurable Values Debug Support... 1

5 VI RTX Debug Libraries Principle of Operation Sample Application Description of Debug API Status Monitor Task Features Sample Application Customization Overview Requirements Adaptation Module Description Module RTXMON Module RTXDISP Module RTXKEYB Module DISP Module KEYB Module SERIO Application Example RTX-51 Compatibility Configuration RTX51API Compatibility Mode Common Problems and Differences Program Example...6 Glossary...11 RTX-166 / CAN...1 PREFACE INTRODUCTION CONCEPT APPLICATION INTERFACE Function Call Overview Function Call Description...9 can_task_create...10 can_hw_init...11 can_def_obj...15 can_def_obj_ext...17 can_undef_obj...19 can_stop...20 can_start...21 can_send...22

6 Contents VII can_write can_receive can_def_buf_size can_bind_obj can_unbind_obj can_wait can_request can_read can_get_status can_get_errors CONFIGURATION Hardware Requirements Configuration Files Memory/System Requirements Linking RTX-166/CAN APPENDIX A: RETURN VALUES APPENDIX B: TIMING / INITIALIZATION Quick Start Bit Timing Sample Point Configuration Requirements APPENDIX C: APPLICATION EXAMPLE APPENDIX D: FILES DELIVERED APPENDIX E: RTX-51/CAN Compatibility Index 1

7 Programming Concepts Programming Concepts 3.1. Task Management The main function of tasks within a Real-Time Multitasking Executive is the time-critical processing of external or internal events. A priority can be assigned to the individual tasks to differentiate between those which are more important. In this case, value 127 corresponds to the highest priority and value 0 corresponds to the lowest priority. RTX-166 always assigns the READY task with the highest priority to the processor. This task only remains control over the processor until another task with a higher priority is ready for execution, or until the task itself surrenders the processor again (preemptive multitasking). If several READY tasks exist with the same priority, a task switching can optionally occur after completion of a time slice (round-robin scheduling). Use the following guideline when assigning task priorities: The application should work error free regardless of task priorities. The priorities only serve for time optimizing Task States RTX-166 recognizes four task states: READY RUNNING (ACTIVE) BLOCKED (WAITING) SLEEPING All tasks which can run are READY. One of these tasks is the RUNNING (ACTIVE) task. Task which is currently being executed by the processor. Only one task can be in this state at a time. Task waits for an event. All tasks which were not started or which have terminated themselves are in this state. An event may be the reaching of a period of time, the sending of a message or signal, or the occurrence of an interrupt. These types of events can lead to state changes of the tasks involved; this, on the other hand, can produce a task switching (task change, task switch). The states "READY", "RUNNING" and "BLOCKED" are called active task states, since these can only be accepted by tasks which were started by the user (see system function

8 3-2 RTX-166 "os_create_task"). "SLEEPING" is an inactive task state. It is accepted from all tasks which were declared but still have not been started.

9 Programming Concepts 3-3 The figure shows the three active task states and their interaction. READY Ta sk Sw itc hi ng Processor is released by running task which starts waiting for an event. Highest priority ready task starts running. RUNNING Event for task with higher priority occurs. It preempts running task, which is inserted in list of ready tasks. Event for task occurs, which has higher priority than running task: it preempts it. Task starts waiting for an event. Processor is assigned to next ready task. The RTX-166 system section, which the processor assigns to the individual tasks is referred to as the scheduler (also dispatcher). The RTX-166 scheduler works according to the following rules: The task with the highest priority of all tasks in the READY state is executed. Event for task occurs. Task has lower priority than running task: it is inserted in list of ready tasks. If several tasks of the same priority are in the READY state, the task is started which has not executed the longest period of time (first in the queue). Task switchings are only executed if the first rule would have been otherwise violated (exception: round-robin scheduling). BLOCKED These rules are strictly adhered to and never violated at any time. As soon as a task yields a state change, RTX-166 checks whether a task change is necessary based on the scheduling rules. Time-slice task changes (round-robin scheduling) are executed if the following conditions are satisfied: Round-robin scheduling must be enabled (see configuration). The last task change must have occurred after the selected system time interval (see system function "os_set_slice"). The system time interval can be changed dynamically during program execution. The operating mode preferred by RTX-166 is the preemptive scheduling. If desired by the user, tasks of same priority level can additionally be managed by means of the round-robin scheduling.

10 3-4 RTX Task Classes RTX-166 basically recognizes two classes of tasks: Fast Tasks Contain especially short response and task switch times. Contain a separate register bank and a separate stack area. Can be interrupted by C166 interrupt procedures. A maximum of 126 fast tasks can be declared. Standard Tasks Require somewhat more time for the task switching compared to fast tasks. Share a common register bank and a common stack area. The current contents of registers and stack are stored in the external memory (workspace of the task) during a task change. Can be interrupted by C166 interrupt procedures. A maximum of 256 standard tasks can be declared. Each standard task contains a context area in the external memory. During a task change with standard tasks, all required registers of the running task and of the standard task stack are stored in the corresponding context area. Afterwards, the registers and the standard task stack are reloaded from the context area of the task to be started (swapping). In the case of fast tasks, a task change occurs considerably faster than for standard tasks, since each fast task has a separate register bank and a separate stack area. During a task change to a fast task, only the active register bank and the current stack pointer value must be changed (beside some other CPU registers).

11 Programming Concepts Task Declaration C166 provides an extended function declaration for defining tasks. A task is declared as follows: void func (void) _task_ <taskno> [_priority_ <prio>] [using <rb_id>] Tasks cannot return a value (return type "void"). No parameter values can be passed to tasks ("void" in parameter list). <taskno> is a number assigned by the user in the range Each task must be assigned a unique number. This task number is required in the "os_create_task" system function call for identifying a task. A maximum of 256 tasks can be defined and active. <prio> determines the priority of the task. The value 0 corresponds to the lowest possible priority, value 127 corresponds to the highest possible priority. If no priority is specified, RTX-166 uses the task priority 0. <rb_id> identifies a register bank. This declaration implicitly defines a task to be a fast task. For each fast task a separate register bank has to be used. Examples of task declarations: Example 1: Standard task with task number 8 and priority 0 void example_1 (void) _task_ 8 _priority_ 0 or void example_1 (void) _task_ 8 Example 2: Fast task with task number 134 and priority 3 void example_2 (void) _task_ 134 _priority_ 3 using rb_task134 Example 3: Standard task with task number 5 and priority 7 void example_3 (void) _task_ 5 _priority_ 7

12 3-6 RTX-166 Example of typical task layouts: Task 1 Task 2 Initialisation Initialisation Function to be performed once for each event. Function to be performed once. System call: wait for event System call: delete itself Task 1 shown in the figure above has to perform a certain action each time an event occurs. Such an event may be a received message, a signal or a time-out, just to mention a few. After completing its action it will start to wait for a new event. In this way the task will not consume time just waiting for the next event. Task 2 shown in the figure above has to perform just one specific action. It will delete itself after completing its job. Such a task may be for example a self test, which has to be executed once at power-up. It is often desirable to write such a self test routine as a separate task, than packing it in a routine Task Instances Not only can you run more than one task at a time with RTX-166, you can also run more than one copy, or instance, of the same task at a time. To distinguish one instance from another, RTX supplies a unique instance handle (a unique integer identifying the task) each time the "os_create_task" function is called by the application. To run more than one instance of a task, some rules have to be observed: All data storage of the task must be declared locally to the task function (i.e. as automatic variables).

13 Programming Concepts 3-7 Fast Tasks can not be instantiated more than once, as L166 assigns exactly one register bank for each Fast Task number. RTX uses the same code for all instances of a particular task number. This saves as much space as possible for other task code and data. However, this method requires that the code of the task remains unchanged while any one of the instances is running (this is in a ROM target system guaranteed) Interrupt Management The management and processing of hardware interrupts is one of the major jobs of a Real- Time Multitasking Executive. RTX-166 provides various types of interrupt handling; the usage depends on the application requirements Methods for Interrupt Handling RTX-166 provides two different methods for handling interrupts. One of the two methods can be additionally divided into two sub-classes: (1) C166 Interrupt procedures (2) RTX-166 task interrupts - Fast task interrupts - Standard task interrupts Method (1) corresponds to the standard C166 interrupt procedures which can even be used without RTX-166 (also referred to as ISR, Interrupt Service Routine). When an interrupt occurs, a jump is made to the corresponding interrupt procedure directly and independent of the currently running task. The interrupt is processed outside of RTX-166 and therefore independent of the task scheduling rules. With method (2), a fast or standard task is used to handle an interrupt. As soon as this interrupt occurs, the WAITING (BLOCKED) task is made READY and started according to the task scheduling rules. This type of interrupt processing is completely integrated in RTX-166. A hardware interrupt is handled identical to the receipt of a message or a signal (normal event within RTX-166). The possible methods to handle interrupts have specific advantages and disadvantages, as described in greater detail in the following section. One of the methods can be selected depending on the requirements of the interrupt source and the application. The methods can be combined in any form within a program. The following summary illustrates the special features of the individual methods for handling interrupts:

14 3-8 RTX-166 Method C166 Interrupt Fast Task Standard Task Function (ISR) Interrupt very fast medium slow Response Time ( < 1 µs) 1) (about µs) 1) (about µs) 1)2) Interrupts never - all system - all system Disabled During (interrupt lock- functions (including functions (including out time = 0 µs) System Clock Task) System Clock Task Interruptable - ISR of higher prio. - ISR - ISR With - any task with higher - any task with priority higher priority - System Clock Task - System Clock Task System many many none Resources Used (stack and usually (stack and extra (stack and register extra register bank) register bank) bank is shared with other standard tasks) Interrupt static dynamic dynamic Assignment Allowed RTX-166 some special all all System Calls 1) : A clock frequency of 20 MHz is assumed. 2) : Time increases with growing stack The following points of emphasis deal with the features of the individual methods for handling interrupts mentioned above: C166 Interrupt procedures - Very sudden, periodically occurring interrupts without large coupling with the rest of the system (only infrequent communication with RTX-166 tasks, etc.). - Very important interrupts which must be served immediately independent of the current system state. Fast Task Interrupts - Important or periodic interrupts which must heavily communicate with the rest of the system when they occur. Standard Task Interrupts - Only seldom occurring interrupts which must not be served immediately Handling of the 80C166 Interrupt H/W RTX-166 must have sole control over the CPU Priority Field (PSW ) of the 80C166 in order to adhere to the dispatcher rules and guarantee error-free execution of interrupt procedures. The CPU Priority Field (PSW ) of the 80C166 is managed by RTX-166 and must not be directly manipulated by the user!

15 3-12 RTX Mailboxes By means of the mailbox concept, messages can be exchanged free of conflicts between the individual tasks. RTX-166 provides a variable number of mailboxes. Messages can be exchanged in different message sizes through these mailboxes. There are two message size types supported. The first type (used by mailboxes with the VAR_SIZE attribute) allows the exchange of messages containing an arbitrary number of bytes (up to 16 kb). The complete message of variable size is copied to the receiver task by the mailbox. The second type (used by mailboxes with the FIX_SIZE attribute) copies only the address of a user owned buffer to the receiving task. Only a word or a double-word (depending on used memory model) is exchanged, because the message represents the identification of a data buffer (defined by the user). In comparison to the signals, mailboxes are not assigned a fix task, but can be freely used by all tasks and (under certain conditions) with interrupt procedures. These are identified with a mailbox handle. Mailboxes allow the following operations: Create and initialize a mailbox Send a message Read a message Check free space in mailbox for messages Mailbox Types Concerning the message size two types of mailboxes are supported. They are characterized as follows: Type Message Content Application Advantages Disadvantages VAR_SIZE Any number of data bytes. Slow mailbox FIX_SIZE Address of a user owned buffer. The complete data has to be passed directly to the receiver. The data itself is stored in a user owned buffer. Only the identification of this buffer has to be passed to the receiver. No buffer handling is required. Good task de-coupling. Fast mailbox operations. Best suited if buffer handling is used anyway. operations for big data blocks. Buffer handling required. Sending task allocates a buffer, receiver releases it. Concerning the combined use of the mailbox by tasks and interrupt procedures additional sub-types (so-called transfer types) are defined:

16 Programming Concepts 3-13 TSK_TO_TSK: ISR_TO_TSK: TSK_TO_ISR: Tasks may send and receive messages from this mailbox ISR's send and tasks receive messages from this mailbox Tasks send and ISR's receive messages from this mailbox The message size type and the transfer type of a particular mailbox are selected as separate attributes, when it is created (see "os_create_mailbox"). Afterwards no types have to be specified, however, operations not compatible with the selected type will be recognized by RTX-166 as errors Mailbox Lists Each mailbox internally consists of three wait lists. The user does not have direct access to these lists. Knowledge of their functions is, however, an advantage for understanding mailbox functions: (1) Message list List of the messages written in the mailbox. These comprise a variable maximum number of messages, depending on the message sizes and the initially defined list size. (2) Write wait list Wait list for tasks which want to write a message in the message list of the mailbox (maximum 256 tasks). (3) Read wait list Wait list for tasks which want to read a message from the message list of the mailbox (maximum 256 tasks). The message list is implemented as a FIFO queue (First-In, First-Out) without priority assignment; i.e., when read, the message that waits the longest (first in the queue) becomes the oldest messages in the mailbox. The write and read wait lists are ordered according to task priorities. The task with the highest priority waiting will be served first. Wait lists can comprise the following states in operation: State Description Message List Write Wait List Read Wait List No messages, empty empty empty no wait tasks No messages empty empty not empty Tasks exist that want to read Messages exist, not empty empty empty no wait tasks Message list is full, full not empty empty Tasks exist that want to write

17 3-14 RTX Send a Message to a Mailbox Each task can send a message to any arbitrary mailbox. In this case, the message to be sent is copied in the message list. For VAR_SIZE type mailboxes the sending task therefore has free access to the message after the sending. For FIX_SIZE type mailboxes the address of a user owned buffer was copied only. It is the user's responsibility to manage access to such buffers in this case. If the message list of the mailbox is already full during the sending, the task is placed in the wait state (entered in the write wait list). It remains in the wait state until another task fetches a message from the mailbox and, thus, provides space. As an alternative, a time limit can also be specified for the sending after the waiting is aborted (if the message could not be entered in the mailbox). If the message list is not full when the sending occurs, the message is immediately copied in the message list and the task must not wait Read a Message from a Mailbox Each task can read a message from an arbitrary mailbox. If the message list of the mailbox is currently empty (no message available), the task is placed in the wait state (entered in the read wait list). It remains in the wait state until another task sends a message to the mailbox. As an alternative, a time limit can also be specified for the reading after which the waiting is to be aborted (if no message is available). If the message list is not empty when reading, then the reading task immediately receives the message. It must not wait in this case Semaphores By means of the semaphore concept, resources can be shared free of conflicts between the individual tasks. In a multi-tasking system there is often competition for resources. When several tasks can use the same portion of memory, the same serial I/O channel or another system resource, you have to find a way to keep the tasks out of each other's way. The semaphore is a protocol mechanism, which is used primarily to control access to shared resources (mutual exclusion). A semaphore contains a token that your code acquires to continue execution. If the resource is already in use, the requesting task is blocked until the token is returned to the semaphore by its current owner. There are two types of semaphores: binary semaphores and counting semaphores. As its name implies, a binary semaphore can only take two values: zero or one (token is in or out). A counting semaphore, however, allows values between zero and Three operations are possible for semaphores:

18 Programming Concepts 3-15 Initialize semaphore Wait for token(s) Return token(s) Initialize Semaphore The application can create up to 256 semaphores either of the binary or counting type. The initial token count contained by the semaphore can be selected (see system function "os_create_semaphore") Wait for Token A task requesting a resource controlled by a semaphore can obtain one or more tokens from this semaphore by a wait operation (see system functions "os_wait_token" and "os_wait"). If enough tokens are available the task will continue its execution. Otherwise it will be blocked until the required number of tokens is available or an optional time limit is exceeded Send Token After completing its operation on a resource a task will return the associated token(s) to the semaphore by a send function (see system function "os_send_token"). The number of tokens returned may be selected Dynamic Memory Management Dynamic memory space is often desired in a multitasking system for generating intermediate results or messages. The requesting and returning of individual memory blocks should be possible within constant time limits in a real-time system. Memory management which function with memory blocks of variable size such as the standard C functions "malloc()" and "free()" are less suitable for this reason. RTX-166 uses a simple and effective algorithm which functions with memory blocks of a fixed size. All memory blocks of the same size are managed in a so-called memory pool. A maximum of 256 memory pools each a different block size can be defined. A maximum of 255 memory blocks can be managed in each pool. Four operations are possible for memory pools: Create and initialize a pool Request memory block from pool Return memory block to pool Check number of free blocks in pool

19 4-4 RTX Overview Initialize and Start the System: os_start_system (*config_data) os_heap_use (), os_heap_use_far () Task Management: os_create_task (*task, task_number, wsp_size) os_delete_task (task) os_change_prio (new_priority) os_pass_task () os_running_task_prio () os_running_task_id () Interrupt Management: os_attach_interrupt (task, interrupt_nbr) os_detach_interrupt (task) os_enable_isr (interrupt_nbr) os_disable_isr (interrupt_nbr) os_wait_interrupt (timeout) General Wait Function: os_wait (event_selector, timeout, *buf_ptr, buf_size, mailbox, semaphore) Signal Functions: os_send_signal (task) os_wait_signal (timeout) os_clear_signal (task) isr_send_signal (task) isr_clear_signal (task) Message Functions: os_create_mailbox (*mailbox, msg_buf_size, size_attr, type_attr) os_delete_mailbox (mailbox) os_check_mailbox (mailbox) os_send_message (mailbox, timeout, *msg_ptr, msg_size) os_wait_message (mailbox, timeout, *buf_ptr, buf_size, timeout) isr_send_message (mailbox, *msg_ptr, msg_size) isr_recv_message (mailbox, *buffer_ptr, buffer_size) Semaphore Functions: os_create_semaphore (*semaphore, max_count, initial_count) os_delete_semaphore (semaphore) os_send_token (semaphore, token_count) os_wait_token (semaphore, token_count, timeout) Dynamic Memory Management: os_create_pool (*pool, block_size, *memory_ptr, mem_size)

20 Programmer s Reference 4-5 os_get_block (pool) os_free_block (pool, *block) os_check_pool (pool) Time Functions: os_set_slice (timeslice) os_delay_task (delay) os_set_timeout (timelimit) os_check_timeout () os_set_interval (task, interval) os_wait_interval () os_get_timebase() Exception Handling: os_set_error_handler (new_handler) rtx_default_error_handler (err_code, system_call) os_get_error_code ()

21 Programmer s Reference 4-9 os_start_system Task function Initialize RTX-166 and make the main program the first task (= main task). This function is normally called in the main program (main) of the C166 application. For more details about starting up RTX-166: see preceding chapter. Prototype: t_rtx_exit os_start_system (t_rtx_config *config_data) Parameter: config_data contains all the data, which RTX-166 during its startup needs to configure system tables. RTX-166 allocates several system tables dynamically to optimize RAM usage for each application. The data type 't_rtx_config' is especially defined for this parameter. It has a different structure for the TINY and SMALL models compared with the COMPACT/MEDIUM/LARGE memory models. For the TINY and SMALL models only one heap is used by RTX-166. This heap is located in near memory space and serves for system data and for context storage allocation, as well. Type definition for COMPACT/MEDIUM/LARGE memory model: typedef struct t_rtx_config { unsigned int unsigned int unsigned int unsigned int unsigned int unsigned int BOOLEAN unsigned int huge unsigned long BOOLEAN unsigned int near unsigned int } t_rtx_config; max_tasks; max_mailboxes; max_semaphores; max_mem_pools; idle_wsp_size; clock_wsp_size; round_robin; *system_pool; system_pool_size; rtx51; *context_pool; context_pool_size; Type definition for TINY/SMALL memory model: typedef struct t_rtx_config { unsigned int unsigned int unsigned int unsigned int unsigned int unsigned int BOOLEAN max_tasks; max_mailboxes; max_semaphores; max_mem_pools; idle_wsp_size; clock_wsp_size; round_robin;

22 4-10 RTX-166 unsigned int near unsigned int BOOLEAN } t_rtx_config; *system_pool; system_pool_size; rtx51; Explanation of the individual fields: max_tasks: Maximum number of tasks, which may be created (active) at any time. This number defines how many descriptors are built at startup. By configuring this number the amount of used RAM may be optimized. For each descriptor about bytes (depending on memory model used) are required. Note, that 3 descriptors are already in use, before any user tasks are activated. They are used by the idle task, the clock task and the main task. This number may be well below the number of declared tasks, if there is no need, that all of them have to be active (created) at the same time. Permissible rage is max_mailboxes: Maximum number of mailboxes, which may be created (active) at any time. This number defines how many descriptors are built at startup. By configuring this number the amount of used RAM may be optimized. For each descriptor about bytes (depending on memory model used) are required. Note, that this number does not include the space required for the message FIFO. Permissible rage is max_semaphores: Maximum number of semaphores, which may be created (active) at any time. This number defines how many descriptors are built at startup. By configuring this number the amount of used RAM may be optimized. For each descriptor about bytes (depending on memory model used) are required. Permissible rage is max_mem_pools: Maximum number of memory pools, which may be created (active) at any time. This number defines how many descriptors are built at startup. By configuring this number the amount of used RAM may be optimized. For each descriptor about bytes (depending on memory model used) are required. Note, that the space for the pool itself is not contained in this number. Permissible rage is idle_wsp_size: Workspace size allocated for the idle task (number of bytes). This size may be configured to meet different applications. The

23 Programmer s Reference 4-11 required workspace depends on the number of possible interrupt nesting. The number of nested interrupts depends on the number of used priority levels. The idle task may be interrupted by all ISR's and all task interrupts. For hints about useful values: see description of 'os_create_task'. clock_wsp_size: Workspace size allocated for the clock task (number of bytes). This size may be configured to meet different applications. The required workspace depends on the number of possible interrupt nesting. The number of nested interrupts depends on the number of used priority levels. The idle task may be interrupted by all ISR's and all task interrupts. For hints about useful values: see description of 'os_create_task'. round_robin: By use of this flag the round-robin scheduling may be switched on or off. The value TRUE means "on", while the value FALSE means "off". rtx51: When set to TRUE a special RTX-51 compatibility mode of RTX- 166 will be enabled (see chapter "RTX-51 Compatibility"). Otherwise, when set to FALSE, this RTX-51 compatibility mode is not used. *system_pool (TINY/SMALL model): A memory area has to be reserved for the RTX system heap. This heap is used to allocate system tables, mailbox message lists and task workspaces during startup and operation of RTX-166. This parameter has to point to the start of this memory area. This memory area has to be situated in the near RAM area and it may have a size up to 16 kb (limited to data page size). system_pool_size (TINY/SMALL model): Size of reserved memory for system pool (number of bytes). This size may be estimated by observing the number of bytes returned by the "os_heap_use call at a time when all tasks and mailboxes have been created. Note: if you are using big mailbox message lists, then a considerable amount of memory has to be added to the system pool. *system_pool (COMPACT/MEDIUM/LARGE model): A memory area has to be reserved for the RTX system heap. This heap is used to allocate system tables and mailbox message lists during startup and operation of RTX-166. This parameter has to point to the start of this memory area. This memory area may be situated anywhere in the RAM and it may have any size, as it is declared as a huge data block. It is important to know, that

24 4-12 RTX-166 the RTX heap manager will allocate only blocks, which are inside of the same data page (allows far addressing for RTX). Thus the total heap size possibly has to be greater than the total requested memory by RTX. system_pool_size (COMPACT/MEDIUM/LARGE model): Size of reserved memory for system pool (number of bytes). This size may be estimated by observing the number of bytes returned by the "os_heap_use_far call at a time when all mailboxes have been created. Note: if you are using big mailbox message lists, then a considerable amount of memory has to be added to the system pool. *context_pool (COMPACT/MEDIUM/LARGE model only): A memory area has to be reserved for the RTX context heap. This heap is used to allocate task workspaces during startup and operation of RTX-166. This parameter has to point to the start of this memory area. As the workspace of a task contains its context save area and its private user stack, it is required, that the context heap is located in NDATA memory (-> declared with 'near' attribute). context_pool_size (COMPACT/MEDIUM/LARGE model only): Size of reserved memory for context pool (number of bytes). This size may be estimated by adding up all workspaces needed for system and user tasks. If you are using a common workspace size of (for example) WSPSIZE, then the context_pool_size has to be set to "max_tasks" multiplied by WSPSIZE. This size may also be determined by observing the number of bytes returned by the "os_heap_use call at a time when all tasks have been created. Note: to optimize RAM usage it may be an advantage to use different workspace sizes for Standard and Fast Tasks (more information about useful workspace sizes is presented in the description of "os_create_task"). Return value: Completion code of RTX-166 system startup. OK: System could be started successfully NOT_OK: System could not be started. One of the following errors was determined: Hardware initialization error during starting. RAM allocation error (system heap to small). System tasks could not be created (max_tasks too small or not enough memory from context pool is available). System tables could not be initialized because of a RAM failure (there is no RAM or there is ROM).

25 Programmer s Reference 4-13 See also: os_create_task, os_heap_use, os_heap_use_far Note: (1) This is the first function of RTX-166, which may be called in a program. If any other function is called first, then results are unpredictable. (2) The parameter variable rtx_conf must keep its values during operation of RTX-166, as the operating systems accesses it not only in "os_start- _system", but also during some other system functions. It is for example possible to switch "on" or "off" the round robin scheduling after completion of "os_start_system" by modifying rtx_conf->round_robin. (3) No calls to the system error handler are done, if the system call completes with exit code NOT_OK. Example for COMPACT/MEDIUM/LARGE: #include <rtx166.h> /* Use a default size for task work spaces: this figure has to be changed to meet your application s needs. */ #define WSPSIZE 256 /* Reserve space for the system heap: 20 Kbytes */ unsigned int huge system_heap[0x2800]; /* Reserve space for the context heap: 4 Kbytes */ unsigned int near context_heap[0x800]; /* Declare a variable for dynamic configuration */ t_rtx_config rtx_conf; void main (void) { /* Set up configuration record */ rtx_conf.max_tasks = 8; /* main task + 5 other tasks */ rtx_conf.max_mailboxes = 2; rtx_conf.max_semaphores = 4; rtx_conf.max_mem_pools = 0; rtx_conf.idle_wsp_size = WSPSIZE; rtx_conf.clock_wsp_size = WSPSIZE; rtx_conf.round_robin = TRUE; rtx_conf.system_pool = system_heap; rtx_conf.system_pool_size = sizeof(system_heap); rtx_conf.rtx51 = FALSE; rtx_conf.context_pool = context_heap; rtx_conf.context_pool_size = sizeof(context_heap);

26 4-14 RTX-166 } /* Initialize system before making any system calls */ if (os_start_system (&rtx_conf)) { /* RTX-166 could not be started: make a useful error handling */... error handling for (;;); } else { /* RTX-166 is running now: Create the first tasks and mailboxes or make anything else (for example initialization of your hardware). */... /* If the main task has fulfilled its job, then it may be deleted (for example) */ if (!os_delete_task (os_running_task_id())) { /* Termination failed: display an error message or make something else */... for (;;); } Example for TINY/SMALL: #include <rtx166.h> /* Use a default size for task work spaces: this figure has to be changed to meet your application s needs. */ #define WSPSIZE 256 /* Reserve space for the system heap: 10 Kbytes */ unsigned int near system_heap[0x1400]; /* Declare a variable for dynamic configuration */ t_rtx_config rtx_conf; void main (void) { /* Set up configuration record */ rtx_conf.max_tasks = 8; /* main task + 5 other tasks */ rtx_conf.max_mailboxes = 2; rtx_conf.max_semaphores = 4; rtx_conf.max_mem_pools = 0; rtx_conf.idle_wsp_size = WSPSIZE; rtx_conf.clock_wsp_size = WSPSIZE; rtx_conf.round_robin = TRUE; rtx_conf.system_pool = system_heap; rtx_conf.system_pool_size = sizeof(system_heap); rtx_conf.rtx51 = FALSE;

27 Programmer s Reference 4-15 /* Initialize system before making any system calls */ if (os_start_system (&rtx_conf)) { /* RTX-166 could not be started: make a useful error handling */... error handling for (;;); } else { /* RTX-166 is running now: Create the first tasks and mailboxes or make anything else (for example initialization of your hardware). */... /* If the main task has fulfilled its job, then it may be deleted (for example) */ if (!os_delete_task (os_running_task_id())) { /* Termination failed: display an error message or make something else */... for (;;); }

28 4-44 RTX-166 os_wait Task function This is the general RTX-166 wait function. "os_wait" can be used to wait for one or more events. Events can be any combination of an interrupt, signal, semaphore token, time-out, end of interval or mailbox message. If one of the specified events occurs, the called task is made READY again (OR'ing the individual events). If a wait for just one event (interrupt, token, signal, message, interval) possibly combined with time-out is desired, then specialized wait functions may be used (i.e. os_wait_interrupt, os_wait_token, os_wait_signal, os_wait_message, os_delay_task, os_wait_interval). Prototype: t_rtx_exit os_wait (unsigned int event_selector, unsigned int timeout, void *buffer_ptr, unsigned int buffer_size, t_rtx_handle mailbox, t_rtx_handle semaphore) Parameter: event_selector specifies the events which are to be waited for. "os_wait" will wait until one of the selected events occur, i.e. it will wait until event1 OR event 2 OR.. occurs. To select one or more events, they have to be specified by using an OR connection: event_selector = <event1> [ <event2>] [ <event3>]... [ eventn] For '<event?>' the following symbols are defined: K_MBX wait for a message from a mailbox K_INT wait for an interrupt K_SIG wait for a signal K_TMO wait for a time-out K_IVL wait for end of interval K_SEM wait for a token from a semaphore Example1: to wait for an interrupt and a signal: event_selector = K_INT K_SIG; Example2: to wait for a message and a signal and a time-out: event_selector = K_MBX K_SIG K_TMO;

29 Programmer s Reference 4-45 timeout determines the number of system intervals to occur until a timeout event occurs. This parameter is insignificant if the wait time for timeout (K_TMO) was not specified. The parameter can have the following values : : Number of system intervals for which the task should wait for. If the value 0 was specified, the system checks if one of the other specified events already occurred (interrupt already pending, signal already set, etc.). If no other event was specified, or if no other event already occurred, the system function returns the time-out return value (TMO_EVENT). Otherwise, the corresponding event value is returned. NILCARD (=65535): Endless waiting (same function like without waiting for time-out (K_TMO)). *buffer_ptr points to a variable where the message that is read by the mailbox is to be stored. This parameter is insignificant if no wait for a message was specified by mailbox (a null pointer can be specified). buffer_size is the size of the message buffer (in bytes), which has to be declared by the user. This parameter is insignificant, if no wait for message is selected or a mailbox of the FIX_SIZE type is addressed. mailbox identifies the mailbox (mailbox handle), a message shall be received from. This parameter is insignificant, if no wait for message is selected. semaphore identifies the semaphore (semaphore handle), a token shall be obtained from. This parameter is insignificant, if no wait for semaphore is selected. Return value: MSG_EVENT: A message was received from mailbox and stored at memory location "buffer_ptr" points to. INT_EVENT: An interrupt occurred. SIG_EVENT: A signal was received. SEM_EVENT: A token was received. TMO_EVENT: A time-out occurred. IVL_EVENT: An end of interval occurred. NOT_OK: Function not executed, one of the following errors was determined: Specified mailbox does not exist. Code passed to system error handler is BAD- HANDLE_ERROR. Specified semaphore does not exist.

30 4-46 RTX-166 Code passed to system error handler is BAD- HANDLE_ERROR. No interrupt is attached to task. Code passed to system error handler is GENERAL_- ERROR. Interval already expired. Code passed to system error handler is INTERVAL_- ERROR. No interval timer is set up for task. Code passed to system error handler is GENERAL_- ERROR. See also: os_wait_interrupt, os_wait_token, os_wait_signal, os_delay_task, os_wait-_message, os_send_message, isr_send_message, isr_recv_message, os_wait_interval, os_set_interval Note: (1) The "os_wait" function specifies implicitly a token_count of 1, when a wait for semaphore is selected. (2) This general wait function may not be called by interrupt procedures, like any other task function. (3) Advise: do not confuse the event selector constants (K_xxx) with the event return constants (xxx_event). (4) "os_wait" checks first if there are any pending events a wait shall be made for. This check uses a fixed sequence, which is as follows: Example 1: - check for messages (if K_MBX in event_selector) - check for pending interrupt (if K_INT in event_selector) - check for pending signal (if K_SIG in event_selector) - check for available token (if K_SEM in event_selector) - check for time-out value = 0 (if K_TMO in event_selector) - check for end of interval (if K_IVL in event_selector) #include <rtx166.h> void count_task (void) _task_ 2 _priority_ 0 { /* Define Interrupt and Group Priority */ CC14IC = 0x08; /* ILVL= 2, GLVL=0 */ /* Assign interrupt 30 to this task*/ if (os_attach_interrupt (os_running_task_id(), 30)) {... error handling } for (;;) { /* Endless loop */ /* Wait for interrupt or time-out (limit = 10 ticks) */

31 Programmer s Reference 4-47 } } if (os_wait (K_INT K_TMO, 10) == TMO_EVENT) { /* If interrupt does not occur within 10 system cycles, then perform this section */ } else { /* The interrupt occurred within 10 system cycles/ interrupt processing }... task code Example 2: #include <rtx166.h> /* mbox1 and sema2 are handles initialized by a different module */ extern t_rtx_handle mbox1, sema2; void multiple_wait (void) _task_ 19 { static unsigned int mes[2]; switch (os_wait (K_MBX K_SIG K_SEM K_TMO, 10, mes, 4, mbox1, sema2)) { case MSG_EVENT: /* Message receipt from mailbox 2 in "mes" */ break; case SIG_EVENT: /* Signal receipt */ break; case SEM_EVENT: /* Token receipt */ break; case TMO_EVENT: /* No message/signal/token receipt within 10 system cycles --> time-out */......

32 4-48 RTX-166 break; } } Example 3: #include <rtx166.h> void delay_task (void) _task_ 54 _priority_ 2 { for (;;) { /* Wait only for Time-out. Such a wait could be done by 'os_delay_task', as well */ os_wait (K_TMO, 100); /* The following functions are executed all 100 system cycles */... } }

33 10-6 RTX CONCEPT The RTX-166/CAN software runs as C166 interrupt function under RTX-166 and supports the following functions: Receiving objects from the CAN network. Removing undesired messages. Notify to application task that a data frame was received by a dedicated mailbox or through a common mailbox. Sending data and remote frames as requested by the application. The interface between the application tasks and the CAN communication task is built by function calls similar to the RTX-166 system calls. The CAN interface enhances the RTX- 166 system calls with functions common to the CAN communication. APPLICATION TASK 1 APPLICATION TASK 2 APPLICATION TASK 3 Mbx 7 CAN COMMUNICATION DRIVER (C Interrupt function) Figure 1: Concept CAN CONTROLLER

34 RTX-166/CAN APPLICATION INTERFACE The CAN communication interface is similar to the RTX-166 interface. Using RTX-166/CAN with the Keil C166 compiler is straightforward. The header file RTXCAN.H is provided to simplify application programming. Each CAN function returns status information, which can be tested by the application programm. Example: #include rtxcan.h.. /* Define object 1000 */ if (can_def_obj (1000, 2, D_REC)!= C_OK) { /* Return status indicates not okay */ }.. There is one particular simplification important to be explained a little bit: This API addresses objects by an identifier consisting of a maximum of 16 bits. Nevertheless it is possible to use a full 29-bit identifier (extended identifier according to CAN specification 2.0b), if the need exists. Usually a 29-bit identifier contains many additional informations like a node number, company identifications, version numbers and so on. Therefore it is sufficient to define objects with a full 29-bit identifier, which are addressed on the same node with their 16 lowest bits only. There is one function (CAN_DEF_OBJ_EXT) which requires a 29-bit identifier; all other functions use either an 11-bit identifier or the lowest 16-bits of an extended identifier for object identification (requires 29-bit identifiers to be different in their 16 lowest bits!).

35 10-8 RTX Function Call Overview Function CAN_TASK_CREATE CAN_HW_INIT CAN_DEF_OBJ Description Initializes the CAN communication driver. Must be the first instruction to the RTX- 166/CAN software. CAN controller hardware init, defines the bus timing and the output driver configuration. Defines the communication objects (using a standard identifier). * CAN_DEF_OBJ_EXTD Defines the communication objects (using an extended identifier). * CAN_UNDEF_OBJ Undefines a previously defined object (with CAN_STOP CAN_START CAN_SEND CAN_WRITE CAN_RECEIVE standard or extended identifier) Stops the CAN communication. Starts the CAN communication. Sends an object over the CAN bus. Writes new data to an object without sending it. Receives all not binded objects. * CAN_DEF_BUF_SIZE Sets a new default buffer size for the receive CAN_BIND_OBJ CAN_UNBIND_OBJ CAN_WAIT CAN_REQUEST CAN_READ CAN_GET_STATUS mailboxes (read by CAN_WAIT) Binds an object to a task. The task will be started when the object is received. Unties the binding between a task and an object (made with CAN_BIND_OBJ or CAN_BIND_OBJ_EXTD). Waits for receiving of a binded object. Sends a remote frame for the specified object. Reads an object data direct. Gets the actual Can controller status. * CAN_GET_ERRORS Gets the actual receive and transmit error counts of an object. : these functions are not provided by RTX-51/CAN.

36 10-10 RTX-166 can_task_create Creates the CAN task. Must be the first function call before any other CAN functions are used. Declaration: unsigned char can_task_create (void); Parameter: -- Return value: C_OK C_NOT_STARTED CAN communication driver is initialized Errors while initializing the CAN communication driver Notes: 1. The CAN driver uses its own register bank and a hardware priority which may be defined in the user configurable file CONF167C.C (for 80C167C). 2. The name can_task_create was chosen for RTX-51/CAN, which uses a fast task instead of an interrupt function. To be as compatible as possible concerning the API this name was not changed for RTX-166/CAN. Example: /* Initialize the CAN driver */ if (can_task_create()!= C_OK) { /* CAN task create failed */ }..