EXTENDED [email protected] SYSTEMDOCU M E NTATIONVOLUME 3SYSTEM CALLS intef

(1)

intef

E X T E N D E D i R M X @ I I . 3 O P E R A T I N G S Y S T E M

D O C U M E N T A T I O N V O L U M E 3 SYSTEM CALLS

O r d e r N u m b e r : 4 6 1 8 4 6 - 0 0 1

I n t e l C o r p o r a t r o n 3 0 6 5 B o w e r s A v e n u e 5 a n t a C l a r a , C a l i f o r n l a 9 5 0 5 1

C o p y r r g h t ' 1 9 8 8 , l n t e l C o r p o r a t i o n , A l l R g h t s R e s e r v e d

(2)

I n l o c a t i o n s o u t s i d e t h e ( j n i t e d S t a t e s , o b t a i n : ì d d i t r o n a l c o p i e s o l l n t e l d o { L r m e n t a t i o n b y c o n t a î t i n g y o u r l o c a l l n t c l s a l e s o l l i c e . I . ' o r v o u r c o n v e n r e n c e . i n t e r n a t r o n a l s a l e s o m c e a d d r e s s e s a r € l { } ( a t e d d ì r e c t l y b e f ì ì r e th e r e a d e r r e p ì y î a r d i n t h e b a c k o f t h e n r a n u a l .

T h e i n f ò r n ì a l i o n i n t h j s d o ( u m e n l i s s u b j e c l t o r l ì ? r n s e s i t h o L r t n o t i c r

I n t e ì ( r ) r p o r a l L i ) n n ì . ì k o s n { r s a r r a n l y r ì l a n y k i d d \ ! r l h r c s a f d l o t h r s I l ì a t r r i r l , r n ( l u d i n g , b u t n o t l i n ì i t e d t o . l b e r m p l i e d \ \ a r r a n L r e s o f m c r c h a n t a b i ì r t v a n d f i t n e s s fì ) r a p t ì r t i c u l a r p u r p o s e I n t e l ( i l r p o n r t i o n assunìcs no responsrLility fìrr nny i'rrors that nìay appear in this document. Intel C o r p o r a t i o n n r u k e s n o ( ' r ) n r n ì i l n ì c n t t i ' u p , l r r ! c , r r t o k e e t c u r r e n t t h c i n f o r n ì a t i 0 n c o n t a i n e d i n t h i s

I r t e l ( ' o r p o r a t i o n a s s r . r n c s n o r r s p o n s r b ì l ì r y i b r l h € u s e o f a n v c i r c u r L r v o t h € r l h a n c i r c u i t r y e n r b r r d r e d r n a n I . l e l p r ' ) r l u c t . \ , ) o t h e r c r r c u r l p a t e n t l i r e n s e s a r e r ù ì p l i r d .

I n t c l s o l ì \ \ a r e p r o d r r c t s a r e c o p r r r g h t e d b y a n d s h a l l r e m a r n t h e p r o p e r t y , ) f I n t € l C o r p o r a t ì o n . t j s e . ll u p l r c a t r r n o r d r s r l o s L r r | r s s L r b l f r t l o r e s t r r c l i o n s s h l e d I n I n t r ì l s s o f t \ | a r e l r c e n s e , r ) r a s d e l ì n r d r n A S I ' R ? 1 0 4 . 9 1 a ) 1 9 )

\ o p a r t i ) f t h i s d r ) c L r n { n t n ì a y b e c o p r . d o r r c p r o d u ( o d i n a n y f o r m o r b y a n y m e a D s \ \ l t h o u t p r i o r w r r t t e n c o n s e n t o l l n l e l C o r p o r a L r o n .

' I ' h e

I ì r ì l r l r n g a r e l r a d e n r a r k s o l l n t e l C o r p o r a t i o n a n d i t s a l l ì l ì a r e s a n d n ì a ! b e u s e d o n l y t o r d c n l L i y t r ì l e l p r o d L ì c l s :

A b o r e i l . B X BITRL:S

CONf\'fputer iMDt)X

CRI.]I)IT jM\'IX

l)ata t']ipeline lnsile G e n r u s i n t " l

A

i i n t p l B o s

r l n l e l € v r s i o n

I Z I C E i , , t e l i s e n t I d e n t r f i c r l C l l i n t e h q e n t P r , ) [ . a l r t n ì i n g

r ( l U t , I n l c l l o c

i ( ' S I n l f l l i n k

r l ) U l ' ì O S P

I D I S r I J D S

ì l ) S I l

rPS(l i R M X r S U C r S B X rSIl M r S S u rSX \l

l,rbrarv !lanager

\ f C S

!fegachassis

\tICRO \'IAI \!'RA}f !]

\fL-I-TII]L'S

\f L: I-TI C H A NN !] T, IfUI,TI\'IODULE

O p e n N F ì t o\c Fi

I r l u q A I l L , b b l e PROMPT QUrisT Q u e X Ripplenrode R \f x/ti0 RL: PI Seamless

st,t)

UPI VI,Si(]EL

X E N I X , V S t ) O S , \ , f u l t i p l a n . a n d M i c r o s o l t a r e t r a d e m a r k s o l l ú i c r o s o f t Corporation. L'\lX is a L r a d e n ì a r k o f B e l l L a b o r a t o r r e s . [ ] t h e r n e t i s a L r a d e n ì a r k o f X e r o x ( ' o r p o r a t r o n . Centronics is a l r a d e n r a r k r ) f ( ' c n t r o n r r s D a t a C o m p u t c r C , ; r p o r a t i o n . C b a s s r s T r e k i s a trademark oi General D e v i c e s ( l o n r p a l y , I n c . V A K a n d V \ t S a r c t r a d e n r a r k s o f l l ì g i r a l E q u i p n l e n t C o r p o r a r r o n . S r n a r t r n o d e n ì l 2 f ) 0 a n d t l a v e s a r e t r a r J e r n a r k s o f H a y e s M i c r o c o m p u t e r P r o d L k t s . I n r . I I I M r s a r e g Ì s t e r e d t r a d e n ì a r k o i l n t e r n a t i o n à l B u s r n e s s M a c h i n e s . S l r f t S k o p e is a reetsterod trademark of C l o n L u r r e n l S { i e n r c s .

C o p y f l g h t r 1 9 8 8 . In t e l ( l o r p o r a t i o n

l l

(3)

VOLUME PREFACE

M A N U A L S I N T H I S V O L U M E

This volume (Volume 3, F-rtended |RM)€ II System Cal/s) contains the following manuals, all of which document the iRMX II system calls. In each manual you will find the system calls listed with their syntax and descriptions. Note that since these are reference manuals, their format differs somewhat from the other iRMX II Operating System manuals.

Ertended iRM}.F II Nucleus System Calk Reference Manual Ertended iRMXo II Basic I/O System Calb Reference Manual Ertended iRMXo II Extended I/O System Calls Reference Manual Ettended iRMXo II Application Loader System Calls Reference Manual Extended iRMXo II Human Interface System Calls Reference Manual Extended |RMX@ II UDI System Calls Reference Manual

The Exteruled iRMXo II Nucleus System CalLs Reference Manual descri\es the use of all Nucleus system calls.

T'lte Extendett IRMxcI^ II Busic I/O System Calls Reference Man,al describes the use of all BIOS system calls.

The Ertenderl lRM)@ II Extended J/O Svstem Calb Reference Manual describes the use of all EIOS system calls.

The Extended |RM}@ II Application Loader System Calls Ret'erence Man&a/ describes the use of all loader system calls.

The Extended iRMx{'^ II Human Interface System Calls Reference Manual describes the use of all Human Interface system calls.

T\e Extendcd iRM),o ll IJDI Svstem Calls Reference Manual describes the use of all UDI system calls.

iRMX@ II Svstem Calls Volume ^{I l r}

(4)

VOLUME PREFACE

VOLUME CONTENTS

Manuals are listed in the order they appear in the volumes. For a synopsis of each manual, reîer to the Introduction to îhe Ertended |RMX\ II Operatíng Sy*em.

VOLUME 1: Extended .RMP II Introduction, Installation, and Operating Instructions Introduction to the Extended |RMX II Operating System

Ertended iRMX II Hardware and Software lnstallation Gukle Operator's Guide to the Extentled iRMX II Human InterJace Master Ind"J

