KR-51
Real-Time Kernel for the 8051 family
User Manual

Document version
23 February 2010


KR-51

Contents
1. Introduction........................................................................................................................6
1.1 Purpose of this manual....................................................................................................................6
1.2 Scope of this manual.......................................................................................................................6
1.3 Additional help or information..........................................................................................................6

2. Overview............................................................................................................................7
2.1 Organisation of the manual..............................................................................................................7
2.2 General description of tasks............................................................................................................7
2.3 A first example: 2 LEDs..................................................................................................................8
2.4 The multitasking capability...............................................................................................................9
2.5 KR-51 specification..........................................................................................................................9
2.6 Simple example.............................................................................................................................10
2.7 Files supplied.................................................................................................................................10
2.8 Program development tools...........................................................................................................10
2.9 Available versions..........................................................................................................................10

3. Task description ..............................................................................................................12
3.1 Task definition...............................................................................................................................12
3.2 Task states....................................................................................................................................12
3.3 Priorities and register banks..........................................................................................................13

3.4 Clock frequency groups.................................................................................................................13
3.5 Waiting for an event.......................................................................................................................14
3.5.1 Timeout..................................................................................................................................14
3.5.2 Signal......................................................................................................................................14

4. Scheduler ........................................................................................................................15
4.1 Kernel clock...................................................................................................................................15
4.1.1 Pooler.....................................................................................................................................15
4.1.2 Initiator....................................................................................................................................16
4.2 Task execution..............................................................................................................................16
4.3 Receiver........................................................................................................................................16
4.4 Direct pooling.................................................................................................................................16
4.4.1 Principle..................................................................................................................................16
4.5 Interrupt handling...........................................................................................................................17

-2-


KR-51
4.5.1 Implementation.......................................................................................................................17
4.5.2 Register banks........................................................................................................................17
4.5.3 Kernel and parallel interrupt priority........................................................................................17
4.5.4 Response time........................................................................................................................18
4.5.5 Permissible delay....................................................................................................................18
4.5.6 Tasks/interrupts interface.......................................................................................................18
4.6 Possible actions on IE and IP registers..........................................................................................18
4.7 Task lifetime..................................................................................................................................19
4.8 Notes and suggestions..................................................................................................................19

5. Implementation...............................................................................................................20

5.1 KR-51 files and installation............................................................................................................20
5.2 Implementation..............................................................................................................................20
5.3 Task declaration ...........................................................................................................................20
5.4 Tasks written in another language.................................................................................................21
5.4.1 Significance of the different keywords.....................................................................................21
5.4.2 Kernel settings........................................................................................................................22
5.4.3 Questions...............................................................................................................................22
5.5 Saving stacks and local variables..................................................................................................23
5.5.1 Stack storage..........................................................................................................................23
5.5.2 External stack capability (external versions)...........................................................................23
5.6 Set-up utility program.....................................................................................................................25
5.7 Task editing...................................................................................................................................26
5.8 Debug versions..............................................................................................................................26
5.8.1 General...................................................................................................................................26
5.8.2 Recommendations..................................................................................................................26
5.8.3 Quick reference tables to return codes in the DEBUG utility program...................................26

6. List of services.................................................................................................................28
6.1 Types of services...........................................................................................................................28
6.1.1 System services......................................................................................................................28
6.1.2 Information services...............................................................................................................28
6.1.3 Utility services.........................................................................................................................28
6.2 Quick reference to the services.....................................................................................................28
6.3 Parameter passing convention......................................................................................................29
6.4 Values returned by services...........................................................................................................29
6.5 KR_CREATE (system function).....................................................................................................29
6.6 KR_DELETE (system function)......................................................................................................30

-3-



KR-51
6.7 KR_DEL_ABS (system function)....................................................................................................30
6.7.1 Possible problems with KR_DEL_ABS...................................................................................31
6.8 KR_DEL_REL (system function)....................................................................................................33
6.9 KR_SENDSIG (system function)...................................................................................................34
6.10 KR_WAITSIG (system function)..................................................................................................34
6.11 KR_DELSIG (or KR_DELSIG_REL)............................................................................................34
6.12 KR_DELSIG_ABS........................................................................................................................34
6.13 KR_PAUSE (system function).....................................................................................................35
6.14 List of the information services....................................................................................................35

7. Semaphore .....................................................................................................................36
7.1 Semaphores with time-outs (external versions only)......................................................................36
7.2 Normal semaphores......................................................................................................................37
7.2.1 Implementation.......................................................................................................................37
7.2.2 Semaphore services for standard semaphores......................................................................37
7.3 Implementation..............................................................................................................................37
7.4 Notes and suggestions..................................................................................................................38
7.5 Semaphores and task groups (external versions)..........................................................................38
7.6 Semaphores and task synchronisation..........................................................................................39
7.7 Resources used.............................................................................................................................39

8. Mailbox ............................................................................................................................40
8.1 Available services..........................................................................................................................40
8.1.1 MAIL_RESET(0).....................................................................................................................40
8.1.2 MAIL_SEND(char box, char message_character)..................................................................40
8.1.3 MAIL_READ (char box)..........................................................................................................40
8.1.4 MAIL_SIZE (char box)............................................................................................................41
8.1.5 MAIL_FLUSH (char box)........................................................................................................41

8.1.6 MAIL_TEST (char box)...........................................................................................................41
8.2 Notes and suggestions..................................................................................................................41
8.3 Resources used.............................................................................................................................41

9. Memory allocator (KRX) ..................................................................................................42
9.1 Available services..........................................................................................................................42
9.1.1 MEM_ALLOC .........................................................................................................................42
9.1.2 MEMFREE..............................................................................................................................42
9.1.3 PRECAUTIONAY MEASURES...............................................................................................42

-4-


KR-51
10. Calendar ........................................................................................................................43
10.1 Available services........................................................................................................................43
10.1.1 SPLIT=>COMPRESSED format : (structure=>long).............................................................43
10.1.2 COMPRESSED -> SPLIT format (long -> structure).............................................................44
10.2 Implementation............................................................................................................................45

