Keil RTX51 User manual

Preface 1
Preface
This manual explains how to use the RTX51 Tiny Real-Time Operating System and gives
an overview of the functionality of RTX51 Full. The manual is not a detailed introduc-
tion to real-time applications and assumes that you are familiar with Keil C51, A51, the
related Utilities, the DOS operating system and the hardware and instruction set of the
8051 microcontrollers.
The following literature is recommended as an extensive introduction in the area of real-
time programming:
Deitel, H.M., Operating Systems, second edition,
Addison-Wesley Publishing Company, 1990
Ripps, David, A Guide to Real-Time Programming, Englewood Cliffs, N.J,
Prentice Hall, 1988/
Allworth, S.T., Introduction to Real-Time Software Design,
Springer-Verlag Inc., New York
This user’s guide contains 6 parts:
Part 1: Overview, describes the functionality of a the RTX51 real-time opeating
systems and discusses the basic features and differences of RTX51 Tiny and
RTX51 Full. Also included are the technical data of RTX51 Full and
RTX51 Tiny.
Part 2: Requirements and Definitions, discusses the development tools and the
target system requirements of RTX51 Tiny, explains the terms used in the
the RTX51 Tiny manual and decribes the task definition.
Part 3: Creating RTX51 Tiny Applicaitons, describes the steps necessary to cre-
ate RTX51 Tiny applications.
Part 4: Library Functions, provides a reference for all RTX51 Tiny library rou-
tines.
Part 5: System Debugging, describes the stack handling of RTX51 Tiny and con-
tains information about the system debugging.
Part 6: Applications Examples, contains several examples using RTX51 Tiny and
describes the software development process. This information can be used
as a guideline for your real-time designs.

2Contents
OVERVIEW..........................................................................................................7
Introduction ............................................................................................................... 7
Single Task Program.................................................................................................. 8
Round-Robin Program............................................................................................... 8
Round-Robin Scheduling With RTX51..................................................................... 8
RTX51 Events ........................................................................................................... 9
Compiling and Linking with RTX51....................................................................... 11
REQUIREMENTS AND DEFINITIONS ..............................................................15
Development Tool Requirements............................................................................................................ 15
Target System Requirements................................................................................................................... 15
Interrupt Handling ................................................................................................... 15
Reentrant Functions................................................................................................. 16
C51 Library Functions............................................................................................. 16
Usage of Multiple Data Pointers and Arithmetic Units ........................................... 16
Registerbanks........................................................................................................... 17
Task Definition ....................................................................................................................................... 17
Task Management................................................................................................................................... 17
Task Switching ........................................................................................................ 18
Events...................................................................................................................... 18
CREATING RTX51 TINY APPLICATIONS ........................................................21
RTX51 Tiny Configuration..................................................................................................................... 21
Compiling RTX51 Tiny Programs.......................................................................................................... 23
Linking RTX51 Tiny Programs .............................................................................................................. 23
Optimizing RTX51 Tiny Programs......................................................................................................... 23
RTX51 TINY SYSTEM FUNCTIONS..................................................................25
Function Reference ................................................................................................................................. 26
isr_send_signal.................................................................................................................................. 27
os_clear_signal.................................................................................................................................. 28

Preface 3
os_create_task....................................................................................................................................29
os_delete_task....................................................................................................................................30
os_running_task_id............................................................................................................................31
os_send_signal...................................................................................................................................32
os_wait...............................................................................................................................................34
os_wait1.............................................................................................................................................36
os_wait2.............................................................................................................................................37
SYSTEM DEBUGGING......................................................................................41
Stack Management...................................................................................................................................41
Debugging with dScope-51......................................................................................................................41
APPLICATION EXAMPLES...............................................................................45
RTX_EX1: Your First RTX51 Program.................................................................................................45
RTX_EX2: A Simple RTX51 Application.............................................................................................47
TRAFFIC: A Traffic Light Controller....................................................................................................49
Traffic Light Controller Commands.........................................................................49
Software ...................................................................................................................49
Compiling and Linking TRAFFIC............................................................................62
Testing and Debugging TRAFFIC ...........................................................................62

RTX Tiny 5
1
Notational Conventions
This manual uses the following format conventions:
Examples Description
BL51 Bold capital texts used for the names of executable programs, data files,
source files, environment variables, and other commands entered at the
DOS command prompt. This text usually represents commands that you
must type in literally. For example:
CLS DIR DS51.INI
C51 A51 SET
Note that you are not actually required to enter these commands using all
capital letters.
Courier Text in this typeface is used to represent the appearance of information
that would be displayed on the screen or printed on the printer.
This typeface is also used within the text when discussing or describing
items which appear on the command line.
KEYS Text in this typeface represents actual keys on the keyboard. For
example, “Press Enter to Continue.”
ALT+<x> Indicates an Alt key combination; the Alt and the <x> key must be
simultaneously pressed.
CTRL+<x> Indicates an control key combination; the Ctrl and the <x> key must be
simultaneously pressed.