VOLUME 2: Extended |RMl@ II Operating System User Guides Extended |RM),@ II Nucleus User's Cuide

Ertended iRMP II Basic I/O System User's Cuide Ertended |RM)@ II Extended I/O System Use r's Guide Lrtended |RM)F II Human Interface User'.s Gukle Extendzd |RMP II Application Loader User'.s Guide

Extended |RM}o II Universal DeveloDnrcnt Interface User's Guide Device Driverc User's Guid.e

VOLUME 3: Extended IRM)..o II System Culls

Extended |RMN II Nucleus System Calls Reference Manual Extended |RM)F II Basic I/O System Calls Ret'erence Manual Extended IRM}@ II Extended I/O System Calls Reference Manual Extended |RMÌ@ II Application Loader Ststem Calls Ret'erence Manual Ertended lRMXo II Human Interface S.v-stent Culls Ret'erence Manual Extended IRMXD II UDI System Calb Reference Manual

VOLUME 4: Extended |RM},€ II Operating Systetn Utilities Extendtd |RMXD II Bootstrap Loader Ret'ertnce Manual Extended |RMN II System Debugger Reference Manual Lttended LRM)Ó II Disk Veification Utiliry Ret'erence Manual Extended iRM},@ II Programming Technique s Reference Manual Guide to the Lrtended |RM)P II Interactive Configuration Utility

VOLUME 5: Extended |RM}@ II Interactive ConJìgurutbn Utiliry Reference Extended |RMXo II Interactive Conftguration Utility Reference Manual

lv iRlllX@ II Svstem Calls Volume

(5)

REV. REVISION HISTORY DATB

-001 O r i g i n a l Is s u e . 0 l / 8 8

(6)

(7)

intel

E X T E N D E D i R M X @ I I N U C L E U S S Y S T E M C A L L S R E F E R E N C E M A N U A L

I n t e l C o r p o r a t i o n 3 0 6 5 B o w e r s A v e n u e 5 a n t a C l a r a , C a l i f o r n i a 9 5 0 5 1

C o p y r i g h t . 1 9 8 8 , In t e l C o r p o r a l i o n , A l l R i q h t s R e s e r v e d

(8)

(9)

PREFACE

I N T R O D U C T I O N

This manual documents the system calls of the Nucleus, the innermost layer of the Extended iRMX@ II Operating System. The inlbrmation provided in this manual is intended as a reference to the systen.ì calls and provides detailed descriptions of each call.

READER LEVEL

This manual is intended for programnrers who rre familiar with the concepts and

terminolory introduced in the Ertended |RMX II Nucleus User's Guide and with the PL/M- 2 8 ó p r o g r a m m i n g l a n g u a g e .

MANUAL ORGANIZATION

This manual presents logical groupings of Nucleus System calls. The individual calls within each group are in alphabetical orcier îor easy reference. The following list shows how the system calls are groupccl:

. Calls for jobs

. Calls for mailboxes . Calls for semaphores

. Calls for segments and mcmory pools . Calls for descriptors

. Calls for all objects

. Calls for exception handlers . Calls for exception handÌers

o Calls for interrupt handlers, ttsks, ancì levels . Calls for composite objects

. Cal.ls for extension objects . Calls for deletion control

. Calls f o r o p e r a t i n g s y s t c m c \ t c n s i ( ) n s . Calls for regions

. Calìs for MULTIBUS@ ll svstems

Nucleus Svstem Calls ^{l l l}

(10)

PREI-ACE

lv

Thjs manual uses the following conventions:

. System call names appear as headings on the outside upper corner of each page. The first appearance of each system call name is printed in ink; subsequent

appearances are in black ink.

. Throughout this manual, most system calls are shown using a generic shorthand (such as ACCEFNCONTROL instead of RQ$ACCEPT$CONTROL). This convention is used to make the names easier to understand. Only the calls that are iRMX II

versions of iRMX I system calls are spelled out completely (such as

RQE$CREATE$JOB). When you use the system calls in your programs, you must specifo the actual PL/M-286 external-procedure names.

You can also invoke the system calls from assembly language, but you must obey the PL/M-286 calling sequences when doing so. For more information on these calling sequences refer to the Extended |RMX II Progranmting Teclmique.s Reference Manual.

Nucleus System Calls

(11)

INTRODUCTION

This manual presents the iRMXo II Nucleus system calls in functional groups and provides a detailed description of each one.

The callìng sequence for each call is the same as for the PLIM-286 interface. The information for each system call is organized in the following order:

o A brief sketch of the effects of the calÌ.

o The PL/M-286 calling sequence for the system call.

. Definitions of the input parameters, if any.

. Definitions of the output parameters, if any.

o A detailed description of the effects of the call.

. An example of how the system call can be used.

. The condition codes that can result from using the call, with a description of the possible causes of each condition.

Throughout this manual, PLIM-286 data types such as BYTE, WORD, POINTER and SELECTOR are used. In addition, the iRMX II data tlpes TOKEN and STRING are used. A TOKEN is a 16-bit value that uniquely identifies an iRMX II object. A STRING is a sequence of consecutive bytes in which the first byte specifies the number of bytes that follow it in the string. When these terms are used as data types, they are aÌways

capitalized.

Because TOKEN is not a PL/M-28ó data type, you must declare it to be lìterally a SELECTOR every place you use it. The word "token" in lowercase refers to a value that the iRMX II Operating System returns to a TOKEN (the data qpe) when it creates the obiect.

(16)

E X T E N D E D i R M X O I I N U C L E U S S Y S T E M C A L L S

The examples used in this manual assume the reader is familiar with PL/M. In these examples, the appropriate DECI-A,RE and INCLUDE statements are made first. The reader should note the use of an INCLUDE statement that declares all of the system calls included in the iRMX II Operating System.

Following this introduction is a system call dictionary in which the calls are grouped according to rype. The dictionary includes short descriptions and page numbers ofthe complete descriptions that follow.

Nucleus Svstem Calls

(17)

NUCLEUS SYSTEM CALL DICTIONARY

c a L L S F O R JO8S... . . . P A G E CREATE$JOB -- Creates a job (whose memory pool is limited ro lM

b y t e ) w i t h a task and returns a t o k e n f o r t h e jo b . . . l 0 RQE$CREATE$JOB - Creates a job (with memory pool up to 16M

b y t e s ) a n d a t a s k a n d re t u r n s t h e to k e n f o r t h e jo b . . . l 8 D E L E T E $ J O B - Deletes a jo b . . . . . . 2 6 OFFSPRING -- Provides a segment containing tokens of the schild

j o b s of the specified j o b . . . . . . 2 8 RQE$OFFSPRING - Provides, in a user-supplied dara structure, a lìst

o f t o k e n s f o r t h e c h i l d j o b s of the specified j o b . . . 3 1 C A L L S F O R T A S K S . . . . . . P A G E

C R E A T E $ T A S K - - Creates a t a s k a n d re t u r n s a t o k e n f o r i t . . . 3 4 D E L E T E $ T A S K - - Deletes a t a s k t h a t is n o t a n in t e r r u p t t a s k . . . 3 8

G E T $ P R I O R I T Y - - Returns t h e s t a t i c p r i o r i r y o f a r a s k . . . 4 1 GET$TASK$TOKENS -- Returns to the caller a roken for either itself,

i t s jo b , it s jo b ' s p a r a m e t e r o b j e c t , o r t h e r o o t jo b . . . . . . 4 3 RESUME$TASK -- Decreases a task's suspension depth by one;

resumes (unsuspends) the task if the suspension depth becomes

z e r o . . . , , . , . . . . . . 4 5 S E T $ P R I O R I T Y - - Changes a t a s k ' s p r i o r i t y . . . . . 4 8 SLEEP -- Places the calling task in the asleep state for a specifìed

a m o u n t o f t i m e . . . . . 5 2 SUSPEND$TASK -- Increases a task's suspension depth by one;

s u s p e n d s t h e ta s k i f i t i s n o t a l r e a d y s u s p e n d e d . . . . . . 5 4 C A L L S F O R M A I L B O X E S . . . . . . P A G E CREATE$MAILBOX - Creates a mailbox and returns a token for

i t . . . . . . 5 7 D E L E T E $ M A I L B O X - Deletes a m a i . l b o x . . . . . . ó 1