11. Internal version: KRY ....................................................................................................46
11.1 Resources used...........................................................................................................................46
11.2 Example.......................................................................................................................................47
11.3 Performances..............................................................................................................................47

12. External versions: KRX / KRH ......................................................................................48
12.1 Resources used...........................................................................................................................48
12.2 Example.......................................................................................................................................49
12.3 Performance................................................................................................................................50


13. APPENDIX ....................................................................................................................51
13.1 TELEMEAS application (recorder)...............................................................................................51

14. Conformity......................................................................................................................74
15. Glossary.........................................................................................................................75
16. Index..............................................................................................................................76
17. History............................................................................................................................78

-5-


1. Introduction

KR-51

1. Introduction
The KR-51 executive is a real time kernel for the 8051 microcontroller family. Placed in the heart of an
application, it provides efficient task scheduling by driving :
•
task activation: initiate, waiting or termination.
•
task relationships.
KR-51 is easy to implement and permits the programmer to concentrate on each task independently.
KR-51 recognizes tasks written in either assembly, PL/M-51 or the C-51 language and provides
support for any compatible derivatives of the 8051, except the 83C751 and 83C752.

1.1 Purpose of this manual
This is a reference manual for the KR-51.

1.2 Scope of this manual

This manual is applicable to all derivatives of the 8051, except the 83C751 and 83C752.

1.3 Additional help or information
Please visit the Raisonance website: and the forum
or contact Raisonance.
Address:

Raisonance S.A.S.
17, Avenue Jean Kuntzmann,
38330 Montbonnot Saint Martin
France

Telephone:
Fax:
Email:

+33 4 76 61 02 30
+33 4 76 41 81 68


If you find any errors or omissions, or if you have suggestions for improving this manual, please let us
know by email.

-6-


KR-51

2. Overview


2. Overview
The KR-51 consists of two parts:
•
The scheduler, which is the task scheduling program.
•
The services or functions that can be called by tasks to send various requests to the scheduler.

2.1 Organisation of the manual
The chapters describe the operation of the Kernel in increasing levels of detail:
•
Overview: Corresponds to this chapter.
•
Tasks: Gives a static description of the tasks.
•
Scheduler: Describes the dynamic characteristics of the scheduler.
•
Implementation: Indicates how to use KR-51 and associate it with tasks written in a high level
language or assembly language.
•
List of services: Describes the kernel’s services.
•
Semaphores: Describes how the flag capability ensures resource sharing between tasks.
•
Mailbox: Describes the mailbox services. Mailboxes represent a powerful task communication
module.
•
Memory allocation: Permits dynamic allocation of the external memory space.
•
Calendar: Conversion to/from various formats.


2.2 General description of tasks
A task is a void function, which has no parameters, returns no value, and implements part of the user’s
application.
A typical declaration is shown in the example below:
Example: task declaration
void taski (void) task 5;

However, a task can affect its own process or that of related tasks, but always via the scheduler to
which the requests have to be sent.
Requests can be:
•
to run another task.
•
to move a task to the idle state for a given time or to wait for an event.
•
for task synchronisation or communication...
Note that task lifetime varies. It can be:
•
"permanent": the task will initiate at the beginning of the application and will never terminate,
although it can be suspended for a short duration
•
"temporary": the task is initiated for a given action.
•
"periodic": the task is initiated in a cyclic fashion at regular or irregular time intervals.

-7-


2. Overview


KR-51

2.3 A first example: 2 LEDs
Let’s see the following program:
#include <krdcl.h>

// Declarations for the services

#define _TSKLED1_ 1

// Reference task #1

#define _TSKLED2_ 2

// Reference task #2

at 0x91 sbit LED1;

// LED 1 driven by P1.1

at 0x92 sbit LED2;

// LED 2 driven by P1.2

void main (void)
{
kr_init();
kr_create(_TSKLED1_);

// Creates and runs task 1


kr_create(_TSKLED2_);

// Creates and runs task 2

while (1);

// Loop for ever

}
void tskled1 (void ) task _TSKLED1_

//Task 1

{
while (1)
{
LED1 = !LED1;

// Toggles P1.1

kr_del_abs(7);

// Waits for 7 ticks

}
}
void tskled2 (void ) task _TSKLED2_

//Task 2


{
while (1)
{
LED2 = !LED2;

// Toggles P1.2

kr_del_abs(23);

// Waits for 23 ticks

}
}

This program has to be compiled and linked with LX51. For example:
RC51 2led
LX51 2led.obj, KRX.LIB

The two permanent tasks will run forever, and the LEDS will blink:
•
at the base frequency divided by (2*7) for the task 1.
•
at the base frequency divided by (2*23) for the task 2.
The base frequency can to be set in Ride7. A typical value would be 1 KHz, which allocates time in 1
millisecond intervals.

-8-



KR-51

2. Overview

2.4 The multitasking capability
Strictly speaking, KR-51 does not support either the parallel operation or time slicing functionality used
for multi-user systems.
In fact, a parallel organisation requires a multiprocessor physical architecture. KR-51 has been
designed to operate on a standalone microcontroller only, on which only one instruction runs at a given
time within a single task).
KR-51 uses the time-slicing capabilities applicable to any 1-processor based system with an interrupt
handler.
•
In a multi-user computing system, CPU time is ‘sliced’ between different users at such a rate
that each user is unaware of the other users.
•
To the system, each user is merely a ‘task’.
•
Although time slicing offers numerous advantages, it is often unsuitable for applications
concerned with process control.
•
It is difficult to use the 8051 where a great number of different tasks must be performed, each
with often a short lifetime.
•
KR-51 thus provides time-slicing capabilities that have been modified for optimised use of the
resources available on the 8051 microcontroller.
In particular the concept of task is almost identical to that of an interrupt service routine:
•
Each task is specified by a configurable priority level between 0 and 3. As for interrupts, the
priority level feature permits context overlay on the stack, as only the initiated highest priority

