KR-51Real-Time Kernel for the 8051 familyUser Manual

KR-51 Real-Time Kernel for the 8051 family User Manual Document version 23 February 2010 KR-51 Contents Introduction 1.1 Purpose of this manual 1.2 Scope of this manual .6 1.3 Additional help or information Overview 2.1 Organisation of the manual 2.2 General description of tasks 2.3 A first example: LEDs 2.4 The multitasking capability .9 2.5 KR-51 specification 2.6 Simple example 10 2.7 Files supplied .10 2.8 Program development tools 10 2.9 Available versions 10 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 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 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 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 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 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 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- Introduction KR-51 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: http://www.raisonance.com/ and the forum http://www.raisonance.com/Forum/punbb/ or contact Raisonance Address: Raisonance S.A.S 17, Avenue Jean Kuntzmann, 38330 Montbonnot Saint Martin France Telephone: Fax: Email: +33 76 61 02 30 +33 76 41 81 68 support@raisonance.com 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 Overview 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- Overview KR-51 2.3 A first example: LEDs Let’s see the following program: #include // Declarations for the services #define _TSKLED1_ // Reference task #1 #define _TSKLED2_ // Reference task #2 at 0x91 sbit LED1; // LED driven by P1.1 at 0x92 sbit LED2; // LED driven by P1.2 void main (void) { kr_init(); kr_create(_TSKLED1_); // Creates and runs task kr_create(_TSKLED2_); // Creates and runs task while (1); // Loop for ever } void tskled1 (void ) task _TSKLED1_ //Task { while (1) { LED1 = !LED1; // Toggles P1.1 kr_del_abs(7); // Waits for ticks } } void tskled2 (void ) task _TSKLED2_ //Task { 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 • at the base frequency divided by (2*23) for the task The base frequency can to be set in Ride7 A typical value would be KHz, which allocates time in millisecond intervals -8- KR-51 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 and 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- 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 - 13 APPENDIX KR-51 { if (i) i-=2; } else buf[i] = c; } buf [i] = 0; return buf; } void error (char *message) { printf("\n\nerror : %s%c",message,BEL); printf("\nStrike any key"); getchar(); } /************************************************************************\ 3-CHANNEL RECORDER -File : SX_MESU (including TSK_MESU task ) Date : 12/92 Author : FL/Raisonance Aim : KRX example ========================================================================== This file contains the code of task TSK_MESU (fmeasurement) as well as other functions called by TSK_MENU Principle : Each pack of measures (256 bytes) holds a series of values corresponding to one hour of measurements (i.e 60*3 values) Every second, a new mesurement is carried out (on each of the channels) and then used to calculate an "average value" on the current minute All these values (measures and averages) are expressed on 10 bits Every minute, the above average values are "concatened" to form a 32-bits object (00+3*10) The most significant bits are just put to zero Every hour, the current pack of measures is closed and the next one is opened About 128 packs can therefore be stored in the 32K external memeory segment dedicated for this purpose A pack of measures contains 60*4 = 240 bytes The extra 16 bytes are used to store other information : - date + hour of the first recording (for the pack), - 64 - KR-51 13 APPENDIX - number of measurements (some packs may be uncomplete), - maximum value in the pack - security code Note : due to channels, a meaurment is carried out every 1rd of second \********************************************************************/ #pragma NOAREGS #define M80C552 /* this application requires an A/D converter */ #if defined(M80C552) #include /* SFR declaration for 80C552 */ #elif defined(M80C515) #include /* SFR declaration for 80C515 */ #else #include /* SFR declaration for 8051 */ #endif #include #include /* prototype of KR-51 services */ #include "sx.h" /* declarations proper to the application SX */ #define BOX_TRM_FULL (MAIL_FULL&1) #define BOX_TRM_EMPTY (MAIL_EMPTY&1) #ifdef EOF # undef EOF #endif #define EOF 0xD /* convention used to indicate the end of a file */ /* */ /* Declaration of a pack (=1 hour of measurements) typedef struct /* size = 256 bytes */ */ { char state3; /* : not used, 0xA5 : measurements in progress, 0x5A : full char number; measurements (0 59) done */ */ /* number of unsigned long measurement [60] ; /* Average result each minute */ struct stime instant ;/* Beginning of the series of measurements */ unsigned char jam; maxi [3]; */ /* maximum values in the hour (one value/channel) */ /* Available checksum upon exportation - 65 - 13 APPENDIX KR-51 } pack_measurement ; extern unsigned long seconds; #define MAX_PACK 10 /* maximum number of packs */ at 0x8000 xdata pack_measurement pack [MAX_PACK] ; /* 32 K reserved for data storage*/ pack_measurement xdata *pack_act; static int dp_stop; /* pack in progress */ /* flag used by task_measurement */ /* -*/ /* private functions */ static unsigned measurement (unsigned channel); /* Return a 10-bit analog measurement */ code unsigned char shifting [3] = {0,10,20}; /* -*/ /* Corps de la tƒche TSK_MESU */ void fmeasurement () task _measurement_ priority group /* Measurements are carried out on the channels 64 times per minute */ { int i, j, full_measurement = 0; static unsigned long average [3], global_value; dp_stop = 0; { for (j = ; j < 64 ; j ++ ) /* 64 measurements per minute */ { /* Prise measurement channel */ for (i=0;i>= 5; /* division per 64 to calculate the average value */ if (pack_act->maxi[i] < average[i]) pack_act->maxi[i] = average[i]; /* New maximum value */ - 66 - KR-51 13 APPENDIX average [i] >>= shifting [i]; /* 30-bit storage */ global_value += average [i] ; average [i] = ; /* (re) initialization */ } kr_del_abs (25); /* 64 * 25 * * 12.5 ms = minute */ if (dp_stop) break; } if (dp_stop) break; } if (!dp_stop) /* After one minute, the result is stored ; */ pack_act -> measurement [pack_act -> number++] = global_value /* (re) initialization of the values for the next series */ global_value = 0; /* if one hour has elapsed, the current pack is close */ if (dp_stop || (pack_act -> number == 60)) { char xdata *p; char c; /* calculation of the check-sum */ p = (xdata char *) pack_act; pack_act->jam = 0; for (i=0;ijam = -c; pack_act->state3 = 0x5A; pack_act ++; /* changing pack */ */ if (pack_act == NULL) /* test if there is storage space left { full_measurement = 1; break; } else if (!dp_stop) { - 67 - 13 APPENDIX KR-51 /* Initialization of a new pack */ pack_act->state3 = 0xA5; /* in progress */ pack_act->number = 0; kr_tst(SEMA_TIME); time_2struct (seconds, &(pack_act->instant) ); kr_free(SEMA_TIME); pack_act->maxi [0] = pack_act->maxi [1] = pack_act->maxi [2] = 0; } } if (dp_stop) return; /* end of task */ } while (!full_measurement) ; } /* -*/ /* Task TSK_EXPORT (export the measurements on the serial port) */ void fexport () task _export_ priority group /* This function is initiated by the task MENU Protocol is as follows : Each pack (one hour of measurements) are sent one after another The byte jam holds the check-sum */ { int i, j; char xdata *p; /* Wait until emission of the buffer is completed */ kr_del_abs(10); while (!BOX_TRM_EMPTY); kr_del_abs(100); /* 10 seconds of delay */ /* no more parity */ PARITY = 0; for (i = ; i < MAX_PACK ; i ++) if (pack [ i ] state3 == 0x5A ) { p = &pack[i].state3; for (j = ; jnumber = 0; kr_tst(SEMA_TIME); time_2struct (seconds, &(pack_act->instant) ); kr_free(SEMA_TIME); pack_act->maxi [0] = pack_act->maxi [1] = pack_act->maxi [2] = 0; /* creation of the task measurement */ kr_create(_measurement_); } /* -*/ void display_measurement (int n) /* Display of the measurement on channel n Measurements are carried out on 10 bits, and the reference analog voltage are 0V (0), and 5V (0x3ff) Analog values are then "manually" converted in float, to avoid referring to the floating point arithmetic library */ { unsigned long result; kr_tst(SEMA_MEASUREMENT); /* Acces to the function measurement is regulated by a semaphore as both TSK_MESU (for storage purpose) and TSK_MENU (for display purpose) can concurrently refer to it */ result = measurement(n); kr_free(SEMA_MEASUREMENT); printf("\n channel %d : %d.%02.2d (%X)", n, (unsigned) ((result*5)/0x3ff), (unsigned) (((result*500)/0x3ff)%100), (unsigned) result); } /* -*/ /* Measurement on channel n */ unsigned measurement (unsigned n) /* n = channel number */ { unsigned mes; - 70 - KR-51 13 APPENDIX #if defined(M80C552) /* Cf documentation NXP sur l'ADC du 552 (IC20 page 414) */ ADCON = 0x08 + n; /* conversion commences */ for (n=0;n