(18)

CALLS FOR MAILBOXES (continued) PAGE

RQ$RECEM$DATA - Allows the calling task to receive a data message from a mailbox; the task has the option of waiting if no

m e s s a g e s a r e p r e s e n t . . . . . . . 6 3 RECEM$MESSAGE - Allows the calling task to receive an object;

the task has the option of waiting if no objects are present... ... 66 SEND$DATA - Sends a data message of up to 80H characters to a

m a i 1 b o x . . . . . . . . . 7 0 S E N D $ M E S S A G E - - Sends a n o b i e c t t o a m a i l b o x . . . . . . 7 3 C A L L S F O R S E M A P H O R E S . . . . , . , . . . P A G E CREATE$SEMAPHORE -- Creates a semaphore and returns a token

f o r i t . . . . . . . 7 7 D E L E T E $ S E M A P H O R E - - Deletes a s e m a p h o r e . . . . . . 8 0 RECEIVE$UNITS -- Asks for a specific number of units from a

s e m a p h o r e . . . . . . 8 3 SEND$UNITS - Adds a specific number of units to a semaphore... 86

C A L L S F O R S E G M E N T S A N D M E M O R Y P O O L S . . . P A G E CREATE$SEGMENT - Creates a segment and returns a token

f o r i t . . . . . . 8 9 DELETE$SEGMENT - Returns a segment to the memory pool from

which it was allocated; can also delete a descriptor from the Global

D e s c r i p t o r T a b l e ( G D T ) . . . . . . . 9 l GET$POOL$ATTRIBUTES -- Returns the following memory pool

attributes of the caller's job: pool minimum and pool maximum (both limited to lM byte of memory), initial size, number of allocated 16-byte paragraphs, number of available 16-byte

p a r a g r a p h s . . . . 9 4 RQE$GET$POOTSATTRIB -- Returns the same information as

GET$POOL$ATTRIBUTES for any job, plus the amount of memory borrowed and the token of the parent job; returns pool mi

n i m u m a n d m a x i m u m v a l u e s f o r p o o l s g r e a t e r t h a n 1 M b y t e . . . . . . - . 9 7

(19)

CALLS FOR SEGMENTS AND MEMORY POOLS (continued)..,...PAGE G E T $ S I Z E - - returns t h e s i z e , i n b y t e s , o f a s e g m e n t . . . 1 0 1 SET$POOI-$MIN - Changes the minimum attribure of the memory

p o o l o f t h e c a l Ì e r ' s j o b . . . . . . 1 0 4

CALLS FOR BUFFER POOLS PAGE

CREATE$BUFFER$POOL - creates a buffer pool object... 106 DELETE$BUFFER$POOL -- deletes a buffer pool object ... 108 RELEASE$BUFFER -- Returns previously allocated buffer space to

t h e s p e c i f i e d b u f f e r p o o 1 . . . . . . 1 0 9 R E Q U E S T $ B U F F E R - - gets a b u f f e r f r o m a b u f f e r p o o l . . . 1 1 1 C A L L S F O R D E S C R I F T O R S . . . , . . . , . . . . P A G E RQE$CHANGE$DESCRIPTOR -- Changes the physical address or

s i z e o f a s e g m e n t b y m o d i f i n g it s descriptor i n t h e G D T . . . 1 1 3 RQE$CREATE$DESCRI OR -- Creates a descriptor in the GDT

describing a segment, and returns a token for that descriptor... ... 116 RQE$DELETE$DESCRIPTOR -- Removes a descriptor entry from

t h e G D T . . . . . . 1 1 9 CALLS FOR ALL OBJECTS ... ... PAGE CATALOG$OBJECT - Places an object in an object directory. ... 1,21 RQE$CHANGE$OBJECI$ACCESS -- Changes the access of an

n h i a n r t . A

RQE$GET$ADDRESS -- Returns the physical address of an

o b i e c t . . . . . . 1 2 8 RQE$GET$OBJEC'I$ACCESS -- Returns the access qpe of an

o b j e c t . . . . . . 1 3 1 GET$TYPE - Accepts a token for an object and returns its tlpe

c o d e . . . . . . 1 3 5 LOOKUP$OBJECT - Accepts a cataloged name of an object and

returns a token for i t . . . , . . , . . , . . , . . , . . . . ... 138

(20)

UNCATALOG$OBJECI -- Removes an object from an object

d i r e c t o r y . . . . . . 1 4 1

CALLS FOR EXCEPTION HANDLERS .... PAGE

GET$EXCEPTION$HANDLER -- Returns the current values of the

caller's exception handler and exception mode attributes ... 145 SET$EXCEPTION$HANDLER - Sets the exception handler and

e x c e p t i o n m o d e a t t r i b u t e s o f t h e c a l l e r . . . . . . 7 4 7 CALLS FOR INTERRUPT ÍIANDLERS, TASKS, AND LEVELS... PAGE

(* indicates the system calls that an interrupt handler can make)

. D I S A B L E - Disables a n in t e r r u p t 1 e v e 1 . . . . . . 1 5 1 E N A B L E - - E n a b l e s a n in t e r r u p t l e v e l . . . . . . 1 5 4 END$INIT$TASK - Informs root task that a synchronous

i n i t i a l i z a t i o n p r o c e s s h a s c o m p l e t e d . . . . . . 1 5 7

*ENTER$INTERRUPT -- Sets up a previously designated data

segment base address for the calling interrupt handler... 158 .EXIT$INTERRUPT -- Used by interrupt handlers to send an end-of-

i n t e r r u p t s i g n a l t o h a r d w a r e . . . . . . 1 6 2

*GET$LEVEL -- Returns the interrupt level of highest priority for which an interrupt handler has started but has not yet finished

p r o c e s s l n g . . . . . . 1 ó 5 RESET$INTERRUPT -- Cancels the assignment of an interrupt

handler to a level and, if applicable, deletes the inrerrupt task for

t h a t 1 e v e 1 . . . . . . 1 6 7 SET$INTERRUPT - Assigns an interrupt handler and, if desired, an

i n t e r r u p t t a s k t o a n in t e r r u p t l e v e I . . . . . . 1 7 1

*SIGNAL$INTERRUPT -- Used by interrupt handlers to invoke

i n t e r r u p t t a s k s . . . . . . 1 7 6 RQE$IMED$INTERRUPT -- Puts the calling interrupt task to sleep

until either it is called into service by an interrupt handler or a

s p e c i f i e d t i m e p e r i o d e I a p s e s . . . . . . 1 8 0

(21)

WAIT$INTERRUPT -- Puts the calling interrupt task to sleep until it

is called into service by an interrupt handler... ... 184

C A L L S F O R C O M P O S I T E O B J E C T S . . . . . . P A G E ALTER$COMPOSITE -- Replaces components of composite

o b j e c t s . . . . . . 1 8 8 CREATE$COMPOSITE -- Creates a composite object and returns a

t o k e n f o r i t . . . . . . 1 9 0 D E L E T E $ C O M P O S I T E - - Deletes a c o m p o s i t e o b j e c t . . . 1 9 3 INSPECT$COMPOSITE -- Returns a list of the component tokens

c o n t a i n e d i n a c o m p o s i t e o b j e c t . . . . . . 1 9 5 C A L L S F O R E X T E N S T O N O B J E C T S . . . . . . p A c E CREATE$EXTENSION -- Creates a new object type and returns a

t o k e n f o r i t . . . . . . . , . . . _ . . . 1 9 7 DELETE$EXTENSION -- Deletes an extension object and all

c o m p o s i t e s o f t h a t ty p e . . . . . . 2 0 0 C A L L S F O R D E L E T T O N C O N T R O L . . . . . . P A G E DISABLE$DELETION -- Makes an object immune to ordinary

d e l e t i o n . . . . . . 2 0 3 ENABLE$DELETION -- Makes an object susceptible to ordinary

deletion. Required only if the object has had its deletion

d i s a b l e d . . . . . . 2 0 6 FORCE$DELETE -- Deletes objects whose disabling depths arezero

o r o n e . . . . . . - 2 0 9 CALLS FOR OPERATING SYSTEM EXTENSIONS ...PAGE RQE$SET$OS$EXTENSION -- Attaches the entry-point address of a

user-written OS extension to a call gate or deletes such an entry... ...21,?, SIGNAT-$EXCEPIION -- Used by OS extensions to signal the