task takes control of the CPU.
•
A task is given a time-slice only if it is in the waiting state, or if a higher priority task takes control
of the CPU.
In principle KRX and KRH, which use external RAM, could support a more dynamic task management
scheme where, for example, the task's priority or group can be changed during execution. However,
the current version does not support these capabilities.

2.5 KR-51 specification
The features used have been selected to best suit the 8051. The kernel was coded for the best
possible balance of conflicting requirements. Here is a list of some of the requirements:
•
execute a great number of tasks without leaving some out
•
run the highest priority tasks within the minimum delay (minimum context switch time)
•
provide reliable time management: a task that generates a square wave signal must create fixed
frequency edges. A slight offset caused by the execution of a highest priority task is possible,
but offsets should not accumulate
•
limit and minimal CPU time assigned to the kernel.
•
limit the number of resources used by the kernel (restrictions on internal RAM use).
•
provide a variety of system functions (task communication via MAILBOXES .. etc.).
•
provide resource sharing (via flags).
•
provide interrupt handling and TASK/INTERRUPT interface.
•

ensure low latency for high priority interrupts
•
best suit the resources available in the application (availability of an external RAM (XDATA) or
not...).
•
accept development tools used: compilers, assemblers,.. and support the usual parameter
passing conventions.
•
offer easy configuration by the user.
•
ensure easy debugging and provide DEBUG capabilities.

-9-


2. Overview

KR-51

2.6 Simple example
For a telemetering application, the tasks can be split as follows:
•
measurement acquisition.
•
formatting, calculation and storage of the measurements.
•
perpetual calendar/clock.
•
phone line management: monitoring, dialing,...
•

set-up dialog
•
send file handshake management.
•
local keyboard read.
•
backup battery control.
These tasks are specified by:
•
a priority level. Some can be delayed for several milliseconds or even several seconds; others
must be executed quickly.
•
a scheduling mode. Some tasks (such as perpetual calendar management) occur at regular
intervals; while others follow an asynchronous or sequential logic e.g. measurement processing
follows the measurement and will generate an alarm which will initiate phone dialing ...
•
the rate of occurrence: some tasks are initiated once a day, others every 10 milliseconds.
In this example, a compiler for a high level language provides a static structure for data and algorithms,
whereas KR-51 determines the dynamic characteristics.

2.7 Files supplied
KR-51 is supplied with:
•
12 libraries corresponding to the versions described above in the ..\LIB directory.
•
Header files needed for ‘C’, PL/M or assembler in the ..\INC directory.
•
TUTORIAL directory contains some applications showing some specific features of the kernel:
signals, semaphores...
•

README.DOC file that contains additional information which are not featured in this manual.

2.8 Program development tools
KR-51 requires the LX-51 linker and RC-51 ‘C’ compiler programs from Raisonance, and the Ride7
Integrated Development Environment is recommended to simplify project management.

2.9 Available versions
KR-51 is available in several versions with each optimised for specific requirements.
The first choice relates to the use of either the IDATA (internal RAM) or XDATA (external RAM)
memory space. Access to the internal RAM is more rapid but the space is limited, however access to
the external RAM is slower but the available space is large (64 K).
•
KRY refers to a kernel, which uses internal RAM and is well suited to applications with a limited
number of tasks or no XDATA space. KRY can be used for tasks written in the ‘C’ language if
the ‘SMALL’ memory model is used during compilation (no external stack).
•
KRX and KRH require 256 and 1024 bytes of external memory space respectively, but no
internal RAM. They offer more capability and support more tasks than KRY but are slightly
slower.
The second important choice relates to the inclusion of a ‘semaphore’ capability. Without semaphores
the KR-51 module is more rapid and uses less RAM, as the processes and resources required by this
feature are ignored. (Semaphores are used to share resources between tasks: e.g. to control access to
sensitive global variables or peripherals).

- 10 -


KR-51

2. Overview


Version

xdata requirement

Maximum number of tasks

Notes

KRY.LIB

None

7*

for small applications

KRX.LIB

256 bytes

29

the most popular version

KRH.LIB

1 Kbytes

125


for larger applications

* Note: The KRY.LIB creates automatically a task to manage the tasks of group 1 (even if there is not).
So only 6 tasks are still available.
Each collection of libraries includes 4 sub-versions:
•
Standard version (for example KRX.LIB)
•
DEBUG versions that include Debug capabilities. Performance is sometimes reduced to gain
reliability. Parameter consistency checks are performed at function invocation and, if any
abnormality is detected, a trap is executed to try to recover correct operation of the program.
The libraries that contain DEBUG information are given a ‘D_’ prefix (e.g. D_KRX.LIB).
•
SEMAPHORE versions include semaphore capabilities and have a ‘S’ suffix (e.g. KRXS.LIB).
•
Versions which include both the DEBUG and the SEMAPHORE capabilities have a ‘D_’ prefix
and an ‘S’ suffix (e.g D_KRXS.LIB).

Note:During development, the DEBUG versions are recommended, but they may later be replaced if
performance is too low.

- 11 -


3. Task description

KR-51

3. Task description

3.1 Task definition
For the KR-51 scheduler, a task is specified by:
•
a reference: This corresponds to an identification number used with kernel function calls.
•
a descriptor: Indicates the task's priority, current state and events triggers (including
semaphore release). Note - For KR-51, the task's priority is associated with a register bank used
during the task execution.
•
a group: each task is assigned a "GROUP" which corresponds to a time base (or clock
frequency).
•
a task code (a function) : specified by the address of the code to be executed.
•
a stack size: when a task enters the Waiting state, the stack contents are stored (swapped).
However, the storage size must be previously defined.
•
an external stack size (KRX and KRH versions) : when a task enters the waiting state, the
automatic variables are stored in the ‘external stack’. However, the storage size must be
previously defined.
•
an appearance (or creation) time : when a task is initiated, the time when it should be executed
is specified. If a delay or "time-out" is required, this time is regarded as the starting point, which
helps to avoid clock skews caused by offsets. Similarly, if more than one task with equal priority
is in the READY state, the oldest is selected.
These values are not all directly accessible by tasks. However, they help to understand how the
scheduler operates internally.
They are initialised at the beginning of the application, using the task declaration table in CODE space
(see Implementation section).