RTX Tiny 7
1
Overview
RTX51 is a multitasking real-time operating system for the 8051 family of processors.
RTX51 simplifies software design of complex, time-critical projects.
There are two distinct versions of RTX51 available:
RTX51 Full Performs both round-robin and preemptive task switching using up
to four task priorities. RTX51 works in parallel with interrupt
functions. Signals and messages may be passed between tasks us-
ing a mailbox system. You can allocate and free memory from a
memory pool. You can force a task to wait for an interrupt, time-
out, or signal or message from another task or interrupt.
RTX51 Tiny Is a subset of RTX51 that will easily run on single-chip 8051 sys-
tems without any external data memory. RTX51 Tiny supports
many of the features found in RTX51 with the following excep-
tions: RTX51 Tiny only supports round-robin and the use of sig-
nals for task switching. Preemptive task switching is not sup-
ported. No message routines are included. No memory pool allo-
cation routines are available.
The remainder of this chapter uses RTX51 to refer to both variants. Differences between
the two are so stated in the text as their need becomes applicable.
Introduction
Many microcontroller applications require simultaneous execution of multiple jobs or
tasks. For such applications, a real-time operating system (RTOS) allows flexible sched-
uling of system resources (CPU, memory, etc.) to several tasks. RTX51 implements a
powerful RTOS which is easy to use. RTX51 works with all 8051 derivatives.
You write and compile RTX51 programs using standard C constructs and compiling them
with C51. Only a few deviations from standard C are required in order to specify the task
ID and priority. RTX51 programs also require that you include the real-time executive
header file and link using the BL51 Linker/Locator and the appropriate RTX51 library
file.

8RTX51 Real-Time Operating System
1Single Task Program
A standard C program starts execution with the main function. In an embedded applica-
tion, main is usually coded as an endless loop and can be thought of as a single task which
is executed continuously. For example:
int counter;
void main (void) {
counter = 0;
while (1) { /* repeat forever */
counter++; /* increment counter */
}
}
Round-Robin Program
A more sophisticated C program may implement what is called a round-robin pseudo-
multitasking scheme without using a RTOS. In this scheme, tasks or functions are called
iteratively from within an endless loop. For example:
int counter;
void main (void) {
counter = 0;
while (1) { /* repeat forever */
check_serial_io ();
process_serial_cmds (); /* process serial input */
check_kbd_io ();
process_kbd_cmds (); /* process keyboard input */
adjust_ctrlr_parms (); /* adjust the controller */
counter++; /* increment counter */
}
}
Round-Robin Scheduling With RTX51
RTX51 also performs round-robin multitasking which allows quasi-parallel execution of
several endless loops or tasks. Tasks are not executed concurrently but are time-sliced.
The available CPU time is divided into time slices and RTX51 assigns a time slice to
every task. Each task is allowed to execute for a predetermined amount of time. Then,
RTX51 switches to another task that is ready to run and allows that task to execute for a
while. The time slices are very short, usually only a few milliseconds. For this reason, it
appears as though the tasks are executing simultaneously.

RTX Tiny 9
1
RTX51 uses a timing routine which is interrupt driven by one of the 8051 hardware tim-
ers. The periodic interrupt that is generated is used to drive the RTX51 clock.
RTX51 does not require you to have a main function in your program. It will automati-
cally begin executing task 0. If you do have a main function, you must manually start
RTX51 using the os_create_task function in RTX51 Tiny and the os_start_system
function in RTX51.
The following example shows a simple RTX51 application that uses only round-robin
task scheduling. The two tasks in this program are simple counter loops. RTX51 starts
executing task 0 which is the function names job0. This function adds another task
called job1. After job0 executes for a while, RTX51 switches to job1. After
job1 executes for a while, RTX51 switches back to job0. This process is repeated in-
definitely.
#include <rtx51tny.h>
int counter0;
int counter1;
void job0 (void) _task_ 0 {
os_create (1); /* mark task 1 as ready */
while (1) { /* loop forever */
counter0++; /* update the counter */
}
}
void job1 (void) _task_ 1 {
while (1) { /* loop forever */
counter1++; /* update the counter */
}
}
RTX51 Events
Rather than waiting for a task’s time slice to be up, you can use the os_wait function to
signal RTX51 that it can let another task begin execution. This function suspends execu-
tion of the current task and waits for a specified event to occur. During this time, any
number of other tasks may be executing.
Using Time-outs with RTX51
The simplest event you can wait for with the os_wait function is a time-out period in
RTX51 clock ticks. This type of event can be used in a task where a delay is required.
This could be used in code that polled a switch. In such a situation, the switch need only
be checked every 50ms or so.
The next example shows how you can use the os_wait function to delay execution while
allowing other tasks to execute.

10 RTX51 Real-Time Operating System
1#include <rtx51tny.h>
int counter0;
int counter1;
void job0 (void) _task_ 0 {
os_create (1); /* mark task 1 as ready */
while (1) { /* loop forever */
counter0++; /* update the counter */
os_wait (K_TMO, 3); /* pause for 3 clock ticks */
}
}
void job1 (void) _task_ 1 {
while (1) { /* loop forever */
counter1++; /* update the counter */
os_wait (K_TMO, 5); /* pause for 5 clock ticks */
}
}
In the above example, job0 enables job1 as before. But now, after incrementing
counter0, job0 calls the os_wait function to pause for 3 clock ticks. At this time,
RTX51 switches to the next task, which is job1. After job1 increments counter1,
it too calls os_wait to pause for 5 clock ticks. Now, RTX51 has no other tasks to exe-
cute, so it enters an idle loop waiting for 3 clock ticks to elapse before it can continue
executing job0.
The result of this example is that counter0 gets incremented every 3 timer ticks and
counter1 gets incremented every 5 timer ticks.
Using Signals with RTX51
You can use the os_wait function to pause a task while waiting for a signal (or binary
semaphore) from another task. This can be used for coordinating two or more tasks.
Waiting for a signal works as follows: If a task goes to wait for a signal, and the signal
flag is 0, the task is suspended until the signal is sent. If the signal flag is already 1 when
the task queries the signal, the flag is cleared, and execution of the task continues. The
following example illustrates this:
#include <rtx51tny.h>
int counter0;
int counter1;
void job0 (void) _task_ 0 {
os_create (1); /* mark task 1 as ready */
while (1) { /* loop forever */
if (++counter0 == 0) /* update the counter */
os_send_signal (1); /* signal task 1 */
}
}