o c c u r r e n c e o f a n e x c e p t i o n . . . 2 1 5

(22)

C A L L S F O R R E G I O N S . . . . . . P A G E ACCEP,|$CONTROL - Causes the calling task to accept control from

the region only if control is immediately available. If control is not

available, the calling task does not wait at the region...218 CREATE$REGION -- Creates a region and returns a token for it... ...221 D E L E T E $ R E G I O N - Deletes a r e g i o n . . . . . . 2 2 3 RECEIVE$CONTROL - Causes the calling task to wait at the region

u n t i l th e ta s k r e c e i v e s c o n t r o l . . . . . . 2 2 6 SEND$CONTROL - Relinquishes control to the next task waiting at

t h e r e g i o n . . . . . . 2 2 9 N U C L E U S C O M M U N I C A T I O N S E R V I C E C A L L S . . . P A G E ATTACH$BUFFER$POOL -- Associates a buffer pool with one or

m o r e p o r t s . . . . . . 2 3 2 ATTACH$PORT - Forwards all messages sent to the port that issued

the call to another port known as a sink port... ...234 BROADCAST -- Sends a control message to every agent on the iPSB

b u s . . . . . . 2 3 6 CANCEL -- Performs synchronous cancellation of RSVP message

t r a n s m i s s i o n . . . . . . 2 3 8 CONNECT -- Locally connects a port and assigns a default remote

s o c k e t . . . . . . 2 4 0 CREATE$PORT -- Creates a port object that can be used to send and

receive MULTIBUS II messages between bus agents...242 D E L E T E $ P O R T - - Deletes a p o r t .. . . . . . 2 4 7 DETACH$BUFFER$POOL -- Ends the association between a buffer

p o o l a n d a p o r t . . . . . . 2 4 8 DETACH$PORT - Ends message forwarding from the source port to

t h e s i n k p o r t . . . . . . 2 5 0

(23)

NUCLEUS COMMUNICATION SERI'ICE CALLS (continued) ...PAGE GET$HOST$ID -- Returns the host ID of the board (agent) that

t h e ta s k is r u n n i n g o n . . . . . . 2 5 2 GET$PORTSATTRIBUTES -- Returns information about how the

specified port is set up ... .... ...253 RECEIVE - Accepts a message at a port... ...256 RECEM$FRAGMENT - Acceprs a part (fragmenr) of a requesr

( R S V P ) d a t a f n e s s a g e . . . . . . 2 6 0 RECEM$REPLY - Accepts a message that is a reply to an earlier

r e q u e s t . . . . . . 2 6 2 RECEIVE$SIGNAL -- Receives a signal from a remote host ar a

s p e c i f i e d p o r t . . . . . . 2 6 6 SEND -- Sends a data message from a port to a port on another board2

68

SEND$RSVP - lnitiates a request/response message interchange...271 SEND$REPLY - Sent in response to the RQ$SEND$RSVP system

c a l l .. . . . . . 2 7 4 SEND$SIGNAL -- Sends a MULTIBUS Il signal (dataless message)

t o a r e m o t e a g e n t ( b o a r d ) t h r o u g h t h e s p e c i f i e d p o r t .. . . . . . 2 7 7 MULTIBUS II INTERCONNECT CALLS...

GET$INTERCONNECT -- Retrieves the contents of the soecified

i n t e r c o n n e c t r e g i s t e r . . . . . . - . . . . . . 2 7 8 SET$INTERCONNECT - Ajters the conrents of an interconnecr

register to a value specified in the caII... ...280

(24)

The CREATE$JOB system call creates a job with a single task. The memory pool assigned with this system call is limited in size to 1M byte.