3.2 Task states
The task's state is contained in the descriptor.
It can be :
•
UNVALIDATED if the task has never been set, or if it has already been executed to completion.
•
READY if the task is ready to be initiated.
•
WAITING if the task is waiting for an event : it may have been initiated but suspended for a given
duration. When the event occurs, the task returns to the READY state.
•
SUSPENDED if the task has been initiated but pre-empted during execution by a task of higher
priority.
•
RUNNING if the task is currently running.
•
UNKNOWN if the task is non-existent. It may be an illegal reference. Context switching occurs
via the kernel or by system calls.
Each task may be either UNVALIDATED, READY or WAITING state. However, for a given priority
level, there may be only one (or possibly zero) task in the SUSPENDED state.
One task only can be in the RUNNING state.

- 12 -


KR-51

3. Task description

3.3 Priorities and register banks

The priority of the task is indicated in the descriptor and can be in the range 0 to 3.
A task of priority 3 is a highest priority task, and will be initiated using register bank 3. If more than one
task is simultaneously in the READY state, the highest priority task in the ‘run’ queue, that is ready to
run will be the first executed.
Register bank 3 (address : 18h-1Fh) is also used by the kernel itself. It corresponds to that of the
highest priority tasks and if a task of priority 3 is currently running, the register bank select bits (RS1
and RS0) are not modified.
•
One SUSPENDED task only per level is allowed.
•
Each priority level is associated with a register bank. More precisely, priority level i corresponds
to bank Rbi and the four register banks correspond to the four priority levels. The association of
register banks with a priority level avoids the need to save and restore registers when the
context is switched.
•
An interrupt priority level is usually associated with a register bank. (Interrupt handling is
discussed hereafter).
•
If a priority level and associated register bank is not used, the bank can be used by a service
routine associated with an asynchronous interrupt.

3.4 Clock frequency groups
Four clock rates (or two for KRY) hereafter referred as GROUPS are available and each task is
associated with one of the four (or two) groups.
The clock rate is reduced by successive divisions : the scheduler pools tasks of group 0, and every n1
clocks, creates the clock corresponding to group 1 which initiates that group's pooling task. Similarly,
every n2 clocks of group 1, a clock is generated for group 2, and so on...
•
An advantage of the clock frequency group feature is that the scheduler does not have to pool
systematically all tasks.

•
n1, n2 and n3 dividers are referred to as DIVIDE_1, DIVIDE_2 and DIVIDE_3. They are PUBLIC
symbols of NUMBER type to be defined by the user when configuring the system (see
"IMPLEMENTATION" section).
•
Dividers can be used for generating clocks, which vary from milli-seconds to minutes.

- 13 -


3. Task description

KR-51

3.5 Waiting for an event
A trigger can be a TIMEOUT, a SIGNAL or a combination of TIMEOUT and SIGNAL or a flag release.
See chapter 7 for further information on flag capabilities.

3.5.1 Timeout
The task is SUSPENDED for a given number of clocks by calling KR_DEL_ABS or KR_DEL_REL
function. These functions are fully described in the "List of services" section. Note that these functions
are frequently used when working with a real time kernel.
Systematic suspension of a task by calling this function with a constant parameter causes task initiation
at a regular time rate. A typical example is in the construction of a perpetual calendar.
Time-outs are expressed as signed 8-bit words. A time-out is hence limited to 127 clock cycles (or
ticks) of the previous group.
Example 1 : In the ‘C’ language the following macro permits simulation of a time-out function with a
time parameter in the form of a 16-bit word :
#define delay16(time)
{

static unsigned n;

\

unsigned n1;

\

n = time;

\

while (n)

\

{

\
n1 = (n<125) ? n : 125;

\

n -= n1;

\

kr_del_abs(n1);

\


}
}

\

/* End of macro delay16 */

Note: The '\' character represents the end of a line and allows a macro to appear over several lines.

