EXAMPLE-.4 RING BUFFER MANAGER

This exaúple shows thc most educational portions of a ring buffer managcr, It also serves to illustrate the varioùs parts of an operating system extension. Be advised, however, that the example is inmmplete and should be imitated with dissetion. In particulaq the example has the following shortcomings:

The issue of exceptiol handling is nof addressed. Clearly the code supporting a system call should examine each invocatiori for validity, but, for brevity, the ring buffer example does not do this.

There are no saleguards against partial creation of an object. When ceating a composite object, a type manager must fust create the components of the object.

Occasionally, after oeating some of the components, the manager might be unable to cr€ate the others. A type manager should be able to recover from this situatioq usually by deleting the components aheady created arid returriing an exception code to the caller. the example, again for bre', ity, does not do this

The entry routine does not check the entry code for validitr.

The potential for problems with deletion is ignored. For this reason, you should imagine that the envhonment of the example is constrained in at least two ways. Fftst, only one task will eveî îry to delete a ring buffer and, when it does try, no other task will be using that buffer. Second, when a job contairÌírig a task that created a ring bulfer is deleted, no tasks in otheî jobs are using that ring buffer.

' The example las been desk-checked, but the example has riot actually beeri tested.

A ring buffer is a block of memory in which bltes of data are placed at successively higher addresses. Interspersed with byte insertions are b''te removals, vr'ith the restdction that the byte being removed must ahvays be the byte that has been ifl the buffer foÌ the longest time. Thus, data enters and leaves a ring buffer in a FIFO manner. Ring buffers are so named because the lowest address logically follows the hìghest address. That is, if the last byte placed in (or retrieved from) the buffer is at its highest address, then the next bj/te to be placed in it (or retrieved from it) is at the lowest address. As data enters and leaves the buffer, the portion containing data "runsÍ around the ring, with the pointer to the last byte out 'bhasing" the pointer to the last b,'te in. Figure 11-3 illùstrates these

characteristics.

Nucleùs Usefs Guide tl-7

TYPE M.{NAGERS

figure ll-3. A Ring B!fier

The main (service) part of the example consists of four proceduret: CREATE_RING BUFFER, DELETE_RING_BUFFER, PUT_BYTE, and GET_BYTE. The last two prccedures are for placing a character in a ring buffer and for retrieving a character, resDectivelv.

1t-8 Nucleus Uset's Guide

IYPE MANAGERS

/*************************:t*:t**********it*********************************

* N O T E : T h e following common líleral f i l e ( C O M U O N . L Ì T ) i s i n c l u d e d *

* i n e a c h of thc PLIM-286 porrions of the exdple.

*********************x*x************************************************//

DECLARE TOKEN ]-ITERAILY 'SEI-ECTOR' ; DECIARE forever LITERALLY ,ltHlLE 1,;

D E C I A R E i n d e f t n i t e l y L I T E R A L L Y . o F F F F f l , ; DECIAREASTR$STRUC LIÎEMLLY'STRUCÎ'RE(

num$slors woRD,

numsco[ponents lrIoRD,

seg TOKEN,

enpry9cr ToKEN,

full$ct TOKEN), ; DECIARE POINÎER$STRUC LIÎERALLY ' STRUCTURE(

offset WORD,

selector SELECTOR)' ; DECI,ARE SEGMENT9STRUC LITERAI,LY ' STRÙCI'TIRE (

síze IùORD,

head t{oRD,

tail WoRD,

buffer(1) sYIE)' ;

1 1 .6.1 Initialization

The initialization creates a region to protect data in ring buffers from being manipulated by more than one task at a time. This part of the OS extension also creates the requted exlension gpe, qeates a deletion mailbo! and then waits at the deletion mailbox. The OS e\tension call-gates are established during configuration. For this example, they are GDT slots 440H, 441H.44211 and 443Il' Cod€ lor the iniriirlizarion ircludes the

following:

$INCLUDE( | Ix: COI'ÍMON. LIT) ; /* Declares conrnon literals */

Nùcleus Uset's Guide 1t-9

TYPE N,TANACERS

DECI,ARE delete$obj ecr ToREN;

DECI,ARE exceprion UORD;

DECIARE ftfo rITERALLY ,0' ;

DECLARE rb$code ITTnRALLY ,8000H' ;

DECLARE deletion$mbox TOKEN;

DECURE response$mbox TOKEN;

ríng$buffer$region = RQ$CREATEgREGÌoN ( f i f o ,

G e x c e p t i o n ) ;

deletion$nbox = RQ$CREATE$MAILBOX ( \--l

f i f o ,

delete$object : RQ$RECETVEgMESSACE (

deletiongnbox, \---l

1l-10 Nucleus Use s Guide

PUSH

11.6.2 The Interface Library

The user interface library consists of four small procedures, ofle for each of the system calls provided by the operating system qtension. The library supports application code writteri in the PL/M-286 I-ARGE model. If a different model had been used for

compiling the application code, these interface procedures would be slightly different, reflectiry the fact that, when making procedùre calls in othef modelq the stack is used differendy than in the LARGE model. The interface procedures are as follows:

CREATERB PROC FAR

paraneter--the rlng buffer to delete

; c a l l t h e o s - e x t e n s i o n w i a a c a l l g a t e

paraneter--ring buffer to read fron

; c a l l t h è O s - é x t e n s i o n v i a a c a l l - g a t e GETRBYTE

PUTRBI'ÎE

FAR

Nucleùs Uset's Guide 11-11

TYPE MANAGERS

PUSH BP \-/

M O V B P , S P

PUSH BP+8 ; paraneter:--the char:acter to nr:ite PÙSl{ ÀP+6 ; pataneter--ring buffer to grfte to CALL CAîE 443 ; call Os-extenslon via a call-sate

POP BP

RXT 4

PUTRBYÎE END?

These interface proc€dures correspond to a set of external procedure dealaratior$ iri the

application PL/M-286 code:

CREATERB: PROCEDITRE(SIZe) ToKENEXTERNAL;

DECI,ARE size l{oRD;

END CREATIRB;

DELETERB: IROCEDI'RE ( ring$buffer$token) EXTERNAL; \--"

DECLARE ring$buffer$token T0KEN;

END DELETERS;

GETRBBYTE: PRoCEDURE(riîgqbuffer$token) BYTE EXTERNAL;

DECLARE ring$bufferstoken TOKEN;

END GETRBBYIE;

PUTRBBYTE: PROCEDURE(Chat, ling$buffer$token) EXTERNAL;

DECI,ARE char BYTE;

DECI,ARE rtng$buffer$tokèn ToKEN; \" -'

END PUTRBBYTE;

Lt-12 Nucleus Uset's Guide