j o b : R Q $ C R E A T E $ J o B ( d i r e c t o r y $ s i z e , p a r a r n $ o b j , p o o l $ m i n , p o o l $ m a x , r n a x $ o b j e c t s , r n a x $ t a s k s , rn a x $ p r i o r i t y , e x c e p t $ h a n d l e r ,

j o b $ f I a g s . c a s k $ p r i o r i c y , s c a r c $ a d d r e s s , d a c a $ s e g , s t a c k $ p t r ,

s t n c L S c i z e t : c L S f l r o < è y . è n r S n t r \ '

Input Parameters

directory$size A WORD specifying the miuimum allowable number of entries a job can have in its object directory. The value zero indicates that no object directory is desired. The maximum value for this p a r a m e t e r i s 0 F F 0 H .

param$obj A TOKEN indicating the presence or absence of a parameter object. See the Extended |RMX II Nucleus User's Guide for an

:-tilff:T..* ,."-']"'i "ii"r " token ror the new job,s

parameter object.

If set to SELECTOR$OF(NIL), it indicates that the new jotr has no parameter object.

pool$min A WORD that specifies the minimum allowable size of the new job's pool, in 16-byte paragraphs. The poolgmin parameter is also the initial size of the new job's pool. Pool$min should be at least two paragraphs (20H). If the stack$ptr parameter has a base value of SELECTOR$OF(NIL), pool$min should be at least rwo

paragraphs plus the value of stack$size in 16-byte paragraphs.

pool$max A WORD that indicates the maximum allowable size of the new job's memory in 16-byte paragraphs. If pool$max is smaller than pool$min, an E$PARAM error is reîurned.

max$objects A WORD that specifies rhe maximum number of objects that the created iob can own.

o If not 0FFFFH, contains the maximum number of objects, created by tasks in the new job, that can exist at one time.

' 11,',1i.1îî;,l,l:i:ì'll."f ffi ::nl'Ji::" the number of

t 0 Nucleus System Calls

(25)

CREATE$JOB

max$tasks A WORD that specifies the maximum number of tasks that can exist simultaneously in the new job.

. If not 0FFFFH, it contains the maximum number of tasks that can exist simultaneously in the new job.

. If 0FFFFH, it indicates that there is no limit to the number of tasks that tasks in the new job can create.

. It cannot b€ zero. A value of 0H will produce the E$LIMIT exception.

max$priority A BYTE that sets an upper limit on the priority of the tasks created in the new job.

o If not zero, it contains the maximum allowable priority of tasks in the new job. If max$priority exceeds the maximum priority of the parent job, an E$LIMIT error is returned.

o lî zero, it indicates that the new job is to inherit the maximum priority attribute of its parent job.

except$handler A POINTER to a structure of the following form:

STRÙCTURE (

EXCEPTION$HANDLER$ PTR POINTER, E X C E P T I O N $ M O D E B Y T E ) :

If exception$handler$ptr is not NIL, then it is a POINTER to the first instruction ofthe newjob's own exception handler. If

exception$handler$ptr is NIL, the new job's exception handler is the system default exception handler. In both cases, the exception handler for the new task becomes the default exceotion handler for the job.

The exception$mode indicates when control is to be passed to the exception handler. It is encoded as follows:

When Control Passes Value To Exceotion Handler

0 Never

I On programmer errors only 2 On environmental conditions only 3 On all exceptional conditions

Nucleus System Calls _{l l}

(26)

CREATE$JOB

job$flags A WORD containing information that the Nucleus needs to create and maintain thejob. The bits (where bit 15 is the high-order bit) have the following meanings:

Bits Meaning

15-2 Reserved bits that should be set to zero.

1 If0, then whenever a task in the newjob or any of its

descendant jobs makes a Nucleus system call, the Nucleus will check the parameters for validity.

If 1, the Nucleus will not check the parameters of Nucleus system calls made by tasks in the new job. However, if any ancestor of the new job has been created with this bit set to 0, there will be parameter checking for the new job.

0 Reserved bit that should be set to zero.

task$priority A BYTE that controls task priority as follows:

o If not zero, it contains the priority of the new job's initial task.

If the task$priority parameter is greater (numerically smaller) than the new job's maximum priority attribute, an E$PARAM e r r o r is r e t u r n e d .

. Ifzero, it indicates that the new job's initial task is to have a priority equal to the new job's maximum priority attribute.

start$arldress A POINTER to the first instruction of the new iob's initial task (the task created with thejob).

data$seg A TOKEN that specifies which data segment the new job's initial task is to use.

. If a valid selector, it is the base selector of the data segment of the new job's initial task.

. If SELECTOR$OF(NIL), it indicates that the new job's initial task assigns its own data segment. Refer to the Guide to the Extended |RMX II Interacti.ve Configuration Utility and the Extended |RMX II Interacti.ve Configuration UrrTiO, Reference manual for more information about data segment allocation.

stack$ptr A POINTER that specifies the location ofthe stack for the new job's initial task.

. If the pointer is valid, it points to the base of the user-provided stack of the new iob's initial task.

12 Nucleus Systen Calls

(27)

Description

The CREATE$JOB system call creates a job with an initial task and rerurns a token for thejob. The new job's parent is the calling task'sjob. The new job counts as one againsr the parent job's object limit. The new task counts as one against the new job,s object and task limits. The new job's resources come from the parent job, as described in the

Exten{led |RMX II Nucleus User's Guide. ln particular, the max$task and max$objects values are deducted from the creatingjob's maximum task and maximum objects attributes, respectively.

CREATE$JOB

o If the pointer is set to ML, it indicates that the Nucleus should allocate a stack for the new job's initial task. The length of the allocated segment is equal to the value of the stack$size parameter.

A WORD containing the size, in bytes, of the stack of the new job's initial task. The stack size must be at least 16 bytes and should be at least 300 (decimal) bytes if the new task is going to make Nucleus system calls. Refer to the Extended ikMX II Programming Techniques manual for further information on estimating stack sizes.

A WORD containing information that the Nucleus needs to create and maintain the job's initial task. The bits (where bit 15 is the high order bit) have the following meanings:

Bits Meaning stack$size

task$flags

Output Parameters

job

except$ptr

l5- 1 0

Reserved bits which should be set to zero.

If one, the initial task contains floating-point

instructions. These instructions require the Numeric Processor Extension (NPX) component for execution.

If zero, the initial task does not contain floating-point instructions.

A TOKEN to which the Operating System will return a roken for the new job.

A POINTER to a WORD to which the iRMX II Operating System will return the condition code generated by this system call.

Nucleus System Calls 13

(28)

CREATE$JOB

This system call is included for compatibility with iRMX I systems. When you use it, your memory pools are limited to 1M byte in size. To allocate larger memory pools, use the RQE$CREATE$JOB system call.

Example

/*****************************************************************

* T h i s exanple illustrates h o l r t h e C R E A T E $ J o B s y s c e n c a l l c a n b e *

* u s e d . *

***************************************************************** /

DECIARE TOKEN LITEMLLY ' SELECTOR' ;

, / * N U C L U S . E X T d e c l a r e s a l 1 s y s E e m c a 1 l s * /

$ INCLUDE ( /rrnx 2 8 6,z inclNUCLUS . EXT )

INITIALTASK: PROCEDURE EXTERNAL:

E N D I N I T I A L T A S K ; DECIARE j ob$ Eoken D E C T A R E d i r e c t o r y $ s iz e DECIARE paran$obj DECIARE poo I $rnin DECIARE poo l$rnax DECIARE nax$obj ects DECI-ARE rnax$ tasks D E C T A R E r n a x $ p r i o r i t y DECI-ARE except$handler D E C U R E j o b $ f l a g s DECLARE cask$pr ior i ty DECIARE s tart$addres s DECfARE data$seg DECIARE s tack$po inte r DECIARE s tack$ s ize DECI-ARE task$ flags DECLARE s tatus

TOKEN ; WORD ; TOKEN : WORD ; WORD ; WORD ; WORD ; B Y T E ; P O I N T E R ; WORD ; BYTE ; P O I N T E R : TOKEN ; P O I N T E R ; WORD ; WORD ; WORD :

SA},TPLEPROCEDURE :

P R O C E D U R E ;

d i r e c t o r y $ s i z e : 10; , / * m a x 1 0 e n t r i e s i n o b j e c t d i r e c t o r y * / p a r a m $ o b j * S E L E C T o R $ o F ( N I L ) ; / * n e v j o b h a s n o p a r a n e r e r o b j e c r * / p o o l $ m i n - O I F F H ; / * m i n 0 1 F F H , r n a x 0 F F F F t l 1 6 - b y t e * / p o o l $ m a x : O F F F F H ; / * p a r a g r a p h s i n j o b p o o l * / m a x $ o b j e c t s : O F F F F H ; , / * n o l i m i c t o n u m b e r o f o b j e c t s * / m a x $ t a s k s : l 0 ; , / * 1 0 t a s k s c a n e x i s t s i n u l È a n e o u s l y * / m a x $ p r i o r i t y : 0 ; / * i n h e r i t n a x p r l o r i t y o f p a r e n ! * / e x c e p t $ h a n d l e r - N I L ; / * u s e s y s t e m d e f a u l t e x c e p t h a n d l e r * / j o b $ f l a g s : 0 ; / * p a r a r n e r e r v a l i d a t i o n i s o n * / t a s k $ p r i o r i t y : 0 ; , / * s e t i n i r i a l t a s k t o m a x p r i o r i . l y * /

s t a r t $ a d d r e s s - @INITIALTASK;

/ * p o i n t s È o f i r s t i n s t r u c t i o n o f

i n i t i a l r a s k * /

t4 Nucleus System Calls

(29)

d a c a $ s e g - S E L E C T O R $ o F ( N I L ) ; s t a c k $ p o i n t e r : N I L ;

s c a c K v s r z e : ) I z : t a s k $ f l a g s : 0 ;

T y p i c a l P L / Y I - 2 8 6 S È a r e r n e n t s

CREATE$JOB

/* initlal task seÈs up or.rn data

segnent */

, / * N u c l e u s a l l o c a t e s s t a c k * / / * 5 1 2 b y t e s i n s t a c k o f i n i t i a l t a s k , / * n o f l o a t l n g - p o i n t i n s t r u c È i o n s * / . T y p i c a l P L / 1 4 - 2 8 6 S t a t e m e n t s

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

* T h e c a l l i n g t a s k c r e a t e s a j o b w l t h a n i n i t i a l t a s k l a b e l e d *

* I N I T I A L î A S K . *

******************************************************************/

j o b $ to k e n - R Q $ C R E A T E $ J O B ( d i r e c t o r y $ s i z e , p a r a m $ o b j , p o o l $ r n i n , p o o l $ m a x , n a x $ o b j e c ts , m a x $ t a s k s , r n a x $ p r i o r i t y , e x c e p t $ h a n d I e r , j o b $ fl a g s , t a s k $ p r i o r i t y , s t a r t $ a d d r e s s , d a t a $ s e g , s t a c k $ p o in t e r , s t a c k $ s i z e , t a s k $ f l a g s ,

@ s t a t u s ) ;

END SAMPLEPROCEDURE ;

Condition Codes

E$OK

E$B,,\D$ADDR

E$CONTEXT

0000H No exceotional conditions.

800FH At least one of the except$handler, data$seg, or stack$ptr parameters is invalid. Either a selector does not refer to a valid segnent, or an offset is outside the segment boundaries.

0005H Thejob containing the calling task is in the process of being deleted.

Nucleus System Calls l 5

(30)

CREATE$JOB

E$EXIST

E$LIMIT

E$MEM

E$PARAM

0006H The param$obj parameter is not

SELECTOR$OF(ML) and is not a token for an existing object.

0004H At least one ofthe following is true:

o max$objects is larger than the unused portion of the object allotment in the calling task's job.

. max$tasks is larger than the unused portion of the task allotment in the calling task's job.

. max$priority is greater (numerically smaller) than the maximum allowable task prioriw in the calling task's job.

. directory$size is larger than 0FF0H.

. The initial task would exceed the object limit in the new job. That is, the max$objects

parameter rs set to zero.

. The initial task would exceed the task limit in the new job. The max$tasks parameter is set to zefo.

0002H At least one of the following is true:

r The memory available to the new job is not sufficient to create a job descriptor (an internal data structure) and the object directory.

. The memory available to the new job is not sufficient to satisfy the pool$min parameter.

o The memory available to the new job is not sufficient to create the task as specified.

. pool$min is less than 16 + (number of paragraphs needed for the initial task and a system-alìocated stack) + 5 (if the task uses rhe NPX component).

o pool$min is greater than pool$max.

. task$priority is unequal to zero and greater (numerically smaller) than max$priority.

o stack$size is less than 16.

. the exception handler mode is not valid.

l ó Nucleus Svstem Calls

(31)

CREATE$JOB

E$SLOT 000CH There isn't enough room in the GDT for the new job and task descriptors.

Nucleus System Calls t 7

(32)

The RQE$CREATE$JOB system call creates a job with a single task. It provides the same services and has the same syntax as the CREATE$JOB system call, except that it can allocate memory oools of uD to lóM bvtes in size.

j o b - R Q E S C R E A T E S J O B ( d i r e c t o r y g s i z e , p a r a u r $ o b J , p o o l $ n i n , p o o l $ m a x , r n a x $ o b j e c t s , m a x $ t a s k s , n a x $ p r i o r i t y ,

e x c e p c $ h a n d l e r , j o b $ f l a g s , t a s k $ p r l o r l t y , s c a r t $ a d d r e s s , d a t a $ s e g , s t a c k $ p t r , s t a c k $ s i z e , t a s k $ f 1 a g s , e x c e p t $ p t r ) ;

Input Parameters

directorv$size

param$obj

pool$min

pool$max

mò\$objects

A WORD specifying the maximum allowable number of entrres a job can have in its object directory. The value zero is permitted, for the case where no object directory is desired. The maximum value for this parameter is 0FF0H.

A TOKEN indicating the presence or absence of a parameter object. See the Extended |RMX II Nucleus User's Guidz îor an explanation of parameter objects.

. If a valid selector, it must contain a token for the new lob's parameter object.

o If set to SELECTOR$OF(ML), it indicates that the new job has no parameter object.

A DWORD that specifies the minimum allowable size of the new job's pool, in 16-byte paragraphs. The pool$min parameter is also

the initial size of the new job's pool. Poolgmin should be at least two paragraphs (20H bytes) and no more than OFFFFFH. If the stack$ptr parameter has a base value of SELECTOR$OF(NIL), pool$min should be at least two paragraphs plus the value of stack$size in 16 byte paragraphs.

A DWORD that indicates the maximum allowable size of the new job's memory in 16-byte paragraphs. If poolgmax is smal.ler than

pool$min, an E$PARAM error is returned.

A WORD that specifies the maximum number of objecrs that the created job can own.

. If not OFFFFH, contains the maximum number of objects, created by tasks in the new job, that can exist at one time.

l 8 Nucleus System Calls

(33)

RQESCREATE$JOB

. If 0FFFFH, indicates that there is no limit to the number of objects that tasks in the new job can create.

max$tasks A WORD that specifies the maximum number of tasks that can exist simultaneously in the new job.

o If not OFFFFH, it contains the maximum number of tasks that can exist simultaneously in the new job.

. If OFFFFH, it indicates that there is no limit to the number of tasks that tasks in the new job can create.

. It cannot be zero. A value of 0H will produce the E$LIMIT exception.

max$priority A BYTE that sets an upper limit on the priority of the tasks created in the new job.

. If not zero, it contains the maximum allowable priority of tasks in the new job. If max$priority exceeds the maximum priority of the parent job, an E$LIMIT error is returned.

o If zero, it indicates that the new job is to inherit the mzr-rimum priority attribute of its parent job.

except$handler A POINTER to a structure of the following form:

STRUCTURE (

EXCEPTION$HANDLER$PTR POINTER, E X C E P T I O N $ M O D E B Y T E ) ;

If exception$handler$ptr is not NIL, then it is a POINTER to the fifst instruction of the new job's own exception handler. If exception$handler$ptr is NIL, the new job's exception handler is the system default exception handler. In both cases, the exception handler for the new task becomes the default exception handler for the job.

The exception$mode indicates when control is to be passed to the exception handler. It is encoded as follows:

When Control Passes Value To Exception Handler

0 Never

1 On programmer errors only 2 On environmental conditions only 3 On all exceptional conditions

Nucleus System Calls l 9

(34)

ROE$CREATE$JOB

job$flags A WORD containing information that the Nucleus needs to create and maintain thejob. The bits (where bit 15 is the high-order bit) have the following meanings:

Bits Meaning

l5-2 Reserved bits that should be set to zero.

1 If 0, then whenever a task in the newjob or any of its descendant jobs makes a Nucleus system call, the Nucleus will check the parameters for validity.

If l, the Nucleus will not check the parameters of Nucleus system calls made by tasks in the new job.

However, if any ancestor of the new job has been created with this bit set to 0. there will be Darameter checking for the new job.

0 Reserved bit that should be set to zero.

task$priority A BYTE that controls task priority as follows:

o If not zero, it contains the priority of the new job's initial task.

If the task$priority parameter is greater (numerically smaller) than the new job's maximum priority attribute, an E$PARAM error is returned.

c If zero, it indicates that the newjob's initial task is to have a priority equal to the new job's maximum priority attribute.

start$address A POINTER to the first instruction of the new iob's initial task (the task created with the job).

data$seg A TOKEN that specifies which data segment the new job's initial task is to use.

o If a valid selector, it is the base selector of the data segrnent of the new job's initial task.

. If SELECTOR$OF(NIL), it indicates that the new job's initial task assigns its own data segment. Refer to the Guide to the Extended |RMX II Interactive Configumtion Utílity and the Extended |RMX II Interactive Configuration Utility Reference manual for more information about data segment allocation.

stack$ptr A POINTER that specifies the location of the stack for the new job's initial task.

. If the pointer is valid, it points to the base of the user-provided stack of the new iob's initial task.

20 Nucleus System Calls

(35)

Output Parameters

j n b

except$ptr

Description

The RQE$CREATE$JOB system call creates a job with an initial task and returns a token for thejob. The new job's parent is the calling task'sjob. The new job counts as one against the parent job's object limit. The new task counts as one against the new job's object and task limits. The new job's resources come from the parent job, as described in the Extended |RMX II Nucleus User's Guilz. In particular, the max$task and maxgobjects values are deducted from the creatingjob's maximum task and maximum objects

attributes, respectively.

RQE$CREATE$JOB

. If the pointer is set to ML it indicates that the Nucleus should allocate a stack for the new job's initial task. The length of the allocated segment is equal to the value of the stack$size parameter.

A WORD containing the size, in bytes, of the stack of the new job,s initial task. This size must be at least 16 (decimal) bytes. The Nucleus increases specified values that are not multiples of 16 up to the next higher multiple of 16.

The stack size should be at least 300 (decimal) bytes if the new task is going to make Nucleus system calls. Refer to the Extended iRMX II Programming Techniques manual for further information on estimating stack sizes.

A WORD containing information that the Nucleus needs to create and maintain the job's initial task. The bits (where bit 15 is rhe high order bit) have the following meanings:

B i t s M e a n i n g stack$size

task$flags

15- 1 0

Reserved bits which should be set to zero.

If one, the initial task contains floating-point

instructions. These instructions require the Numeric Processor Extension (NPX) component for execution.

If zero, the initial task does not contain floating-point instructions.

A TOKEN to which the Operating System will return a token for the new job.

A POINTER to a WORD to which the iRMll II Operating System will return the condition code generated by this system call.

Nucleus Svstem Calls 2 l

(36)

ROE$CREATE$JOB

This system call is an extension ofthe CREATE$JOB system that supports the full memory-addressing capabilities of the iRMX II Operating System. When you use it, you can assign memory pools of up to 16M bytes in size.

DECI-ARE DECIARE D EC I-A,RE DECI.ARE DECI^ARE DECIARE DECI.ARE DECI.{RE DECI.ARE DECI.ARE DECI"ARE DECIARE DECIARE DECIARE DECT.ARE DECT^ARE DECIARE

j o b $ t o k e n d i r e c t o r y $ s i z e pararn$obj p o o l $ m i n poo 1$rnax rnax$obj ec ts rnax$ tasks r n a x $ p r i o r i t y e x c e p t $ h a n d l e r

t a s k $ p r i o r i c y s t a r t $ a d d r e s s d a t a $ s e g s t a c k $ p o in t e r t a s k $ f l a g s

s E a E u s

TOKEN ; WORD ; TOKEN ; DWORD ; DWORD ; WORD ; WORD ;

av-t c

P O I N T E R ; WORD ;

R\/TF .

PO INTER : TOKEN ; PO INTER ; 1IORD ; WORD ; WORD ;

SAI'fPLEPROCEDURE :

P R O C E D U R E ;

u r r c w u v r J v r r z

p a r a n $ o b j : S E L E C T O R $ O F ( N I L )

p o o l ì m l n : u 1 i . l H ; P o o I l m a x : U Ì t I I l t l ; m a x $ o b j e c t s - O F F F F H ;

r n a x $ t a s k s - 1 0 ; m a x $ p r i o r i t y : 0 ; e x c e p t $ h a n d l e r : N I L ; j o b $ f l a g s - 0 ;

t a s k $ p r i o r i t y - 0 ;

, / * m a x 1 0 e n t r i e s i n o b j e c t d i r e c t o r y * / / * n e w j o b h a s n o p a r a m e t e r o b j e c L * / /* rnin 01Fl'H, max oFFFFFH L6-byte */

/* par agr aphs in job pool */

/ * n o l i m i t c o n u r n b e r o f o b j e c t s * / , / * 1 0 t a s k s c a n e x i s t s i m u l - t a n e o u s l y * / , / * í n h e r i t m a x p r i o r i t y o f p a r e n t * / / * u s e s y s t e m d e f a u l t e x c e p t h a n d l e r * / / * p a r a m e t e r v a l i d a t i o n l s o n * / , / * s e t i n i t i a l t a s k t o m a x p r i o r Í t y x /

Example

/ * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * : k * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *

* T h i s e x a n p l e i l l u s t r a t e s h o w t h e R Q E $ C R E A T E $ J o B s y s t e r o c a l l *

* c a n b e u s e d . *

******************************************************************/

DECIARE TOKEN L I T E R A L L Y ' S E L E C T O R ' ; , / * N U C L U S . E X T d e c l a r e s a l l s y s t e n c a l l s * , /

$ INcLUDE ( /rrnx2 8 6/ inclNUcLUS . EXT )

INITIALTASK: PROCEDURE EXTERNAL;

E N D T N I T I A L T A S K ;

22 Nucleus Svstem Calls

(37)

s t a r t $ a d d r e s s : @INITIALTASK:

d a t a $ s e g : S E L E C T O R S O F ( N I L ) ;

RQE$CREATE$JOB

/ * p o i n t s c o f i r s t i n s t r u c t i o n o f

i n i t i a l t a s k * /

, / * í n i t i a t t a s k s e t s u p o v n d a t a

s e g m e n t * /

, / * N u c l e u s a l l o c a t e s s t a c k * / / * 5 1 2 b y t e s i n s r a c k o f i n i t i a l t a s k * . / / * n o f l o a C i n g - p o i n t i n s c r u c t i o n s * / s t a c k $ p o i n t e r

s t a c k $ s i z e - t a s k $ f l a g s :

- N I L ; 5 L 2 ; 0 ;

. T y p i c a l P L / 1 1 - 2 8 6 S ra r e n e n r s

/******************x***************************)k*******)r***********

* T h e c a l l i n g t a s k c r e a t e s a j o b w i t h a n i n i t i a l t a s k l a b e l e d *

* I N I T I A L T A S K . *

***************************************x**************************

/ j o b $ t o k e n : RQEgCREATE$JOB ( d i r e c t o r y $ s i z e ,

p a r a m $ o b j , p o o I l m l n , p o o l $ m a x , m a x $ o b j e c ts , m a x $ t a s k s , r n a x $ p r i o r i t y , e x c e p t $ h a n d l e r , j o b $ f l a g s , t a s k $ p r i o r i t y , s t a r t $ a d d r e s s , d a t a $ s e g , s t a c k $ p o i n t e r , t a s k $ f 1 a g s , Gs tatus ) ; T y p i c a l P L / Y I - 2 8 6 S ra r e n e n t s

END SA},IPLEPROCEDURE :

Nucleus Systern Calls 23

(38)

RQE$CREATE$JOB

Condition Codes

E $ O K

E$BAD$ADDR

E$CONTEXT E$EXIST

E $ L I M I T

E$MEM

0000H No exceptional conditions.

800FH At least one of the following parameters is invalid: except$handler, data$seg, or stack$ptr.

Either a selector does not refer to a valid segment, or an offset is outside the segment boundaries.

0005H Thejob containing the calling task is in the process of being deleted.

0006H The param$obj parameter is not

SELECTOR$OF(NIL) and is not a token for an existing object.

. max$objects is larger than the unused portion of the object allotment in the calling task's job.

. max$tasks is larger than the unused portion of the task allotment in the calling task's job.

. max$priority is greater (numerically smaller) than the maximum allowable task priority in the calling task's job.

o directory$size is larger than 0FF0H.

. The initial task would exceed the object limit in the new job. That is, the max$objects

parameter is set to zero.

. The initial task would exceed the task limit in the new job. The max$tasks parameter is set to zefo-

At least one of the following is true:

The memory available to the new job is not sufficient to create a job descriptor (an internal data structure) and the object directory.

The memory available to the new job is not suffìcient to satisfy the pool$min parameter.

The memory available to the new job is not sufficient to create the task as soecified.

0002H

2 4 Nucleus Svstem Calls

(39)

RQE$CREATE$JOB

E$PARAM 8004H At least one of the following is true:

o pool$min is less than 16 + (number of paragraphs needed for the initial task and a system-allocated stack) + 5 (if the task uses the NPX component).

. pool$min is greater than pool$max.

. task$priority is unequal to zero and greater (numerically smaller) than max$priority.

. stack$size is less than 16.

o the exception handler mode is not valid.

E$SLOT 000CH There isn't enough room in the GDT for the new job and task descriptors.

Nucleus Svstem Calls ) <

(40)

The DELETE$JOB system calì deletes a job.

C A L L R Q S D E L E T E $ J O B ( j o b , e x c e p t $ p t r ) ;

Input Parameter

j n b

Output Parameter

except$ptr A POINTER to a WORD to which the iRMX II Operating System will return the condition code generated by this system call.

Description

The DELETE$JOB system call deletes the specified job, all of the job's tasks, and all objects created by the tasks. Exceptions are that jobs and extension objects (see the Extended |RMX II Nucleus User's Cuide) created by tasks in the target job must be deleted prior to the call to DELETE$JOB. Information concerning the descendants of a job can be obtained by invoking the OFFSPRING system call.

During the deletion of any interrupt tasks owned by the job, the interrupt levels associated with those tasks are reset. The levels that do not have interrupt tasks associated with

them will not be reset during an RQ$DELETE$JOB call.

During deletion, all resources thar the target job had borrowed from its parent are r e t u rn e d .

Deleting a job causes a credit of one toward the object totaì of the parent job. Also, the maximum tasks and maximum objects attributes of the deleted job are credited to the current tasks and current objects attributes, respectively, of the parent job.

Example

/********************************************************************

* T h i s exarnple ilLustrates how the DELETE$JOB s y s t e r n c a l l c a n b e *

* u s e d t o d e l e t e t h e c a l l i n g t a s k ' s j o b . *

* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * ) k * * * * * * * * * * * * * * * * * * * * * * * * /

DECIARE TOKEN LITEMLLY ' SELECTOR' :

A TOKEN for the job to be deleted. A value of SELECTOR$OF(NIL) specifies the calling task's job.

26 Nucleus System Calls

(41)

DELETE$JOB

/ * N U C L U S . E X T d e c l a r e s a l l s y s t e r n c a l 1 s * /

$ INCLUDE ( /rmx2 8 6/ inclNUcLUS . EXT )

DECIARE cal l ing$ rasks gj ob TOKEN;

DECI-qRE status WORD;

SAMPLEPROCEDURE :

PROCEDURE;

c a l l i n g $ t a s k $ j o b - S E L E C T O R g o T ( N I L ) ; /* Ser job co task,s job. x7

. T y p i c a l P L / Y L - 2 8 6 S t a t e n e n t s

/********************************************************************

* If you ser rhe job pararnerer ro SELECTOR$OF(NIL), r h e D E L E T E g J O B *

* s y s t e m c a l l w i l l d e l e t e t h e c a l l i n g t a s k , s j o b . *

******************************************************************** /

C A L L R Q $ D E L E T E $ J O B ( c a l l i n g g t a s k s g j o b , G s t a r u s ) ;

END SAMPLEPROCEDURE ;

E$NOT$CONFIGURED 0008H This system call is not part of the present configuration.

E$TYPE 8002H The jobparameter is a token for an object that rs not a Joo.

0005H At least one of the following is true:

o There are undeleted jobs or extension objects (see the Extended |RMX II Nucleus User's Guide) which have been created by tasks in the target job.

. The deleting task has access to data guarded by a region contained in the job to be deleted.

(Refer to the Extended |RMX II Nucleus User's Guide for information concerning regions.) 0006H Thejob parameter is not a token for an existing

object.

Condition Codes

E$OK

E$CONTEXT

E$EXIST

Nucleus Svstem Calls ^{, 1}

(42)

The OFFSPRING system call returns a token for each child (ob) of a job.

t o k e n $ l i s t - R Q $ o F F S P R I N C ( j o b , e x c e p t S p t r ) ;

Input Parameter

j o b A TOKEN for the job whose offspring are desired. A value of SELECTOR$OF(NIL) specifies the calling task's job.

Output Parameter

token$list A TOKEN that indicates the children of the specified job.

. If a valid selector, the TOKEN contains a token for a segrnent.

The first word in the segment contains the number ofwords in the remainder of the segment. Subsequent words contain the tokens for jobs that are the immediate children of the specified job.

. If SELECTOR$OF(NIL), the specified job has no children.

Description

The OFFSPRING system call returns the token for a segment. The segment contains a token for each chiid of the specifie<J job. By repeated use of this call, tokens can be obtained for all descendants of a job; this information is needed by a task which is attempting to delete a job that has child jobs.

Example

/************************************************************************

* T h i s e x a n p l e i l l u s t r a t e s h o r . r th e O F F S P R I N G s y s t e r n c a l l c a n b e u s e d *

* t o r e t u r n a t o k e n f o r e a c h c h i l d o f a j o b . *

************************************************************************/

DECIARE TOKEN LITEMLLY 'SELECTOR' ;

/ x N U C L U S . E X T d e c l a r e s a l l s y s c e m c a l l s * /

$ INCLUDE ( /rmx2 8 6/ incINUCLUS . EXT )

: 8 Nucleus System Calls

(43)

OFFSPRING

D E C I A R E t o k e n $ l i s t T o K E N : D E C I A R E c a l I i n g $ ta s k s $ j o b T O K E N ;

DECIARE status WoRD;

SA.MPLEPROCEDURE :

PROCEDURE;

. Typical PL/14-286 statenents

/************)r***********************************************************

* I n t h i s e x a m p l e , t h e c a l l i n g t a s k l n v o k e s t h e s y s t e n c a l l O F F S P R I N G *

* t o o b t a i n a t o k e n f o r a s e g m e n t . T h i s s e g n e n t c o n t a i n s t h e t o k e n s *

* f o r j o b s L h a t a r e i m r n e d i a t e c h i l d r e n o f t h e c a l l i n g t a s k ' s j o b . *

************************************************************************/

c a l l i n g $ t a s k s 9 j o b : S E L E C T O R $ O F ( N I L ) ;

t o k e n $ l i s t : R Q $ O F F S P R I N G ( c a l l i n g $ t a s k s g j o b ,

@ s t a t u s ) ; . T y P i c a l P L / t t L - 2 8 6 S ta t e m e n t s

END SAI'ÍPLEPROCEDURE;

Condition Codes

E$OK E$EXIST

0006H Thejob parameter is not a token for an existing object.

E$LIMIT 0004H The calling task'sjob has already reached its object limit.

E$MEM 0002H The memory available to the specified job is not sufficient to complete this call.

E$NOT$CONFIGURED 0008H This.system call is not part of the present conlrquratron.

Nucleus System Calls 29

(44)

O F F S P R I N G

E$SLOT 000CH There isn't enough room in the GDT for another descriptar.

E$TYPE 8002H Thejob parameter contains a token for an object that is not a job.

3 0 Nucleus Svstem Calls

(45)

The RQE$OFFSPRING system call performs the same function as the Re$OFFSPRING system call. However, RQE$OFFSPRING returns the list of child iob tokens in a

structure that you supply, rather than in a segment.

C A L L R Q E $ O F F S P R I N C ( j o b , l i s r g p r r , e x c e p r g p r r ) ;

Input Parameter

j n b

Output Parameters

list$ptr

A TOKEN for the jobwhose offspring are desired. Avalue of SELECTOR$OF(ML) specifies the calling task's job.

A POINTER to a STRUCTURE in which the system call returns tokens for the children of the specified job. The format of this data structure is as follows:

DECIÀRE offspring STRUCTURE (

m a x l n u m w u K U , a c t u a l W O R D ,

c h i l d r e n ( * ) T O K E N ) ;

The fields of this structure are as follows:

max$num This is actualìy an input field. Before invoking the system call, you must set this field to indicate the maximum number of child job tokens the system call can return in this structure. That is, this field must specifo the number of slots for children tokens in this structure. The value in this field must be greater than zero.

The system call fills in this field to indicate the number of tokens it returned in this structure. This number will never be larser than the max$num value.

children(.) The system call fills in these fields with the tokens for the immediate children of the specified job. The number of tokens in this list is indicated in the actual field.

actual

Nucleus Systern Calls 3 l

(46)

R Q E $ O F F S P R I N G

Description

The RQE$OFFSPRING system call returns a structure that contains a token for each child of the specified job. By repeated use of this call, tokens can be obtained for all descendants of a job. This information is needed by a task that is attempting to delete a job that has child jobs.

This system call returns exactly the same information as RQ$OFFSPRING. The only difference between the two system calls is that RQ$OFFSPRING creates an iRMX II segment to contain the information about the offspring tokens; RQE$OFFSPRING returns the token information in a structure that you supply. Using structures instead of iRMX II segments minimizes the number of iRMX II objects (and thus the number of GDT entries). It also means that the memory for the list is allocated when the task starts running, not dynamically when needed. This minimizes the chance of the system call failing because of a lack of memory.

The offspring structure that you supply has two fields in addition to the slots in which the system call returns the tokens. The first, max$num, is an input parameter that you fi[ in to indicate the amount of room in the structure for offspring tokens. The second field, actual, is filled in by the system call when it returns the tokens. The actual field is set to indicate the number of tokens actually returned. If there are more tokens to be returned than slots in the structure, the system call returns only enough to fill up the structure (that is, max$num).

Example

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

* T h i s e x a m p l e i l l u s t r a t e s h o w t h e R Q E $ O F F S P R I N G s y s t e m c a l l c a n b e *

* u s e d t o r e t u r n a t o k e n f o r e a c h c h i l d o f a j o b . *

************************************************************************ /

DECI-ARE TOKEN L I T E R A L L Y 'S E L E C T O R ' ; / * N U C L U S . E X T d e c l a r e s a l 1 s y s t e n c a l L s * /

$ INCLUDE ( /rrnx2 8 6/ inc/NUCLUS . EXT ) D E C T A R E t o k e n $ l i s t

max$nurn a c t u a l

c h i l d r e n ( 2 0 ) DECIARE c a I I i ng$ ta s ks $ j ob DECI,ARE status

STRUCTURE WORD , WORD , TOKEN) ; TOKEN ; WORD ;

1 t Nucleus System Calls

(47)

RQE$OFFSPRING

SAMPLEPROCEDURE:

P R O C E D U R E ;

. T y p i c a l P L / l . l - 2 8 6 S ra r e r n e n t s

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

* I n t h i s e x a m p l e , t h e c a l l i n g task invokes the systen call *

* R Q E $ o F F S P R I N G r o o b t a i n a l i s t o f u p c o 2 0 t o k e n s f o r r h e j o b s thar *

* a r e t h e i m r n e d i a t e c h i l d r e n of the calling task,s job. *

************************************************************************/

c a l I i n g $ t a s k s $j ob - SELECTORgOF(NIL);

t o k e n $ 1 i s t . n a x $ n u r n - 2 0 ;

CALL RQE$OFFSPRING ( c a l l i n g $ t a s k s g j ob, Grokeng l is r G s t a t u s ) ;

. Typical PL/1.1-286 S ta cenent s

E N D S M P L E P R O C E D U R E ;

Condition Codes

E$OK E$EXIST

E$NOT$CONFIGURED E$TYPE

0006H Thejob parameter is not a token for an existing object.

0008H This system call is not part of the present configuration.

8002H Thejob parameter contains a token for an object that is not a job.

Nucleus System Calls J.'