3.5.2 Signal
The task waits for a signal from another task. The signal is a simple inter-task communication and
synchronisation tool. Practically, a signal is a flag (a bit in the task's descriptor). It goes high (assigned)
to indicate a WAITING task (waiting for a signal or event). It goes low (de-asserted) when the signal is
sent by another task.
•
The KR_WAITSIG function causes a task to enter the ‘Wait for signal’ state.
•
The KR_SENDSIG function causes sending of a signal to a user-specified task.
•
The KR_DELSIG function causes a task to move to the ‘Wait for a signal’ OR ‘time-out’ state.
When one of the events occurs the task is activated.
KR_SENDSIG, KR_WAITSIG and KR_DELSIG are described in chapter 6 (list of the services).
Other features :
•
Sending a signal to a task that is not waiting for a signal has no effect.
•
Similarly, sending a series of signals will probably have the same effect as sending a signal.
•
Signal is an easy-to-use task synchronisation feature.

•
Signals are reset at initialisation by a call to KR_INIT.

- 14 -


KR-51

4. Scheduler

4. Scheduler
This chapter describes the dynamic characteristics of the scheduler and a full understanding is
essential to make best use of the services provided by KR-51. KR-51 contains a function library for
task services and a scheduler. The scheduler consists of the following functional modules:
1. CLOCK
2. POOLER
3. INITIATOR
4. RECEIVER
The CLOCK occurs at regular time intervals and calls the POOLER, which determines if any time-out
has occurred or if tasks waiting for a flag release can be moved to the READY state.
If a task is ready to be initiated, the INITIATOR causes its correct placement and initiation.
Finally, the RECEIVER takes control, when a task terminates or moves to the Waiting state.

4.1 Kernel clock
The CLOCK function is initiated at regular intervals via the TIMER 0 interrupt service routine.
Each clock (or tick) causes :
•
increment of the clock timer (which is used as a time reference for time--out management).
•
reloading of timer 0 to the user defined value. The reloading mode adopted eliminates any

cumulative.
•
and finally, initiation of the POOLER by the CLOCK (except if timer 0 interrupt was itself delayed
by a previous execution of POOLER).
Note: For the versions with external RAM, several CLOCKS are used in cascade (divisions in series), as
if there were several schedulers.
However, the secondary clocks are not built into the scheduler module : they consist of tasks that are
initiated by the INITIATOR module and are only used to place other tasks in the READY state. The
POOLER module will recover them at next pooling cycle.

4.1.1 Pooler
The POOLER examines all tasks that are defined in the group, to determine if some tasks in the
Waiting state (waiting for a time-out or a signal flag release) may move to the READY state.
During the analysis phase,
•
It identifies the READY task with the highest priority.
•
It then calls the INITIATOR if this task has a higher priority than the currently active task.
•
If more than one task with equal priority is ready to be initiated, only the "oldest" will be selected.
A task's ‘creation time’ corresponds to the time when the task moves to the READY state.
•
At similar priority levels and ages, the final selection is performed as follows:
generally, the first task in the READY queue will be selected.
The POOLER places the READY tasks in the READY queue.
The READY queue is then examined to select the task to be initiated.
Tasks of GROUP 0 only (for which the clock corresponds to the timer overflow) are moved to the
READY state by the POOLER. The predefined tasks TASK_CL1, TASK_CL2 and TASK_CL3 cause
pooling of tasks of group 1, 2 and 3 respectively.
The pre-defined tasks bear the following numbers :


- 15 -


4. Scheduler
Task

KR-51
Task Number for the
KRY version

Task Number for the
KRX version

Task number for the
KRH version

TASK_CL1

7

29

125

TASK_CL2

--

30


126

TASK_CL3

--

31

127

Note : All TASK_CLi predefined tasks have priority 3.
When initiated, TASK_CLi can move one task (or more) of the GROUP to which it belongs to the READY
state. The initiation will be performed only at the next TIMER0 interrupt unless the "DIRECT POOLING"
mode has been activated.

4.1.2 Initiator
The INITIATOR saves the context (PSW, ACC, B, DPH, DPL and stack level) of the task that was
previously running, then initiates the new task using the register bank allocated to its priority level.
The task is executed at the last INITIATOR instruction, which is a RETI. The task is thus placed
outside of the interrupt service structure to allow a scheduler cycle to be performed at the next clock
and also to permit asynchronous interrupts.

4.2 Task execution
Once initiated, a task runs until it terminates, waits for an event or a flag release or is deleted by itself
or by another task. It can also be interrupted by a higher priority task following the scheduler phase. In
this case, it remains in the SUSPENDED state, but its context is saved and then to be retrieved when
the higher priority task terminates. The context contains the return address and also the topmost
section of the stack that contains the return addresses of the nested calls, as well as the automatic
local variables.


4.3 Receiver
A task terminates, if a "ret" instruction is executed from within the task or if the kr_delete function is
called with the identity of the task as a parameter. The RECEIVER then takes control of the execution.
It retrieves the context of the suspended task (of lower priority) and reinitiates it. The following section
describes how to chain the RECEIVER to the POOLER and thereby immediately reinitiate another
READY task.

4.4 Direct pooling
4.4.1 Principle
Waiting, task pooling and initiation occurs only during the timer 0 interrupt service routine, hence at
each timer 0 overflow or ‘clock’. If, when a task moves to the Waiting state, no lower priority task is
SUSPENDED, a READY task will be initiated only at the next clock. For part of a clock cycle, it may
occur that no task is executed, although several tasks are READY. To eliminate these dead times, the
POOLER is initiated by setting the TF0 bit independently from the CLOCK in the following cases :
•
at any task termination (automatically at the end of the RECEIVER execution).
•
at signal sending, semaphore release, initiation of a daughter task.
This mechanism has no effect on the time management as direct pooling is distinguished from a real
timer 0 overflow.

- 16 -


KR-51

4. Scheduler

4.5 Interrupt handling

4.5.1 Implementation
In addition to TIMER0, KR-51 recognises any other unmasked interrupt source. These so called
parallel (// below) or asynchronous interrupts can be handled without difficulty, provided you proceed
carefully with :
• the use of register banks.
• the delay that KR-51 may cause to interrupt handling.
• the delay that may be caused by the interrupt handling
• the priority level hierarchy.
Note: the priority level for parallel interrupts must be higher than or equal to that of the scheduler.

4.5.2 Register banks
One of the fundamental rules of the KR-51 kernel consists in associating a register bank with a task's
priority level. Tasks of priority 3 are hence automatically associated with bank 3, those of priority 2 with
bank 2 and so on...
Usually, a register bank is also associated with a particular interrupt priority level.
Consequently, to avoid unnecessary swapping of a task's registers, a register bank should be reserved
for parallel interrupts, and tasks with the corresponding priority level should not be declared.
Consequently, a register bank must be associated exclusively with :
•
a task's priority level
•
an interrupt level (for a parallel interrupt)
Moreover, bank 3 for priority level 3, must be allocated only to tasks as it is also used by the
SCHEDULER.
The table below gives some examples of how to use register banks.
Example A

Example B

Example C


Bank 3(used by KR51)

Tasks priority3
+ KR 51

Tasks priority 3
+KR 51

Tasks priority3
+KR 51

Bank 2

Tasks priority2

Ints // priority1

Ints // priority2

Bank 1

Tasks priority1

Tasks priority1

Ints // priority1

Bank 0


Tasks priority0

Tasks priority0

Task priority0

In example A, the 4 banks are available so that the kernel can process 4 priority levels.
In example B, one bank is reserved for the parallel (//) interrupts. Three priority levels are available for
the kernel.
In example C, 2 banks are reserved for the parallel (//) interrupts. Two priority levels are still available
for tasks. In this case, the device is assumed to have 4 priority levels.

4.5.3 Kernel and parallel interrupt priority
At initialisation (KR_INIT function), TIMER 0 interrupt, which is associated with the KR51 kernel, is
given the default priority level (0). It is recommended not to change this priority level.
Parallel interrupts must have a priority level equal to or higher than that of TIMER0 interrupt. A parallel
interrupt may interrupt the kernel.

- 17 -


4. Scheduler

KR-51

4.5.4 Response time
This paragraph is concerned with only to delays caused by the KR51 kernel. Delays caused by the
other enabled user interrupts should also be considered.
An interrupt of a priority identical to that of the scheduler can be delayed for at most the kernel’s
execution time. The maximum duration depends on the number of tasks, but also of the task's state.

An interrupt of higher priority will run with delays defined by the manufacturer of the microcontroller,
unless the interrupts were disabled in the kernel by resetting EA bit. Interrupts are disabled under the
following conditions :
•
To reload TIMER 0 and eliminate the risk of offset, the scheduler blocks interrupts for 14 CPU
clock cycles.
•
In the KR_TST (semaphore "test and set") function call, the flag is manipulated with the
interrupts disabled. Flag manipulation may last for up to 12 CPU clock cycles.
•
In the KR_DEL_ABS, KR_DEL_REL, KR_DELETE function calls, task switching is also
performed with the interrupts disabled, but lasts only 7 CPU clock cycles.
•
Utility services such as MAILBOXES can also block interrupts for a short time. See the
description of these services for further details.

4.5.5 Permissible delay
At timer 0 reloading, the scheduler CLOCK includes the time expired since the previous overflow. The
maximum permissible delay is equal to the clock duration. If exceeded, the following clock will then be
offset by 65536 CPU clock cycles.
Practically, it is recommended to limit the duration of the parallel interrupts. If an important interrupt
processing session is to be initiated, it should be performed as a task (see following paragraph).

4.5.6 Tasks/interrupts interface
A parallel interrupt can initiate some kernel functions such as :
•
Information queries.
•
Initiate task (KR_CREATE).
•

Send signal to task.
•
Functions related to MAILBOXES.
However, parallel interrupts may not terminate a task by calling KR_DELETE. Similarly, the use of
semaphores is reserved for tasks because an interrupt routine cannot be moved to the Idle state.
Practically, these prohibited functions can still be called via a task initiation to go from the "parallel
interrupt" mode to the more powerful "task" mode.

4.6 Possible actions on IE and IP registers
KR_51 does not require exclusive access to interrupt control registers. The strategy applied is :
•
The user can enable/disable the interrupts and can also give them different priority levels.
•
KR-51 does not initialise and never changes the register(s) which set(s) interrupt priority (IP or
IPO/IP1). The scheduler is hence initialised with the lowest priority level.
However, the TIMER0 interrupt and the interrupt associated with the direct pooling initiation (if any)
should be maintained at lowest priority level.

- 18 -


KR-51

4. Scheduler

4.7 Task lifetime
This section describes the dynamic properties of the scheduler by analysing the various phases in the
lifetime of task T1. The mechanisms are now detailed from the viewpoint of T1.
•
At RESET, the scheduler initialisation procedure moves the task to the UNVALIDATED state.

•
If task T1 is permanent (or repetitive), the application’s initialisation routine must be used. If not,
the initiation is performed later at the request of another task, or during the parallel interrupt
service routine.
•
The initiation moves the task to the READY state, until it is selected by the POOLER. The
INITIATOR then moves it to the RUNNING state.
•
The task may temporarily leave the RUNNING state, if a higher priority task pre-empts it. The
TASK remains in the SUSPENDED state to allow the higher priority task(s) to be executed.
When the task that interrupted it terminates (or enters the WAITING state), task T1 moves to
the RUNNING state.
•
If T1 is waiting for an event or calls a shared resource protected by a semaphore, T1 becomes
WAITING, allowing another task of equal priority to be activated.
•
T1 is maintained in the WAITING state until the event occurs. At detection of the event by the
POOLER, T1 moves to the READY state (as for the first initiation).
•
A Task continues, alternating between the "RUNNING", "WAITING", "SUSPENDED" and
"READY" states. It can also be "INTERRUPTED" (for short times) by the activation of a parallel
interrupt or scheduler (TIMER0 overflow).
•
Finally, non-permanent tasks can be terminated (killed by themselves of by another task) and
hence return to the UNVALIDATED state.

4.8 Notes and suggestions
Variables may be overlaid, when using a real time kernel. To eliminate this risk, the following rules
should be observed:
•

in the parallel interrupt services routine, working registers: PSW, ACC, B, DPL and DPH should
be saved. With PL/M-51 and C-51 compilers, these values are automatically stored, when a
function is declared with the "INTERRUPT" attribute.
•
common resources such as variables internal peripherals, tasks and mailboxes should be used
only if they are protected by semaphores, or if the "volatile" feature of these resources is
controlled and does not pose any problem.
•
if tasks are written in assembly language, the scheduler function calls that may suspend the
current task (kr_del_abs, kr_tst, etc...) should be used carefully as various registers may be
corrupted.
Hence, the following lines should not be written :
;example of bad practice
inc

R6

mov

R7,#3

;passage of the parameter "delay" in R7

lcall KR_DEL_ABS

;call to the kernel service KR_DEL_ABS

mov

;R6 lost! (KR_DEL_ABS uses R6)


A,R6

Note: Generally, kernel services (as with any RC51 or PL/M-51 function) may modify the values in the
currently working registers : R0...R7, ACC, B, PSW, DPL and DPH. As a consequence, storing values in
them for later retrieval is bad practice.

- 19 -


5. Implementation

KR-51

5. Implementation
5.1 KR-51 files and installation
KR-51 is installed with RKit-51 software. To use KR-51, you need a valid serial number.
The supplied files are :
•
KR-51 libraries in the \LIB directory,
•
INCLUDE files, in the \INC directory, that corresponds to the programming language used:
KRDCL.H for the ‘C’ language, and KRDCL.H51 for the MA-51 assembler.
The INCLUDE files must be inserted at the beginning of the application files. For programmers
using RC51, the following control should be placed at the beginning of each file :
#include "KRDCL.H"

/* Prototypes of the functions of KR-51 */

#include "REG51.H"


/* SFR of the 8051 */

...

•

These files contain :
•
constant definitions (especially the codes returned by the information services).
•
pre-defined types (especially for task declaration).
•
kernel service prototypes.
Examples in the \EXAMPLES\RTOS directory.

5.2 Implementation
To construct a KR-51 based application, proceed as follows :
1. Ensure the linker is configured to use the Kernel libraries (either KRY,KRx or KRH) via Project |
Options | LX51 | Kernel in Ride7.
2. Define the tick rate and the value of the dividers.
3. Write a "main" task initialisation procedure: kernel should be initialised by a call to KR_INIT. If
you use mailboxes, MAIL_RESET() should also be called.
4. Write the tasks specific to the application.
5. Compile and link the project.

5.3 Task declaration
The keywords task, group, priority, stack and stackx allow direct implementation of the tasks
under RC-51. Example:
void fmenu() task _menu_ group 1 priority 3 istack 3 xstack 4

...

In this example the fmenu function is a task, with the following attributes :
•
Tsk Number : _menu_
•
Group 1
•
Priority : 3
•
istack and xstack settings correspond to the space allocated to save the internal and external
stacks respectively. See the section «Saving stacks».

- 20 -


KR-51

5. Implementation

5.4 Tasks written in another language
It is possible to write tasks in another language (e.g. from the MA-51 Assembler). To allow the linker to
take into account this task, you must declare it with the external attribute in a ‘C’ source module. If the
application comprises of several ‘C’ modules, the task declaration must be carried out only once.
code
...
PUBLIC FLCD:

;task code is written in Assembler
mov A,NUMBER


LABEL1:
...
mov R7,TEMPO1
lcall kr

_del_abs

;task is put to sleep

...
/* Task declaration in a ‘C’ module */
extern void flcd () task _TLCD_ group 2 priority 0
// This task is written in assembler and will be accepted
// by the linker and the kernel.
// ATTENTION: This external declaration must appear only once!!
...

The parameters NUM_TASK and NUM_TASKi (number of tasks for each group) are processed by the
linker and the Compiler. They do not have to be defined by the user.

5.4.1 Significance of the different keywords
Keyword

Significance

Note

task


Indicates to the linker that the function must be dealt with as
task.
Must be followed by a constant value corresponding to the task
number

mandatory parameter

group

Must be followed by a constant corresponding to group to which
the task belongs

optional parameter
default value = 0

priority

indicates the task priority

optional parameter
default value = 0

istack (1)

indicates the memory used to save the stack

optional parameter
default value = 16 bytes
(8 for KRY)


xstack (1)

indicates the memory used to save the stack
Ignore for KRY

optional parameter
default value = 16 bytes

(1) : refer to the section ‘Implementation - Saving stacks and local variables’.

- 21 -


5. Implementation

KR-51

5.4.2 Kernel settings
The kernel options have the following default values :
Parameter

Description

Default value

Notes

TIMO_INIT

Tick rate(= reload value)


1000

i.e. 1 ms @ 12MHz

DIVIDE_1

Group 1 divisor

100

i.e. 0.1 s @ 12MHz

DIVIDE_2

Group 2 divisor

10

i.e. 1 s @ 12MHz

DIVIDE_3

Group 3 divisor

60

i.e. 1 min @ 12MHz

The quickest way to change these parameters is to select Options | Project | LX51 | Kernel from

Ride7.
Moreover you can set KR_XLEN which is the size of HR_XTOP segment (in xdata memory). The
default value is 1024.
Example:
$if(1)
PUBLIC KR_XLEN
KR_XLEN
RKRXDEF?XD
rseg

EQU

512

segment XDATA

RKRXDEF?XD

PUBLIC KR_XTOP
KR_XTOP:

ds

KR_XLEN

$endif
END

5.4.3 Questions
How do we calculate the number of CPU cycles/tick to be able to get 16 usec per tick?

The clock goes at 16MHz, so one CPU cycle takes 1/16=0.0625µs . Therefore we'll have
16/0.0625=256 cycles in 16µs. So we should set 256.
This is the theoretical value, but it may lead to problems. see below.
What is a smallest CPU cycles/tick that could be set?
The minimum value allowed is 200. If you enter a smaller value, Ride7 uses 200 (the maximum is
65535).
This limitation exists because the kernel takes about 200 cycles to analyse the tasks list when there is
only one group 0 task. If you used a smaller value, the CPU would spend all its time managing the
system, and the task would never be executed. (or some ticks would be skipped)
This is really a theoretical minimum, usable only if you have a few tasks of group 0.
When actually using the kernel in an application, the number of tasks grows, mailboxes and
semaphores are created, etc. All these things take time to be managed and the CPU time needed for
the system itself gets bigger. In practice, we advise to use at least a value of 500 if you want to avoid
problems.
That is why even if you set a value of 256, you may still have trouble. It all depends on the complexity
of the application.
In fact, when you want to perform such precisely timed operations (let's say, below 100µs between
ticks, if you have a 16MHz crystal), the best is to use another timer with a higher interrupt level and a
dedicated ISR. You can still use the kernel for the slower tasks.
Indeed, managing an OS takes time, you can't avoid it.
The number of clock by CPU cycles depends on the derivative you are using. The standard 51 takes
12 clock cycles per CPU cycle.

- 22 -


KR-51

5. Implementation


5.5 Saving stacks and local variables
5.5.1 Stack storage
The management of return addresses of interrupted tasks requires information to be placed on top of
the stack. The "size" corresponds to a space reserved in XDATA (or IDATA for KRY) for data storage.
The return address need not be included in this size. To calculate the stack size :
•
if the task code does not invoke any sub-program (except kernel function calls), a size of 0 is
sufficient.
•
data storage occurs at "SUSPEND" calls where a task is moved to the WAITING state. Subprograms that do not use this function can be ignored.
•
RC51 and PL/M-51 do not stack variables before a function call, (except for reentrant functions)
and only the function return addresses should be considered.
•
Enter the required size after the keyword istack in the task declaration. Example :
void ftime task _time_ priority 2 istack 2 xstack 0
{
while (1) {
if(++second==60) { inc_minute(); second = 0;}
kr_del_abs(100); /* assuming 100 Ticks per second */
}
}
void inc_minute()
{
if (++minute==60) minute = 0;
}
/* A 0 byte size is sufficient for the stack saving. The call to inc_minute
function is not taken into account */

The stack information is stored in an XDATA segment, using the KR_XTOP symbol to indicate the start

address and KR_XLEN for the size. The KR_XTOP segment is allocated automatically by the kernel.
The default value of the size of this segment is 1024 bytes. To change this size, you can :
•
Change the value from the kernel dialog box in Ride7
•
Change the value either in an Assembler module or in a ‘C’ module using the following syntax :
•
Assembler:
PUBLIC KR_XLEN
KR_XLEN NUMBERxx // xx is the size
•
C: #pragma defj(KR_XLEN = xx)
// xx is the size
The number of bytes, N, to reserve should be at least the sum of the declared sizes for stack spaces :
+ (NUM_TASK * 4) where NUM_TASKS is the total number of tasks declared by the user,
+ 16 bytes,
+ the bytes used for external stack storage (see next section).
to which the size of the space for the memory allocator (if used) should be added (see section 8).

5.5.2 External stack capability (external versions)
This section explains the concept of dynamic external stack management used by the ‘C’ compiler.
You can skip the remaining part of the section if your tasks are written in assembly, or in the ‘C’
language and compiled with the SMALL memory model where no external stack is used.
Although the "SMALL" model may be used, it is logical to compile tasks in the "LARGE" model, if you
use kernel KRX versions in order to benefit from the external stack.
The reference manual for the RC-51 compiler gives a description of the external stack feature.

- 23 -



5. Implementation

KR-51

5.5.2.1 External stacks
If printf is used when ‘Use external stack’ is set, the buffer used for formatting is located in external
stack.
External stacks are saved at invocation of a SUSPEND function (kr_del_abs, kr_tst, kr_waitsig...). The
stack is saved and then automatically restored when reinitiating the task. The swapping procedure is
performed internally and does not pose any problem, except that the external stack storage size to be
assigned to each task.
The maximum size for automatic variable storage should be determined before calling a kernel
SUSPEND function. The example below explains how to determine the maximum size (which must be
placed after the keyword xstack).
pragma auto
float f1=12;

/*static variable*/

void fcounter() task _counter_ istack 4 xstack 4
/*task counter*/
{
int

i;

/*int = 2 bytes used for this automatic variable*/

for (i=0;i<=5,i++)
{

printf ("fct=fcompteur

:

compteur=%2.2",i)

fct2 ();
kr_del_abs (5);

/*timeout of 5 ticks*/

}
return ()
}
void fct2 ()
{
char c;

/*automatic variable char = 1 byte used*/

for (c='0';c<='5',c++)
{
printf ("fct=fcompteur

:

counter=%c",c)

fct3();
kr_del_abs (5);


/*timeout of 5 ticks*/

}
return();
}
void fct3 (char c2)
{

/*no automatic variable in this function*/

printf ("fct=fct3")

/*but one parameter passed (c2)*/
/*this parameter will be stored in external stack*/

kr_del_abs (5);

/*timeout of 5 ticks*/

printf ("%6.6f %c",sin(f1),c2);
}

- 24 -


KR-51

5. Implementation


Note: via the putchar function, the printf function may indirectly call a kernel suspend function. The
TELEMEAS example supplied (and printed out at the end of the manual) illustrates this case.
Sufficient reservation (for internal and external stacks) should then be performed to include the possible
kernel suspend function calls from printf.
In the example above, the external stack storage requires a minimum of 4 bytes as in the ‘worst case’,
the counter task may be suspended within fct3 function.
Before calling a suspend function within fct3, the following information should be stored in the external
stack :
•
i value, in fcounter (int=2 bytes)
•
c value, in fct2 (char=1 byte)
•
the value of the parameter transmitted between fct2 and fct3 (here a char i.e. 1 byte).
The minimum size to be reserved for the external stack is hence the sum of the 3 preceding values,
which is 4 bytes.
These 4 bytes should be included when determining the size of KR_XTOP and KR_LEN (see previous
section).
As for the stack storage, it is advisable to reserve some additional bytes for the external stack storage
in case hand calculations are too small. A size of 0 for the external stack is appropriate for the following
cases :
•
tasks written in assembly language
•
tasks written in the ‘C’ language but compiled in the ‘SMALL’ memory model.

5.6 Set-up utility program
For a KR-51 based application, the typical start-up process consists of the following initialisation
procedures :
•

Primary start-up
•
Application variable set-up
•
Kernel set-up
•
Internal peripheral set-up
•
"Permanent" task initiation
•
Kernel Activation
•
Base loop
The primary start-up procedure consists in initialising the Stack Pointer register (SP) and resetting
internal RAM (not essential but recommended). The configuration parameters are often placed in the
compiler’s set-up utility programs and hence need be of no great concern to most programmers.
For the RC-51 compiler, the application variables set-up can also be performed automatically.
Practically, some variables will still need to be set up.
Initialisation the kernel is achieved by calling the KR_INIT function. In the KR_INIT function call, timer 0
is configured, the interrupts enabled (EA and ETO) and tasks moved to the UNVALIDATED state.
Finally, in the KRX version, the pre-defined tasks (CLOCK of GROUPS 1, 2 and 3) are initiated. Note
that timer 0 is not initiated : the first clock will occur only after 65536 CPU clock cycles, unless
anticipated by the user (by entering FFh in the TH0 bit for example).
The internal peripheral set-up procedure applies to the peripherals used by the application : serial
port,.. except for timer 0 and its interrupt.
The permanent task initiation procedure (refers to tasks that occur at fixed intervals) is performed by
the KR_CREATE function.
Finally, the base loop is executed, if no task is running it often consists of a simple loop (sjmp$). A
background function may be inserted in the procedure, if the register bank used is not the same as that
of any tasks or interrupts.


- 25 -