461847 001_Extended_i RMX_II.3_Volume_4_System_Utilities_and_Programming_Information_1988 001 Extended I RMX II.3 Volume 4 System Utilities And Programming Information 1988

461847-001_Extended_iRMX_II.3_Volume_4_System_Utilities_and_Programming_Information_1988 461847-001_Extended_iRMX_II.3_Volume_4_System_Utilities_and_Programming_Information_1988

User Manual: 461847-001_Extended_iRMX_II.3_Volume_4_System_Utilities_and_Programming_Information_1988

Open the PDF directly: View PDF .
Page Count: 748 [warning: Documents this large are best viewed by clicking the View PDF Link!]

intef

SYSTEM

PROGRAMMING

EXTENDED

iRMX@II.3

OPERATING SYSTEM

DOCUMENTATION

VOLUME

UTILITIES

AND

INFORMATION

Order Number;

461847

001

ntel

Corporation

306 5 Bowers Aven

u e

5anta Clara, Calrforn a 95051

Copyrrght ì988, lnte

In lDcati(rns

outsrde

the Unrted States, obtain rddìtronal rrrpres,rl

lnteì doeumcnlalion by

r,)ntrL(ting

yorrr

local Inteì sales

,rffice.

I'ìrr

yoLrr

conscnrence, Lntefnati,)nal sal{rs,rffice addressr:s

are located

directly beiìrre

the reader repìv tard in rhe back

Il l

he manua I

the inlormation in tb

rs documI ot is sr.tbier t t,r .hanqe

{ rt ho ut rì,,t r(r'

lntel

(',)rforalrl)n

rìrrkos d,)

warrant\',rfrìrìv

krrl wrth

rfjlard l,r thrs ùìat{.rìal. incl(ìding,

bLrl

nr)l

limrted 1o, the inrpìiod

||rrrartìos )l nrfrrha.lrl)rlL!v arrl fitness lìr a particular

purpos€.

Inlel

(1,)rp,)rati,)n rfspi)nsLbrlilr' iì)r rì!ìv frf,rfs rhrl nìrìv

rppear rn lhis d(xLìnrent.

Inl€l

Corporation makes n,r

r,rrrrrnilnreot rr)

Lrpdatp ). t,r

kepp.Lrrrenl

the In{i)rmatir)n contarnod ìn thrs

Inlel ( orp,Jralion assunìrs

n,ì .{rsprìnsrbility fi)r thf use ri irnv

fi.ruilr! orh€r than cLrcuilry

r:mbrxìied in lrn Inlel

l)r,rlLr(l

\,),rl.her.ircuit0ttlenlli.{'rì\psrreirrrplied.

Intel

s.)lìrrn.r

pr)du.ts arf Lopvrrr:htcd

bv an(l

rhall rcmaìn

the pr)perty ,)i

lntel

(,)rporrlr)n.

t'se. dLrplìcalirrn,rr

rlìscl,rsure is subte(t

t,) rrstrìcti,).\ italPd rn Intels,;oftsare lrconsp.,'r ns

rleiìned in ASt)R 7 10,1

rr) r9r.

\o part ,)f

thrs do(.unìen1

rnar be f,)pred

0r reprrxluced rn any form or bv anv rneans ,r rl hout pr ror

{ riltfn consent r)l I nte |

(',)r

p,)flrti,)n.

Ìhe flllo$Lng

are tradem?ìrks

,)l

Intpl

( orporîtioÌ1 and rts

affiùates

and may be uscd only L0

rdenlilv Ir)tel

pr,!luf

is:

Ab,rve ,l.lìX

BII II( S

('OY Ypute r rll I)l)K

(lRl'iDiî r\lMX

I)rìta Iìpehne lnsrle

lìfnil's ,n r,,l

T rnrcllìOs

r Intolevisrr)n

f2lCFi ,nreligent ldent,fior

lCFl ,ntelisent i']rr)sranìminq

rCÉlL I nlo llec

iCS Inteìlink

rDtìl' ,OSP

IDIS rPl)S

ì l'Stì

rPS(l

rlìUX

r SII('

rSllX

LSI)U

SSII

iSX 11

Lrbrarl \fenrLqer

tf('s

\fega( hassrs

\ft('tìo \f'\ r

\ t RA lll]

\fUI,TIB(,S

\ILI,'TI(]HA\\EI,

\fL;t.l t \fot)( Lu

Open\L L

o\a !l

Illus A Ilubbìe

PIIoMPT

QL:EST

Quex

Rrpplenode

R\f x/80

RUPI

SI,II

LPI

VLS'('!:1.

KE.\*lK, \fS DOS, \fLrltLplan. rnd \ficrosolì are trademarks,rl \licrosoft C,-rrporatLon.

\lK rs

trrdenìark

'ri

Bell Lriborrt,rrres Fltherncl

rs a lra(lenrrrk

'rt

Xer|\ (,)rporation.

C('nrr,rnrrs ìs a

Lrademark,rl

(lentron'rs

Datr ( ,)mpuler

(',,rporatLon.

( hassis

Trak rs a lradenÌark

,rl

(Ìeneral

[)evÌces

Conrpanv,

Irìf. \'A\,rod VUS rrf tradenìxrks rf l)rqrtrl tqurpmenr Corporarion_

Snìartmodem i200and llayes

are rrademarks of Ila\'fs \lrcroco|nput('r

l,roducrs,

Inc. IBM is a

rfgrsterpd tradeùrark ,)l

lnlt'rnaÌional llusÌness

\fachrnes. Soft S{.0pe

a regtstered rrnrlernark

(li)ncurrent Scrences.

(',)pyriqht!

l9lllì. lntol C,rrporrtion

VOLUME

PREFACE

MANUALS

THIS VOLUME

This volume (Volume 1, Ertended iRMl{'@

II Operating Syltent Lltilitit:s

and prograntniry4

Infonnation) includes

the following

manuals:

Exteruled

IRMXP

II Boorstap Loader Reference

Manual

Extended iRMÀo II Systent

Debug4er

Reference Manuol

Extended iRlll)o II Disk Verilication Lltilitl Reference Manuul

Guide to tlu: Etcntletl IRM}@ II lrtteructive Configuration utiliq,

Ertended iRltl)@ II Prograrntning

Technique.s

Reftrente Mrtttuttl

The Extended iRMA\o

II Bootstrap

Loader Refercncc

Manual tlescril.tes thc use

of the

Bootstrap

Loader and how

to modify

the Bootstritp

Loatler îiles.

The Ertenderl

iRhl)@

II System

Dehugqer

Reference

Manualdescribes

the iRMX@ II

Operating

System's

static debug-eer.

All of thc System Debugge

r commancis are

explained

and an example debug-uing

session

is provided.

The Ertended iRMXo II Dkk Veificatbn lrility Rcferenu Munual rlescrihes

the Disk

verilication

Utility

which

is used

to examine

and rnotlify

thc datlì structures

of iRMXo II

named

and

physical

volumes.

The Guide to the Efiended iRMXo II Interactive

Conf.guration Utlltv'manual describes

the

Interactive

Confi{uration

Utility commands

and menus, and provides

an example system

configuration.

The Extended iL\lÀl@

II Progrurnnting

Techniques

Reference

!úanuul provides programnring

techniques

and examoles.

Itl

iRMX@ II System Utilities and Prograrnming lnformation Volume

VOLUME PREFACE

VOLUME CONTENTS

Manuals are listed

in the order they appear

in the

volumes. For a synopsis of each

manual,

refer to fhe Introductiort

to the Ertended |RMX\ II Operating System.

VOLUME 1. Erk:nried

iRMXo II Introduction, It$tallation,

and Operating Instructions

Introductiort to the Ertended iRMX II Operating System

Exteruled |RMX ll Hardware and SoffA,are Installation Cuide

Operator's Guide to the Extenried |RMX II Human Interface

Master Iruler

VOLUME 2: Extended

iRMXo II Operating System User

Guide.s

Extended iRltlXÒ II Nucleus

U.ser's Guide

Extended iRMXo II Ba.sic I/O Systent User's Guide

Extended

|RIVX@ I I E.rtended I/O Systent U.ser'.s Guide

Extended iRM)P ll Hurnctn Interface User's Guide

Extended iRMXo II Applicatbn Loader User's Guitle

Erteruled iRl'ltX@ ll Universal Development Intefaca U.ser's Cuide

Device Div'cr.s Uscr's Gu' le

VOLUME 3: Ertended iRMXo II Sy*em Calk

Extended iRMXo II Nucleus Systent Calls Referente Manual

Extended iRMÀ@ II Basic I/O System Calls Reference Manual

Extended iRhl}.@ II Ertended I/O System Calls Reference Manual

Ertended |RMX@ ll Applicatiort Loader Systent Calls Reference Manual

Extended iRMXa II Hurnrut Interface Sy-stent Calls Reference Manrutl

Ertended iRlllYù II UDI Sl,stern Calls Reference Martual

VOLUME 4: Ertendad |RMX@ II Operuting

$,stem Utilities

Extended

iRltlX@

II Bootstrup Loadar Reference Manual

Extended iRlt't)@ II S1'stent

Debugger Ret'erence l4anual

Exte nded iRltl)'@ II Di.sk

Verification Utility Ret'ere ce lllanual

Extended |RMXò II Progranuning Techniques Reference Mrutual

Guide to the E.rtundd iRMX@ II Interactive Configuration Utilitl,^

VOLUME 5'.

Ettended íRMXò II Interoctive Configurutbn Utility Reference

Extended iRltlXE II Inteructive Configurution Utility Reference Manual

lv iRl\tX@ ll System Utilities and Programming Information Volume

REV. REVISION IIISTORY DATE

-001 f)riginnll**ur 0l/88

intel

EXTENDED

iRMX@II

BOOTSTRAP

LOADER

REFERENCE

MANUAL

lntel Corporatron

306

5 Bowers Aven

u e

Santa Clara, Californ a 95051

Intel

Corporatron, Ail R ghts Reserved

PREFACE

INTRODUCTION

The Bootstrap

Loader enables you

to generate

a system îhat can

bootload from

Intel-

supplied or custom

devices.

A hootable system

gains control

immediately after power-up

or system

reset.

This manual provides

information

that enables you

to configure your

system to boot

from specific

devices, to

include

your

own custom

device drivers

part

the system,

and to place

your generated

system

into PROM devices.

READER

LEVEL

The

manual assumes that you

are familiar with

the iRMX

ìl Operating System and

editor with which

you

can edit source code

fiÌes. lt may also be

helpful if you are familiar

with

the following:

o SUBMIT

files.

. ASM86

source cocle

files.

MANUAL

OVERVIEW

This

manual is organized

as tbllows:

Chapter

I This chapter provides

an overview of the

Bootstrap Loader

operations.

Chapter

2 This chapter provides

operator's

viewpoint

of using the Bootstrap

Loader.

Chapter 3 This chapter

describes how

to configure the

first stage of the Bootstralr

Loa der.

Chapter 4 This

chapter describes

how ro configure

the third srage

of the

Bootstrap

Loader.

Chapter

5 This chapter

describes

how to

write

custom first-stage

drivers.

Chapter 6 This

chapter clescribes

how to

write

custom third-stage

drivers.

Bootstrap [,0ader llt

PREFACE

Chapter 7 This chapter describes

error handling

procedures.

Appendir A This appendir

describes how

to include automatic boot device

rccogn

it ion into

your systcm.

Appendix B This appendix describes how to load

the Bootstrap Loader

and the

monitor into PROM

devices.

CONVENTIONS

The following conventions

are used throughout this manual:

o Information

appearing as UPPERCASE characters

when shown in keyboard

examples must be entered or coded exactly as shown.

You may, however, mix lower

and uppercase characters

when

entering the text.

. Fields appearing as lowercase characters

within angle brackets

(

< >

) when

shown in

keyboard examples indicate

variable

information.

You must enter an appropriate

value

or symbol lbr variable

fields.

. User input appears in one of the following forms:

as bolded text nithln a screen

. The term

"iRMX

If'refers to the Extended iRMX ll.3 Operating System.

. The term'iRMX

I'refers

to the iRMX I (iRMX

86) Operating System.

. All numbers, unless otherwise stated, are assumed to be decimal. Hexadecimal

numbers

include the "H" radix character

(for

example,

OFF

tv Bootstrap l,oadcr

CONTENTS

CHAPTER 1

OVERVIEW

BOOTSTRAP

LOADER

OPERATIONS PAGE

CHAPTER 2

USING

THE

BOOTSTRAP LOADER PAGE

CHAPTER 3

CONFIGURING THE FIRST

STAGE PAGE

Bootstrap [,oader

CONTENTS

CHAPTER

3 (continued) PAGE

CHAPTER

CONFIGURING

THE THIRD

STAGE PAGE

vl Brntstrap Inader

CONTENTS

CHAPTER 4

(continued) PAGE

CHAPTER 5

WRITING

CUSTOM

FIRST.STAGE

DBIVER PAGE

5.1 Introduction ..............................5-1

5.2 Device Initialize Procedure........... .......................5-2

5.3 Device

Read Procedure.... ............................. 5-3

5.4 Supplying

Configuration Information

to the First-Stage Driver...............................5-4

5.4.1 Hard-Cocìing

the Configuration

Information .......................5-4

5.4.2 Providing a Configuration

Fiìe...................... ..........................5-5

5.5 Using the MULTIBUS@

Il Transport

Protocol .............................5-8

5.5.1

Message Passing Controller

Initialization.. ...........................5-9

5.5.2 Message Tlpes .................. ..........,..............5-10

5.5.3 Request/

Response

Transaction ModeI......... .......................

5.5.4 Send and Receive

Transaction

Models ................................ 5- l5

5.5.5 Message

Broadcasting...... ......................... 5-20

5.5.6 Transmission

Modes........... ......................5-22

5.5.7 Interconnect

Space .......5-22

5.5.8 Driver Code Considerat

ions...................... .............................

5-30

5.6 Changing BSl.A86

or BS1M82.,486 to Include

the New First-Stage Driver........ 5-33

-5.7 Generating a New

First Stage Containing

the Custom Device Driver ..................

5-34

CHAPTER 6

WRITING

A CUSTOM THIRD-STAGE

ORIVER PAGE

6.1 Introduction ..................,...........6-1

tr.2 What

a Third-Stage Device

Driver Must Contain..... ........,...........6-1

6.3

Device Initialization

Procedure........... ................ 6-3

6.4

Device Read Procedure ..........6-4

6.5

Protected Mode Considerations

.................... ...................................6-ó

6.(r Supplying

Configuration

lnformation to the Third-Stage Driver .............. ...............6-1

ó.7 Using

MULTIBUS@ II Transport

Protocol .............. ......................6-8

6.8 Changing

BS3.A86 to Include the New Third-Stage

Driver............................-..........6-8

fi.9

Generating a New Third Stage

Containing the Custom Driver................. ...............6-9

Bootstrap Loader vtl

CONTENTS

CHAPTEB

7 PAGE

ERROR

HANDLING

7.1

Introduction ..............................7-1

7.2

Analyzing Bootstrap Loader Failures. ...............l

-l

7.2.1

Actions Taken by the Bootstrap Loader After an 8rror...,..........

.....................7

-1

7 .2.2 AnalyzingBrrors With Displayed Error Messages . .............7

-2

7.2.3

Analyzing Errors

Without

Displayed Error Messages.......................................7-5

7.2.4 lnitialization

Errors.............. ........................7

-7

APPENDIX A PAGE

AUTOMATIC

BOOT DEVICE RECOGNITION

4.1 Introduction........................... ...............................A-1

A.2 How Automatic Boot Devìce Recognition Works........... ............ A-1

A.3 How to Include Automatic

Boot Device Recognition....... ......... A-2

A.4 How to Exclude Automatic Boot Device

Recosnition ............................................. A-5

APPENDIX B PAGE

PROMMING

THE BOOTSTRAP

LOADER AND THE ISDM" MONITOR

B.l Introduction .............................B-1

8.2 Incorporating

the iSDM" Monitor.............. ....................................8-l

vltt Brxrtstrap l{)ader

CONTENTS

TABLES

TABLE PAGE

l-1 Intel-Supplied

Bootstrap

Loader

Drivers. ......................................

1-8

2-1 Supplied

Third Stage

Files..................... ..............2-7

3- l Procedure Names

for Intel-Supplied

First Stage

Drivers ...............,........................

3-25

3-2 5.25-lnch

Diskettes

Supported

by iSBC@ 20tl and

MSC-specific

Drivers............. 3-26

3-3

8-Inch Diskettes

Supported

by iSBC@

208 and

MSC-Specific Drivers..................3-2ó

4-l Names

for Intel-Supplied

Third

Stage Drivers ................ ..............4-7

4-2 Memory

Locations

Used by the

Bootstrap Loader...................................................4-

lfi

I Postmortem

Analysis

of Bootstrap

Loader Failure

.. ....................7

-6

FIGURES

FIGURE PAGE

B(x)tstrap Lr|ader

CHAPTER 1

OVERVIEW OF

BOOTSTRAP

LOADER OPERATIONS

1.1 INTRODUCTION

The Bootstrap Loader is a

program that is not part of any particular Operating

System.

Rather, it is a program that loads an application

system into RAM from

secondary storage

so that it can begin running.

This process is called bootstrap

loadìng or booting. Booting

can occur

when

the system is turned on,

when

the

system is reset, or under

operator

control

when

the monitor is active.

The Bootstrap Loader eliminates

the need to place complete

applications into PROM

devices. Instead,

you

can

place

the Bootstrap

Loader--ir relatively

small

program--into

PROM devices

and store your application system on

a mass storage device.

The Bootslrap

Loader can

then be used to load the application

program into RAM.

The Bootstrap Loader consists

of three stages.

The first

stage resides in PROM devices. It determines the name

of the file to load,

loads

part of the second stage, and

passes control to that

part. Intel System 300

Series

Microcomputers

are delivered

with

the

first stage of the

Bootstrap Loader

and the iSDM

monitor already

placed in PROM devices.

Intel Modules

Development Platforms

are

delivered similarly

except

with

the D-MON386

monitor.

If you are huilding

your own

computer

systems,

you

can use

the information in

this manual to

configure a first

stage and

place it into PROM

devices.

The second

stage resides on

track 0 of every iRMX-formattcd

nrmed

volume.

That

is,

whenever you

use

the Human Interlàce FORMAT

command

to format

volume, the

second stage

is copied to that

volume.

When

invoked,

the second

stage finishes

itself into

memory

and then loads a file from

the same

volume and

passes control

to it.

The

contents of

this load file depend

on the kind of

system

you are loading. If you are

loading an

iRMX I system, the

file loaded by

the second

stage contains

the application

system itself.

Ifyou are loading

an iRMX II system, the file

loaded

by the second stage

contains the third

stage of the Bootstrap

Loader,

which finishes the

process.

Bootstrap Loader l-l

OVERVIEW OF BOOTSTRAP LOADER OPERATIONS

Thc third

stage is necessary for loading iRMX ll applications, because these applications

require the 80286

processor

to be running in

protected

mode and because they

use the

OMF-2tì6 object module format. The OMF-28fi format is different from the OMF-86

format and therefore cannot be handled b1'the second stage. The third stage

places

the

processor

protected

mode, loads the iRMX II application system, and transfers control

to that application system.

The

third stage

resides in a

named

file on the same

volume as

the second stage. Your Bootstrap Loader package contains a configured third stage that

can load applications from selected devices. The instructions in this manual can help

you

configure your own third stage to add support for other dcr iees.

The bootstrap

process

cannot

completed

without

a device driver. The device

driver is a small program that providcs the interface between the Bootstrap

Loader

and a

hardware device

(or

a controller for the device). When you configure

the Bootstrap

Loader

task that is independent of operating system configuration), you specifo the

device drivers that the Bootstrap Loader

rcquires. During the course of configuration,

these device drivers

(which

are usually distinct from the drìvers

needetJ by the application

system) are linked to

the Bootstrap Loader automatically.

1.2 THE

STAGES

THE BOOTSTRAP

LOADER

The Bootstrap Loader has a number of staqes

that control the loacling of

the applicatior.

system. iRMX I applications load

u'ith

a two-stage process.

iRMX II applications use

these

two stages but also require a third stage.

1.2.1

First Stage

The Bootstrap

Loader's first stage consists

of two parts. One part is the code for the first

stage, and the other part is a set of minimal device

drivers used by

the first and second

stages to initialize

and read from the device

that contains the system

to be booted.

The Bootstrap

Loader package contains

device drivers for many

common Intel devices. To

support

other devices,

you can write your own drivers and

configure them into the first

slage.

To use

the Bootstrap Loader,

the first stage

must be in one of two places.

The natural

place

fbr the first stage

is in PROM devices, either

as a standalone product

or combined

with

a monitor. f ntel System 310 and

380 Series Microcomputers

are delivered with

the

Bootstrap Loatler's

first stage, the iSDM monitor, anrJ the

System Conficlence

Test

(SCT)

in the PROM devices.

Intel System

320 Series Microcomputers

are delivered

with the

Bootstrap Loader's

first stage, the iSDM monitor, the

D-MON3tì(r monitor,

and the SCT in

the PROM devices.

Intel Mociules

Development Platforms

are delivcred with

the

Bootstrap Loaclcr's

first stage, the D-MON386

monitor,

and the SCT in the PROM

devices.

t-2 Brxrtstrap [-oader

OVERVIEW

BOOTSTRAP

LOADER

OPERATIONS

lf you

have a system

that includes

the iSDM

monitor and you are aclding your

own device

driver to the Bootstrap

Loader's

first stage, you might

find it useful to load the

first stage

into the target system's

RAM using

a development

system iSDM kracìer

and activate thc

first stage

under iSDM control

from the

development systcm.

After activating the first

stage, you

could then

debug driver

code. If

your

system

includes the D-MON38(r monitor,

however, you must perform all driver debugging

from the target system.

You cannot

download the first stage from a development system into the

target

system

and then use D-

MON38ó

to initiate program

execution. When debugging

under these latter

circumstances,

you

may

wish

to either debug within

the

PROM devices or perhaps use a working

Bootstrap Loader to bootload

the Bootstrap

Loader that contains the new

driver.

When

the first stage begins

running, it

first identifies the bootstrap device and the name

the

file to boot, either by accepting

that

information from a command line enterecl ut the

monitor

or by using default

characteristics establishcd whcn

the first

stage was

configuretì.

The Bootstrap

Loader next calls

its internal device driver for the clevice, which initializes

the device

and reatis the first portion of the second sttìge into memory. (The second stage

always resides on track

0 and block 0 of the named

volume,

so it can be accessed easily by

the

first stage.) After calling

the internal device driver, the îirst stage passes

control

to the

second stage.

Because the first stage works

on both lt0tl6/ lllfi- ancl 802t16/31.ì(r-basccl computers,

operates in real address

mode

when

running in an tl02tl6/386-based systcm.

This

means

that any device drivers you write for the first stage must also opcrate in real

address mode.

1.2.2

Second Stage

Unlike the first stage, the second stage of the Bootstrap Loadcr is not configurable. Its slze

is always the same

(less

than fìK bytes),

and it does not

depend on the application in any

way.

The cotìe for the second stage

resides on all

volurnes

forrrattcd

with the

iRMX I or

iRMX II Human lnterface

FORMAT commands. Thercfìrre, the

second stagc is always

available

for loading applications residing on random access tlevices.

When the second stage receives

control, it finishes loading

itsclf into memory and then

loads the file determined by the

first stage. When loading

the file, it uses the same

device

driver used by the first stage. In iRMX I systems, the load file is the

application systcm

itself. In iRMX II systems, this file is the thirtl stage of the Bootstrap

Loader.

Bmtstrap LOader l-3

OVERVIEW

OF BOOTSTRAP

LOADER

OPERATIONS

NOTE

You cannot

bootstrap load

the iRMX IL 1, 11.2,

II.3 Operating

System from

volume

that

was formatted using

the iRMX 1.6

or I.7

(iRMX 86 Release 6 or 7)

FORMAT command.

However,

you

can make the

volume bootable

without

reformatting

the entire

volume and losing

the data stored

on it. To be able

boot

both the iRMX I and iRMX II Operating

Systems

from the same

volume,

invoke

the iRMX II.3 FORMAT command

and specify

the BOOTSTRAP

control.

With

BOOTSTRAP

specified, FORMAT

just

replaces

the second

stage on track 0 of the

volume

while

leaving

the remaining data untouched.

When

the FORMAT command

finishes,

you

can bootstrap

load both the

iRMX

I and iRMX II Operating Systems

from the same

volume.

1.2.3 Third Stage

The third

stage of the Bootstrap Loader

is used for loading

iRMX Il-based applications

into memory. The third

stage resides in a named

file on the bootstrap device.

Both the

third stage and the application

system to be loaded

must reside in the same directory

the

volume.

There are two

types of third stages:

a generic third stage and a device-specific

third

stage.

The type needed

for your system depends

on the size of the application

system you intend

to load.

1 .2.3.1

Generic

Third

Stage

The generic third stage is so named because it can load

application systems from any

device

that

the first

stage

recognizes.

This stage contains no device driver

of its own.

Instead, it uses the same device driver used by the first

and second stages. This means that

you won't need to

write

a separate device driver to

work in protected mode, but it also

means that the

generic

third stage runs in

real address mode. In real address mode,

addressability is restricted to the first

(lowest)

megabyte of memory. Therefore,

the

generic third stage can load only those application systems that are smaller than

840K

bytes. The remaining space is used by the Bootstrap Loader, the monitor and the

SCT. To

load larger applications, you must use a device-specific third stage.

When the generic third stage receives control, it uses the device driver supplied in the first

stage to load the application system. Then it switches the

processor

into

protected virtual

address mode and

passes

control to

the

application.

l-4 Bo()tstrap lrader

OYERYIEW OF BOOTSTRAP LOADER OPERATIONS

1.2.3.2 Devicespecilic Third

Stage

The device-specific third stage switches the processor to protected

virtual address mode

before loading the application system. This enables

this stage to load into memory

addresses higher than one megabyte. However, because this

stage switches the

processor

into

protected

mode, it cannot use the first stage's

device drivers

(which

operate only

real mode). Instead, it must contain its own device driver, operating

in protected mode,

control the device from which the application system is loaded.

The device-specific third

stage supplied in your Bootstrap Loader

package supports the

following devices:

. iSBC 21SG/iSBX

2l8A winchester

and diskette controller

combination

or the

iSBC 214

controller

. iSBC 264 bubble memory controller

. iSBC

186/224A multi-peripheral controller

o SCSI

(Small

Computer Systems lnterface)

an<l SASI

(Shugart Associates Systems

Interface)

peripheral bus controllers having

iSBC 2861100A

CPU board as

the host.

If you want to boot from any other device,

you must

write a protected mode device

driver

for the device and link

the driver in when

you

configure

the device

specific third

stage

(see

Chapter ó).

When the device-specific

third stage receives

control, it

performs the

same operations

the

generic

third stage. However,

before invoking

the device driver

to load the

application

system, it switches the

processor into protected

mode. This enables

the third

stage to load

applications

that reside outside

the first megabyte.

1.2.3.3 Naming

the Third stage

Both the

generic and the

device-specific third

stages are stored

as executable

files. The

base

portion of

this file's name

the filename

minus any

extension

'- must be the

same as

the base

portion of

the file containing

the applìcation

system to

be loaded. Because

the

name

of the third

stage and the name

of the application

system

must match,

you must

provide

a separate

third stage fi-le for each

bootable

system on

the

volume. To

provide

additional third

stage files, simply make

a copy of the

third stage

file

you are currently

using. Name

the copy so that it matches the application

system

you intend to

load.

1.2.4 Load File

The load

file is a file

containing the

application

system

you are trying

to boot.

The load

file

shoulcl be on

an iRMX I- or iRMX ll-formatted

named

volume. This

volume

must have

been formatted

by the Human

Interface FORMAT

command.

lf the load

file is an

iRMX

II application,

the

volume

must

also have a

file containing

the

third stage

of the Bootstrap

Loader.

Bootstrap

Loader 1.5

O!'ERVIEW OF

IÌOOTSTRAP

LOADER OPERATIONS

your

load file is an

iRMX II application, the name of that file must correspond to the

nanre of the

Bootstrap Loatler third stage, as fbllows:

. The base

portion

of the loarl file's

name

(the

filename minus the extension) must be

the same as that of the file containing

the third stage.

o The extension portion of

the loacl file's name must consist of the characters

".286".

The lbllowing are examples ofvalicl

and invalid third stage/Ìoad

file comhinations:

Valicl

Combinations

Third stage

Load file

Th ird stagc

l-oad file

Inva lid Comhinations

Third stage

Load file

Third stage

Load file

MYSYS

MYSYS.286

SYS I.3RD

SYS

l.2tì6

MYSYS

YOURSYS.2I.ì6

MYSYS.]RD

MYSYS.LOD

When you

configure the

first stage of the

Bootstrap

Loader,

you

can

choose the file name

that

will

be used

if the operator

doesn't specify

a filenamc when

invoking the Bootstrap

Loader. By ciefault,

the file name

/SYSTEM/RMX86

for iRMX

I load files. For

iRMX

II systems,

/SYSTEM/RMX[J6

is the

default name of

the Bootsrrap

Loader's third stage

and

/SYSTEM/RMX86.2E6

is the clefault

name of

rhe iRMX II load

file.

NOTE

Because

of the way

the

Bootstrap Loader

interprets

filenames, the

only pcriod

(.)

allowed in

the entire pathname

for the load

file is the one that prececles

the

extension

28(r.

For example.

the pathname

/SYSTEM

/MYSYS.286

is invalirl

because it contains

more than one

neriod.

l-6 Bootstrap

lnader

OVERVIEW

OF BOOTSTRAP LOADER

OPERATIONS

1.3 DEVICE

DRIVERS

When the Bootstrap Loader

starts running, there is

no sofiware

in place

to enable the

processor

to communicate

with the

device from which

you want to load the system. Part of

the task of the Bootstrap

Loader is to establish communications with the boot device. To

communicate with devices,

the Bootstrap Loader must include programs,

called device

drivers,

for the devices from which you want

to boot. When configurìng the Bootstrap

Loader, you specify the

device drivers you want to include. The configuration

process

links

the drivers to the Bootstrap Loader code.

Both the first stage and

the device-specific third stage

require

their own

drivers. The first-

stage drivers operate in real address

mode and are used to load iRMX I applications and

the third stage of the Bootstrap

Loader. The generic third stage also uses the first-stage

drivers to load iRMX II applications.

The thir<J-stage

drivers operate in protected virtual aticlress mode ancl

are used

by thc

device-specific

third stage

to load iRMX II applications into the full 16 megatryte address

space.

The first stage must include a real mode

device driver for each device from which you want

to boot. The generic third stage

includes no drivers of its own, but the device-specific third

stage must include a protected mode

driver for each of the boot devices. Intel includes

several real and protected mode drivers

in the Bootstrap Loader

package,

as listed in

Table

l-1. AlÌ the reaÌ mode drivers

can be used

with

the first

stage

and

with

the

generic third

stage. All the

protected

mode drivers

can

used

with the

device-specific third stage.

lf you

want

to boot from a device not supported by these device drivers, you can

write your

own device driver. See Chapter 5 for information on

writing a new device driver.

Bootstrap l,oader t-7

Table l-1. Intel-Supplied Bfi)tstrap lnader

Drivers

Driver îyp"

iSBC 208 Flexible Disk Drive

Controller. Real Mode.

Also

used

with the

generic

third stage.

Mass Storage Controller

(MSC),

supporting the

iSBC

214

and iSBC 215G controller

boards.

Also

suooorts the

|SBX 218A controller when it is mounied on the iSBC 215G

ooafo_

Both

Real

and Protected Mode.

ìSBX 218A Flexible Disk

Controller

(used

on a processor

board) Real Mode only. Also used

wiîh the

generic

third stage.

iSBC 220

SMD

Disk

Controller Real Mode only. Also used

wiîh the

generic

third stage.

isBc 186/224A Both Real and Protected Mode.

iSBX 251 Bubble Memory

Controller Real Mode

Only.

iSBC

254 Bubble Memory

Controller Real Mode

Only.

iSBC 264 Bubble Memorv

Controller Both Real and Prot€cted Mode.

SCSI

(Small

Computer Systems

Interface) and

SASI

(Shugart

Associates

Systems

lnterface) Peripheral Bus

Controllers

when the host for

these controllers is the

iSBC

286/100A CPU board.

Both

Real

and

Protected

Mode.

SCSI

(Small

Computer

Systems

Intelace) and

SASI

(Shugart

Associates

Systems Interface) Peripheral Bus

Controllers

when the host for

these controllers ìs the

iSBC 186/03A

CPU

board.

Real Mode

Only.

OVERVIEW OF BOOTSTRAP LOADER OPERATIONS

1.4 MEMORY

LOCATIONS

USED

BYTHE

BOOTSTRAP LOADER

All three stages of the

Bootstrap Loader reside

in or are loaded into memory.

This sectron

discusses the memory

locations for different tnres

of systems.

NOTE

When you

configure your

own

version

of the

Bootstrap Loader, you

must

ensure

that the memory

locations occupied by the three stages

do not overlap.

ln addition, when you

configure the application

system,

you

must ensure that it

will

not be loaded

into the memory

occupied by the stage that is loading

it.

However, you

can configure this

memory so that the iRMX I and iRMX II free

space manager

has access to it once the application begins running.

l-8 Bu)tstrap lrrader

OVERVIEW OF BOOTSTRAP LOADER

OPERATIONS

The code for the first stage is normally located in

PROM devices in

the upper part of the

memory address space. The first stage data and

stack are located

by in conjunction

with

the

second stage code at address 088000H. The

second stage uses the

same data and stack

the first stage. The first stage data and stack

plus

the

second stage code require

bytes of memory.

You can change the locations of

the first stage data and

stack, and the

second stage code

by selecting a different address for the second stage

when you invoke the

SUBMTT

file, BS1.CSD, to configure the first

stage. Chapter 3 describes

the BSl.CSD file.

The device-specific third stage is

located by default at address

0BC000H. lt requires

16K

byes of memory, and it uses

its own stack and data segments.

You can change

the locatton

of the device-specific

third stage by using the BS3.CSD

SUBMIT file

to generate

your own

version.

Chapter

4 describes the BS3.CSD file.

The generic third stage is located

by default at address

0BC000H.

Unlike the device-

specific third stage,

it uses the data and

stack of the first stage

(because

it uses the first-

stage device drivers). You can

change the location of

the generic

third stage by using

the

BG3.CSD

SUBMIT file to

senerate vour

own

version of it. Chapter

4 describes

the

BG3.CSD

file.

When

you

use the second

stage and

generic

third

stage loaded into

memory

at their

default

addresses

(088000H

and 0BC000H), blocks

of memory

beginning

at these two

addresses

are used to load

the application. The

generic third stage

uses 16K

bytes of memory.

Thus,

ifyour application

were

occupy memory between

0B8000H

and OBFFFFH,

the

generrc

third stage

would fail to load the application.

1.5 CONFIGURING

YOUR OWN BOOTSTRAP

LOADER

If you

intend

to create

your own

version

the Bootstrap

Loader,

you must

use the

Bootstrap Loader

configuration

and generation

files supplietl

by Intel. In iRMX I systems'

these files reside

by default in

the directory

/RMX86/BOOT. In iRMX II systems,

the

files reside in the

directory

/RMX286/BOOT. Information

about

configuring

the first

and

third stages is available

in Chapters 3

and 4, and information

writing new

device

drivers

is available in Charrters

5 and 6.

Bootstrap l-oader 1-9

USING THE CHAPTER 2

BOOTSTRAP LOADER

2.1 INTRODUCTION

The procedure for

using the Bootstrap Loader depends on where you

locate the first stage,

and for iRMX II users,

which

third stage you choose.

This chapter

explains

the operator's

role, methods of defining

the first stage, and options to consider

when

choosing a third

stage.

2.2 OPERATOR'S

ROLE

IN BOOTSTRAP LOADING

The operator's princìpal role in the

bootstrap loading

process

is to

specify

the

pathname of

the

file that is to be loaded. For iRMX I systems, this is the pathname of the application

system. For iRMX II systems,

this is the

pathname

of the Bootstrap Loader's

third stage.

If the operator is using the lntel-supplied

first stage, the load

file specifications can be

entered

in one of the following

ways:

. By specifying neither the device

name nor the file name

. By specifying both the

device name and the file name

. By specifying the device name only

. By specifying the file name only

addition, ifyou have the iSDM monitor, the operator can

also use the Debug option to

specily that control should pass to the monitor atier loading is complete.

(The

D-MON386

monitor does not support a debug option.)

2.2.1 Specifying

the Load File

An operator can speci! a load file:

. When the monitor has

issued

a prompt. In this case, the operator

can enter the

rnonitor's B (bootstrap) command, followed by the

name of the load file (include

the

name

within

single

quotes

you

are using

the D-MON3tìfi monitor).

For this to

work,

the Bootstrap

option

must

have been configured into

the monitor. Refer to the

|SDM

Systen Dehug

Monitor User's Gufule and th'e D-MON39ó

Dehug Monitor

for the 80386

User's Guide for informatìon on confisurins monitors.

B0otstrap l,oader 2-l

USING

THE BOOTSTRAP

LOADER

. When the first stage of the Bootstrap

Loader has issued an asterisk

(

*) prompt.

When

this

prompt appears, the first

stage

waits

for an operator

to enter the name

of the load

file.

The

method used to determine

which

file

to load depends on the configuration

of the

Bootstrap Loader's

first stage. Refer to Chapter 3

for more information about

first stage

configuration.

When

entering

the monitor's B command or responding to

the Bootstrap Loader's asterisk

prompt, the operator must specifo the

load file. One

way

to do this is to

simply press

Carriage Return. This causes

the Bootstrap Loader to search for a default

file on the

default device

(these

defaults are

set up when you configure the first stage). The

Intel-

supplied first stage uses the following

pathname as its default

/SYSTEM/RMX86

If you were using the default first stage and you

wanted

to load the file called

/SYSTEM/RMX86

from the default

device, you could simply type the B command

with

parameters (ifyou boot from the monitor) and

press

Carriage Return, or type

a Carriage

Return only

(if the Bootstrap Loader displays its own

prompt).

Ifyou need to speci! a load file that is

different from the default one,

use

the following

format

for the

specification:

:device:pathname (iSDM)

':device:pathname' (D-MON386)

Where:

:device: This is the name ofthe secondary storage device that contains the load

file. Ifyou omit the device name, the default device is used (as

established during first stage configuration).

pathname When loading iRMX I applications, this

is the full

pathname

of the file

you want to load. When

loading iRMX II applications, this is the full

pathname of the Bootstrap

Loader's third stage. For iRMX II systems,

the file to be loaded is assumed to have the same pathname

as the third

stage

except

for

the filename extension,

which

is assumed

to be

.286.

If you omit this name,

the Bootstrap Loader attempts to load the

default file (always

/SYSTEM/RMX86).

To invoke

the Bootstrap Loader

with

the monitor's

B command, the processor must be

running in real

address mode. Ifyour processor

running in real address mode,

you

can

simolv break

to the monitor and issue the boot command.

2-2 Bootstrap Lader

USING THE

BOOTSTRAP LOADER

However,

if the processor is running in

protected

virtual

address

mode

(as

it is

when the

iRMX II Operating System is in control),

you

cannot

boot another

system by breaking

the monitor and issuing a boot command.

You must first reset the

system. After resetting

the system,

you

can invoke

the Bootstrap Loader at the monitor

prompt.

Example 1: Assume

that an iRMX I application

system resides in the

file

/SYSTEM/MY86SYS on drive :WFO:. You can

boot this system

by issuing the following

command at the

iSDM monitor

prompt:

Example 2: Assume

that an iRMX II system resides

in the file

/SYSTEM/MYSYS.286

drive :WF0:, and that

the third stage of the Bootstrap

Loader resides

in the fiÌe

/SYSTEM/MYSYS.

If the

processor

is in real

address mode,

you

can boot

this system

issuing the following

command at the D-MON386

monitor

prompt:

2.2.2 DebugOption

Assuming

that the iSDM monitor is

present in the system,

the operator can

include a

debug

option

when

specifying a load

file

(the

D-MON386

monitor

does not support

debug

option). This option instructs

the Bootstrap

Loader

to do the following

immediately

after loading is complete:

. Set a breakpoint

at the first instruction

to be executed

by the application system.

For

iRMX I systems, the breakpoint

will be set in the

load file. For iRMX Il systems,

the

load

file (the third stage) will be loaded as

always and

it will load

the application

system. The breakpoint

will then be

set in the application

system.

o Pass control

to the iSDM monitor,

which displays an

"Interrupt

at <>ooo<:pm<>"

message at the

terminal, issues its

prompt (a single

period for real-mode

iRMX I

systems,

fwo

periods for protected-mode iRMX II systems),

and

waits for a command

from the

terminal. At this

point the operator

can invoke any

of the iSDM

monitor

commands

that are

appropriate for real

or protected mode.

(To

continue running

the

loaded

program, enter G

<cr >.)

One advantage

of the Debug

switch is that

the monitor's

interrupt

message tells

you

that

the loacling

process was successful.

If a system

you are booting

fails,

you

might

not

otherwise

be able to

tell

whether the bootstrap load

itself

was unsuccessful,

whether the

system

loaded

successfully and

then failed

during initialization. The presence or absence

the interrupt

message

when you

use

the Debug

option clarifies

whether the loading

was

successful.

Bootstrap

l-oader , -'l

USING

THE BOOTSTRAP LOADER

Because the Debug option leaves you in the monitor, you can alter the contents of specific

memory locations and

perform

other monitor actions

(such

as <Jebugging) before

you

start

your system running with the

monitor's

G command.

To use the Debug option when you are invoking the Bootstrap

Loader from

the iSDM

monitor, include the letter D in the command line immediately after the B (boot)

command. Speci! any

load file

pathname

after lhe B and D characters.

For example, any of the following command

Iines invoke the Bootstrap Loader

(from

the

iSDM monitor)

with

the Debug option:

Notice

that the "D" and any pathname

must be separated by at least one space.

You can also use the Debug option on systcms in which

the Bootstrap Loader is configured

to request the load file name; that is, on systems

that issue the Bootstrap

Loader's first

stage asterisk

(.) prompt. On these systems,

place

the "D" in the command line before the

load

file specification (separated by

at least one space).

Examples of this are:

2.3 PLACING

THE

BOOTSTRAP LOADER

INTO MEMORY

Before you

can invoke the

Bootstrap Loader, you

must

place

it into

memory. Several

rvays

exist to place

the Bootstrap

Loader into memory:

l. Place the

first stage, configured

for standalone operation,

in PROM devices.

In thts

case, îhe first

stage begins to

run on

power-up

or reset. Depending

on its

configuration,

the standalone

Bootstrap Loader

may issue an asterisk prompt so

that

you

can enter the

name of the

load file. To configure

the first stage for standalone

operation, refer

to Chapter 3.

2-4 Brxrtstrap Loader

USING THE BOOTSTRAP

LOADER

2. Configure

the monitor to include

the Bootstrap option,

reconfigure the first stage of

the Bootstrap

Loader to include the

first stage device driver(s)

needed for bootstrap

loading as not all

of the device

drivers supplied with the

Bootstrap Loader will fit

into the

memory range provided

by the

monitor. Then

program

new PROM

devices

with

the combination

the monitor and the

first stage of the Bootstrap

Loader.

With this

method,

you

initiate bootstrap loading via

the monitor's

'B'

(boot)

command. To use

this method,

refer to chapter 3 for configuration

information.

Refer to the Guide to the Extended i.RMX

II Interactive Configuration Utility for

information

programming

a monitor and the

Bootstrap Loader into the same set

of PROM devices.

3. Place the first stage in secondary

storage.

Then, using the iSDM monitor or ICE in-

circuit emulator, invoke

the first stage.

This

procedure

particularly

useful

when

you

are adding a new

device driver to the

first stage and

you

need to debug the code.

configure the first stage

for standalone operation where

loading is to be

performed with

the iSDM

monitor or ICE in-circuit emulator,

refer to Chapter 3.

NOTE

If your system

includes the D-MON38ó

monitor,

you

cannot download

the first stage

from one system to another and

then invoke it using

D-MON386 as

described above. The

description

applies only

to a system configured with

the iSDM monitor or ICE in-circuit

emulator.

4. Place the first stage in secondary storage,

and then load it programmatically.

This

applies only to iRMX I systems. Because the iRMX Il Operating System cannot

switch back to

real mode from

protected

mode, it cannot load the

first

stage, which

runs in real mode.

(These

systems

can load the first stage in real mode only.)

The rest

of this section

gives

instructions

for using the fourth method.

Although bootstrap

is usually

performed

in response to an external event

(such

as a

system reset or a

monitor command),

it can be initiated by an executing

program.

Such a

program

can load another system by

calling the PUBLIC symbol BOOTSTRAP ENTRY.

To prepare

for

such

a call, do the following:

l. Define BOOTSTRAP ENTRY as an

EXTERNAL

svmbol in the code of the

invoking program. -

2. Place a call to BOOTSTRAP ENTRY

the code of the invoking program. The

form of the call is

CALL BOOTSTRAP ENTRY(@filename)

Bootstrap hader t_<

USING THE BOOTSTRAP LOADER

where:

filename An ASCII

string containing either the

pathname of the

target

file followed by a CARRIAGE RETURN, or a

CARRIAGE RETURN only. If the

string contains a

pathname, the named file is loaded. If the

string

contains a CARRIAGE RETURN only, the default

file,

as defined by the %DEFAULTFILE macro in the

BS1.A86 or BS1MB2.A86 configuration file, is loaded,

(The

BS1.A86 and BS1MB2.A86 files

are

discussed

Chapter 3.)

The call must follow the PL/M-8ó I-ARGE model of segmentation.

(Even

though

this

is a call, rather than a

jump,

it does not return.)

3. Link the calling

program

to a

version

of the first stage of the Bootstrap Loader. You

can do this by using the BSl.CSD file as a model and making the

following

changes:

. Add the calling

program

to the list of modules that are linked in BS1.CSD.

r "Comment

out" the locate sequence ifyou want

to use any code other than absolute

code. For more details on absolute code, refer to the LAPX 8ó, 88 Family Utilitíes

Guide.

More information on the

BS'l.CSD file

is available

in Chaoter 3.

2.4 CHOOSING ATHIRD

STAGE

Ifyou plan

to load iRMX II applications, you must

include a

version

of the Bootstrap

I-oader's third

stage on the secondary storage device from which you are

your

applìcation. You can

use the following kinds of third stages, depending on the type of

system

you

are loading.

o A generic third

stage

. A default device-specific third stage

. Your own configuration ofthe device-specific third stage containing

customized

device

drivers.

The rest of this section

should help you decide which

third stage best suits your needs.

The important factors

to consider

when

choosing a third stage

are the size of

your

system,

the tlpe of

mass storage devices you are using

to boot

your

system, and the

CPU

board you

are usrng.

If you plan

to load

your

system

from any of the Intel-supplied

devices,

you

can use the

default device-specific

third stage regardless of the

size of your system or a default

generic

third stage

for systems up to 840K

bytes. Both third stages are supplied

for 80286 and

80386

CPU boards.

2-6 Bmtstrap hader

USING THE BOOTSTRAP

LOADER

If you plan

to load your system

from a custom device, the size

the system

determines

which

third stage

)'ou

should

use.

. For

systems that are not

expected to exceed

tt40K bytes, use the generic third stage. In

this case, you do not

need to supply a custom

device driver for the thirtl stage. You will

already be supplying

a custom

first stage driver; the generic third stage will

use that

same driver

to access the

custom device.

. If your

application exceeds

840K bytes, you must

use

the

device-specific third stage,

because

it switches the processor

into protected mode before

loading the application.

This enables the third

stage to load

into the entire l6 megabyte address space

supported

protected

mode.

However, to Ìoad applications from your custom

device,

you must write

a third stage clevice

driver for

your

device. This driver can be a

modification

of your first stage

driver that runs in thc iì02fì6 proccssrtr's protccted

mode. For information

writing

a third stage

driver, refer to Chapter 6.

NOTE

The 840K byte

limit on systems loaded by the generic third stage applies

to the boot file only.

Once the boot fiÌe is loaded and has control, the

entire lfr megabytes

of memory address space

available for the

system

(both

the free space

managcr and the Application Loader).

Table 2-l lists the versions of the

third stage that arr: supplicd on the Bootstrap Loader

Release Diskette.

This table enables you to pick

the

appropriate

thircl

stage

firr

your

system. After you install your system, these files are available in the /RMX286/BOOT

directory.

Table 2-1.

Supplied

Third

Slage

Files

CPU Bosrd Devico-Spscilic

Third

Stag€

Gonsric

Third

Stage

isBc 286/10

isBc

286/10A

isBc 286/12

isBc

286/100A

isBc 386/2X

isBc 386/3X

isBc

386/116

isBc

386/120

2fú12

28612

2861mA

38520

38620

386100

28612.G8N

28612.GEN

28612.

2861OOA. G E

38620.GEN

3861@.GEN

386100.GEN

Bff)tstrap k)ader

CONFIGURING CHAPTER 3

THE

FIRST STAGE

3.1

INTRODUCTION

There are three stages to the Bootstrap Loader, anrJ

two of these

stages (the first stage and

the third stage)

can be configured

to m:rtch your application

system. The second st:rge is

constant and

does not need to be configured.

This chaptor tlescribes how to configure the

first stage.

Configuring

the first stage of the BoÒtstrap Loacler

involves

the

tollowing operations:

. Editing three

or more assembly

language source files to inclicatc the configurable

options and

device drivers

to include in the first stage

. lnvoking

a SUBMIT file to assemble

the sourcc files, link thcm togcthcr with

the code

for the fìrst stage,

and assign absolute

addresses to the code in preparation

for placing

it into PROM devices.

Default versions

of the assembly language

source files ancl the SUBMIT filc arc placed

the

/RMX86/BOOT or

/RMX286/BOOT directory during installation.

These files

include the following:

BSl.AlJ() This assembly language source

file contains nlacros that speciry

information

about the processor

and the bus, how the boot device

and load file are selected.

and

which

devices can bc booted

from.

You should use

this file if your system is a MULTIBUS I system.

This assembly language

source file contains macros that speciry

information

about the processor

and

the bus,

how the boot devicc

and

load file are selected, and which tlevices can be booted

from.

You should use

this file if

your

system is a MULTIBUS II system.

This assembly language source lile contains macros that tell the

Bootstrap Loader

what

to do if errors occur during bootstrap

loadins.

BS1M82.A86

BSERR,A86

Brxrtstrap l,oader -1-

CONFIGURING

THE FIRST STAGE

B208.486

BMSC,A86

8218A.A8ó

82244.A86

B251.A86

B254.486

8264.486

BSCSI.A86

BSl.CSD

These

assembly language

source

files

contain configuration

information about the first

stage device drivers. Each file

describes

one device

driver. For each device driver

that

you want

to include

in the first stage, you must

set up the appropriate file

and link it to

the rest

of the first staqe.

This SUBM

IT file contains the commands

needed to assemble the

preceding source files, link

the

resulting

modules

(and

any others

that

you supply), and locate the resulting

object module containing

the configurecl first

stage.

As shipped on the release diskettes,

these files are set up to generate the default

version

the Bootstrap Loader's

first stage. If you decide to configure

your

own

version of the first

stage,

you will

most likely edit

either the BS 1.,A86 or BS I MB2.A86 configuration file

(depending upon

your

system), the BSERR.A86 configuratìon

file, and the BSl.CSD

submit file. Make changes in the device driver configuration files only if

you want to

change the Intel-supplied defaults in those files.

The following sections describe how to modifu all the configuration files to tailor

the first

stage

the Bootstrap

Loader

to meet your specifications

NOTE

It's important that the BSl.,486 or BS1M82.A86 configuration file and the

BSI.CSD

SUBMIT file agree as to the device drivers

that

are included in the

first stage. Whenever you

change the device driver specifications in one of

these files, be sure to check the other file as well. Specific

areas that

you

should

check are discussed

descriotions

of the files.

3.2

BS1.A86 AND BS1MB2.A86

CONFIGURATION FILES

Figures 3-1 and 3-2 show the BSl.,4lì6

and BS1MB2.A86 files as they are delivered from

Intel. These files consist of four

INCLUDE statements and several macros. The

definitions of the

macros that can appear in these files are contained

in the INCLUDE file

BS 1.INC. The macros themselves are discussed

in the next few sections.

ì-7 Bmtstrap l-oader

CONFIGURING THE

FIRST

STAGE

NOTE

Depending on your system, you

must choose between BS1.,486 and

BS1MB2.A86 as the correct

configuration file. If your

system is a MULTIBUS

I system, choose the BS1.A8tr configuration file. Ifyour system is a

MULTIBUS II system, choose the BS1M82.A86 configuration file.

Figure

3-1.

Intel-Supplied

BSI-486 File

nane bs1

include

(

: f1 :bcico. inc

)

include

(

:fl:bmb2.

inc

)

inc lude

(

: fI : bmps . inc )

u cpu

(

80386

)

íSBC 188/48 initialization of the iAPX 188

iAPX_186_INIT

(y, Ofc3 8h, none, 8Obbh, none, 003bh

)

isBc 186//03(A)

and iSBC 186/51 initÍalization of the iAPX

186

1APX_186_INIT(y, none, none

8Obbh, none

,0038h)

%console

Zmanual

Zauto

%loadfile

Xde

faul t fi le ( '

/sys tern/rmx8

' )

% re rrie s

(5)

l-ear_s dm_extens ions

c ico

ísBc 86

/05 /I2a/I4/30 /35

ser ial_channel (

825Ia, 0d8h, 2, 8253, O dA}l, 2, 2,

isBX 3s1 (on isBX

/10)

serial channel

(

825la,

0A0h,

8253, 0B0h,

2, 8)

Boolstrap

[,oader 3-3

CONFIGURING

THE FIRST STAGE

1SBX 354 Channel A (on iSBX /10)

serial_channef

(

82530,084H, 2

,82530 ,084H,2,0 ,

Oeh, a)

iSBX 354 Channel B (on iSBX

il0)

serial_channel

(82530,

080H, 2, 82530, 080H, 2,

0, Oeh, b)

8 MHz 1SBC 186/03A Channel A

se r ia l_channe t

(

8274,0d8h,2,80186,0ff00h,2

,0dh)

8 t4Hz iSBC 186//03A Channel B

serial_channel

(8274

,0dah,2 ,

80186

,0ffO0h,

,0dh)

serial_channe l (827

4, Odah, 2, 801 30, 0e0h, 2, 2, 034h)

6 MHz iSBC 186/03/51 Channel A

s er ial_channe I

(

8274

,0d8h,

,80186,0ff00h,

,0,0ah)

6 MHz

iSBC I86/03/5L ChanneL B

serial_channel

(

82 74

0dah

,80186 ,0ff0Oh,

,1 ,0ah)

se r ial_channe l (

8274

0dah

2,80130,0e0h, 2,2

,O21h)

i-SBC 188/48/56 SCC

#1 Channel A

serial_channel

(

82530,

0dOh,

82530, 0dOh, 1, 0, 0eh, a)

1.SBC 188/48/56 SCC

/11

Channel B

s er ial_channe L

(

82 530,0d2h, 1,82530,0d2h,1

,0,0eh,

iSBC 286110(A)/12 Channel A

se r ial_channe

(8214,0d8h,2,8254,0d0h,

2,2

,8 )

íSBC 286110(A)/12 Channel B

s er ial_channe l

(8274,0dah,2,8254,0dOh,

2,1,8

)

isBc 386/2X and ISBC

386/3X

seríal channel

(

8251a, 0d8h

,8254 ,0d0h,2 ,2 ,8)

Figure

3-1.

Intel-Supplied

BSI;\86 File

lcontinued )

3-4 Bfi)tstrap Loader

CONFIGURING

THE FIRST STAGE

Multibus I devices :

0, devÍceinit208gen, devi c e

re ad2

08gen

)

l, devicè init208gen, deviceread2 08gen)

0, deviceinitmscgen, devicereadmscgen)

1, devicè ini tmscgen, devicereadmscgen)

8, device ini tnsc gen, devicereadmscgen)

9, device initmscgèn, devicereadrns

cgen)

%device

(

af0

ldevice (afl

%device

(w0

Zdevice ($rl ,

ldevíce (wf0

itdevice (wf 1

%device(s0, 0, deviceinitscsi, devicereadscsi)

Z device

(

sx1410a0

, 0, deviceinitscsi, devicereadscsí, sasi_x1410a)

l device

(

sx1410b0, 0, devieeinÍtscsÍ, deviceteadscsi, sasi_x1410br

ldevicè(snf0,2, devlceinitsesi, devicereadscsi, s as i_x14 20mf

)

%device(prnf0, 0, deviceinit2l8A, deviceread2LSA)

Tdevice(pbO, 0, deviceinit25l, deviceread25l)

Zdevice(b0,

0, deviceiniL254, deviceread254)

%device(baO, 0, devicèinit264, devíceread264)

Zend

Figure

3-1. Intel-Supplied

tsSr.4,86 File

(continued)

-t-s

Bootstrap Loader

CONFIGIIRING THE FI RST

STACE

Figure

3-2. Intel-Supplied

BSIMB2-486

File

name bsl

$include (

: fl :bcico. inc)

9include (

fl :brnb2.

inc)

$include

(

: fl :bmps. inc)

;bist(0FFFFH:0FFFFH)

;

copy(08000H, 00FFH, 08000H,

000FH,

08000H,

0H)

; (LBX), (PSB,addr) or (LBX+PSB)

;

auto_c onf i gure_memory (

LBX)

lrncruoe(:r1:DsLlncJ

%cpu(80386)

; MPC and AD|{A configuration for 1SBC 286/L00 with iElW 100 MPC module

;bnps(00H,

4, 088H, 200H, 3, 2, 0A0H, 16)

; MPC and ADI4A configuratíon for íSBC 286/700A

;bmps(00H,

4, 08BH,

200H, 2, 3, 0EOH,

16)

; MPC and ADMA

configuration for 1SBC 386/100

Zbmps(00H,4,089H,

2O0H, 2, 3, 000H, 16)

Zconsole

%manual

%auto

%loadfile

%defaul-tf

ile (' /system/rnx86' )

Xretries(5)

;

c lear_s dm_extens

ions

;ci-co

3-6 Brxrtstrap

l,oader

1SBX

351 (on iSBX

/10)

serial_channel

(

825Ia,

0A0h, 2,

8253, 080h, 2, 2, 8)

iSBX 354 Channel A (on iSBX

/10) for 1SBC

serial_channel

(

82530,

084H, 2, 82530, 084H,

2, 0,

iSBX 354 Channel B (on iSBX

/10) for iSBC

serial_channel

(

82530, 080H,

2, 82530, 080H,

2, 0,

386

/r00

0eh,a)

3 8 6/100

Oeh,b)

iSBC 286lf00A Channel A

serial_channel

(82530,

0dch, 2,

82530, 0dch, 2, O, Oeh, a)

iSBC 28611004

Channel B

serial_channel-

(

82530,

0d8h, 2, 82530,

0d8h, 2, 0, Oeh, b)

Mult íbus devices

ldevícels0, 0, deviceini

tscsi. devicereadscsí

)

Zdevice(sx1410a0,

0, deviceinitscsi, devicereadscsi, sasi_x1410a)

Zdevice

(

sx1410b0

, 0, deviceinitscsi, devicereadscsi, sasi_xl410b)

Zdevice(smf0, 2, devíceinitscsi, devlcereadscsi, sasi_x142Ornf)

Zdevice(pmf0,0, deviceinit2l84, devicere ad2l SA

)

Tdevice

(w0, 0, device_ini x_224a

, devlce_read_2 24a

)

%device(w1

, I, device_iní t_224a

, device_read_224a)

Tdevice

(wfo, 4, device_ini t:._224a, device_read_2

2+a

Zdevice(wfl , 5, devic e_ini t_224a, device_read_2

24a

)

%end

CONFIGURING THE FIRST

STAGE

Figure

3-2. Intel-Supplied

IlSlM82"{8ó File

(continued)

To configure your

own

version

of the Bootstrap

Loader

first

stage,

edit either the BS1.A86

or BS1MB2.A86 file

you

need to include

or exclude macros.

A percent

sign

(%)

preceding

the macro name

includes

(invokes)

the macro, and

semicolon (;) preceding

the

macro name excÌudes

the macro.

treatins it as a comment.

NOTE

When you

exclude a macro, you

must replace the

percent

sign with a semicolon.

Do not simply add a semicolon

in front of the

percent

sign.

The order

which

the macros should appear

is the

same

order

that they are listed in the

BS1.A86 or BS

1M82.A86

file.

tsfi)tstrap l,oader J-/

CONFIGURING

THE FIRST STAGE

The following

sections describe the macros that

can appear in the BS1.,4lì6

and

BSlMB2.A8ó

files. Because the

Bootstrap Loader supports

both iRMX I and iRMX II

Operating Systems,

some of these macros apply to one Operating

System and not the

other. In such cases, the

section heading notes the operating system to

which

the

macro

applìes.

When

no operating

system designation appears, the macro is

valid

for both

the

iRMX I and iRMX Il Operating Systems. The

macros are described in the order

they are

listed in

the BS1.A86 and BS1MB2.A86 files.

If you

make a syntax error

when entering macros into the BS 1.A86 or BS1MB2.A86 fiìe, an

error message appears

when

assembling

the

file. For

example, if you misspell a macro

name in a macro call, the following type of message

may be returned:

*** ERROR

#301 IN 129, (MACRO)

UNDEFINED MACRO NA.|.{E

INSIDE CALL: BADNAME

*** ERITOR

/I1 TN 129, SYNTAX ERROR

If an error such as this occurs. check for correctness in the BSl.Atì6 or BSlM82.A86 file

and attemDt to reassemble the file.

3.2.1 %BIST Macro

(MULTIBUS@

llOnly)

MULTIBUS Il systems

include

a Built-In Self

Test

(BfSD program

in PROM devices that

verifies

MULTIBUS Il hardware

when

the hardware is

powered

up. The ToBIST macro

causes the Bootstrap Loader to invoke the BIST program on

the CPU board during

Bootstrap Loader initialization. The BIST program

then tests the hardware.

If the BIST program encounters

an error condition, it places

an error

code in the AX

It does not call the Bootstrap Loader's BSERROR

routine because an

error

of this tlpe implies that the system hardware

inoperable.

The

%BIST macro

should

be included only for MULTIBUS

II systems, and only for those

systems that

don't also include a monitor in PROM devices.

In systems that

include

monitor, the monitor becomes

active before the Bootstrap Loader,

and it invokes the BIST

program.

Therefore, invoking the BIST program from the

Bootstrap Loader is

unnecessary.

3-8 Bootstrap l-oader

CONFICURINC THE FIRST STAGE

The

syntax

of the macro is

%BIST (address)

where:

address Address

of the CPU board's BIST program.

This

parameter

must be

entered

in the form

BASE:OFFSET

(for

example, 1234:5678). To

determine

the address

ofyour CPU board's BIST program, refer to the

hardware reference

manual for that board.

3.2.2.

o/"COPY

Macro

(MULTIBUS@

llOnly)

T'he

ToCOPY macro isusedwith 386l116-

and 386/120-based systems. Ifyour system is

not of this t)?e, do not

include the

o/oCOPY

macro in the BSlM82.,486

file.

Both

3tl6/ 1 16- and 386/120-based systems

locate EPROM memory at the top of the 4

gigabyte

address space supported by

the E0386 upon reset. However, the first stage of the

Bootstrap

Loader must execute

within

the

first megabyte of address

space (real

mode).

Because the

first

stage

must be repositioned within

memory,

you must

use the

o/oCOPY

macro for any application where

the EPROM memory is mapped outside of the first

megabyte of address space

upon reset.

contrast, the 386/2X and 38ó/3X

systems locate EPROM memory at the top of the first

megabyte of memory space

upon reset. Thus, the

ToCOPY

macro is unnecessary.

This macro copies the first

stage of the Bootstrap Loader from EPROM devices to the low

megabyte of RAM. You should only specifo this macro

you do not have a monitor

installed and the Bootstrap

loader executes first upon system reset.

The syntax of the

o/eCOPY

macro is as follows:

ToCOPY(src_lo,

src_hi,

dest_lo, dest_hi, count_Ìo, count_hi)

where:

src lo

r.Jhi

dest_lo

dest_hi

count lo

count

The low

word

of the 24-bit

physical

source address.

The high byte of the 24-bit

physical

source address.

The low word of the 24-bit physical destination address.

The high byte of the 24-bit

physical

destination address.

The low

word of

the number

of bytes in the first stage.

The high byte of the number

of bytes in the first stage.

Bootstrap l,oader 3-9

CONFIGURING

THE FIRST

STACE

3.2.3.

"/'AUTO

CONFIGURE

MEMORY Macro

(MULTIBUS@

Only)

This macro causes the Bootstrap

Loader to automatically configure

the starting and ending

addresses of all iLBX and/or iPSB memory boarcls

available to MULTIBUS II systems.

Configuration begins

with

the memory board

in the lowest numbered slot and

progresses

through the memory board in the highest numbered

slot.

Configuration

occurs differently

depending upon how you invoke the macro.

You should include the %AUTO CONFIGURE MEMORY macro only for MULTIBUS

ll systems. and only for those sysGms in

which

the Bootstrap Loatler

is invoked upon

system reset (as opposed to under program control). In systems that include the

monitor

in PROM devices, the monitor becomes active before the Bootstrap Loader,

and it should

invoke its own

%AUTO CONFIGURE MEMORY macro. Therefore. invokins the

macro from the Bot-rtstrap Loader is unnia"a.ory.

The

syntax

of the macro is

%AUTO_CONFIGURE_MEMoRY(interface_type

[,start_address]

)

where:

interface_$pe

start address

A string representing the bus interface

the memory

board(s) to be configured.

Valid

strings are LBX, PSB,

or LBX

PSB.

The starting 64K page of memory when

PSB

memory is

hcino cnnfim r red

Three

pcssible

configuration options exist: iLBX only, iPSB

only, or iLBX and iPSB. You

must speci! the required parameters

using one of the following three methods:

a/oAUTO_CONFIGURE_MEM

O RY (LBX)

This option configures

memory boards accessible to the

processor

via

the iLBX bus.

Using

this configuration option, the macro assigns sequential

consecutive addresses

beginning with

zero for the start and stop addresses

of each iLBX memory board.

Board configuration proceeds

from the board occupying the lowest slot

number

the

board

occupying the

highest

slot

number.

%AUTO_CONFIGURE_MEMORY (PSB,

start address)

This option configures

memory boards accessible to the CPU via

the iPSB

bus. Using

this configuration

option, the macro assigns sequential consecutive

addresses for the

starî

and stop addresses of each iPSB memory board.

The assigned addresses begin

with

the supplied starting address. Board configuration

proceeds from the board

occupying the lowest slot number to the board

occupying the highest slot number.

3-10 Bmtstrap l-oader

CONFIGURING THE

FIRST

STAGE

ToAUTO_CONFIGU

RE_MEMORY

(LBX+

PSB)

This option configures memory in the same manner as the first

option,

with

one

additional configuration. All boards on the iLBX bus that also have iPSB interfaces

have the same

starting

and ending addresses

for both interiaces.

The following

syntax errors can occur if you enter incorrect parameters

or incorrect

combinations of

parameters.

ERROR

- <type>, inval-id interface type

ERROR

- invalid Daraneter cornbination

3.2.4

"/"CPU

Macro

The %CPU

macro identifies the type of CPU that

performs the bootstrap loading

operation. You must include

this

macro

in the BS1.A86 or BSlM82..486

file once

(and

only once).

The syntax of

the CPU macro rs

%CPU(cpu_type)

where:

cpu_type The type of CPU

performing

the

bootstrap operation.

Valid types are:

Typ"

8086

8088

8018ó

801llti

80286

80386

Description

8[ì86

processor (iRMX I only)

8088 processor

(iRMX I only)

8018ó

processor (iRMX I only)

lì0ltllì processor

(iRMX I only)

80286 processor (iRMX I

and iRMX II)

80386 processor

(iRMX I and iRMX II)

3.2.5

"/"BMPS

Macro

(MULTIBUS@

llOnly)

The

%BMPS

macro configures the message

passing system used

during bootstrap loading.

This macro identifies

the base address of the Message Passing

Coprocessor

(MPC),

address distance between

MPC

ports,

and information

that defines how

direct memory

access

(DMA) transfers occur. If you

have a MULTIBUS

II system that

bootloads from

device

whose

driver

uses MULTIBUS II transport

protocol (i.e. the

186/224A driver),

you

must use this macro.

lf you

have a MULTIBUS

I s)'stem or a

system that bootloads

from a

device

whose driver does not use MULTIBUS II transport

protocol, you

must not

use this

macro.

Bootstrap

lnader 3-ll

CONFIGURING THE FIRST STAGE

The syntax of the

%BMPS

macro ls

%BMPS

(mpc$base$addr, port$sep,

duty$rycle, dma$base$addr,

dma$in, dma$out,

dma$trans, data$width)

where:

mpc$base$addr

port$sep

duty$rycle

dma$base$addr

dma$in

dma$out

The base I/O port

address

of the

MPC. Refer to the

appropriate single board computer user's guide for this

address.

The number of addresses separating individual MPC

ports.

For example, if the mpc$base$addr is 0000H and

the next three I/O port addresses are 0004H, 0008H,

and 000CH, respectively, the port$sep is 4H. Refer to

the appropriate single board computer user's guide for

the l/O port address map.

The MPC duty

cycle for the local bus.

(The

rate at

which

data

packets

are

generated.)

For information on

how to calculate

a duty cycle suitable for the local bus,

refer to the MPC User's Manual. For duty cycles suitable

for Intel single board computers, refer to the appropriate

single board computer

user's

guide.

The base I/O port

address for the

Advanced

Direct

Memory Access (ADMA) controller. Refer to the

appropriate single board computer

user's

guide

for this

address.

The channel used to receive (input)

DMA message

passing

transfers. Refer to the appropriate single

board

computer user's guide

for this channel number.

The channel used

to send

(output)

DMA message

passing.

Refer

to the appropriate single board computer

user's guide

for thìs channel

number.

The

l/O port

address used for DMA data transfers.

Reier to the appropriate single

board computer user's

guide

for this address.

The data

width

in bits of the

local bus. This

value

must

be either l6

or 32

ldecimall. If

thewidth

is set to 32 bits

on a 386/116- or 386/120-based board,

flyby

(one

cycle)

DMA mode is enabled.

dma$trans

data$width

The

%BMPS macro

can

qenerate

errors if the

local bus

width

is not l6 or 32 bits

wide.

3-t2 Bmtstrap l-oader

CONFIGURING THE FIRST

STAGE

3.2.6 %IAPX 186 lNlT

Macro

(!RMX

MULTIBUS@

| Systems

Only)

T\e o/oIAPX_186_INIT

macro specifies the

initial chip select and mode values

for 8018ó

and

80188 CPUs.

Include this macro

only for systems that use the 80186

or 80188

processor

and do not

include a monitor

in PROM devices.

systems

that include the

iSDM monitor, the

monitor becomes active

before the Bootstrap

Loader, and the monitor

must initialize the

CPU. An iSDM configuration

macro is available

for this

purpose.

See

the iSDM System Debug

Monitor Reference

Manual for more information.

The syntax of the iAPX_186_INIT

macro is

ToiAPX_186_INIT(rmx,

umcs, lmcs,

mmcs, mpcs, pacs)

where:

rmx The

initial mode of the 80186

Programmable Interrupt Controller

(PIC). Acceptable values

are as follows:

Value

Description

The 8018ó PIC is initialized in iRMX compatibility

mode.

umcs

lmcs

mmcs

mpcs

pacs

n The 80186 PIC is initialized in default mode.

Initial value

for the upper-memory chip-select control register.

Initial value

for the lower-memory chip-select

control register

Initial

value

for the

midrange-memory chip-select control register.

Initial

value

for the

memory-peripheral chip-select control register.

Initial value

for the

peripheral-address

chip-select control register.

In all parameters except the

first one

(rmx),

NONE is also an acceptable

value,

implying

that no initialization

value

should

be placed in the corresponding register. For information

on the

chip-select control registers,

and the

values

place

in them, see the data sheets for

the 80186 and 8018t1 processors.

All the

default

parameter

values for this

macro

(in

the Intel-supplied BSl.Alt6

file shown in

Figure 3-1) are appropriate to initialize

the CPUs on the iSBC 186/03(A), iSBC

186/51

and iSBC 188 /48 /56 boards.

The iRMX I Operating System

does not allow

you

to move the

80186

relocation

I/O addresses other than 0FF00H,

its

default

Bootstrap l-oader 3-13

CONFIGURING

THE FIRST

STAGE

3.2.7

%CONSOLE, %MANUAL,

and

%AUTO Macros

The CONSOLE, MANUAL, and AUTO macros specify how the first stage identifies the

file that the second stage will load (either the load file or the third stage) and the device on

which the

file is found.

The syntax of the

a/oCONSOLE, o/oMANUAL,

and

%AUTO macros is

TaCONSOLE

TaMANUAL

ToAUîO

There are no parameters

associated

with

any of these macros.

Depending on the action you want

the Bootstrap Loader to take, you

can include none,

any,

or all of these macros, and the

combination

you

choose defines the

set of actions

taken. Because the

ToMANUAL macro automatically

includes both the

%CONSOLE

and

%AUTO macros, five functionally-distinct

combinations are

possible.

Each of these

combinations

requires that the

device list at the end of the BS1.A86

or BS1MB2.A86 file

be set up

in a certain

way.

For more information

on the device

list, see the discussion of

the ToDEYICE macro later in this

chapter. The following paragraphs

list the

possible

macro combinations,

the device requirements, and the

actions that the Bootstrap Loader

takes when

each combination

is invoked.

No (Requires

that

the device list defined with

ToDEVICE macros have

o/oCONSOLE, only

one entry.)

%MANUAL.

or TaAU'f O

macro

o The

Bootstrap Loader

tries once to load from the

active

device.

. The

Bootstrap Loader tries

once to load the

file

with

the default

pathname (the

one you define with

the

%DEFAULTFILE macro).

3-14 Bo0tstrap lrader

CONFIGURING

THE FIRST

STAGE

ToCONSOLE (Requires

that the device list have only

one entry.)

oruy

. The Bootstran

Loader

tries

once

to load from the device in the device

list.

r The Bootstrap Loader issues an

asterisk (*) prompt at the console

terminal and waits for an operator to cnter the

pathname

the file to

load. It tries once to load the file

the operator specifies.

-- If the operator enters a pathname, the Bootstrap Loader

loads

the file

with

that

pathname.

-- If the operator enters a CARRIAGE RETURN only, the lile

with the default pathname is loaded.

%MANUAI (Requires

device list with at least one entry.)

only

. The Bootstrap Loader issues an asterisk

(*) prompt for

a pathname at

the console terminal.

. The Bootstrap Loader chooses

a device depending

on the operator's

response.

-- lf a device name is entered, the Bootstrap

Loader loads

from

that device. It tries to load until the

device becomes ready

until

no more

tries are allowed

(as

limited

by the optional

%RETRIES

macro).

-- If only CARRLq.GE RETURN

is entered, the Bootstrap

Loader

looks for a ready

device by searching through the

list of devices

(in

the order the ToDEVICE

macros are listed

in the BSl.,486

or BS I MB2.A86

file). The search continues

until a ready device

is found or

until no more tries are allowed

(as

limited by the

optional

%RETRIES

macro).

If the Bootstrap Loader

finds a

ready device, it loads from that

device.

. The Bootstrap Loader chooses

a file depending

on the operator's

response.

-- If a pathname is entered, it tries

once to load the file

with that

pathname.

-- If no file

name is entered, it tries

once to load

the file

with

the

default

pathname.

Bmtstrap [-oader 3-15

CONFIGURING THE FIRST STAGE

%AUTO (Requires

device

list

with at

least

one entry.)

. The Bootstrap Loader looks for a ready device by searching through

the

list of devices

(in

the order the %DEVICE macros are listed

in the

BSl.A86 or BSlM82.A86 file). The search continues until a ready

device is found or until no more tries are allowed las limited bv the

optional

RETRIES macro).

. If the Bootstrap Loader finds

ready device,

it tries

once to load

the

file

with

the default file name.

o/oAUTO, (Requires a clevice list with at

least one entry.)

ToMANUAL,

and

o/aCONSOLE

. The Bootstrap Loader issues an asterisk (*) prompt

for a

pathname at

the console.

. If the operator responds

with

pathname

that contains no device name,

the Bootstrap Loader looks for a ready device by searching through the

list of devices

(in

the order the

%DEVICE

macros are listed in the

BSl.A86 or BSlMB2.A86 file).

The

continues until a ready

device is found or until no more

tries are allowed las limited bv the

optional

ToRETRIES macro).

. lf the Bootstrap

Loader finds a ready device

or the operator responds

with

pathname

containing

a device name, the Bootstrap

Loader tries

.,"':..

l;:::l;il:l:'::',:"?

::::T:::

;:T;':.,,^",

lathname.

-- If only CARRIAGE RETURN is entered,

it tries to

load the file

with

the default

pathname.

Whenever

the Bootstrap

Loader's asterisk prompt

appears, the operator

can include a

Debug Switch along with

a device and/or

filename specification.

The Debug Switch is

clescribed

in Chapter 2.

3.2.8

o/"LO

ADFI LE Macro

The

%LOADFILE macro

causes the Bootstrap

Loader to display the

pathname of the file

itloads.

you

are loa<Jing

an iRM X I system,

this will bethepathnameof

the load

file. If

you

are loading

an iRMX II system,

the

pathname

of the Bootstrap

Loader's third stage

will

be displayed.

The

macro displays the pathname

at the console

after loading

the

second

stage

but before

loading the

load file

(or

third

stage).

ló Bootstrap

l,oader

CONFIGURING

TIIE

FIRST STACE

If you

include

the

ToLOADFILE macro,

you

must also include either the

o/cCONSOLE

%MANUAL macros

to enable the

Bootstrap Loader to acr:ess

the console.

The syntax of the

%LOADFI

LE macro is

EALOADFILE

There

are no parameters

associated with

this macro.

3.2.9

./'DEFAU

LTFI

LE Macro

The

%DEFAULTFILE macro

specifies the complete pathname

of the default file. The

default

file is the

file that the second stage

loads

whenever

no othcr

file is specified.

The syntax of

the TaDEFAULTFILE

macro is

7o DEFAULTFI LE('pathna

me'

)

where:

pathname Hierarchical pathname

of the default file, starting

at the root directory.

The pathname

must be enclosed in single quotes.

For example, the

name'/BOOT/RMX286l2'

mighr he used.

you

omit this macro from the

BS1.A86 or BSlMB2.Atló

file, a NULL

pathname

assumed by the Bootstrap

Loader

first stage. In this case, the second stage

assumes the

default name is

/SYSTEM/RMX86.

The Intel-supplied BSl.A86 and BSlMB2.A8ó

files

include a ToDEFAULTFILE

macro and assigns

/SYSTEM/RMX86

as the default file.

3.2.10 %RETRIES

Macro

The

%RETRIES macro,

when

included with

the

%AUTO or %MANUAL macros. limits

the

number of times that the

first stage searches the device

list for a ready device.

NOTE

If you omit the

o/aRETRIES

macro

when

including the

%AUTO or

%MANUAL macros and no

device in the list is ready, then the

lbr a

ready device continues indefinitely.

Bootstrap [,oader 3-

CONFIGURING

THE FIRST

STAGE

The syntax of the

%RETRIES macro

%RETRIESlnumber)

where:

number Maximum number of times the first stage checks each device for a ready

condition. You can speci$ any number

in the range of 1 through

OFFEH.

3.2.11

./"CLEAR

SDM EXTENSIONS Macro

The

ToCLEAR SDM EXTENSIONS macro causes the Bootstrap

Loader to clear the

iSDM

monitor iorn-ind extensions (the U, V, antl W commands). Once cleared, a

monitor extension,

such as the iRMX I or iRMX II System Debugger (SDB)

or the System

300 System Confidence Test

(SCT),

must

be reinitialized before it can be used again.

This macro is usefuI when

adding monitor-level clebugging

command extensions. It

prevents

you from inadvertently

attempting to invoke a monitor

extension that

was

loaded

in a

debugging session

and overwriting application or Operating System code.

The syntax of

this macro is

A/O

CLEA R-S D M_E

XTE NS IO NS

The Intel-supplied versions

of the

BS1.A86 and

BS1M82.A86 files do not

invoke this

macro.

This macro

must not be invoked if you are

configuring a standalone

Bootstrap

Loader.

3.2.12 %CICO

Macro

The

CICO macro specifies

that console input

and output are to be performed

standalone Cl and

CO routines; that

is, routines that are

not

part

of the

monitor. Ifyou

include the CICO

macro, you

must

perform

some

other operations

well,

depending on

whether

the CI and

CO rourines

you

want

to use iìre

your

own or those supplied by Intel.

If you

use

the Intel-supplied standalone

CI and

CO routines:

1. Change

the line in the

BSl.CSD file (Figure

3-3) that reads

: fl :bcico. obj , &

2. Include exactly

one instance of the

ToSERIAL

CHANNEL macro (described

in the

next se('tion)

in the

BSI.AEó or

BSlMB2.ASo

-fiIe.

3-18 Bootstrap Loader

CONFIGURTNG THE FIRST

STAGE

If you supply your

own

standalone

CI and CO

routines:

1. Change the line

in the BSI.CSD

file (Figure

3-3) rhat reads

& :fl:bcico.obj,

:f1 :myc ico . obj

, &

where:

mycico.obj An object file that you supply

containing procedures

named CI, CO, and

CINIT. CINIT must perform

initialization

functions

required to prepare the console

for input and output

operations.

2. Do not include the

ToSERIAL

CI:IANNEL macro

in the BS1.A86 or BStMB2.A86

file.

The syntlx

of the

oiCICO

macro is

VoCICO

There

are no parameters

associated with

this macro. The CICO

macro is not invoked

the

Intel-supplied

BSl..{86 or BSlMB2.A86

file. This macro musr be

invoked if you are

configuring

a standalone

Bootstrap

Loader

which

prompts

for the load file pathname.

3.2.13 %SERIAL_CHANNEL

Macro

The

ToSERIAL CLLA.NNEL

macro identifies the

type and characteristics

of the serial

channel usecl

to communicate with your

system console.

You

must omit this macro

if any of the following

conditions are true:

o Your system includes

a monitor.

o Your system

does not use a terminal

during bootstrap

. You supply your

own CI and

CO routines.

NOTE

You

cannot use the

%SERIAI- CHANNEL macro unless the serial device

local to the CPU board.

Also, the

%SERIAL CFIANNEL macro does not

support the on-board

diagnostic serial pn.t

on the |SBC -186/100 boarcl.

Bootstrap l-oader 3-19

CONFIGURING

TIIE

FIRST

STAGE

You must include

this macro

if you are configuring

a standalone

Bootstrap

Loader

to use

the Intel-supplied

Cl and CO routines

(see

the

description

of the

o/cCICO

macro

the

previous section). In

this case, use

the

%SERIAL_CHANNEL

macro to describe

the

serial controller device

that handles

the communication

to and from

the terminal

accessed

by the

Bootstrap Loader.

The Bootstrap

Loader

permits serial

communication

via an 8251A USART,

an 8274 Multi-

Protocol

Serial Controller. or an 82530 Serial

Communications

Controller. The

Intel-

supplied

BS1.A86 and BS1M82.486

files list

appropriate invocations

of the

ToSE,RIAL

CHANNEL macro

for each of these

serial channel controllers.

choose one

of these

veÉions of the macro,

replace the semicolon

on the appropriate

line

with a

percent sign. lncluding more

than one

o/oSERIAL_CHANNEL

macro causes

an assembly

error in BSl.Allfi or BSlMB2.AU6.

The

syntax of the

o/aSERIAL_CHANNEL

macro

is as follows:

o/aSERIAL_CHANNEL

(serial_type, serial_baselort,

serialjort_delta,

counter_type,

counter_baselort,

counterjort_delta,

baud counter, count, flags)

where:

serial_type

serial_base_port

Serial

Channel

82514

8274 Channel A

8274 Channel B

tt2530 Channel A

82,530 Channel B

The

serial controller device

you are using.

Valid values

are 8251A,8274, and 82530.

The l6-bit port address

of the base port used by

the

serial channel. This

port varies according to

the tlpe of

serial controller device

and,

if applicable, the

channel

used on the device. To

determine îhe port

whose

address you should specifo here, look

at the left column

of the following

list. Pick the item that corresponds

the

serial device on

your

CPU board and the

channel

through which the CPU communicates

with your

terminal. Then specify

the port address of the

corresponding

port

listed in

the right column. The

hardware

reference manual for

your

CPU

board lists the

port

acldresses for these seriaÌ devices.

Base Port

Data

Channel A Data Register Port

Channel

Data

Channel A Command Register

Port

Channel B Command

l'o ft

l-20 Bootstrap Loader

serialJrort_delta

counter_type

counter_baseJort

counterjort_delta

baud counter

8253

80130

82530

Timer Type

8253

8254

80 r30

80186

82530

Channel A

CONFIGURING THE FIRST STAGE

The

number of bytes separating consecutive ports

used

by the serial

device.

The type of device

containing the timer your CPU board

uses to generate

baud

rate for the serial device defineci

by this

macro.

Valid values

are:

8254

80186

NONE

Specifing NONE

implies that the baud rate timer is

automatically

initialized and the Bootstrap Loader does

not need to perform this function.

The 1ó-bit port address of the base port used by the

baud rate timer-

The

portwhose

addressyou specify

varies

according to the type of timer device and, if

applicable, the channel used

on the device. The following

list shows the ports for each of the valid

timers. Specify

the address of the port that corresponds

your timer

device. The hardware reference manual for the CPU

board lists the oort addresses for these serial devices.

Base Port

Counter 0 Count

Counter 0 Count Register Port

ICW I Register Port

Use 0FF00H for all boards

Channel A Commantl Register

Port

82530

Channel B Channel B Command Register

Port

The number of bytes separating consecutive ports used

by the timer.

The number of the counter that is used fbr baud-rate

generation.

The lblÌowing list identifies the

possible

counter numbers

you

can specify for each of timers.

Timer Type

8253

8254

80130

80186

82530

Counter Numbers

0, l,or2

0orl

Bootstrap l,oader 3-21

CONFIGURING

THE FIRST STAGE

count A

value that when loaded into the timer register

generates

the desired

baud rate. The method

calculating this

value

follows

these parameter

definitions.

flags Applies

only when the serial t)?e

parameter is defined

as 82530. For other serial controllers.

omit this

parameter.

This

parameter specifies which channel of an 82530

Serial Communications

Controller

will

serve as the

serial

controller. Valid

values

are

Value Channel

Channel A

Channel B

To derive the correct value for the count parameter, you must perform five computations.

The starting

values

for these computations are the desired baud rate at

which

you

want

the

serial

port

to operate and the clock input frequency to the timer. The clock input

frequency is listed in the data sheet for the timer.

First,

perform

one of the following calculations to obtain a temporary value

for

use in later

calculations:

If the timer is an 8253,82-54, lì0130,

or 80186,

temporary_value

= (clock

frequency in

Hz)/(baud rate x 16)

If the timer is an 82530,

temporary_value

= ((clock

frequency in Hz)/(baud ralex2)) - 2

Next,

perform

the following calculation

to obtain the fractional part of the temporary value

found in the

first calculation:

fraction

= temporary_value

- INT(temporary_value)

The INT function gives the integer portion

of temporary_value.

1,-)) Brmtstrap l-oader

CONFIGURING THE FIRST STAGE

The

third and fourth calculations yield

the desired count value and another value,

called

error fraction. The error fraction

value

needed to determine

whether

the calculated

count

value

is feasible, givèn

the clock frequenry

specifiecl in the first calculation.

These

calculations, performed

according

to the size of the value

"fraction"

from the second

calculation,

are as folìows:

If the

value

of "fraction"

greater

than or equal to .5,

count

= INT (temporary value) + 1

error_fraction

= 1

- fraction

If the value of "fraction"

is less than .5,

count

= INT (temporary_value)

error_fraction

= fraction

The fifth and final calculation yields

the percentage

of error that occurs

when

the clock

frequenry is used to

generate

the baud rate, as follows:

EÒ error

= (error_fraction

/ count)

x 100

lÎ the

7o error

value

is less than

3, then the calculated count

value

is appropriate, and the

desired baud

rate

will be

generated

by the specified

clock frequenry. However, if the 7o

error

value

is 3 or greater, you

must do one

or both of the folJowing:

. Provide a higher

clock frequency

. Select a lower baud

rate

After choosing one

or both of these options, go

through the series of computations again to

get

a new

"count" value

and to

see

whether

the revised value

"lo error" is less than 3.

Continue this process until the "7o

errorn

value

is less than 3.

The

%SERIAL CHANNEL macro can

generate

the following error

messages:

ERROR

- invalid port delta for the (ser_type) Serial Device

ERROR

- <ser_type> is an lnvalid Serial Channel type

ERROR

- Invalid port delta for the Baud Rate Timer

ERROR

- 8253/4 Baud Rate Counter is not 0, 1or 2

ERROR

- Counter 2 is the only valid 80130 Baud Rate Counter

ERROR

- 80186 counter counter,type is not a valid Baud Rate Counter

ERROR

- <counter type> is an invalid Baud Rate Tirner cype

ERROR

- Counter 0 is the only valid 82530 Baud Rate Counter

IIRROR

- 825J0 channel must be specified as A or B only

ERROR

- Max Baud Rate Count must be sreater than 1

Bootstrap

lnader 3-23

CONFIGURING THE FIRST STAGE

3.2.14 %DEVICE Macro

The VoDEYICE macro defines a device unit from

which

your appÌication system can be

bootstrap loaded. If the BS1.A86 or BS1MB2.A86 file contains multiple

ToDEYICE

macros, their order in the

file is

the order

which

the first stage searches for a ready

device unit.

All, ToDEYICE macros that select device units on the same controller must be listed

consecutively in BS1.A86

or BSlMB2.A86, or assembly errors

will

occur. Recall that

multiple

%DEVICE

macros may be included only if the

VoAUTO or ToMANUAL macro

is included (otherwise, an

error occurs during the assembly of BS 1.,486 or 8S1MB2.A86.1.

The syntax

of the

ToDEVICE

macro is

ToDEVICE(name, unit, device$init, device$read, unit info)

where:

name The

physical

name of the device, not enclosed

quotes

or between

colons. This is the name that you would enter

to speciry this device

when

invoking the Bootstrap

Loader from the keyboard.

(However,

when

invoking the Bootstrap Loader, you would

surround this name

with

colons.)

After the

Bootsîrap Loader loads from a device,

passes

the physical

name of îhe device,

as listed here, to the

load file. To enable the

Operating

System's Automatic

Boot Device Recognition

capability (see

Appendix

A) to function, this physical

name must match a

device-unir

name for the device as specified

during the confìguration

of the

Operating System.

Refer to the Interúctive

Configuration Utílity

Reference Manual for

more information about

configuring the

Operating System.

The number of this unit

on this device. Unit numbering is the same

that used for devices by

the Basic I/O System.

Refer to the

Device

Diver User's Guide îor

more information about

unit numbering.

The name of the

device initialization procedure

thar is part

of the first

stage device

driver for this device-unit.

Before attempting

to read from

the device-unit,

the Bootstrap Loader calls

this

proce<.lure

perform

initialization

functions. If the device-unit

has an

Intel-supplied device

driver,

specify the name

of the device initialization

procedure as

listed

Table 3-1. Ifyou supply your

own driver

(written

as described

Chapter

5), enter the name of the

initialization procedure.

unrt

device$init

3-24 Bootstrap lr}ader

device$read

unit info

TabÌe 3- l lists the names of the device initialization and device read

procedures

for Intel-

supplied

first

stage device drivers.

Table 3-1 lists hoth

specific

and

general procedures for the iSBC 208 and MSC

devices.

Configurations of the Bootstrap Loader that use

the general

version

either driver

will be

larser.

CONFIGURING

TIIE FIRST SI'ACE

The name of the device read procedure that is

part

of the first stage

device driver lbr this device-unit. To read from this device-unit. the

first and second stages of the Bootstrap Loader call this

procedure.

your

Bootstrap Loader uses a

generic

third stage, it too uses this device

read

procedure

to read liom the device unit. If the device-unit has

Intel-supplied device

driver, specify

the name of the device read

procedure

as listed in

Table 3-

1. If you supply your own driver

(written

as described in Chapter 5), enter the name of the device read

procedure.

An ASM8ó label that marks the location of an array of BYTEs

containing specific device-unit

information

required by the mass storage

device defined by

this invocation of

the

ToDEVICE

macro.

This

parameter

is currently used only by the SCSI device driver. Ifyou

include it for any other device, the Bootstrap Loader

will

fail to load

your application from that device. Refer to the

"First

Stage Device

Driver Files" section of this chapter, under the

clescriptions of the

ToSCSI

and

9iSASl UNIT INF'O macros

for information about how

ancl

when

to specify this unTt information and for

examples of its use.

Table

3-1. I'rocedure Names for Intel-Supplied l'irst Stage

Drivers

Dsvice

Drivor Device lnilialize

Procedure Device Read

Procedure

iSBC

208

Specifìc

Driver

iSBC 208

General

Driver

|SBC MSC Specific Dr

ver.

iSBC MSC General Driver

SCSI

Driver

iSBX 218A Driver

iSBC 224A Driver

iSBC

251 Driver

iSBC 254 Driver

iSBC 264 Driver

deviceinit20S

deviceinit20Bgen

deviceinitmsc

deviceinitmscgen

deviceinitscsi

deviceinil2lSA

deviceini1224A

deviceinit25l

deviceinlt254

deviceinlt264

deviceread20S

deviceread20Sgen

devicereadmsc

devicereadmscgen

devicereadscsi

deviceread2'18A

deviceread224A

deviceread25l

deviceread254

deviceread264

The MSC drivers support the iSBC 214, iSBC 215G, |SBC 220 controllers,

as well as the iSBX 218A

controller

mounted

on the iSBC 215G board. The drivers

must be reconfigured to support the

iSBC

220 controller.

Bootstrap l-oader 3-25

CONFIGURING

THE

FIRST

STAGE

One difference

between the two

versions of these device

drivers is that the

general

versions

will bootstrap load applications

from any

of the standard types of diskettes

as defined

the Installation Systems.

The specific

versions

will

bootstrap load applications

only from

specific types of diskettes listed

in Tables 3-2 and 3-3.

These tables apply to the

specific

versions

of both

the iSBC 208 and MSC

device drivers.

The Intel-supplied BSl.A86 and BS1M82.A8ó configuration files include

%DEVICE

macros for all

of the supported

devices, and

include multiple

instances of some of the

macros to indicate multiple units on the same device. It doesn't hurt to include support for

all of these devices,

even if

your application

system

won't

contain

all

of them. And if you

add a new device later, you'll be able to boot from the device

without

generating new boot

PROM devices. However, you can reduce the size ofyour Bootstrap Loader by excluding

support for devices that

you

never intend to use. Release 3.2 of the iSDM monitor

provides space

from 0FE400H

to OFFFTFH

for use by the Bootstrap Loader. This

requires you

choose only the devices

you

need

when you

reconfigure the Bootstrap Loader

will

fit into the space allocated by the iSDM monitor. If the Bootstrap Loader does

not fit into the space allocated by the monitor,

you

must locate it below the monitor.

To exclude a device driver

from

the

Bootstrap Loader, two steps must be

performed.

First,

exclude

all the

ToDEYICE

macros in BS1.A86 or BS1M82.A86 that apply to device units

on that controller. To do this, edit BS1.A86 or BS1MB2.A86 and replace the percent sign

(7o)

in îr<tnt of the

macro

with

a semicolon

(;). The edited

version

of such a macro

would

look similar to:

;device(ba0,

0, deviceinit264, deviceread264)

Table 3-2. 525-Inch

Diskettes

Supported

by iSBC

208

and

MSC-Specilìc Drivers

Seclor Size Density Seclors Der

Track

256

256 Singl€

Double

NOTE: The diskettes can be formatted

with

either

48 tracks

p€r

inch or

tracks

per

inch, and

can b€ either single- or doubl€-sided.

Table

3-3.

8-lnch Diskettes Supported by

iSBC 20E

and

MsC-Specific Drivers

Sector Size Density Seclors o€r

Treck

128

2s6 Singl€

Double 26

NOTE: lhe diskettes may be either single- or double-sided.

3-26 Bu)tstrap l-oader

CONFIGURING THE FIRST

STAGE

The semicolon

replacing

the percent sign

turns the

EIDEWCE macro for the iSBC

264

driver

(in

this caseì into a

comment.

Second,

edit the file BSl.CSD

as described

later in this chapter.

3.2.15 %END

Macro

The

%END macro is

required at the end

of the 851.A86

or BS1MB2.A86 file. The syntax

of this

macro is

%END

There

are no parameters

associated with

the

ToEND macro.

3.3 BSERR.A86

CONFIGURATION

FILE

The BSERR.A86

file, shown

in Figure 3-3, defines what

the first stage of

the Bootstrap

Loader does if it cannot

load the load

file.

name bserr

ìlncluoe (

tI:bserr.lnc)

;console

;

rexr

Ílist

;agaln

;

intl

lnt3

;halt

lend

Figure

3-3. First Stage

Configuration File BSERR.A8ó

The BSERR.A86

file consists

of an INCLUDE statement

and

several

macros. The

BSERR.INC

file in the INCLUDE statement contains the definitions

of the macros in the

BSERR.A86 lile.

The following sections

describe the functions

of the macros in the BSERR.A86 file. For

each

macro, ifa percent sign

(7a) precedes the name, then the

macro is included

(invoked).

If a semicolon (;) replaces

the percent sign, then the

macro is treated as a comment and is

not included.

Bootstrap Inader t_r1

CONFIGURING

THE

FIRST

STAGE

The

first three macros, ToCONSOLE,

ToTEXT,

and

a/oLIST,

determine

what the Bootstrap

Loader displays at the console

whenever a bootstrap

loading error occurs.

The other

four

macros,

%AGAIN, 7olNT1, %INT3,

and ToHAIJT,

determine

what recovery steps,

if any,

the Bootstrap Loader

takes

whenever

bootstrap loading error

occurs. Only one

of the

latter

three macros can be included

in the BSERR.Afì6

file.

3.3.1

%CONSOLE Macro

The

%CONSOLE

macro

causes the Bootstrap Loader

to display a brief message

at the

console

whenever a bootstrap loading

error occurs. The message indicates

the nature

the error

(see

Chapter 7 for the

message list).

The syntax of the

%CONSOLE

macro

ToCONSOLE

There are no

parameters

associated

with

this

macro.

This ToCONSOLE

macro is completely unrelated to

the

%CONSOLE

macro used in the

BS1.A86 or BS1MB2.A86 file. Be careful not

to confuse them.

3.3.2

"/"TEY[

Macro

T\e VoTEXT

macro is similar to the %CONSOLE

macro in that it causes the Bootstrap

Loader to display a message at

the console whenever a bootstrap loading error occurs.

The

advantage of the

%TEXT

macro is that its messages are longer and more descriptive.

The

disadvantage of the

%TEXT

macro is that it

generates

more code

and

makes

the first stage

of the Bootstrap Loader larger.

The syntax of thr 4TEXT macro is

o/o'IEXT

There are no parameters associated with this macro. Ifyou include the

ToTEXT

macro,

the

%CONSOLE

macro

is automaticallv included-

3.3.3 %LIST Macro

The

ToLIST

macro causes the Bootstrap Loader to display a list of the ready device-units

at the console whenever the onerator enters an invalid device-unit name. You can include

this macro only if you includeìhe

TaMANUAL

macro in the BSl.,486 or BS1MB2.A86 file,

dercribed earlier in this chaoîer.

3-28 Bo0tstrap l-oader

CONFICURING

THE FIRST

STAGE

The

syntax of

the

%LIST macro

ToLlST

There

are

parameters

associated

with

this

macro.

If you

inclucle

the

%LIST macro,

the

T"CONSOLE

and

a/oTEXT

macros

are automaticallv

included.

3.3.4

%AGAIN

Macro

The

%AGAIN macro causes

the bootstrap

sequence

to return

to the

beginning

the first

stage whenever

bootstrap

error occurs.

You should

incluile

this

macro iî

you

include

the

TocoNSoLE

macro

in the

BSERR.A86

file,

either directly

or by

inclutling

the

VoTEXT or o/aLIST

macro.

The

syntax

of the

a/oAGAIN

macro is

o/oAGAIN

Exactly

one

of the

ToAGAIN,

%INTI, 7oINT3, and

o/oHALT

macros

must be

included. or

error

will

occur when

BSERR.A86

is assembled.

3.3.5 o/"lNTl

Macro

The

o/aINTl

macro

ciìuses

the

Bootstrap

Loader

îo execute an

INT I (software

interrupt)

instruction whenever

a bootstrap

error occurs.

This macro

useful for passing

control

to the

D-MON386

monitor.

The iSDM

monitor

does not support

this

macro.

The syntax

of the 4lNTl mlcro is

TaINTl

There are

parameters

associated

with

this macro.

Exactly

one of the

a/oAGAIN,

%lNT1,

7olNT3, and

%HALT macros

must be

included. or

an error will

occur when

BSERR.A86

is assembled.

The

%INTI macro,

as well

as the

7aINT3 ancl

VoHAL^l

macros described

next, are

reasonable

choices

if none of

the

TaCoNSoLE,

E TEXT,

or ToLIST macros

are include<l

in the BSERR.A86

file.

Bu)tslrap

Loader 3-29

CONFIGURING

THE FIRST STAGE

3.3.6

"/"lNT3

Macro

The %INT3

macro causes

the Bootstrap Loader

to execute an INT 3 (software interrupt)

instruction

whenever a bootstrap loading

error occurs.

Ifyou are using the iSDM

monitor,

the INT 3

instruction passes control

to the monitor. Otherwise,

the INT 3 instruction

has

no effect unless

you have placed the address

of your custom

interrupt handler in

position

of the interrupt

vector

table.

The syntax

of the %lNT3

macro is

%INT3

There

are no parameters associated

with this macro.

Exactly

one of the

%AGAIN, %INTI, 7oINT3,

and

ToHALT

macros must

be included, or

an error

will occur when BSERR.A86 is assembled.

The %INT3

macro, as well as the 7oINT1 and %HALT macros, are reasonable choices

none of the

a/oCONSOLE,

To'lEX'1,

or ToLIST

macros are included

in the BSERR.A86

file.

3.3.7

%HALT Macro

The

a/oFIALT

macro causes

the Bootstrap Loader to execute a halt instruction

whenever

bootstrap loading error occurs.

The synt:u

of the

%HALT macro is

TOÍIALT

There are no parameters associated

with

this macro.

Exactly

one

the

TaAGAIN, %lNTl, %INT3,

and

ToHALT

macros must be included,

an error

will

occur

when

BSERR.A86 is assembled.

The %HALT macro, as

well

as the %lNT1 and 7aINT3 macros, are reasonable

choices if

none of the

ToCONSOLE, ToTEXT,

or ToLIST

macros are included in the BSERR.A86

file.

3-30 Bootstrap l-oader

CONFIGURING TIIE FIRST

STAGE

3.3.8

o/oEND

Macro

The

%END macro is required

at the end of the

BSERR.Af,ìó

file.

The

syntax of this

macro is

%END

There are

parameters

associated with

the

TaEND macro.

3.4 DEVICE

DRIVER

CONFIGURATION

FILES

A separate

configuration

file is

included

for each device driver provided with

the

Bootstrap

Loader. These

files are named

8208.A86,

BMSC.A8ó,

8218A.A86, 8224A.A86,

B251.A86,

8254.A86, 8264.A86,

and BSCSI.A86.

Each consists ofan include statement and

a macro

call.

The source

file always

has the form

include( :f

1 :hno<.inc)

Tabno<(

parameters

)

where:

)oo( Either

208, MSC,

218A, 224A,251,254,261,

or SCSI, depending

on the

device

driver.

The

number and type ofparameters

that are included with

the macro

depend on the device

driver.

The parameters

for each macro

are discussed

in the following sections.

Additionally, when

a SASI

controller

board is used with

the SCSI device

driver, it requires

another

macro.

Refer to the

"ToBSCS|

Macro" and

'oloSASI

UNIT INFO Macro" sections

for details

and for invocation

examples.

The <lefault parameìer

vrhies

for the macros in

these sections

are compatible

with

the default parameter values

of the

Installation Systems.

You

should prepare

one of these

files for

each tvpe of device you want

the first stage

of the

Bootstrap

Loader to support.

In most cases,

you can use the Intel-supplied

files. The

following

sections describe

the individual

macros so that you

can make changes to them, if

necessarv.

Bootstrap l-oader J-3r

CONFIGT]RING

THE FIRST STAGE

3.4.1 "/oB2O8

Macro

T\e o/o8208

macro has the form

%B20tl(io_base)

where:

io-base I/O port acldress selected

(umpered) on the iSBC 208

controller board.

The

default invocation of this

macro in the 8208.,486

file rs

o/oB208l

l80Hl

3.4.2

%BMSC

and0/"8,220

Macros

The BMSC.A86 file contains

two macros, %BMSC and

o/o8220.

However,

you can use

only one. lf you

have one

of the drivers listed at the bottom

Table 3-

1, you should

use

the

o/oBMSC

macro. If you have the iSBC

220, you should use the /o8220

macro. Both

macros have îhe form

o/oBxxx

(wakeup, cylinders, fixed_heads, removable_heads,

sectors,

dev_gran, alternates)

where:

xxx Either MSC

220.

wakeup Base address of the controller's

wakeup port.

The remaining

parameters are used to speci! the characteristics of the disk drives. If

the

ToDEVICE

macro

you

used for MSC or iSBC

220 devices in the BSl.,486 or

BS 1M B2.Atl6

file

has

deviceinitmsc (rather than deviceinitmscgen) as its third

parameter,

then all MSC or iSBC 220 drives used by the Bootstrap Loader

must have

the

characteristics listecl in

the

following

parameters. That is, they must have the same

number of

rylinders

per platter,

fixed heads, removable heads, sectors

per track, bytes

per

sector, and alternate cylinders. However, if the TaDEVICE macro specifies

deviceinitmscgen, these restrictions do not apply and the following piìrameters are not

used by the Bootstrap Loader.

cylinders Number of

cylinders

on the disk drive or drives.

fixed_heads Number

of hearls on fixed

platters.

removable_heads Number of heads on removable

platters.

sectors Number of sectors oer track.

3-32 Btlotstrap

lrader

CONFIGURINC THE FIRST STACE

dev_gran Number

of bytes per sector.

alîernates Number

of cylinders set aside as backups

for cylinders

having imperfections.

In the BMSC.A86

file, the

default invocation

of the

%BMSC

macro

ToBMSC( 100H,

256,2,0,9,

1024, 5)

and the

default form of

the uninvoked

7o8220 macro is

;8220(

100H, 256,

Z, 0,

1024, 5)

3.4.3 "/oB218A

Macro

The

7oB218A macro has the

form

7oB2 1 8A(base;rort_address,

motor_fl ag)

where:

base_port_address The base port

address of this device unit, as selected

the iSBX

2l8A controller board.

motor_flag A value

indicating

whether

rhe

motor of a 5 l/4" flexible

diskette drive should

be turned off after bootstrap

loading. Valid values

are:

Value Description

0FFH The drive

will

be turned

off after

bootstrap

loading. Specify this value

only

if this device is not to become the

system

device.

Turning off the drive slows slows

bootstrap

00H The drive

will

not be turned off after

bootstrap

The default invocation of this

macro in the 8218A.Atì6

file is

7"82l8A(80H,00H)

This allows you

to mount the iSBX

2l8A module in the SBX I socket ofyour CPU board.

Bootstrap Lader 3-33

CONFIGURING

THE FIRST

STAGE

3.4.4 "/oB224A

Macro

'Íhe 7oB224A

macro has the form

board id

heads

sectors

o/oB224A

(instance, board_id, cylinders,

heads, sectors, device_gran,

slip$sectors, 7a(reserved))

where:

instance A value

indicating

which iSBC 1861224A controller

the driver should

use if the

system contains multiple iSBC

186/2244 boards. During

initialization the driver

calculates the instance by

rcanning the

MULTIBUS II slots in ascending order and

sequentially assigning

numbers

to each iSBC 186/224A controller

found. For example, I is

assigned to

the

iSBC

186/224A board in the lowest-numbered

slot, and

2 to the iSBC

1861224A in the next-lowest-numbered

slot. This method

of identifying the board

provides slot independence.

A ten-byte

string identifring the board. The board-id is found

registers 2-1'l of the header record in the interconnect

space. For the

ISBC 1861224A

controller board, the board_id is ASCII 186/224A

followed

by two ASCII NULL (0) characters and can be

entered in the

8224A.A86

file using the following form:

186/224AXX

where

'XX' are ASCII NULL (0)

characters.

The following parameters are used for initializing

Winchester

disk drives but not

floppy

disk drives:

rylinders A word speciffing the number of cylinders on the disk.

A byte specifying the number of fixed data heads on

Winchester disk

drives.

A byte specifying the number of sectors

per

track.

device_gran A word specifying the number of bytes per sector for the device.

slip$sectors A byte specifying the number of sectors per track to be used as alternate

sectors

when

bad sectors are found during formatting. This feature is

enabled only

when

the sector-slipping option is used. Currently

sector-

slipping is not supported; therefore, this

value

should be set to zero.

3-34 Bmtstrap hader

CONFIGURING THE

FIRST STAGE

reserved This

parameter

is reserved

for future use. It consists of 10 one-byte

values,

separated by

commas. The

driver uses these bytes

as the last ten

bytes of

the

parameter

buffer it uses to initialize the drive.

For

example, the

iSBC 186/224A

expects rhese ten bytes

to be zero. This

parameter

may be specified

as either

%(0,0,0,0,0,0,0,0,0,0)

a/o(10

dup(0))

The iSBC

186

/224A

device

driver sends

an initialize

command to the ISBC

186/ZZ4A

controlìer, which

uses the preceding values

to initialize the Winchester

disk drive. Then

the

volume

label is read.

If the

volume

label

has

valid

device characteristics,

the drive is

reinitialized with

those characteristics.

Intel assumes

the floppy disks

are in standard

format: track 0 formatted

as 128

bltes/sector,

1ó sectors/track.

The disk

characteristics are read from

the

volume

label and

the

drive is

reinitialized

with

those

characteristics.

The

default invocation

of this macro

in the 8224A.A86 file is

voB224A

('186/224A??"

132H, 4,9, 1024,0,0/Ò(10

dup (O)))

Note,

the characters

'??'

represent two

ASCII NULL characters entered

using AEDIT. To

input an

ASCII NULL character,

invoke AEDIT, position

the cursor on top of the second

single quote

mark,

press

the

key'H'for hex input, press

the key'I'for input,, press the key

'0'

for the value.

After inserting one

ASCII NULLcharacter, enter

a second one.

3.4.5 "/oB.251

Macro

T\e 7oB251macro has the

form

VoB251

(io

_base,

dev_gran)

where:

io_base I/O port address

selected

fiumpered)

on the

iSBX 251 controller board.

dev_gran Page size, in bytes.

The default

invocation of this macro

in the B251.A86 file rs

7oB251

(80H,64)

Bootstrap l-oader 3-35

CONFIGURING

THE FIRST STAGE

3.4.6 o/"B.254

Macro

The %B.254

macro has

the form

VoB254

(io

_base,

dev_gran,

num_boards,

board-size)

where:

io_base I/O port address

selected

fiumpered)

on the iSBC 254 controller

board.

dev_gran Page

size, in bytes.

num_boards Number

of boards

grouped in

a single

device unit.

board_size Number of

pages in one iSBC 254

board.

The

default invocation

of this macro in

the 8254.A86

file is

%8254

(0880H, 256, 8, 204t1)

3.4.7 "/o8.264

Macro

The %R.264

macro has the form

VoB264

(io

_base,

dev_gran,

num_boards, board_size)

where:

io_base I/O port address selected

(jumpered)

on the iSBC

264 controller

board-

dev_gran Page size, in bytes.

num_boards Number ofboards

grouped in a single device

unit.

board_size Number ofpages

in one iSBC 264 board.

The

default invocation of this macro

in the 8254..48ó file is

%8264

(0880H,

256, 4,8192)

3--r6 Bootstrap Lóader

CONFIGURING THE

FIRST

STAGE

3.4.8

%BSCSIMacro

This

macro allows you

specify

the details

of a SCSI

host board, such

as the

iSBC 186/03A,

iSBC

28ól100

or iSBC

286/100A

board,

when

82554

programmable

Peripheral

Interface

component

is used

to implement

the host

interface.

The

ToBSCSI macro

has the

form

ToBSCSl (a_port,

b_port,

cJlort,

control_port,

reservcrl,

reserved,

dma_controller,

dma_channel,

dma_base_address,

dma_separation,

scsi_info,

info)

The

END command

at the

end of this file

is an ASM86 statement

and

it does nor require

where:

ajort The WORD address

of Port A of the 8255

Programmable

Peripheral

Interface

(PPI)

used by this

SCSI driver.

b-_port The WORD

address of Port

B of the 825-5

PPI used by

this

SCSI driver.

cJort The WORD

address of Port C of the lì255

PPI used by

this SCSI

driver.

control_port The WORD

address of

the control word

8255

PPI used by

this SCSI driver.

reserved Reserved

for future

use. It should he set

to zero.

reserved Reserved

fitr future use. lt shoultl

be set to

zero.

dma_controller The type

of DMA controller used.

possible

values

are

Value Controller

Type

01 80186 DMA controller

02 822-5[Ì Advanced

DMA controller

Other values

are

reserved for future use.

dma_channel A BYTE

that indicates which

channel on rhe

DMA

controller will

used. Specify the number

of the DMA

channel

as listed in the appropriate

Intel data sheet.

dma_base_address A WORD

that indicates

the base I/O port address

the cont

roller's registcrs.

dma_separation A BYTE

that intlicates the number

ofbytes separating

consecutive ports

on the controller.

Bootstrap

I,()ader 5-S I

CONFIGURING

THE FTRST STAGE

scsi_info This

parameter

is iSBC-board-specific;

it does not

depend

on the

SCSI driver's

requirements.

This

parameter is a

BYTE

which has the following

meaning:

Value Meaning

o Indicates

that no additional

information

is needed

configure

the BootstraP

Loader

for

the iSBC board

vou

are usinq.

I Indicates

this configuration

of the

Bootstran Loader

is used

on the

isBC 28r;/

lo0A board.

2-255 Reserved for future

use.

info Varies depending

on the

value of scsi_info.

If scsi_info is 0, then

no other information

is needed and

info is left blank.

lf scsi_info

is 1, then ìnfo

is a single WORD that

specifies the

port

address

of the iSBC 286/ 100

iSBC 286/100A

port used for

multiplexing DMA sources

into

the on-board 82258 DMA component.

The SCSI driver can be used

to bootstrap load from any random-access

device on

the SCSI

bus. The

SCSI driver can also be used to bootstrap

load from specific random-access

devices on the SASI bus.

When

using

the SASI bus,

you

must select a

specific device,

because the SASI devices require

unitlue initialization information.

Do this by specifying

unique unit information

for each device on the SASI bus

(the

%SASI

UNIT INFO macro

is used for this purpose).

The

ToBSCSI

macro can be invoked only once in

the

BSCSI.A86

configuration file. The

%SASI_UNIT_INFO

macro

(described in the next section) can be invoked multiple

times

to allow specification of the units on the SASI bus. Refer

to the description of the

TaSASI_UNIT_INFO macro

to see how to speci! unique unit information for devices

the SASI bus.

In the BSCSLA86 file, the default

versions

of the

%BSCSI

macro are

o/oBSCSI(0C8H,

OCAH, 0CCH, 0CEH, 0, 0, 1, 0, 0FFCOH, 2,

;BSCSI(0C8H,

OCAH, OCCH, OCEH, 0, 0,

0, 0200H, 2, l, 0DlH)

The SCSI host board interface defined by the first instance

(which

is invoked) is

the

iSBC 186/03A

board and uses the 80186

DMA controller.

-ì-38 Bfi)tstrap [,oader

CONFIGURING THE FIRST STAGE

The SCSI host board interface defined

by the second instance

(which

is not invoked) is the

iSBC

286/100 or iSBC 286/100A MULTIBUS

II board

and uses the on-board 82258

Advanced DMA controller. If you

want

to invoke this board, replace the

";" with

"Vo",

and

replace the "To" with a

";"

to comment out the

interface defined

the first instance

(iSBC

186/03A board using the

80186 DMA controller).

An important feature

to note about devices that use an SCSI controller is the configuration

information

is device-independent. That is, only the

host

board interface to

the controller

needs

to be specified in the configuration

file. The configuration

values

contain no

information about the device(s) actually

being used.

3.4.9

%SASI_UNIT_INFO

Macro

The SCSI device driver provides an

interface to mass

storage devices through either SASI

or SCSI

controllers, If using devices controlled by a SASI controller, you must speci$ a

sequence of initialization bytes for the controller.

This information

not required

by SCSI

controllers. The initialization sequence

identifies the type of device

you

have assigned

the

particular

unit of the SASI controller.

The

sequence will be different depending on the

manufacturer and model of the

hard disk or flexible diskette drive. and the manufacturer

and

model of the SASI controller board itself.

This

macro

enables you

to define the initialization sequences required by

your

devices on

the SASI bus.

For each instance of the

ToDEVICE

macro (in the BSl.,486 or

BS1MB2.A86 file) that defines a device

on the SASI bus,

you

must also include

the

%SASI UNIT INFO macro

(in

the

%BSCSI.A86 file) to define

that device's initialization

r.qr"nJ". The label specified

for

the

unit info field of the

%DEVICE

macro must

match

the label

field of the corresponding

%SASI_UNIT_INFO

field.

The information supplied by an occurrence of

the

%SASI

UNIT INFO macro

is not used

by devices on the SCSI

bus. Therefore in the 851.A86 o. SStlr4g2.aaO file,

ToDEY\CE

macros for devices controlled

by the SCSI bus should never speciff a

value

for the unit info

parameter.

Note that there is only one pair of device

initialization/device

read procedures

for the

SCSI driver regardless of

whether

the controller is SCSI or SASI.

The

%SASI

UNIT INFO macro

can be included only in the SCSI/SASI

driver

conficuration

file. BSCSI.A86. The macro has the form

%SASI_UNIT_INFO

( label, init_command, init_count, init_data

)

Bootstrap l-oader 3-J9

CONFIGURING

THE FIRST

STAGE

where:

label

init_command

init_count

init data

The default invocations of this macro

BSCSI.AIì6

are

A valid

ASM86

labcl name matching

the one

you

specified in the unit info field

of the

%DEWCE macro

for

your device (in the file BS1,A86

or BSlMB2.A86).

A WORD

that is the

initialization command for

vour

particular SASI controller.

A BYTE

specifing the number of initialization

BYTEs

that your SASI controller requires.

The array of BYTEs of initialization data required

your SASI controller. The length

this

array must be

equal to the

value

in the init

count parameter.

: iSBC L86/03A SCSI Host

Zbscsl( 0c8H, 0cAH

, 0ccH

, 0c8H

, 0

, 1, 0, OFFCOH, 2, 0)

i iSBC 286/100 SCSI Host

;bscsi( 0C8H, oCAH, 0CCH, OCEH, 0, 0, 2, 0, 0200H,

2, 1, ODlH)

; Xebec Sl-420 SASI controller and e Teac rnodel F558, 5 1/4-inch

; flexlble dlskecte drlve.

lsasi unit info(sasi x142Ornf

, l1h, 10, 0,

28h,

2, 90h, 3, 0fh,

50h,

Ofh, 014h, 0)

; Xebec 51,410 SASI controller and a Quantum

rnodel

Q540, 5 1-/4-inch

i l,linches ter disk drlve.

Zsasi_unit_info(sasi_x1410b, Och, 8, 2, 0, 8, 2, 0, 0, 0, 0bh)

;

; Xebec S1410 SASI controller and a Computer Memories, Inc.

; model CMI-5619 5 1/4-inch Wlnchester

disk drlve.

lsasi_unit_info(sasí_x140a,Och,8, 1, 32h, 6, 0, 0b4h, 0, 0, Obh)

3.4.1 0 User-Supplied

Drivers

Ifyou want

to bootstrap

load

your system

from a device other than one for which Intel

supplies a first stage device driver, you

must

write your

own device initialization and device

read device driver procedures that the first stage will

call. Chapter 5 describes how to do

this. In addition, perform the

following

actions

to add the procedures îo the Bootstrap

Loader:

. Specify the names

of the device initialization and device re:rd procedures in a

ToDEYICE macro in the BSl.,486 or BSlMB2.A8ó file.

3-40 Bq)tstrap l-oader

CONFIGURING

THE FIRST STACE

. If there are configurable parameters

associated

with your

device

(such

as base

addresses or

wakeup

ports), you

might

want

to create

your

own configuration macro

and

include it in a special configuration

file,

just

like the Intel devices do. Chapter 5

describes

how to set up a macro.

. Assemble

your

device initialization procedure, your

device read

procedure, and your

configuration file

(if you

have one),

and link the resulting object code to the rest of the

Bootstrap Loader object files and

libraries.

3.5 GENERATING THE FIRST

STAGE

The submit

file BSl.CSD

performs

the

assembly, linkage, and location of the first

stage of

the

Bootstrap Loader. Often it

will

need

to be modified to

generate the particular

configuration of the Bootstrap

Loader

you

specified in BS l.A8ó or BS 1MB2.A86. Figure

3-4 shows commands in the Intel-suonlied

BS 1.CSD file.

Burtstrap llader 3-41

CONFIGURING

THE FIRST STAGE

attachflle $ as :fl :

The next four lfnes rnust

be used to generate the Bootstrap Loadèr on

iRMX lI. The tRìO( 11 Updates supply the MPL286

utility.

npl286 : fl:12. a86 $obJect(:f1

:l2.mp1)

mp1286

fl :bserr.

a86

$object(:fI:bserr.mpl)

asn86 :f1 :f2.mp1 rnacro(90)

object(:fl :X2.obj) print(:f1 :U2.lst)

asm86

fl:bserr.mpl rnacro(50) object(:f1:bserr.obj) print(:fl:bserr.lst)

The

iRMX

four

the

next tr^Ìo lines must be used to generate the Bootscrap Loader on

86. No invocation of MPL286 is required. Comment ouc the previous

lines by insertlng a';' in front of the line. Renove the ';' frorn

front of the nexÈ tr.ro lines if generating on iRl'D( 86.

;asn86

:fl:12.a86 macro(90)

object(:f1

:Z2.obj) prÍnt(:f1 :12.lst)

;asn86

:f1:bserr.a86 nacro(50) object(:f1:bserr.obj) prinr(:fI:bserr.lst)

asm86

asn86

asm86

fl :b208 .

a86

fl :brnsc . a86

fl :b218a.

a86

:b251 .

a86

fI:b254 . a86

f1 :b264 . a86

fl :bscsi.a86

macro

(

50)

macro

(

50)

macro

(

50)

maero

(

)

rnacro

(

50)

macro

(

50)

nacro

(

50)

object(

obj ect (

object(

fl:b208.lst)

fl :

bmsc

. ls t)

fl :b218a.Ist)

f1 .|.aql r -+\

LL.WLJL.LJL)

rÌ.uZJ+.1-5L,,

f1:b264.1st)

f1 :b208 .

obj

) print (

f1 :brnsc .

obj

) print (

fl :b218a. obj

) print(

f1 'h?51 nhi \ nYínr-i/

f1 :b2 54 . obj

) princ(

f1 : b264 .

obj

) print (

f1 hcnci nhi \ nrintt/

3-42

Figure

3-4. First Stage Confìgurat

ion

File BS I.CSD

Bmtstrap Loader

CONFIGURING THE FIRST

STAGE

; l,îultibus II conflgurarÍon

;

;asn86:fl:b224a.a86 rnacro

(

50)

link86

fL:7"2.obj

f1 :

bserr .

obj ,

f1 :bcico. obj,

fl :b208

obj ,

fl :bmsc . obj ,

:b2l8a.obj,

fl .hts1 ^hì

f1 :

b264

. obj ,

f7:b224a

obl

f1 :bscsi. obJ

f1 :bs1.1ib

to :

lI:22.

1nk

print(:fl:u2.mp1)

&nopublics except(firststage, &

firststage_l86, &

Renove the 'ó' from the beginning of

iAPX 186 INIT macro is invoked in the

boots trap_entry )

no ini tcode

^È--rtC:

rL4!!\rr&>u5LdÉY,

& Change the previous

& iAPX_186_INIT rnacro

&segs

iz e

(boot (

1800H

) )

obj

ect(: fl: b224a. obj

) print(:f1:b224a.1sÈ)

& ;for standalone serial channel support

the previous line if

configuration fi1e. the

loc86 : fl :22 .

lnk

addresses(classes (code (0%0),

stack(021) ) )

order(classes (stack, data,boot, code, code error) )

line to 'start(firststage_186)' if the

is invoked in the configuration fí1e.

Figure

3-4. First

Stage Configuration File BSI.CSD

(continued)

3-43

Bootstrap

lrader

CONFIGURING

THE FIRST

STAGE

map

princ(:

fl:12.mp2) &

;bootstrap

Remove Lhe';' froru the line ':bootstrap' when generating a

a standalone Bootstrap Loadèr ín PROM for a 80286-based

CPU

board.

Do not rernove the ' ;' if uhe BooEstrap Loader ls beÍng generated

for an 80386-based CPU

board.

Bootstrap Loader fÍrst stage generation conplete.

Figure

3-4. First Stage Configuration

File BSI.CSD

(continued)

3.5.1

Moditying the BSl.CSD

Submit

File

To generate your own version

the

Bootstrap Loader first

stage, there are several

changes you might need to make.

First, ifyou have excluded any device drivers from the Bootstrap Loader

(by

excluding

TaDEYICE macros from the BSl.A86 or BS'lMB2.A86 file), you

won't

ìvant to link the

code for those drivers into the the first stage. To prevent the linking of a device driver, edit

the LINKSó command in the BSI.CSD file and place an ampersand (&) in front of any file

name that corresponds to a driver you want to exclude. Figure 3-5 is an example that

shows a portion

of the BSl.CSD file after excluding the iSBC 208, iSBX 218A, iSBX 251,

iSBC 254 and SCSI device drivers.

3-44 Bmtstrap l-oader

CONFIGURJNG THE FIRST

STAGE

Figure

3-5. Excluding

the iSBC

251

and

iSBC 254

Drivers

NOTE

If you

exclude a

dcvice driver,

do NOT include

any

%DEVICE macros for

it in

the BSl.A86

or BS

I lt{82.A86

configuration

file or errors from

LINK86

will

occur.

Also,

you

are not using

an iRMX I or iRMX II system

to configure

the Bootstrap

Loader, you

must comment

out

the command

attaching the directory where

the Bootstrap

Loader

files reside

as the logical

name :F1:.

Change the

line:

ATTACHFILE

$ AS :Fl :

;ATTACHFILE

$ AS :F1 :

3-45

1ink86

f1 :12.obj,

fl :bserr. obJ

f1 :bcico.obj,

f1 : b208

obj ,

f1 :bnsc

obj ,

fl :b218a

obJ

fl :b25l.obj,

fl : b254

obj ,

fl :

b264.

obj ,

f7:b224a

. obj

:bscsi. obj,

fl :bs1.1ib

fl: l2.lnk print (:

fl: 22 . urpl) &

& ;

for s tandalone

serial channel support

&nopublics except

(f irststage,

firststage_l86, &

Renove the '&' from the beginning of the previous line if Èhe

iAPX_186_INIT

rnacro

is invoked in rhe configurarion file.

Bootstrap

l,oader

CONFIGURING THE FIRST STAGE

3.5.2

Invoking the

BSl.CSD Submit

File

After

you

have modified

the BSl.CSD file

to correspond

to your configuration,

invoke

the

submit

file to assemble

the Bootstrap

Loader files, link

them together,

and assiglt

absolute

addresses. The format

for invokins

the submit file is

as follows:

ATTACHFILE /RMX286/BOOT

SUBMIT BSl(first-stage_address,

second-stage-address.

Iirst-stage-fi1e)

where:

first_stage_address The starting address

of the first stage

of the Bootstràp

Loader. This can be

a RAM address ifyou intend to run

the Bootstrap Loader from

RAM, or it can be

a PROM

devices address if

you

intend to

place

the Bootstrap

Loader

into PROM devices.

The address

you

specif

should be a full 20-bit address.

Do not use the

base:offset form

to indicate the address.

The iSDM

Release 3.2 monitor

allocates the address range

from

0FE400H to 0FFFTFH

to the Bootstrap Loader.

Ifyour

configuration

of the Bootstrap Loader

will not fit in this

space,

locate it at a lower address than FF8000H.

The

address in RAM where the second stage of the

Bootstrap Loader

will

be loaded. The data

area for the

first

and second stages is also located here.

The size of

this second

stage area consists of less than 8K

contiguous

bytes. The

default address for the second stage

0B8000H. This address has been chosen to

compatible

with

the default address

of the third stage

which is 0BC000H.

The first-stage configuration file to use. lfyour system is

a MULTIBUS I system, set this parameter equal

to the

string'bs1'. Setting this

parameter

'bs1'causes

the

located Bootstrap Loader file to be named'bs1'.

Ifyour

system is a MULTIBUS II system, set this

parameter

equal to the string'bslmb2'. Setting this

parameter to

'bs1mb2'causes

the located Bootstrap Loader

file to be

named'bs1mb2'.

second_stage_address

first_stage_file

3-46 B(x)tstrap

l-oader

To invoke

the

BSl.cSD

SUBMIT

file with

the default

addresses

for combining with

the

iSDM

monitor,

type one

of the two

sets

of commands

below:

3.6 MEMORY

LOCATIONS

OF THE FIRST

AND

SECOND

STAGES

when you

invoke the

BSl.csD file, you

assign

memory locations

to the

first and secon<l

stages.

It is important

that

îhe addresses you

assign do not

cause the stages

to overlap,

either with

themselves

or with

the files

they load.

Chapter 4

discusses

the memory

locations

of all

three stages

of the

Bootstrap

Loader

and the

stcps to take

to ensure that

they

don't

overlap.

Also

inspect

the map

file, BSl.Mp2,

ensure the segments

are

properly

laid out. If too

many device

drivers

have been

confìgured

into the Bootstrap

Loader, some

segments

will

be located

low memory

starting at

200H.

This is

unacceptable

and

you

must remove

some

more device

drivers from

vour

confisuration.

CONFIGURING

THE FIRST

STAGE

Bootstrap bader 3-17

CONFIGURING CHAPTER

THE

THIRD

STAGE

4.1 INTRODUCTION

The third

stage

of the Bootstrap

Loader is used

only

for loading iRMX lI sysrems.

provides

the

capability

of loading

modules

that usc

the 80286 object

motJule

formar (such

those produced

using

BND286

an<J

BLD2[ì6)

and those that

require the processor's

protected

virtual

address

mode. This

chapter

describes

how to configure

the third

stage.

There

are two different

tipes

of third

stages that

can be used

to load iRMX ll files:

the

generic

third stage

and the device-specific

third stage.

Both load

OMF-28ó

modules, but

the generic

third

stage leaves

the processor

real address

mode

while

it loads. This

permits

it to use the

first-stage

device drivers

to access

the storage devices.

The

device-

specific

third stage

switches

the processor

into

protected

mode before

calling the device

driver.

Although

this permits

the device

driver

to load into

the entire

l6 megabyte arJdress

space,

special

device drivers

that work

protected

mode

must be included

in the third

stage.

configuration

the third stage

differs

slightly

depending

whether

you

configure the

generic

or device-specifìc

third

stage.

However,

the differences

are small

enough that both

will

be described

together

throughout

most of

this chapter.

The next two sections

pnrvitle

overviews

configuring

each

type of third

stage.

The rest of the chapter

provides

thc

details

of third-stage

configuration,

noting

any options rhat

apply specifically

to one

type of

third

stage.

4.2 OVERVIEW

OF THIRD

STAGE

CONFIGURATION

configuring

the third stage

(either

the generic

or device-specific

third

stage) is very

similar

to configuring

the first stage.

It involves the

following

operations:

Ì. Editing an assembly

language

source

file

to intiicate

which

CPU board to

run on ancì

what

to do

if errors

occur during

bootstrap

If you

are using the

<ìevice-

specific third

stage, you

must also

indicate which

devices the

third stage supports.

Invoking a

SUBMIT

file to assemble

one or more assembly language

source files,

link them with

code

for the third

stage, and

assign absolute addresses

to the code,

This executable

module

remains

in a file to be loaded by

the second stage.

Bootstrap

l,oader 4-t

CONFIGURING

THE THIRD STAGE

the iìrst stage,

the device-specific

third

stage requires

its own

device drivers.

l'herefore,

you

might

expect

to modiff, assemble,

and link

configuration

fi-les for each

the

devices,

just

as you do for the

first stage.

Actually, the

SUBMIT file

does assemble

and

link the device

configuration

files, but

you don't need to

do any additional

work on these

files. Because

device-specific

information

(such as the I/O port address, the

number of

cylinders,

etc.)

is the same regardless

which stage accesses

the device,

the SUBMIT

file

uses the

same device configuration

files

used for first-stage

configuration.

The

generic third stage

uses the

first-stage device

drivers to communicate

with

mass

storage

devices. Therefore

there

is no need to

supply configuration

information

about

devices to

the generic third

stage.

Default

versions of the assembly

language source

files and the SUBMIT

file are

placed in

the

/RM)086/BOOT directory during

installation. These

files include the

following:

853.A86 These

assembly language

source files contain

macros that

specify

BS3MB2.A86 the devices

supported by

the third stage

(for

device-specific

third

BG3.A86 stage

only), identify

the CPU board, and

indicate

what

do if

errors

occur during bootstrap

loading. The 853.,486

file applies

the device-specific

third

stage for MULTIBUS

I systems, the

BS3M82.A86 file

applies to the device-specific

third stage for

MULTIBUS Il systems,

and the BG3.Alì6 fiìe applies

to the

generic

third

stage on either

MULTIBUS I or MULTIBUS

II systems.

These

assembly language source

files apply

just

to the

device-

specific third

stage. They contain configuration

information

about

the

devices

your

system. These

are the same files that

were used

during the configuration

of the first stage. You

do not need to

modify them for

the device-specific third

stage.

These

SUBMIT files contain

the commands needed to assemble

the

source files,

link the resulting moduÌes

(and

any other

you supply)

with the code for the third stage, and locate

the resulting object

module. The BS3.CSD

file applies to the device-specific

third stage,

while

the BG3.CSD file

applies to the generic third stage.

BMSC.A86

B264.Atì6

BS3.CSD

BG3.CSD

As shipped on the release diskettes,

these files are set up to

generate

the default

versions

of the Bootstrap Loader's device-specific

and

generic

third stages.

4.3 8S3.A86, BS3M82.A86,

AND BG3.A86

CONFIGURATION

FILES

Figures 4- 1, 4-2, and 4-3 list the assembly

language configuration files for the

device-

specific third stage files BS3.A86 and BS3M B2.AlÌ(r

and the generic third stage file

BG3.A86. Each of these files consists

of an INCLUDE statement and several macros.

The

definitions of the macros that can

appear in these files are contained in the INCLUDE file

(BS3CNF.INC). These macros

are similar to the macros that can appear in the

first stage

confisuration file.

4-2 Brntstrap l,oader

CONFIGURING THE THIRD

STAGE

configure your

own version

of the generic

device-specific

third

stage,

you

should

etlit

the

BS3.Atl6,

BS3MB2.A86,

or BG3.A86

file to include or exclude macros.

For each

macro,

percent

sign (7o) preceding

the name

includes

(invokes)

the

macro, ancl a

semicolon

(;)

preceding

the

name

excludes the

macro,

treatinc it as

a comment.

NOTE

When

you

exclude a

macro, you

must

replace

the

percent

sign with

semicolon.

Don't

just

add a semicolon

in front

of the percent

sign.

The following

sections

describe

the

macros

thar can

appear in the

853.A86, BS3MB2.A|ìó,

and

BG3.A86

files. Unless

otherwise

specified,

the macros can

appear

in either of the

three

files

(the

%DEVICE

macro

is the only

one that applies

just

to the

device-specific

third

stage).

Figure 4-1.

Intel-Supplied

B53..486 File

bs3

rnc

lude (

:il:bslcnf. inc)

lrncluoe (

tI : rrmps. tnc)

ldevice (

device lni tms

gen,

device readmsc gen

data_ms

)

Xdevice (1,w1 ,

device ini tms cgen

device readms

c gen, data_rnsc

)

Zdevice (

wfO

device íni trns cgen, devicere adrns c

gen,

da ta_rnsc

)

ldevice (9, wfl, device initnscgen, devicereadmscgen, data_nsc)

ldevlce (0,s0,devicelnitscsi, devicereadscs

i ,

data_sc s

i )

Zdevice (0,sx14l0a0,deviceinitscsi,devicereadscsi,data_scsi,sasi_x14t0a)

ldevice (0,sx14l0b0,deviceinitscsi,devicereadscsi,data_scsi,sasi_xl410b)

U device (2, srnf0, deviceinitscsi, devic e readsc s i, data_scs i ,

sasi_xL42Ornf)

Ídevice (

prnfO

devÍce ini t218Agen, deviceread2lSAgen, da ta_218 )

Zdevice (0,ba0,deviceinit264, deviceread264,data 264)

;intl

U int3

;halt

Scpu*board (286

/12)

Xena

Multibus I devic e s

Bootstrap

Loader 4-.1

CONFIGURING THE THIRD STAGE

name bs3

include (

:f1 :bs3cnf.

inc)

;

; MPC and ADMA confíguratíon for isBC 286/100 wlth iEXM 100 MPC

module

;brnps

(00H, 4, 08BH, 200H,

3, 2, 0A0H, 16)

;

; MPC and ADMA

configuration for iSBC 2861100A

;brnps(00H,

4, 088H, 200H,

2, 3, 0E0H, 16)

; UfC rna AD!4A conflguration for iSBC 386/100

Tbmps(00H,4,089H, 200H, 2, 3, 000H, 16)

ldevice (0

Zdevice (0

%device (0

iidevice (2

%device

(0,

% devi ce

(

I ,

% device (

device (

;int1

% int3

;halt

%cpu_board

(386/100)

% end

;;;;;;;;;;;;; ;;;;;;;;;;;;;

;;; ;;;iiiiii;i;i;i;;;;,,,

Multibus II devices

; i , ,

i ,

i ; ; ;

;

; ;

;

; ;

;

; ; ;

; :

;

: :

;

: :

i;;;;;

s0,devÍceinitscsí . devícereadscsi,data_scsi)

sx1410a0

devicei-nitscs i, devicereadscsi, data_scsi, s as i_x

1410a

)

sx1410b0

deviceinitscs i, dev i ce readsc s i ,

data_scsi, s as i_x1410b

)

smf0, devíceinitscs i, devicereadscsi, data_scs i, sasi_x142Ornf

)

w0, device_in it_224a , dev ice_read_2 24a

, data_bs_drivers)

,,1 .1-,,i^^ i^it ))/,- è,ò.'i-^ -^.A 1at,- .1.1- h- .ìrirrorcì

wfO, device_inix_224a , devi c e_read_2

24a

, data-bs_drivers)

,,€r ,^,,i-^ í-iÈ îra^ À^,.i-^ r^-.1 11/,- .r-r. h. àrirrarc\

Figure 4-2. Intel-Supplied BS3MB2.Atl6

File

4-1 Bootstrap

[-oader

CONFIGURING THE THIRD STAGE

name bg3

$include (:

fl :bs3cnf.

inc)

;

lntl

ínt3

;halt

Xcpu board 1286/12)

9:-^!^t ! ^!: ^- /- \

! !r> rd r r d L ru rr

\ r r./

lend

Figure

4-3. Intel-Supplied BG3"{8ó

File

4.3.1

o/"BMPS

Macro

(MULT|BUS@

il Onty)

The

ToBMPS macro configures the message passing system

used during bootstrap loading.

This macro identifies

the base address of the

Message Passing Coprocessor

(MPC),

address

distance between

MPC

ports,

and information

that defines how direct memory

access (DMA) transfers

occur.

The syntax

of the ToBMPS macro ls

%BMPS (mpc$base$addr,

port$sep,

duty$cycle, dma$base$addr, dma$in, dma$out,

dmagtrans,

datagwidth)

where:

mpc$base$addr The base I/O port address of the MPC. Refer

to the

appropriate single board computer user's guide for this

address.

port$sep The number of addresses separating individual MPC

ports.

For example, if the mpc$base$addr is 0000H and

the next three l/O port

addresses are 0004H, 0008H,

and 000CH, respectively, the

port$sep

is 4H. Refer to

the appropriate single board computer user's

guide fbr

the

I/O port address map.

Bootstrap [.oader ,l-5

CONFIGURING

THE

THIRD

STAGE

duty$cycle The MPC

duty cycle for

the local bus.

(The rate at

which data packets

are

generated.)

For information

how

to calculate a duty

cycle suitable for

the local

bus,

refer

to the MPC

User's Manual. For duty

cycles

suitable for Intel

singie board computers,

refer

to the

appropriate

single board computer

user's

guide.

dma$base$addr The base I/O port

address for the Advanced

Direct

Memory Access

(ADMA) controller.

Refer to the

appropriate

sing.le board computer

user's

guide

for

this

address.

dma$in The channel used to

receive

(input)

DMA message

passing

transfers. Refer

to the appropriate

single board

computer user's

guide for this channel number.

dma$out The channel

used to send

(output) DMA message

passing

transfers. Refer

to the appropriate

single board

computer

user's guide for this channel

number.

dma$trans The I/O port

address used for DMA data transfers.

Refer to ihe approprint.

single board computer

user's

guide

for

this address.

data$width The

data width in bits of the local

bus. This

value

must

be eìther l6 or 32

(decimal). If the

width

set to 32 bits

on a 386/116- or 386/

120-basetJ board, flyby

(one cycle)

mode is enabled.

The

ToBMPS

macro can

generate errors

the local bus width is not l6 or 32 bits

wide.

4.3.2 %OEVICE

Macro

(853.A86

and

BS3M82.A86

Only)

T\e /oDEYICE

macro applies only to the device-specific third stage

(BS3.A86 and

BS3MB2.A86

files).

It associates a device with a particular third stage device driver.

The

syntajK of the ToDEYICE macro is as follows:

ToDEYICE

(unit, name, device$init, device$read, device$da

ta.u

n it_in fo

)

where:

unit The unit number of this device. Unit numbering

should be the same as

that used in the BS1.A86 or BS1MB2.A86 file described in Chapter 3

name The name of the device. You should always specifu the

same name that

you

used for the device in the BSl.A86 or BSlMB2.A86

file.

4-6 Bootstrap LOader

CONFIGURJNG

THE THIRD

STAGE

device$init Public

name oî

the third

stage

device

driver,s initialization

procedure.

Table

4-1 lists

the

names used

for lntel-supplied

device drivers.

lfyou

supply your

own

driver (written

as described

in Chapter 6),

enter the

name

of its initialization

procedure.

device$read Public

name

ofthe third

stage device

driver's

read procedure.

Table 4-1

lists the names

used for

Intel-supplied

device

drivers.

If you

supply your

own driver

(written

described

in Chapter

6), enter

the name

of its

read procedure.

device$data Public

name of

a label

that marks

the

first byte

of the data

segment used

the third

stage

device driver.

Table 4-l lists the

names used

for Intel-

supplied

device

drivers.

Ifyou supply your

own driver (written

described

in Chapter

6),

you

must

create such

a label and

enter its name

here.

unit info An ASM86

label that

marks

the location

of an

array of ByTEs

containing

specific

device-unit

information

required hy

the mass srorage

device

defined

this invocation

the

%DEVICE macro.

Table

4-1

lists the

names of

the device

initialization

procedures,

device

read procedures,

and

data

segments

for Intel-supplied

third stage

device

drivers.

4.3.3

"/"SASl_UNIT_INFO

Macro (BSCSl.A86

Fite)

The

SCSI

device

driver provides

interface to

mass storage

devices

through

either SASI

or SCSI

controllers.

ìf using devices

controlled

by a SASI

controller, you

must

specifo a

sequence

of initialization

bytes

for the

controller.

This

information

is not required

by SCSI

controllers.

The initialization

sequence

identifies

the type

of iìevice you

have assigned

the particular

unit

of the SASI

controlìer.

The

sequence will

be clifferent

depending

on the

manufacturer

and

model

of the

hard disk

or flexible

diskette drive.

and the

manufacturer

and model

of the SASI

controller

board

itsell

Table

4-1. Names

for Intel-Supplied

Third Stage Drivers

Devico

Driver Oevice

Inhislize

Procedur€ Devica Read

Proc6dure Dsta

569ment

MSC Driver

iSBC

264 Driver

iSBC

186/224A

Driver

SCSI Driver

deviceiniîmscgen

deviceinit264

device init 2244

deviceinltscsi

d€vicereadmscgen

deviceread264

deYicelead 2244

devicereadscsi

data msc

aaazu

data bs drivers

oala scsl

Bootstrap

Loader 1-7

CONFIGURING

THE

THIRD STAGE

This macro

enables

you

to define

the

initialization

sequences

required

by your

devices

the SASI

bus. For each instance

of the ToDEVICE

macro

(in

the 851.A86

BS1MB2.A86

file) that defines

a device

on the

SASI bus,

you must also

include

the

ToSASI_UMT_INFO

macro

(in the

%BSCSI.A86

file) to

define that

device's initialization

sequence.

The label

specified for

the unit info

field of the %DEVICE

macro

must

match

the

label field of the

corresponding %SASI_UNIT-INFO

field.

The information

supplied

by an occurrence

of the %SASI-UNIT-INFO

macro

is not used

devices on the

SCSI bus. Therefore

in the BS1.A86

or BSIMB2.A86

file, VoDEYICE

macros

for devices

controlled by the

SCSI bus

should never specif a

value

for

the unit info

parameter. Note

that there is only

one

pair

of device

initialization/device

read

procedures

for the

SCSI driver regardless

whether the controller

is SCSI or SASI.

The %SASI_UNIT_INFO

macro

can be included

only in the

SCSI/SASI

driver

confisuration file.

BSCSÌ.A86.

The macro has the

form

%SASI-UNIT

where:

label

init_command

init_count

init data

_INFO(

label, init_command,

init_count,

init_data

)

A valid ASM86 label name

matching the one

you

specified in

the unit info field of the ToDEVICE

macro

for

your

device

(in

the file

BS1.,{86 or BSlM82.,486).

A WORD that is the initialization

command for

your

particular SASI

controller.

A BYTE specifying

the number of initialization

BYTEs

that

your

SASI

controller requires.

The array of BYTEs of initialization

data required

your SASI controller. The

length of this array must

equal to the

value in the init count parameter.

4-8 Bootstrap

Inader

CONFIGURING THE THIRD

STAGE

The

default invocations

of this macro

in BSCSLA86 are

; j.SBC

786/03A SCSI Host

lbscsi( 0C8H

, OCAH,

OCCH, OCEH

, 0

, 1,0,OFFCOH,2,0)

; iSBc 286/700 SCSI

Hosc

bscsi( 0C8H,

0cAH,

0CCH, 0CEH,

0,0,2,0, 0200H, 2, l, 0D1H)

; Xebec 51420 SASI controller and a Teac model F558. 5 L/4-ínch

; flexible di skette drive.

X s as

i_uni t_fnfo

(sasi_x1420mf,

1lh,10,0,28h,2,90h,3,0fh,50h,0fh,014h,0)

; Xebec 51410 SASI conÈroller and a Quantum

roodel

Q540, 5 L/4-lnch

; l,linchester dÍsk drive.

Zsasi_unit_info(sasi_x1410b,

Och, 8, 2, 0, 8, 2, 0, 0, 0, Obh)

;

; Xebec S1410 SASI controller and a Computer Memories, Inc.

; rnodel CMI-5619

5 1/4-inch l,Jinchester disk drive.

Zsasi_unit_info(sasi_x140a, Och, 8, 1, 32h, 6, 0, 0b4h, 0, 0, Obh)

4.3.4

o/"lNTl

Macro

The

ToINTl macro causes the

third stage to

execute an INT 1 (soliware interrupt)

instruction whcnever

a bootstrap

loading error occurs.

This enables

you

to pass control to

user-written program

if loading fails.

However, to pass control to

another

program, you

must place the

address of that program

position

1 of the interrupt vector

table. This

macro

is supported by only

the D-MON3Só

monitor. The iSDM monitor does

nor support

this

macro.

The svntax of the

%lNTl maero is

a/ol

NTI

There are no parameters

associated with this

macro.

Exactly

one of the

%lNTl, %lNT3,

and

%HALT macros

must

included, or an error

will

occur when

BS3.Alì6,

BS3MB2.A[ìó, or BG3.A8ó are

assembled.

Bootstrap Loader 4-9

CONFIGURING

THE THIRD STAGE

4.3.5 %lNT3

Macro

The %INT3

macro causes

the third stage

to execute an INT 3 (sofrware interrupt)

instruction

whenever a bootstrap

loading error

occurs. Ifyou are using

the iSDM

monitor,

the INT 3 instruction

passes control

to the monitor. Otherwise,

the INT 3 instruction

has

no effect unless

you have placed the address

of your custom interrupt

handler in

position 3

of the interrupt

vector

table.

The

syntax of the

aol

NT3 macro

7aINT3

There are no

parameters

associated

with

this macro.

Exactly one of the %lNT1, %lNT3,

and

TaHALT

macros

must be included, or an error

will

occur

when

8S3.A86, BS3MB2.A86,

or BG3.A86 are assembled.

4.3.6

%HALT Maero

'Íhe ToHAIJT

macro causes the third stage to execute a halt instruction

whenever a

bootstrap

error occurs.

The syntax of the VoÍIALT macro is as follows:

ToHAlT

There are no

parameters

associated

with this macro.

Exactly one of the ToINTl, %INT3,

and

ToHALT

macros must be included, or an error

will

occur

when

BS3.A86, B53MB2.A86,

or BG3.A86 are assembled.

4.3.7 a/oCPU

BOARD Macro

The

ToCPU

BOARD macro specifies the type of processor board in your system. The

third stage needs this information

so that it can properly

initialize

the

board

when

switching into

protected virtual

address mode. The syntax of the

%CPU BOARD macro

is as follows:

TaCPU_BOARD (type)

4-10 Bootstrap

Loader

CONFIGURING

THE THIRD

STAGE

where:

type The tlpe of processor

board in your system.

The following are the valid

values:

Value Processor

Board

286/12 iSBC

286/10 board

286/|Z iSBC 2861104 board

286112 iSBC 28ól12

board

2861100A iSBC

2861100.4 board

386/20 iSBC 386/2X board

or iSBC 386/3X Board

386/100 iSBC

386/116 board or

iSBC 386/120 Board

4.3.8

%INSTALLATION

Macro

(8G3.A86

Only)

The TaINSTALI-ATION

macro specifies whether the generic third stage will

enter the

monitor after loading the application

system or not. The syntax of the

%INSTALLATION

macro ls:

ToINSTALI-ATION (monitor_entry)

where:

monltor_entry The type of action the

Bootstrap Loader is to take upon

loading the application system. If monitor entry is

'n'

the

system

is loaded and then executed

with

no monitor

entry

inbetween. If it is'y', the monitor is entered after

the system is loaded. You must

rype

in the monitor GO

command to continue.

When

the monitor is entered,

as a result of specifying

'y'

for the monitor_entry

parameter,

the Bootstrap

Loader

prints

the following

message to the terminal:

Insert the Start-uD Svsten Cornmands

Dlskette and tvDe "G<RETURN>"

NOTE

If your system has

the D-MON386 monitor rather

than the

iSDM monitor, type

''GO<

RETURN>".

Bootstrap

Loader 4-t I

CONFIGUR-ING

THE

THIRD

STAGE

This macro

is used to

generate the

generic

third

stage used to

boot the Operating

System

from diskettes. The %INSTALT

ATION macro allows one diskette,

which

contains

only

the Operating

System boot file and

the third stage to be usetl

to load the system

from

diskette into memory.

In entering the monitor,

it allows a second

diskette,

which contains

the necessary system

commands, to be used as

the system device

when

the

system is

initialized.

4.3.9 %END

Macro

The

ToEND

macro is required

at the end of the 853.A86,

BS3MB2.A8ó, and BG3.A86

files. The syntax of this macro

is as follows:

ToEND

There are no

parameters

associated

with

the

ToEND

macro.

4.3.1

0 User-Supplied

Drivers

If you want

to use the device-specific third

stage to

load

your system from a device other

than one

for

which

Intel

supplies a third-stage driver, you must write

your

own device

driver

procedures

that the third stage

will

call. Chapter

describes how to

do this. In

addition,

perform the

following

actions to add the procedures to the Bootstrap Loader:

Speci! the

names of the device initialization

procedure, the device read

procedure,

and the driver's data

segment in a ToDEYICE macro in

the

853..4[ì6 file.

If there are configurable parameters associated with your device

(such

as base

addresses or

wakeup

ports), you might want to create your own configuration macro

and include

it in

a special

configuration file,

just

like the Intel devices do. Chapter

describes how to set up a macro. You

will probably

use the same configuration file for

both the first- and third-stage drivers.

Assemble your

device initialization

procedure,

your device read procedure, and

your

configuration file (ifyou have one), and link the resulting object code to the rest of the

BootstraD Loader

obiect files

and

libraries.

4-12 Bfi)tstrap hader

4.4

GENERATING

THE

THIRD

STAGE

Two SUBMIT

files

(BS3.cSD

and

BG3.csD)

are

used

generate

the

two types

of third

stages.

B53.cSD

performs

the

assembly,

linkage,

and

location ofthe

device-specific

third

stage.

BG3.GSD

performs

the same

operations

for

the

generic

third stage.

Figures 4-4

and

4-5 show

the Intel-supplied

B53.CSD

and

BG3.CSD

files.

CONFIGURING THE

THIRD

STAGE

attachfile $ as :fl:

;

rnp1286

asn86

asrn86

asm86

asn86

asm86

;

link86

;

1oc86 :fl: Z0

. lnk

addresses

(classes

(code

(11

) ) )

order(classes

(code,

data)

)

noinitcode purge

s taft (bs

)

map print (

f1 : %0. np2

)

The Third Stage, locared ar

:f1

Í0. a86 $object(%0.rnp1)

fl:f0.rnpl

:bmsc.

a86

f1 :b2l8a

. a86

fL:b264 . a86

: bscsi. a86

fI:b224a . a86

f1 20.

obj

, &

:bs3.lib, &

f1 :brnsc

obj , &

fl :b218a. obj

, &

fl : b264

obj &

:bscsi.obj, &

fl:b224a.obj &

fl:10.lnk print(:f1 :Z0.mp1)

notype nolines nosynbols

address

11, is in the file 10

Figure 4-4.

Device-Specific

Third

Stage

SUAMIT File

(B53.CSD)

Bootstrap

Inader ,:t-

atfacnîlIè I as : f r:

;

asm86 : Fl:

bg3

a86 nolisr

;

link86 &

:f1 :bg3.obJ, &

.!i-.uBJ.r!u ù

to :

fl :bg3.1nk notype nolines nosyurbols

1oc86 : fl : bg3 . lnk &

addresses

(classes (code (Zl)

) ) &

order(classes

(code,

data)

) &

nolnitcode &

èLd! L\urJ./ Pu!óc

to :Fl:20.11

nap

print(:fl :ifO.mp2)

The Generic Third Stage is located at address Z2 and is

in the file Z0 . 11-

CONFIGURING

THE THIRI) STAGE

Figure 4-5.

Generic

Third Stage SUBMIT File

(BG3.CSD)

4.4.1 Modifying the

Submit Files

Before

generating your

own

version

of the third

stage, you

should modify

the appropriate

submit file to match your intended configuration.

If you are using the device-specific third stage and you have excluded any device drivers

from it (by excluding

o/oDEYICE

macros

from

the

853.A86 or BS3MB2.A86 file),

you

won't want

to link the code for those drivers into the the third stage. To prevent

the

linking of

device

driver, edit the LINK86 command in the BS3.CSD file and

place

ampersand (&) in front of any file name that corresponds to a driver

you want

to exclude.

If you are not using an

iRMX I or iRMX II system to configure the third stage, you must

comment out the line where the directory

containing the Bootstrap Loader files is attached

as :fl: before invoking the other commands in the

BS3.CSD or BG3.CSD file. Change

the

line:

ATTACHFILE

$ AS :Fl :

:ATTACHFII-E S AS :F1 :

4-14 Burtstrap [-oader

CONFIGURING

TIIE THIRD

STAGE

4.4.2 Invoking

the

Submit File

After you

have

modified

either

the BS3.CSD

or BG3.CSD

file to

correspond to

your

configuration,

invoke

the

appropriate

SUBMIT

file to assemble

the third

stage files,

link

them

together,

and assign

absolute

addresses.

The

format for invoking

either SUBMIT

file

is as

follows:

Device-soecific

third stage

SUBMIT

B53 (filename,

third_stage_addr)

Generic

third stage

SUBMIT

BG3 (filename,

extension,

third_stage_addr)

where:

filename The

name of the

file in

which

to store

the

senerated

rhird

stage. Also,

the name

the

third-stage

configuration

file

you

are using (BS3.A8ó

for

MULTTBUS

I systems and BS3MB2.A86

for

MULTIBUS

II systems).

The generic

third stage

appends

the next parameter (extension)

to the lìÌename.

The extension

the

generic

third stage is to have.

This

does not apply

to the device

specilìc third stage.

Normal

generic

third

stages usually

have the extension

'GEN'.

Generic

third stages

used lbr Operating

System

installation

should

use the extension

'INS'.

The address

in RAM where

the third stage will

loaded.

The address you

specify should be

a full 20-bit

address.

Do not use the base:offset

form to

indicate the

address.

If you

have

no special requirements

for loading the

third

stage, speci$ a value

of 0BC000H

for this parameter.

extenslon

third_stage_addr

Bootstrap hader 4-r5

CONFIGURING

THE

THIRD STAGE

4.5 MEMORY

LOCATIONS OF

THE

THREE

STAGES

When you

configure

the first and

third stages of the

Bootstrap Loader,

you can assign

the

addresses

at which the three stages

will

be located.

Before setting these

addresses,

you

must understand

how default memory

is assigned in the Bootstrap

Loader.

Table 4-2 lists the

default memory locations

used by the Bootstrap

Loader- It also names

the SUBMIT files

you

can

invoke to

change the memory assignments.

Table

4-2.

Memory

Locations

Used bv the Bootstrap

Loader

The Bootstrap Loader Release Diskette contains

a standalone version of the Bootstrap

Loader, in the file named BS1,

which

selects all the supported lntel device

drivers. The

map file, BS1.MP2, is supplied to show the layout of the segments in BS1. The first

stage is

located

at 0C0000H and the second stase is located at 0B8000H. All default third stases

are located at 0BC000H.

Deacription D€fauh

Marimum

Size'

Configuration

File

1st Stage

Code

2nd Stage

Code, I st/2nd

Data

and Stack

3rd Stage

(specifìc)

Cod€,

Data

and

Stack

3rd Stage

(gen€ric)

Code

Third

Stage

(generic)

Data and

Stack

Applicatìon Dependent

0FE40OH

for

iSDM R3.0

088000H

0Bc000H

0880@H

14K Bytes

8K Bytes

16K Bltes

8K Byîes

BSl,CSD

BSl.CSD

BS3.CSD

BG3,CSD

BSl,CSD

* Maximum siz€

a function ol the

size of the device drivers included in the Bootsfap Load€r,

1-16 Bootstrap Iîader

WRITING

CUSTOMCHAPTER

FIRST.STAGE

DRIVER

5.1 INTRODUCTION

You

can configure

the Bootstrap

Loader

to run with

many kinds of

devices. If you plan

use

one of the

devices for which

Intel supplies

a device

driver, you

can skip this chapter.

If you want

to use

the Bootstrap

Loader with

a device other

than those supported

by Intel,

you

must

write

your

own first-stage

device driver. (lf you

want

to load iRMX II

applications

past the first

megabyte

of address space, you

must also write

a custom third-

stage

driver.

Chapter 6 describes

how

write

thirtJ-stage

drivers.) This

chapter

provides

you

with guidelines

for

writing

a custom first-stage

driver.

You

must include two procedures

in every first-stage

device driver: a device

initialize

procedure

and a device read

procedure.

The device

initialize procedure

must initialize the

bootstrap

device. The device

read procedure

must load

information from

the device into

RAM.

The

rest of this chapter

refers

to the two procedures

as DEVICE$INIT

and

DEVICE$READ. However,

you

can

give

them

any names you want, provided

other

first-stage

driver procedure

uses the chosen

names.

To check the names

of the Intel-

supplied

first-stage procedures,

use LI886

to Iist the modules

in the object

library

/RMX286/BooT/BS

I-lB or

/RMX86/BooT/BS

1.LIB.

You

must

write

both

procedures

in an

t1086 language

(either

PL/M-ll6

or ASM86) and

conform

to the

I-ARGE model

of segmentation

of the

PL/M-86

programming

language.

This

means that you

must declare

the two procedures

as FAR (not

NEAR) an<J all

pointers

must

be 32 bits

long. You must

adhere to

the interfacing and

referencing conventions

the

PL/M-8ó IARGE model

even if you write

the

procedures

in assembly

language.

If your

driver

code is

going

operate in the

MULTIBUS II environment,

two adclitional

driver

code constraints

exist. First, you

must follow

the MULTIBUS II transport protocol

for communication

between

the driver

and the device

controller

you

bootstrap load

tiom

You can au:omplish

this by

using Bootstrap

Loader Communìcation System

utiÌity calls

within

your

driver code.

Second, you

must organize your driver code

so that it belongs to

the BSL-Drivers

COMPACT sub-system.

This last

requirement is necessary because rhe

Bootstrap Loader

Communication

System utilities are all NEAR calls.

Bmtstrap lîader 5-l

WRITING

A CUSTOM

FIRST-STAGE

DRryER

The next

two sections

describe

the interface

these two

procedures

must

present to

the first-

stage Bootstrap

Loader code.

Subsequent

sections describe

how to

supply configuration

information

to the

driver, how to

use Bootstrap

Loader Communication

System utilities

your driver code,

and how to

generate first-stage

Bootstrap Loader

code that

includes the

new

driver.

5.2 DEVTCE

INITIALIZE PROCEDURE

The device

initialize

procedure must

present the following

PL/M-86 interface

to the

Bootstrap

Loader:

device$init: PROCEDURE

(unit) WORD PUBLIC;

DECI-ARE

unit WORD:

. (Typical code)

END

devices ini t :

where:

device$init The name

of the device initialize

procedure. You can

choose any

name

you

wish for this

procedure, as long as it does not conflict

with the

names

of any other first-stage

procedure.

unit The device

unit number, as defined

during Bootstrap Loader

configuration.

The

WORD value returned by the

procedure must be the device

granularity (in bytes) if

the device is ready, or zero if the

device is not ready.

To be compatible

with the Bootstrap Loader, the device

initialize

procedure

must

perlbrm

the following

steps:

1. Test to see if the device is

present.

If not, return

the

value

zero.

2. lnitializ.e the device for reading.

This operation is device-dependent. For guidance

in initializing the device, refer to the hardware reference

manual for the device.

3. Test to see if device initialization is successful. If not.

return the value zero.

4. Obtain

the device granularity. For some devices, only one granularity is

possible,

while for other devices several

granularities

are

possible. The hardware reference

manual for

your device explains this device-dependent issue.

5. Return the device

granulariry.

5-2 Bmtslrap

Loader

WRITING A CUSTOM

FIRST-STAGE DRIVER

NOTE

In addition to the above

five steps, the procedure

must follow N4ULTIBUS

transport protocol

and belong

to the BSL-Drivers

COMPACT sub-system if the

driver

functions in a MULTIBUS

II environment. Refer to

Section 5.5 for

information on these

two requirements.

5.3 DEVICE READ

PROCEDURE

The device read procedure

must present

the following PL/M-86 interface

to the Bootstrap

I-oader:

device$read: PROCEDURE

(unit, blk$nun, buf$ptr) PUBLIC;

DECIARE unit WORD,

b1k$num DWORD,

buf$ptr POÌNTER;

. (Typical code

)

END

deviceSread:

where:

device$read The

name of the device read procedure.

You

can

choose any name

you

wish

for this procedure,

as long as it does not conflict

with

the names of

any other first-stage procedure.

unit The device unit

number, as defined during Bootstrap Loader

configurat

ion.

blk$num A 32-bit number specifying

the block number the Bootstrap Loader

wants

the

procedure

to read.

The size of each block equals the device

granularity,

with

the first block on

the device being block number 0.

buf$ptr A 32-bit POINTER

to the buffer in

which

the device read procedure

must copy the information

it reads

from the

secondary storage

device.

The

device read

procedure

does

not return a value to the caller.

To be

compatible

with

the Bootstrap Loader,

the device read

procedure

must

perform

thc

following steps:

1. Read the block specified by blk$num

from the bootstrap device specified

by unit into

the memory location specified by buf$ptr.

Bootstrap l-oader 5-J

WRITING A CUSTOM

FIRST-STAGE

DRIVER

Check

for I/O errors. [f none occur, return

to the caller. Otherwise,

combine

the

device code, if any, for the device

with

0l (in

the form <

device code

01),

push

the

resultingworcl

value onto the stack, and

call the BSERROR

procedure. For example,

if the device code is 0B3H,

push B301H onto the stack,

and call BSERROR.

If no

device code exists. use

00.

Adding the following statements

aocomplish this in PL/M-86:

DECI.ARE

BSERROR EXTERNAL,

DECI^A.RE

IO-ERROR LITERALLY'OB3O1H'

CALL BSERROR(ÌO_ERROR)

;

lf you call the BSERROR

procedure

from

assembly language, note that BSERROR

follows the PL/M-86

TARGE model of segmentation;

that is, declare BSERROR

extrn BSERROR:far

NOTE

adclition to the above two steps, the procedure must follow MULTIBUS II

transport

protocol

and belong to the BSl-Drivers COMPACT

sub-system if the

driver functions in a MULTIBUS II environment.

Refer to Section 5.5 for

more information on these lwo requircments.

5.4 SUPPLYING CONFIGURATION

INFORMATION TO THE

FIRST.STAGE DRIVER

Any custom device driver you

write

needs some configuration information about the devrce

it supports, such as

the address of

the device wakeup port. (To

determine

what device-

specific information your driver needs, consult the hardware reference manual for the

device.) You can provide this information to the custom device driver one of two

ways:

. Place the information

directly into

the driver (hard-coding)

. Create a configuration file similar to those provided

with

the Intel-supplied drivers.

5.4.1 Hard-Coding the

Configuration

lnformation

One way to supply configuration

information to a custom device driver is to

place it

directly into the code. This method

works,

but if any of the configuration information

changes, or if you

want

to support a similar device that has a slightly different

configuration, you must

change the ciriver ancì reassemble it. Fortunately, first-stage devrce

drivers are usually small enough so that the amount of time required to

reassemble

them is

negligible.

5-4 Brxtlstrap lrtader

WRITING A CUSTOM

FIRST-STAGE

DRIVER

Figure

5-t illustrates how

place

the

configuration information

directly into the code.

This figure lists

the

"Constants

and Data" section

that could be

used to supply the

MSC

first-stage

driver with

device-specific

configuration

information.

Figure

5-1. Hard-Coded

Confìguration

Information

5.4.2 Providing

a Configuration

File

The second way

to supply configuration

inlbrmation is to declare

all device-specifìc

parameters

as variables

that are

external to

your

device

driver. A separate small module

can declare

these

parameters

public

variables

in . You can incorporate this second

module into the Bootstrap

Loader by

placing

assembly and link commands in the first-

stage SUBMIT

file BS1.CSD.

To use this approach,

follow the steps below:

Constants and Data

data_bsmsc segnent ;

Static Data

wakeup_newdrivl dw 100H ;MSC

wakeup address

device_newdrlvl db 0

drtab_ne\,Jdr

ivl d\r 256 ;number of cylinders

db 2 ;nuruber of fixed heads

db 0 ;nurnber of rernovable heads

db 9 ;number

of sectors

db L024 :

device granularicy

db 5 ;nurnber

of alternaÈe cylinders

Bootstrap l-oader 5-5

WRITING

A CUSTOM

FIRST-STAGE DRTVER

1. In the code for the device

driver, declare the device-specific

parameters as external

variables. For example, the following code could

be used instead of the

hard-coding

shown in Fisure 5- l.

narne bpmsc

;

Conf lguration information:

extrn r^rakeup_newdrivl

extrn device_ne\rdrivl

extrn drÈab newdrivl

word

byce

byte

;l,Iakeup

port

;Devlce nurnber

;Device Table

Create an INCLUDE file containing a macro definition. The macro definition

must

declare the device-specific parameters as public

variables (matching

the

external

declarations from the previous step). This file should be named as

"roo<.inc" where

no< is any name you choose. For example, you could

place

the following code into

file called NEWDRIVI.INC to define a macro for the device-soecific

Darameters

declared in Sten 1.

*DEFINE

(bnewdrivl (wakeup

ncyl

,nfsur,nrsur,nsec,secslze,nalt)) (

nane bnewdrivl

publlc wake_rnsc,

devlce_msc, drtab_msc

code_newdrivl segment byte public 'CODE'

wakeup-newdrlvl dw lwakeup

device_newdrivl db 0

drtab_newdrivl dw lncy1

db nfsur

db %nrsur

db Zns ec

drr %secsize

db lnalt

code_newdrivl ends

)

Z* DEFINE

(end) (

end)

3. Create

another file that contains

the macro invocation. You should name this fìle

"roo<.a86",

where

xxx

is any name

you

choose. The file must

also contain an

INCLUDE directive for the INCLUDE file created in the previous

step. To be

consistent

with

the Intel-supplied

device drivers, the INCLUDE directive should use

the

logical name :F1: as a prefix to

the name of the include file. For example,

the

fiìe

NWDRV1MAC.A86 could contain

the followins information

to invoke the macro

defined in Step 2.

5-6 Bootstrap l-oader

WRITING A CUSTOM FIRST.STAGE DRIITR

$lnc1ude

(: f1 :newdrlvl .

inc)

Ibnewdr iv1(

100H,

256, 2, 0,

fend 9

, 1024

If the device-specific

configuration

information

ever changes, you

can change

the

macro invocation

in this

file to reflect

those changes.

This is normally

easier than

changing the source

code

of the driver, especially

for users who

are not familiar with

assembly language.

Store the files

created in Steps

2 and

3 in the directory where

the Bootstrap

Loader

configuration

files

reside (normally

/RMX286/800T or /RMX86/BOOT). For

example, the following

Human Interface

commands

can be used to copy the

files

created in Stens

2 and 3.

- copy nevdrfvl.lnc, nsdrvlmac.aS6 to &

x* /xrrx286 /boot/newdr lvl .

lnc , /rnx286/boot/nsdrvlmac. a86

newdrivl .

inc copied to / rnx286

/newdr ivl . inc

nwdn..mac . a86 copied to /rmx2

8 6/nvdrvmac . a8 6

5. Edit the first-stage

SUBMIT

file (BSI.CSD)

to cause

it to assemble your configurarion

file and link it to

the first stage.

To the

list of ASM86 invocations,

add an ASM86

invocation for the

file created

in Step

(>oo<.a86).

To the list of modules to be linked

(immediately

below

the

LINK86 invocation),

add the name

of the object module

created when

your

file

(no<.a86)

is assembled.

In both the ASMIJ6

invocation and the

LINK86

invocation, preface

the

filename with

the logical name :Fl: (such

:f1:nc<.a86).

Unless you

have reason

to do otherwise,

use the same

ASM86 and

LINK86 options

shown

for other files assembled

and

linked by BSI.CSD.

Figure

5-2 shows

modifications to

BSl.CSD that add

support for the

driver

configuration

files

just

created.

Arrows ar

the left of the

figure show the lines that were

added.

Notice that only

the configuration

file is being

assembled each time

BSl.CSD is

invoked,

not the entire

driver.

BSl.CSD assumes

the use of the configuration

file

BS1.A86 and that you

have assembled

your driver

and added the resulting

object

module into the

library BSl.LIB.

Bootstrap

l.oader f,-/

WRITING A CUSTOM

FIRST-STAGE

DRIVER

Figure 5-2.

Modified BSI.CSD

File

5.5 USING THE MULTIBUS@ IITRANSPORT PROTOCOL

If the driver

you

are creating functions

within

a MULTIBUS I environment, you

need

not

read this section. Skip to Section 5.6.

If the driver

you

are creating functions

within

a MULTIBUS II environment,

you

must

write

the driver code to use the MULTIBUS II message transport protocol.

To help

you

accomplish this task,

Intel

provides

a small, single-thread communication system that

enables

Bootstrap Loader drivers to communicate

with

device

controllers

within

MULTIBUS

II environment. This communication system is called

the Bootstrap Loader

Communication System.

The following paragraphs provide an overview of the Bootstrap

Loader Communication

System, which uses

concepts

similar

to the Nucleus Communication System.

Should

you

desire a more complete description of these

communication system concepts,

refer

to the

Extended |RMX II Nucleus User's Guirie in Volume 2 of the iRMX ll documentation set.

;

;asrn86

:f1:bs1.a86 rnacro(90)

objecc(:f1-:bs1.obJ) Prínr (

: fl:bs1 .

lst)

asrn86 :fl:b264.a86 nacro(50) object(:f1 :b264.obj

) print(:f1 :b264.1st)

asn86 :f1 :bscsl.a86 macro(50)

object(:fl:bscst.obJ) p

r i n t

(

f l : b s c s i . l s t

)

-> asn86 :

fl :nvdrvlnac.aS6 nacro(50) object( :

fl :nvdrwlnac.obj nollsÈ

;

l lnKób

'f1 'hcprr nhì

& :f1:bcico.obj,

&;standaÌonè

serlal channèl support

fl hcnci nhi

fl:b264. obJ

fl : nrdrvlnac .

obj ,

rl:Ds_t.llD

to : f1

:bs1.lnk prlnt(: fl:bs1.npl) &

5-E Bootstrap [.oader

WRITING

A CUSTOM FIRST-STAGE DR-IVER

The Bootstrap

Loader Communication

System

can be thought of as

a subset of the Nucleus

Communication

System.

It fully conforms

to the

MULTIBUS II transport protocol

suitable

for a limited

bootloading environment.

Unlike the Nucleus Communication

System,

the Bootstrap

Loader

Communication

system is designed

to handle bootstrap

only. Consequently,

the system

is synchronous

in nature. In other words,

procedures

execute

to completion

one after

the other; no multitasking

or need to handle

asynchronous

events

exists,

MULTIBUS II transport protocol

functions supported

by the Bootstrap

Loader

Communication

System include

control and data

message tlpes, a subset

of the

request/response

transaction

model, send

and receive transaction

models, message

broadcasting,

and access to device

interconnect space.

To support these

functions, lntel supplies

a set of system utilities grouped

together in a

Bootstrap

Loader

Message Passing System

Module. As a programmer, you

have access to

these utilities

through system

calls

you

place in your

driver code. The remainder

of this

section explains

the supported

functions in the

Bootstrap Loader Communications System

and shows you

how to

use each of the utilities.

5.5.1 Message Passing

Controller Initialization

Before any

Bootstrap Loader

Communication System calls

can be made, you must

initialize certain parts

of the hardware

in preparation for message passing.

You

accomplish

this initialization

through the

BS$MPS$INIT utility. You must make this call

from

your

driver's initialization procedure

before

making any other Bootstrap Loader

Communication

utility calls. The following

utility description presents

BS$MPS$INIT:

CALL BS$MPS$INIT

INPUT PARAMETERS

This utility

has no input parameters.

OUTPUT PARAMETERS

This utility

has no output parameters.

DESCRIPTION

The BS$MPS$INIT

utility provides

hardware initialization for the Message Passing

Controller

(MPC)

and

the Advanced Direct

Memory Access

(ADMA) devices.

You must

perform

a call to this utility before attempting

any other Bootstrap Loader Communication

Svstem

utilitv calls.

Bootstrap Loader 5-9

WRITING A CUSTOM

FIRST-STAGE

DRI!'ER

CONDITION

CODES

This utility has

no condition codes.

5.5.2

Message

Types

The Bootstrap

Loader Communication

System

supports two types

of messages: control

messages and

data messages.

Control messages consist

of only a control

portion.

These messages

occur between

the

sender and

receiver requiring

no explicit buffer resource

allocation.

The reason

for no

buffer allocation

is because a control

message has no data

part. The maximum

length of

control

message is 20 bytes. Also,

a one-to-one correspondence

exists

between control

messages and MULTIBUS

II unsolicited messages

(all unsolicited

messages are control

messages).

Data messages

consist of both a l6-byte

control portion and a

variable length data

portion.

These

messages do require explicit

buffer allocation between

the sender and receiver.

The

reason buffer allocation

is required is because this

type of message contains

a variable

amount

ofdata. The maximum length of

the data portion is 64K-l

bytes.

5.5.3

Request/Response

Transaction Model

The Bootstrap Loader Communication

System supports a

subset of the re<1uest/response

transaction model that the Nucleus

Communication Svstem

uses. This subset has the

folìowing characteristics:

o Because the Bootstrap Loader Communication

System functions

within

a bootloading

environment, request messages

originate only from the host CPU board. The

specific

device controllers then

match responses to requests on a one-to-one

basis.

. No support exists for multiple

outstanding requests.

. Fragmentation and transmission

of response messages into specific application

buffers

can occur. Because this fragmentation

is completely transparent to the user, the

fragmented response is considered

as a single

response

to a single request.

o The Bootstrap Loader Communication

System

receives

messages in the order in

which

they are sent.

Communication

between the CPU host board executing the driver and lhe bootable

device

controller uses the basic transmission model of send and receive. The driver sends

request to the device controller

and then receives a response back. When the driver

initiates the message, an internal

transaction ID is generated that logically associates

the

request

with

the response.

This ID remains valid until the device controller responds,

thus

completing the transaction.

5-10 Bootstrap l-oader

WRITING A CUSTOM FIRST-STAGE DRIVER

For messages that

require data as

part

of the response, the driver can initiate the allocation

of an

rsvp data message buffer in which

to receive the response data. The data can then

arrive either whole

or fragmented. Regardless of fragmentation, the

host CPU

board views

the

response message as one message.

If the request message requires no data as a

response, the response

must be a control message.

The utility the Bootstrap

Loader Communication System uses to support the

request/response transaction

model is BS$SEND$RSVP. The following utiliry description

presents

BS$SEND$RSVP:

CALL BS$SEND$RSVP(socket,control$ptr,data$adr,data$length,

rsrp$control$p,rsrp$data$adr,rsvp$data$length,

flags,exception$ptr)

INPUT PARAMETERS

socket

control$ptr

data$adr

data$length

rsrp$control$p

rsrp$data$adr

A DWORD of the form host$id:port$id identif

ing the

remote destination.

A POINTER to a control message. If data$adr

NULL

(0) or data$length

0, then the control message is 20

bytes long. Otherwise, the control message is 16 bytes

long.

A DWORD containing the absolute

address of a data

message. If data$adr is NULL (0),

then a control

message is sent. Otherwise, data$adr points to a

contiguous

buffer.

A WORD defining the length of the data message. If

data$length is equal to zero, the control message

length

is assumed to be 20

bytes.

A POINTER to the received control message. If

rsvp$data$adr

NULL (0) or rsrp$data$length

0, then

the

control message

is 20 bytes long. Otherwise, the

control message is 16 bytes long.

A DWORD containing the absolute address

of a data

message buffer for the return

response that is expected.

If rsrp$data$adr is NULL (0),

then

a control message is

expected as a reply.

Otherwise, rsw$data$adr

points to

a contiguous

buffer in which the data message

arrives.

Bootstrap Loader 5-ll

WRITINC

CUSTOM

FIRST.STAGE

DRI!'ER

rslp$data$length A WORD

defining

the length of the rsrp data

buffer.

flags WORD reserved

for future use. Aithough

this

parameter is ignored,

you

must

supply a "0"

value

as a

placeholder.

OUTPUT

PARAMETER

exception$ptr A POINTER to a

WORD to which the Operating

System returns the exception code

generated by this

Bootstrap Loader Communication

System call.

DESCRIPTION

The BS$SEND$RSVP utility

sends a message from a port to a remote socket

with

explicit request for a return response. This call is synchronous

with respect

to both the

request and the response.

5-12 Bootstrap l-oader

WRITING A CUSTOM FIRST.STAGE

DRIVER

EXAMPLE

This

example illustrates

the

fundamentals

of the

request/response

transaction

model

between

the

host CPU

board and

bootable

device controller

board.

This examole

written

in PL/M-Só code

and is intended

generic

nature.

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

* îhis exanple sends a 20,byte control nessage to the *

* bootable device controller board located ln slot 1 *

* at port 500 of the MULTIBUS II systen. This nessage *

* sollcits data from the device as DarÈ of the *

* ra <nan c a

The control message sent is contained in the 2o-byte

data array p$couurand$ursg (Peripheral Comrnand

Message). The controL rnessage received is captured

ln the 20-byte data array p$sratusgrnsg (Perlpheral

Status Me s sage

) .

The solicited data is received from the device vÍa

an rsvp buffer. Note that the address polnting to

che rsq buffer rnust be an absolute address before

it is passed ro BS$SEND$RSVP.

Thus, rhe need for

calling a conversion routÍne. In this exarnple, a

routine (not shown) ca1led CONVERT ADDRESS

handles

the address conversion. It is up to the prograrnroer

to supply the converslon routlne.

* Setting data$length and data$adr to NULL

(0) *

* Índicates that only a control nessage is being sent *

* froro the host CPU board to the controller board. *

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

Bootstrap

Loader 5-r3

WRITING A CUSTOM

FIRST-STAGE

DRIVER

SAMPLE_BS

S ENDSRSVP : Do;

DECÌ-ARE socket DWoRD;

DECIARE socket$o s t ruc Eure

(host$id llORD,

port$id I.IORD)

AT (Gsocket);

DECLARE

p$control$msg(20) BYTE:

DECIAREp$status$msg(20) BYTE;

DECLARE send$data(100) BYTE;

DEOI"ARE rswp$data(1024) BYTE;

DECIARE rsvp$data$adr Df.lORD;

DECI,A,RE rsrp$ data$ l ength DI,I0RD;

DECI,ARE flags WORD;

DECÌARE

exception WoRD;

DECIARE slot LITERALLY '1H';

DECLARE

port LITERALLY ' LF4H'

;

DECI,ARE null LITERALLY '0H' ;

CoDE: DO;

^^^1,^ + C ^ t-^- FC i I

è vw Nc uv v . rrv r e

v ru

cnrlzot(n nnrt(i À

rsrp$data$ 1-ength

flags

rc\mqÀr'-.q./r =

- slot;

- port;

- 400H;

: null;

CoNVERT_ADDRESS

(@rsrp$data (0

) ) ;

. (Typical code to define

. the 20-byte p$control$msg block

. with the control nessage.

)

CALL BS$SEND$RSVP

(socket,

@p$control$msg(0),

null,

null, @pgstatusgrnsg(0),

rsrp$data$adr, rsrp$data$1ength,

flags , @exception) ;

IF exception <> 0

THEN CALL BSERROR;

. (Typical code to execuLe

. lor successful status. )

END CODE;

sAÌ,fPLE_BS

I SEND9RSVP

;

5-r4 Bootstrap [-{)ader

WRITINC

CUSTOM

FIRST-STAGE

I)RtVER

CONDITION

CODES

E$OK 0000H No exceptional

conditions.

BS$E$BUFFER$SIZE 0082H The

rsvp buffer posted

is too

small.

BS$E$TRANSMISSION 00ElI{ An error occurretl while

transmitting a

MULTIBUS II

message.

5.5.4

Send

and Receive

Transaction

Models

In addition

to the request/response

transaction

model, the Bootstrap

Lolder

Communication

System supports scnd

and

receive transaction

models. Normally,

communication

between a

driver and a

device in a bootloading

environment

uses the

request/response

or send

models. However,

ifyour host

CPU board can capitalize

on a

receive

transaction

model initiated

liom the

driver, the utility

is available.

You

can make calls to

the send and

receive utilities,

respectively when

you

neetl the driver

to simply send

a message with

no request

for a response,

when

you need the

driver to

wait

lbr spontaneous

communication

from

a specific device

controller.

The two

utilities available

you

that support

the send

and receive transaction

models are

BS$SEND and

BS$RECEIVE.

The following

utility descriptions present

BS$SEND

and

BS$RECEIVE:

CALL BS$SEND (socket,control$ptr,data$adr,data$length,

flags,exceptiongptr)

INPUT

PARAMETERS

socket A DWORD of the form hostgid:portgid

identifying the

remote destination.

control$ptr A POIN'IER

to a control message. lf datagadr

NULL

(0)

or data$length

0, then the control message is 20

bytes

long. Otherwise, the control

message is l6 bytes

long.

data$adr A DWORD containing the absolute address

of a data

message. If data$adr

is NULL (0),

then a control

message is sent. Otherwise, data$adr

points

to a

contiguous

buffer.

B{ntstrap l-oader 5-t-s

WRITING A CUSTOM FIRST-STAGE

DRIVER

data$length A WORD defining the length

of the

data message.

data$length is

equal to zero, the

control message

length

assumed to be 20

bltes.

flags WORD reserved

for future use. Although

this

panrmetcr

is ignored,

you must supply a

"0"

value as a

placeholder.

OUTPUT

PARAMETER

exception$ptr A POINTER

to a

WORD in which the Bootstrap

Loader returns

the exception

code

generated by this

Bootstrap

Loader Communication

System

call.

DESCRIP'TION

The BS$SEND

utility sends either

a contrttl or a data message

to a MULTIBUS II board

identified by the

parameter socket.

EXAMPLE

This example illustrates

the fundamentals

of message passing from

the host CPU

board to

the bootable device

controller board. This

example is

written

in PL/M-Só

code and is

intended

to be

qeneric

in nature.

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

* This exaurple sends a data nessagè to the bootable

* controller board located in slot 1 at port 500 of

* the MULTIBUS II systern.

The control portion of the message

sent is located *

i.n the 16-byte data array p$control$rnsg (Peripheral *

Conmand Message). The data portion of the nessage *

sent is located in the 100-bvÈe

data arrav *

send$data. *

Note that the progranmer is responsible for ".".r.irrg i

p$control$msg and the area containing the data *

portion of the rnessage are initialized lrith correct *

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

5-ló Bfi)tstrap l-oader

SAIPLE_BS$SEND:

D0;

DECI,ARE

s ocke

DECIARE socket$o s truc ture

(ho

s E$ id

Porr$

DECI^ARE

pgcontrol gms

(

l6 )

DECIARE

send$data( 100)

DECIARE data$adr

DECIARE data$ len8th

DECIARE

fl ags

DECIARE exception

DECTARE

sIoC LITEMLLY

DECI-ARE

port I-ITERALLY

DECIARE nul-l LITEMLLY

DECIARE length LITERALLY

CODE:

DO;

socket$o.host$ld:

socket$o

port$

id :

data$lengrh

fl ags

data$adr : coNvERT

DWORD

;

WORD

WORD)

AT (@socket);

BYTE;

BYTE

;

DWORD

;

WORD

;

WORD

;

WORD

;

,lH'

;

,1F4H'

;

'0H';

64H,

slot;

pórt;

length;

null;

ADDRESS

(Gsend$dara (0

) ) ;

. (Typical code to define

. the 16-byte p$control$msg btock

. holding the control message.

)

. (Typi-caÌ code to define

. the 100-byce message

. por

C ion. )

CALL BS

SEND

(socket, @p$concrol$msg(0),

datagadr,

data$

Lengt h, f [ags,@except ion) ;

IF exception <> 0

THEN CALL BSERROR;

. (Typical code to execute

. for success.ful sLaLus.

)

END CODE;

SMPLE_BS$SEND;

WRITING A CUSTOM

FIRST-STAGE

DRIVER

Bootstrap l,oader 5-17

WRITING A CUSTOM

FIRST-STAGE

DRIVER

CONDITION CODES

E$OK

BS$E$TRANSMISSION

exceptional conditions.

An error occurred

while

transmitting a

MULTIBUS II

message.

0000H

OOEIH

CALL BS$RECEIVE (socket,control$ptr,data$adr,data$length,

exception$ptr)

INPUT PARAMETERS

socket

control$ptr

data$adr

A DWORD of the form host$id:port$id identi$ing

the

remote sender.

A POINTER to the area in memory that receives

the

control message.

A DV/ORD containing the absolute address

of a d:rta

messrìge received. If data$adr is NULL (0), then the

host CPU board expects a control message. Otherwise,

data$adr

points

to a

contiguous buffer that receives the

data

portion of the message.

A WO

RD defining the

length of the

data message

received.

data$length

OUTPUT PARAMETERS

exception$ptr A POINTER to a

WORD

which

the Operating

System returns the exception code generated by this

Bootstrap Loader

Communication System call.

DESCRIPTION

The utility BS$RECEI\E,

enables a host CPU board to receive a message from a specific

device controller. The utilities call identifies the

MBII slot to

wait

on, the tlpe of message,

and addresses

for the control

portion

and, if necessary, the data portion

of the message.

To receive data messages, you must provide a buffer containing

adequate space in

which

capture the data. Ifyou do not supply a

large enough buffer, the receiving CPU host

rejects the message. Also, your application must make a call to

BS$RECEIVE before the

actual message

is sent. No facility for

queuing

asynchronously received

messages

exist.

5-18 Bootstrap LOader

WRITING A CUSTOM FIRST-STAGE

DRIVER

EXAMPLE

This example

illustrates

the fundamentals

message passing

from the hootable

device

controller

board to the

host CPU board.

This

example is written

in PL/M-86

code and is

intended

to be

seneric in nature.

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

* This example illustrates how a host CPU board *

* receives a data message

from the bootable *

* controller board located in slot 1 at port 500 of *

* the MULTIBUS

II system. *

* The controf portion of the message

rèceivèd is *

* located in the 16-byte array p$sCatus$msg *

* (Peripheral Starus Message)

. The data portion of *

* the nessage received is located in the 1024-byte *

* data array sent$data. *

***********************************************************)t /

SAHPLE

BSSRECEIVE:

DO:

DECIARE

DECI*ARE

DECI.ARE

DECIARE

DECl-ARE

DECIARE

DECLARE

DECIARE

DECISRE

DECIAREnu11

socke t

socket$o s truc ture

(host$id

porr$id

s tatus $msg

(

)

data$adr

data$length

flags

exception

s enr$

dara

(

1024)

Slot LITERALLY

POTI LITEMLLY

length LITEMLLY

DWORD

;

WORD

I.JORD)

AT (GsÒcket);

BYTE

;

DWORD

;

WORD

;

IIORD

;

WORD

;

BYTE

;

'lH';

,1F4H'

;

400H'

;

,OH';

Ll TEMLLY

CODE: DO;

socket$o. host$id : slot;

cnnl.ot(n ^^rt-( i À : port;

dara$length - lenglh;

fÌags : null;

dara$adr : CoNVERT_ADDRESS

(@sent$dara(0)

);

CALL BS

$RECEIVE

(socket, @p$status$nsg(0) ,

data$adr

.l^+^Cl^-^.r-

udL dv, r, '6t ", I I dés ,

\:cÀuFp L I u'r/ ,

Bootstrap Loader 5-r9

]F exception <> 0

THEN CALL BSERROR;

(Typical code to execute

for successful status. )

END

CODE;

SAMPLE_BS

$RECE

IVE

;

WRITINC

A CUSTOM

FIRST.STAGE

DRIVER

CONDITION

CODES

E$OK 0000H No

exceptional conditìons.

BS$E$BUFFER$SIZE 0082H The receive

clata buffer

posted is

too small.

BS$E$TRANSMISSION 00ElH An

error occurred

while

transmitting a

MULTIBUS II

message.

5.5.5

Message Broadcasting

Message

broadcasting enables one

control message to

out at the

same time to all

boards

(bus

agents) in the MULTIBUS

ll system.

Recall that the identification scheme

for boards

employs sockets,

which

have the

host$id:port$id form. Host$id

indicates the board

involved and

port$id indicates the unique I/O port within the board. During message

broadcasting, the host$id

portion of the socket is uninterpreted. Thus,

the message arrives

every board having a port identifieci

by port$id.

The

Bootstrap Loader Communication

System uses the bs$broadcast utility to support

message

broadcasting. The following utility

description presents bs$broadcast:

CALL BS$BROADCAST (socket,control$ptr,exception$ptr)

INPUT PARAMETERS

socket A DWORD of the form

host$id:port$id identifying the

remote destination.

The host$id component is ignored.

control$ptr A POINTER to the control message sent.

5-20 Bootstrap hader

WRITING A CUSTOM

FIRST.STAGE DRIYER

OUTPUT PARAMETER

exception$ptr A POINTER to a WORD to

which

the Operating

System returns

the exception code generated

by this

Bootstrap

Loader Communication

System call.

DESCR]PTION

The bs$broadcast

utiliry transmits

a single control

message to the MULTIBUS ll boards

having

port whose

ID matches the port$id

portion

of the

parameter

socket. This

message goes

out on all MULTIBUS

Il buses (iPSB parallel

system bus and/or iSSB serial

system

bus) connected to

the broadcastìng CPU

host board.

EXAMPLE

This

example illustrates the fundrrmentals

of broadcasting control

messages over a

MULTIBUS II system. This example is written

in PL/M-tì(r code and is inten<led to be

seneric in nature.

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

* This exarnple

illustrates ho\t a host CPU board *

* broadcasts a control message

to all systen boards *

* having a port$id of 500. During message *

* broadcascing. the host$id portion of socket is *

* ignored.

* The conirol Féss,?oe senE is

* (Peripheral Command Message.

located in p$control$msg *

****************************************************)t*******/

SAMPLF._BS

$BROADCAST

: D0;

DECIARE

DECI^ARE

DECIARE

DECI.ARE

socke

socket$o s L

ruc Lure

(host$id

porr$id

pgcontro

l grns

(

)

exceplion

slot LITEMLLY

POTI LITEMLLY

DWORD

;

I,JORD

WORD) AT (Gsocket);

AVTF.

WORD

;

,1H,.

,1F4H'

;

CODE: DO;

socket$o. host$ id * slot;

cò.Lai-q^ nnrt( i à : n^ri-'

CALL BS$BROADCAST

(

socket,

Gp$control$rnsg(0), @exception)

Bootstrap l-oader 5-21

IF èxception <> 0

THEN

CALL BS ERROR;

END

. (Typical code to execute

. for successfuÌ status .

)

END CODE;

SAMPLE-BS

9BROADCAST ;

WRITING A CUSTOM

FIRST-STACE

I)RIVER

CONDITION CODES

E$OK 000011 No exceptional conditions.

BSSESTRANSMISSION 00E

lH An error occurred

while

transmitting a MULTIBUS

message.

5.5.6

Transmission Modes

Data message transmissions are synchronous in that the sender of the message

waits for

the receiver of the message to rcturn a transmission status

value.

This

value

indicates

whether

or not the receiver successfully acquired the message. Control messages, however,

are

not

synchronous

in this manner. There is no indication to the sender that a

control

message has been received. Also, related to each tlT)e of message transmission is a

transaction ID value. The communication system

uses this

value

internally to match

requests with responses

and to indicate

whether

the message is an rsrp message or a

nonrsvp message. lf the message

sent

is not an rsvp message, the associated transaction ID

value

is zero. If the message sent is an rsvp message, the associated

transaction

ID value is

a nonzero

value

matched

to both the recìuest and the resoonse.

5.5.7

Interconnect

Space

The Bootstrap Loader Communication System

supports access to board interconnect

space. This access enables the driver to determine

critical device status information. The

Bootstrap Loader

Communication System provides

interconnect

space

access through two

system utilities:

BS$GET$INTERCONNECT and

BS$SET$INTERCONNECT.

When

you

use these calls within your

driver code,

you

must verify the value

read or

written

from

or to the interconnect

space is

u'hat you

expect. The Bootstrap

Loader code does not know

what

"correct"

values

should be

<-) ) Bfi)tstrap Loader

WRITING A CUSTOM

FIRST.STAGE

DRIVER

The following utility

description presents

BS$GEfiINTERCONNECT:

value

= BS$GET$INTERCONNECT (slot$number,reg$number,

exception$ptr)

INPUT

PARAMETERS

slot$number A BYTE

that specifies the MBII slot whose

interconnect

space is to be read.

You must speciry this

value

lbllows:

Value Meaning

0-19 specifies iPSB slot

numbers

0-19

20-23 illegal values

24-29 specifies iLBX slot numbers 0-5

30 illegal

3l specifies the iPSB slot ofthe CPU

that the calling software

executing on, regardless of the

actual iPSB slot number of the

CPU

32-255 illegal

values

reg$number A WORD

identifoing the interconnect register to be

read. This value

must be in the range of 0000H to

FFH (the

interconnect space definition).

OUTPUT PARAMETERS

value A BYTE containing the

contents of the interconnect

read.

exception$ptr A POINTER

to a

WORD

which

the Bootstrap

Luader

returns the exception code generated by this

Bootstrap

Loader Communication System call.

DESCRIFIION

The utility BS$GET$INTERCONNECT

reads the contents of the interconnect register

specified

by reg$number from the board specified

by slot$number and returns the contents

in the parameter value.

Bootstrap Loader 5-23

WRITING

A CUSTOM

FIRST-STAGE DRIVER

EXAMPLE

This example illustrates

the fundamentals of reading interconnect

space registers. The

example is

written in PL/M-86 code and is intended

to be generic in nature.

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

* This exarnple reads the general purpose reglster of che *

* unit deflnition record vithin the interconnect spacè *

* found on the board in slot nunber three. Note that *

* this code dóès no checking of stalus after each call to *

* BS$CET$

INTERCONNECT. The programmer Erust ensure the *

* value returned is correct. *

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

SA.I,fPLE_BS$GET$INTERCONNECT

: DO

;

DECIARE slot$nurnber BYTE;

DECI-ARE record$offset IíORD;

DECIARE unit$def$rec BYTE;

DECIAR-E rec$length$reg$off BYTE;

DECTARE

gen$staÈus$reg$off BYTE;

DECLARE record$found BYTE;

DECIÀRE eoE$rec BYTE;

DECI,ARE stacus woRD;

DECTARE value BYTE;

DECI-ARE

slot LITERALLY '3H' ;

DECIARE udr LITERALLY '0FEH'

DECIARE gsro LITERALLY 'OAH'

;

DECIARE eotrec LITERALLY '0FFH'

DECI,ARE rlro LITERALLY '01H' ;

DECLARE ro LITERALLY '020H'

CODE: D0;

slot$nurnber - slot;

unit$def$rec - udr;

gen$statusSreg$off

- gsro;

eot$rec - eotrec;

rec$ length$ reg$ o ff : rlro ;

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

* Set up to read the first nonheader record within the *

* intèrconnect space. This is done by establishing *

* record$offset past the interconnect space header *

* record, which in this case is 32 bytes long. *

*******************************************>r***************/

record$offset : ro;

5-24 Boolstrap LOader

WRITING

CUSTOM

FIRST.STACE

DR]VER

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

* Read the record type register (the firsE register *

* wlthin a record) of the first nonheader record into *

* the variable recordSfound. *

***********************************************************,/

record$f ound = BS$CEîgIMERCONNECT

(

s lotSnumber ,

recordSoffset,

Gstatus ) i

/***************************:t***********************:t***rt****

* Decerminè if this first record is the record we r^tant to *

* read from. If so, bypass the D0 IiHILE loop and get *

* right to reading the specifíc regiscer. lf noc, *

* and the record is not the EOT (End Of Tenplate) record, *

* execute the DO hTllLE loop to get at thè next rècórd. *

***************rk*******:&************************************/

D0 WHILE

(record$found o unit$def$rec) AND

(record$found <> eot$rec) ;

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

* Position record$offset to read lhe next sequential *

* record. This ís done by calllng BS

9CET$

INTERCONNECT *

* to read the aurrent record length, adding 2 (for the *

* tl^io

bytes used for the record type and record length *

* registers), and finally adding the current :r

* recordSoffset value. Note that record$offset + *

* rec

length$re g$o ff yields the interconnect register *

* that holds the current record length. *

**********************)t*************************************/

record$offset - record$offset + 2 +

ET$ 1NÎERCONNECT

(slot$nurnber,

record$offset +

re c

ngt

h$ re

g$o f

f ,

tatus ) ;

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

* Read the next record-type regi,ster into the variable *

* record$found. *

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

Bootstrap L0ader <-?

WRITINC A

CUSTOM

FIRST-STACE I)RIVER

CONDITION

CODES

E$OK 0000H No exceptional conditions.

The following

utility description presenrs

BS$SEfi INTERCONNECT:

record$found = BS

$cET$

INTERCONNECT

(slotSnunber,

recordSoffset,

Gstacus);

END

;

/******************************************************:P*****

* Ca11 BS

$GET$

INTERCONNECT to read the general status *

* register. The exact register location is deterurined by *

* adding the règister offset valuè gen$

s tatus $reg$o

ff to *

* record$offset *

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

value - BS

$GET$

INTERCONNECT

(

slot$nurnber,

record$offset + gen$status$reg$off ,

Gstatus).

END CODE:

END SA}fPLE-BS$GET$INTERCONNECT

;

CALL = BS$SET$INTERCONNECT (value,slot$number,reg$number,

exception$ptr)

s-26 Bootstrap Loader

WRITING A CUSTOM

FIRST-STAGE DRIVER

INPUT

PARAMETERS

value A BYTE containing the value

to be

written

into the interconnect register.

slot$number A BYTE

specirying the MBll slot

whose

interconnect

space

is to be

written.

You must specify this value as

follows:

Value

0- 19

20-23

24-29

32-255

Meaning

specifies iPSB slot numbers 0-19

illegal

values

specifies iLBX slot numbers 0-5

illegal

specifies

the

iPSB

slot of the CPU

that the calling software is

executing on, regardless

of the

actual iPSB slot number of

the

CPU

illegal

values

reg$number

OUTPUT

PARAMETERS

exception$ptr

A WORD

identifuing the interconnect register

to be

written.

This

value

must be in the range

of 0000H to

0lFFH (the interconnect

space definition).

A POINTER to a WORD in

which

the Bootstrap

Loader returns the exception code

generated

by this

Bootstrap Loader Communication System

call.

DESCRIPTION

The utility

BS$SET$INTERCONNECT

writes

the interconnect register

specified by

reg$number on the board specified by slot$number with the contents in the parameter

value.

Bootstrap Loader 5-27

WRITING

A CUSTOM

FIRST.STAGE

DRIVER

EXAMPLE

This example illustrates

the fundamentals

writing

interconnect

space registers.

The

example

is written in PL/M-86

code and is intended

to be

generic

in nature.

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

* This exarnple writes the conÈroller initÍalization *

* register of the parallel systen bus control record *

* within the interconnect space found on the board in *

* slot nunber three. Note that this code does no *

* checkinp of scatus after each call to *

* BS$GET$ INTERCoNNECî

and BS

s ET$ INTERCONNECT . Thè

* prograumer rnust ensure values returned and writcen are

* correct.

* This exarnple uses the sane record -

s earching scheme *

* shown ln the exanple for BS

$GET$

INTERCONNECT. *

************************************************************,/

SAI{PLE_BS

S ET$ INTERCONNECT : D0

;

DECI^ARE slot$nurnber BYTE;

DECLARE status \'ORD;

DECLARE record$offset WORD;

DECI-ARE

psb$ctrl$rec BYTE;

DECLARE

rec $

length$ re g$off BYTE;

DECIARE contr$ init$ reg$off BYTE;

DECI-ARE

record$found BYTE;

DECIARE eot$rec BYîE;

DECIARE host$mess$ id BYTE;

DECIARE sloÈ LITEMLLY ' 3H' ;

DECI,ARE

psbcr LITERALLY '6H' ;

DECLARE ciro LITERALLY 'DH';

DECLARE eotrec LITERALLY 'OFFH'

DECIARE

rlro LITEMLLY ' 01H' ;

DECIARE hnid LITERALLY 'AH';

DECIARE ro LITERALLY '020H'

CoDE:

DQ;

slot$number : slot;

psb$ctrl$rec : psbcr;

contr$init$reg$off - c iro;

eot$rec - eoLrec;

-^^C l --^fhC-^.C^FF - rlyò.

r cLY r c"ór "v ' ct1.?u.

host$mess$id - hnid;

5-28 B(ntstrap [,0ader

WRITING A CUSTOM FIRST-STAGE DRIVER

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

* Set up to read the first nonheader record wíthin the *

* intèrcónnect space. This is done by establishing *

* record$offset past the interconnect space header *

* record, which in this case is 32 bytes lóng. *

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

record$offset - ro;

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

* Read the record type register (thè first register *

* within a record) of the first nonheader record into *

* the variable record$found. *

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

record$found - BS

$cET$

INTERCONNECT

(s1ot$nurnber,

record$offset,

Gstatus);

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

* Deterrnine if chís first record is the record we wanc to *

* write. If so, bypass the D0 l+rHlLE

loop and proceed *

* 'rrítins the sne.ific repísrcr If n.lt end the record *

* is not the EOT (End Of Template) record, executè the DO

* I.IHILE loop to get at the next record. )t

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

DO WHILE

(record$found o psb$ctr1$rec) AND

(record$found O eot$rec) ;

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

* Position record9offset to read the next sequential *

* record. This is done

by calling BS$GET$ INTERCONNECT *

* to read the current record length, addíng 2 (for the *

* Èwo

bytes used for the record type and record length *

* registers), and finally adding the currenc *

* record$offset value. Note that record$offset + *

* rec9length$reg$off yields the interconnect regisrer *

* that holds the current record lengÈh. :*

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

record$o[[set : record$offset + 2 +

9GET$

INTERCONNECT

(

s lor$number

record$offset +

recglengthgreggoff ,

@status);

Bootstrap

l,oader 5-29

WRITING

A CUSTOM

FIRST.STAGE

DRIVER

CONDITION CODES

E$OK 0000H No exceptional conditions.

5.5.8

Driver

Code Considerations

When writing

the first-stage driver,

you

must

provide

two

procedures

to the Bootstrap

Loader: a device

initialization

prrredure

and a device read

procedure.

To be

compatible

with

the Bootstrap Loader, these procedures must perform the same steps as the

initialization and

read

procedures

listed in Sections 5.2 and 5.3.

An additional requirement for driver code used in a MULTIBUS

II environment stipulates

that code using any of the utilities shown in Sections 5.5.2 through 5.5.6 belong to the

Bootstrap Loader Drivers COMPACT sub-system. The reason for this requirement is

because all the utilities

are arcessible as NEAR calls.

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

* Read the nexÈ record-type register into the variable *

* record$found. *

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

record$found - BS

$GET$

INTERCONNECT

(slot$nurnber,

record$offset,

La tus

) ;

END

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

* call BsS SETS INTERCONNECT

to write the controller *

* initialization register. The exact register locatíon *

* is deternined by adding the register offset value *

* contr$ inl t$ reg$o

ff to record$offsèt. *

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

CALL BS

$SET$

INTERCONNECT

(hos

t$mess$ id, s

lot$number,

record$offset + contr$init$reg$off, @s

tatus

)

;

END CODE;

END SAMPLE-BS

S ET$INTERCONNECT

;

5-30 Bfi)tstrap k)ader

WRITING

CUSTOM FIRST.STAGE

DRIVER

In the

above example,

bs2pci is

the name

of the driver

ntodule. You

can name

your

driver

module any

unique name you

desire.

The two

following public

statements

declare

the devicc

initialization and

device read

procedures

as public.

These public

statements

enable the Bootstrap

Loader

code to access

them

as FAR

calls. Again, you

can

nante

your

device initialization

and reatl

procedures

any unique

name you

desire.

Next,

the two group

statements

cnsure that

this driver module

grouped

together with

the

Bootstrap

Loader utilities

as part

of the same

COMPACT sub-system.

You must usc

tlìc

two

group

names bsl_drivers

cgroup

irncl bsl_cirivers_dgroup

ancl the

two segment names

hsl clrivers

code and

bsl drivers

data.

FinaÌÌy, the

two assume statements

establish

the correct

values

for the

code seqment base

address and

the data segment

hase address,

cs and ds.

The following partial

code

provides

ln example

how to ensure your

driver

code is part

the Bootstrap

Loader

Driver

coMPACT sub-system.

In this example,

the cocling

is shown

using the

ASM86 programming

Ianguage.

name bs2pci

public device_ini t_2 24A

public devic

_read_Z24tt

l_dr ive rs_cgroup group

s l_dr ive rs_dgroup group

assume

cs: bs

l_dr ive

rs_c

group

assune ds: bs Ì_dr ive rs_dgroup

bs l_dr ive rs_data segment word

b s

1_dr ive rs*code

bsI drivers data

. (Typical

ends

segment byte

roc

pubÌ ic 'DATA'

code

)

s l_dr ive rs_data

bs l_dr ive r s_c ode

device inir 224A pubLic 'CODE'

far

bs1 drivers code

. (

Typical code)

ends

tsootstrap

l,Oader 5--t

WRITING

A CUSTONI

FIRST-STAGE

I)RIVER

The following

algorithm

is an example

that

illustrates

both

a method

of using

the

Bootstrap

Loader

Communication

System

es a way of

verifuing a certain

board is

present

in the

system

anrl of using

the utility

BS$GET$INTE,RCONNECT.

The example

written

using

pseudo

code

that is

not meant

to represent

any known

programming

language.

*BEGIN COMMENTS:

* Paraneters received are BOARD$ID

and INSTANCE.

* BOARD$ID

is the identificatlon value

* Òf fhe troard beins looked for.

* INSTANCE

Ís the instance of a particular

* troard on the parallel bus system. This

* parameter allows for multiple occurrences of

* the sarne board within the MULTIBUS II systern

* Parameters returned are iPSB$SLOT

* iPsB$sLoT is the MULTIBUS

II board slot when the board

* is found, or the value OFFH when Lhe board is

* not found.

* Note that the variable VENDOR_ID

poínts to the

* cnoní fi. ínl"ar.nnnpr.l- sna.p rèpister fhat

* concains the board identification value.

*END COMMENTS:

**********************************-x***************

*BECIN

CODE:

* DO

until all MULTIBUS

II board slots on the PSB are

* sequentially examined. Use the variabÌe

* iPSB$SLOT

as the looping variable to indicate

* the slor nunber for che board being examined.

* VENDOR$ID

: BS

$GET$

INTERCONNECT

(

iPSB$SLOT,

* VENDOR ID, STATUS)

5-32 Bù)tstrap [,oader

WRITING

CUSTOM

FIRST-STAGE

I)RIVER

* rf

* the VENDOR$ID

returned is nonzero,

* a board exi-sts in the examined slot

* then

x Ìt

* VENDOR$ÌD

rnarche

s BoARDgtD

* then

* lf

* INSTANCE

is the desired Ínstance of

* BOARD

* then

)t return lhe iPSBSSLOT

looping index to

* indicace the sl-oc number of BOARD$ID

* else

* If we have checked all board slots

* then

* Return the value OFFtt

as the ipSB$SLOT

* parameter indicating t-he

device

n to boot from does not exist.

* else

* Loop back to beginning to check the next

* board slot.

* END DO

*END CODE:

5.6.

CHANGING BS1.A86

OR BS1MB2.A86 TO

INCLUDE THE NEW

FIRST.STAGE

DRIVER

The first stage

of the Bootstrap

Loader obtains

information about the devices antl

their

associated

device

drivers from the Bootstrap

Loader configuration

file BS LA86 or

BS1MB2.A86.

To support

a custom device

driver,

you musr add to that file a TTDEVICE

macro

for each unit on the device thît your first-stage device driver supports.

For

example,

if tr.vo flexihle diskette drives

are attached to the

device,

you must add two

ToDEYICE macros to the list

(one

for each clrive).

Chapter 3 describes the syntax ol thc

%DEVICE macro.

Brntstrap hader 5-33

WRITING

A CUSTOM

FIRST-STAGE

I)RIVER

As an

example, Figure

5-3 shows

portion of the BSl.A86

file

that

was

changed

add

%DEVICE

macros for two

units

supported by a custom

first-stage

driver

(changes

BS lMB2.A86

would occur similarly).

The

units have

numbers 0 and

1, and their

physical

names are YZ\ and YZ1,

respectively.

The name

of the custom

driver device

initialization

procedure is NEWDEVICEINIT,

and

the name of the

device read

procedure is

NEWDEVICEREAD. Arrows

to the left

of the fisure show

the added

lines.

bs 1

$include

(

:bs1.

inc)

fcpu(80286)

;iSBC

188/48 initialization of the iAPX 188

;

iAPX_186_INIT

0fc38h

none

BObbh

none

003bh)

Zdevlce (b0

Zdevice (bao

- -> ldevlce(y20,

--> ldevlce (yzI,

Tend

Ò rlorrinaini t?5ú

Ò ..lorrinaini r?6ú

0, nesdevlceinit,

l, newdeviceinit,

deviceread254)

devic e re

ad2 64

)

newdevlceread)

newdeviceread)

Figure 5-3.

Nftrdilìed BSl.Att6

File

5.7. GENERATING

A NEW

FIRST STAGE CONTAINING

THE

CUSTOM

DEVICE

DRIVER

Once you have

written the custom clevice driver and changed

the Bootstrap Loader

Configuration files,

you must

generate ir new first stage that includes the custom

device

driver. To do so, follow the

steps below. (These steps

ilssume

that you use an iRMX II

system

to develop your cocle.)

l. Compìle or assemble

the first-stage clevice initialization

and device read

procedures.

For example, the following

command assembles device read

and device initialize

nroceclures that iìre

assumc(l to reside in the file NEWDEVICE l.Al'tfr.

- asm86 newdrivl .a86 object(newdrlvl .obj)

iRMX rr 8086/87/186 MACRO ASSEMBLER,

V2.0

ASSEMBLY COMPLETED, NO É]RRORS

IOUND

5-34 Bo0tstrap l,{)ader

WRITINC

CUSTOM

FIRST-STAGE I)RIVER

2. Insert the object modules

for the device read and the device

initialize

procedures

into

the object library of the

Bootstrap Loader. This library is named BS

1 .LIB

and

normally resides in the directory

/RMX2tlfr/BOOT

or /RMX86/BOOT. The

following

commands add the object modules generated

ìn Step l.

. LIB86

iRMX II 8086 LIBRARIAN

V2.O

Copyrlght 1980 INTEL CORPOMTION

*add newdrivl .obj to /rnx286/boot/bs1.1ib

3. Attach the directorv

containing the Bootstrap Loader configuration files as the current

default directorv:

- at tachf 11e

/rnx286 /boor ,

/tntx296 /boot

-tsF^^l ^.1 ^c è.

o! LdLL'Eu nJ ,V.

4. Generate a new first stage by invoking

the SUtsMIl'file named BSI.CSD. Chapter

describes the details of the invocation.

an erample, the following command assumes

that you have chosen 40000H as the memory location of the first stage antl 43000H as

the memory location of the seconcl stage.

This step assumes that you have made

appropriate changes to

the BSI.CSD file as

described earlier in this chapter.

The BSl.CSD file places the resulting located

Bootstrap Loader

in the file BSl.

One thing to remember about

this

procedure

is that because

you

added

your

device

driver

to the

object library of the Bootstnìp Loader, the device driver is automatically inclucled in

all future versions of the first stage

created bv BS 1.CSD.

B0otstrap lr'ader 5--t:

WRITING A

CUSTOM CHAPTER 6

THIRD.STAGE

DRIVER

6.1 INTRODUCTION

Ifyou plan to use

the Bootstrap Loatler to

load iRMX ll applications from a device for

which

no Intel-supplied

third-stage driver exists, you

can make one of two choices

dependent upon the

size ofyour loadlile:

. For

loadfiles smal-ter than i3.lt)K bytcs.

use the

generic

third stage.

'I'he

generic

third

stage uses the first-stage

delice cirivers

you

have already supplied. Since the loadlile

fits in the I megabyte aclclress space

supported in real mode, and first-stage device

drivers are

able to place the loadfile, no need

for

you

to create new device drivers exists

for the third stage.

. For loadfiles larger

than 840K bytes, use the device-specifìc

third

stage.

The device-

specific third stage uses new clevice drivers

that

you

must supply. These device drivers

run in

protected virtual

address

mode enabling the loadfile to be

placed

using the full

16 megabyte range of addresses.

This

chapter outlines the

procedure

lirr writing

a thirtl-stage tlriver needed lbr the device-

specific thir<J stage. To

assist

you

writing

your own tlrivers, the iRMX II package

contains the source code fbr a wor king

third stage driver. After installing

your

iRMX II

system, you

can find the sourcc corlc ìn the file

/RMX286/BOOT/BPMSC.A86.

6.2

WHAT A THIRD-STAGE

DEVICE DRIVER MUST

CONTAIN

The third stage device drìver, likc thc lirst stage, must contain a tlevice initialization and a

device read procedure. For the nrost p:rrt,

these

procedures

are

similar to their first-sta,'.,

counterparts.

However, two diflèrences exist.

. Both procedures must

reside

in the same

coLle segment.

. You must also create a PUUI-l(l sl,mbol that contains a pointer to the device driver

data segment. The third stage neerls this information so that it can create a descriptor

for the data segment, enabling the driver to access the segment in

protected morJe.

Bff)tsf rap Loader ó-l

WRITING A CUSTOM

TIIIRI)-STACE

I)RIVER

When developing codc for

your third

stlgc driver, you must remember

that the

second

stage always

loads the third stage. including

the

drivers

you

write. The only type

ofcode

that the second

stage can Ìoad is cocle

thrìt uses the 8086 object

module format (OMF-86),

Therefore,

you

must use t1086

tools

(ASM86,

Pl-/M-86,

LINK|6, etc.) to develop

the third-

stage device initialization and

read

procedures.

Even

though

you

use ll0lJf)

tools to delelop

your

driver code,

the resulting initialization

and

read

procedures

must

be able to run in

protccted mode. One ramification

of running

protected

mode is

thlt all long

pointers protluced by PL/M-86

(or by any other means)

that

were

correct

in real mode

ciìusc rn ILLECAL SELECTOR exception in protected

mocie.

Therefore, ifyou must

use lon{

pointers, your

clevice

initialization and

read

procedure must determine

whether

or not the

processor is ìn protected mode. If protected

mode is

active, the prrredure must replrce

all the selector

portions of

long

pointers

with a

new

selecîor that is

valid

protected

mode.

You can cietermine

the processor nrode

l.rv using the following assembly code:

DB oFH,01H,0E3H ;Opcode

for the ASM286 instruction

;SMSW

BX. You must use

;DB 0Fll,01H,0E3H because SMSW 1s an

;ASl"l286

ir'cr r'uct ion unrecognized by

;ASM86

AND BX, 01H ;Examine Lo\rest bit of MSll to see if

;CPU is running in PVM.

JZ REAL ;No, not running in PVAl'f.

. code to override ;Yes, running in PVAJ'I.

. selectors of i

. long pointers ;

If your driver code is going to operate in the MULTIBUS II environment, two

additional

driver code constraints exist. First, vou must follow the MULTIBUS II transport

protocol

for communication between the ciriver and the device controller you bootstrap load from.

You can accomplish this by using Bootstrap Loader Communication System utility calls

within your

driver code. Second,

you

n.rust

urganize your

driver code so that it belongs to

the BSL-Drivers

COM PACI'I

sub-systen.

h is llst requirement is necessary because the

Bootstrap Loader Communication St'stenr utilities are all NEAR calls.

The next two sections describe the interlrrce these procedures must present to the third

stage. The sections after that describe how to supply configuration information to the

driver and how to

qenerate

a thircl strge thut inclucles the new driver.

6-2 Brxfstrap

l-oader

WRITING A CUSTOM THIRD.STAGE I)RIVER

5.3 DEVICE INITIALIZATION

PROCEDURE

The device initialization

procedure must present

the following PL/M-86 interface to

the

third stage:

device$init: PROCEDURE

(unit) WORD PUBLIC:

DECURE unir WORD:

END deviceSinit:

where:

device$init The name of the

device initialization

procedure.

You can choose any

name

you wish

for this procedure,

as long as it does not conflict

with the

names of other third-stage procedures.

unit The device unit number as defined during Bootstrap

Loader

con[igur:ì t ion.

The WORD value

returned by the

procedure

must be the device

granularity,

in bytes, if the

device is ready, or zero

if the

dcvicc is not ready.

The third-stage device driver initialization procedure, (like the first-stage device

initialization procetlure)

must

perform

the following operations:

1. Test to see if the

device is

present.

If the device is not

present,

return the

value zero.

2. InitiaÌize the device

fbr reading. This is a device-dependent operation. For

guidance

in initializing

the

device, relèr to the hardware reference manual for the device.

3. Test to see if device

initialization

was

successful. If it

was

not, return the

value zero.

4. Read the device volume label to

to obtain the device

granularity. (For information

on the location anci organization

of the

volume

label, see the

|RMX

86 Disk

ijì cat i o n U t i li

r\ n n nua L)

5. If the attempt to obtain the device

granularity was

successful, return the device

granularity. Otherwise,

return the

value

zero.

NOTE

In addition to the above five steps, the

procedure

must follow

MULTIBUS II

transport

protocol

and belong to the BSL-Drivers COMPACT

sub-system if the

driver functions in a MULTIBUS II environment. Refer

to Section 5.5 for

more information

on these t\yo requirements.

Bootstrap lnader 6-3

WRITING A CUSTOM

THIRD-STAGE I)RIVER

Notice that the functions

of the first-stage and

the third-stage device initialization

procedures

are identical.

Therefore,

you

can

take two courses of action

provide

a devlce

initialization

procedure for the third-stage

custom driver.

1. You

can allow the first-stage custom

driver and the third-stage custom

driver to

share the same

data segment. In this case, the third-stage

device initialization

procedure

is redundant

because the device

was

initialized by

the first stage and any

data in

the data segment remains

valid.

Because

the third stage calls the device initialization

procedure

regardless

your

intentions,

you

must supply a third-stage driver device initialization

procedure

even

if it is redundant. However,

thc device initialization

procedure

can

empty

routine whose only function is to return the device

granularity read from the

common data segment.

2. You can require the first-stage

and third-stage drivers to use different data

segments.

In this case, the first-stage

and third-stage initialization

procedures

must

independently initialize their respective data segments.

With

this arrangement,

you

must

provide

two complete device initialization routines. However, because

their

functions are identical (except for assigning a

value

for the data segment),

you

can

use the same code for both nrocedures.

6.4

DEVICE READ PROCEDURE

The device read procedure must present the following PL/M-86 interface to the third

stage:

device$read: PROCEDURE

(unit, blk$num, buf$ptr) PUBLIC;

DECI^ARE unit WORD;

DECI-ARE blk$nurn DWORD

;

DECLARE buf$prr POINTER;

. (

code

)

END device$read;

where:

device$read The name of the device read procedure.

You can choose any name you

wish

for this procedure,

as long as it does not

conflict

with

the names of

any other third-stage procedure.

unit The device unit number as specified

during Bootstrap Loader

configuration.

6-4 Bootst rap hader

WRITING

A CUSTOM

THIRD-STAGE DRIl'ER

blk$num A 32-bit

value

specifying the number of the block that the Bootstrap

Loader

wants

the procedure to read. Each block is of device granularity

size,

with

the first hlock on

the device being bÌock 0.

buf$ptr A 32-bit pointer to the buffer in which

the device reacl

procedure

must

copy the

information it reads from

the

secondary storage device.

The device read

procedure

does not

return a

value

to the caller. lt simply reads data from

the bootstrap

device and

places

it in the memory location specified by the buf$ptr

parameter.

The third-stage and first-stage device read procedures perform similar

functions.

Therefore,

you

may

want

to create the third-stage read procedure by performing

modifications on the first-stage

read

procedure (if,

for instance, it has already been

written

and resides in PROM). lf the first-stage read procedure does not

yet

exist, you can

write

the third-stage read procedure first and then

modify it to create the first-stage procedure.

Unlike the Bootstrap Loader first stage, the third stage has no built-in facilities for

reporting I/O errors. That is, the cievice driver cannot call BS$ERROR. Therefore, ifyou

require I/O error reportìng, you must write a complete custom error-checking mechanism

and include it in the device read procedure. (For an

explanation

of BS$ERROR, refer to

Chapter

3.)

To be

compatible

with

the Bu)tstrap Loader, the device read

procedure

must

perform the

following steps:

l. Save the third stage DS

(the

data segment selector of the calling routine),

and then

copy the driver data segment selector from the AX register into the DS register.

(When calling the device read procedure, the third stage puts the driver data

segment selector

the

AX register.)

The

device

read

procedure must perform this

function immediately.

Because

manipulation

is not possible with

high-level languages

(such as

PL/M-8ó),

you must write

this

portion

of the device read

procedure in assembly

language

(ASM86).

2. Check whether the processor is in real or protected mode. lf the processor is

protected mode, you may want to initialize other selectors to appropriate

values

(buf$ptr for example).

Assuming

Step

I has already been accomplished,

you need

not initialize the code

(CS),

clata

(DS),

ancì stack

(SS)

registers. These registers

will

already be set correctly.

3. Read

the block (specified by the blk$num parameter) from the

bootstrap device

(specified

the

unit

paramcter) and place the data in the memory

location

specified by the buf$ptr

parameter.

4. Restore the third stage data segment selector to

the DS register. As

with Step l,

you

must write this code in assemblv language, because it involves

Bmtstrap I-0ader o-5

WRITING

A CUSTOM

THIRD-STAGE

DRIVER

NOTE

In addition to the above

steps, the procetlure must follow MULTIBUS II

transport

protocol

and

belong to the BSL-Drivers COMPACT sub-system if the

driver functions in a MULTIBUS ll environment. Refer to Section

5.-5 for

more information

on these two reauirements.

6.5

PROTECTED MODE CONSIDERATIONS

Because

you develop your driver

proceclures

using 80tì6

tools and run the

procedures in

protected mode, you should keep

several items in mind:

o When

the third

stage

calls

the device read procedure, it puts

the driver data segment

selector in the AX register. When first called, the device read

procedure

must

save the

DS used by the caller (the third stage data segment selector), and then copy

the driver

data segment selector from the AX register into the DS register. Before exiting,

the

procedure

must restore

the original contents of the DS register. If you are

writing

assembly language,

you can perform this operation as follows:

THE$DEVICE$READ

PROC

PUSH

MOV BP, SP

PUSH DS

Mov Ds, Ax

POP DS

POP BP

RET 8

THE$DEVICEgREAD

ENDP

FAR

:ue

L l1qor essao.LMy Lo

;arguments

'Gét Irl.rl datn ceornent

;Perforrn the device read

;functions

'RPql rrrc thi r.l qt:oc DS

;Restore

;Return

If you

are

writing

code in a high-level language (such as PL/M-86), you

still must code this

function in assembly language.

The reason for this restriction is because higher level

languages do not allow

you

to manipulate registers directly.

You can, however, combine

assembly language

with

your high-level language by writing

an assembly language

"shell"

that handles the register manipulation ancl

then calls a PL/M-86 procedure to perform the

other

device read functions. For instance,

the following example saves the third stage DS,

calls a high-level

language routine to do the device

read, and restores the third stage DS

returning.

6-6 Bu)tstrap l-oader

WRITING A CUSTOM

THIRD.STAGE DRIVER

THE$DEVTCE$READ PROC FAR

PUSH

BP ;Cet Addressability to

;argunents

MOV

BP, SP

PUSH DS :Save third stage DS

MoV DS, AX ;Get local data segnent

CALL PLù{READ ;Call a PLM

procedure Eo

;perforn the

.,1-.'i ^- F"--ríanc

POP OS ;Restore third stage DS

POP BP ;Restore BP

RET 8 ;Return

THE$DEVICE$READ

ENDP

Be careful

when

changing DS, SS, CS, or ES registers

while

protected mode. They

point to

valid

entries in the

g.lobal

descriptor table

(GDT) that

were prepared for your

driver

by the third stage. If you change any of these registers,

the new value must be a

valid GDT entry or an ILLEGAL SELECTOR or

a GENERAL PROTECTION

exception

will occur.

Do nclt link your code to PLM8r,.LlB,

bec:ruse the compiler issues long calls

procedures in that

library.

These long calls cause exceptions

when

the calls

are

attempted in

protected

mode.

The buf$ptr parameter the third stage

passes to the device read

procedure is a valid

pointer in real mode only. You can pass this

value

to the device

as a physical address,

but do not try

use it as a

pointer

protected mode. lfyou require a

pointer, replace

the buff$ptr selector

with

the third stage DS

value. This DS

value

is intact

when the

device read

procedure

is calletl.

6.6 SUPPLYING

CONFIGURATION lNFORMATION

TO THE

THIRD-STAGE DRIVEB

Like a first-stage device driver, all third-stage

drivers require configuration

information

about the devices they support. You can

provide this information either

by hard-coding it

into the driver or hy

creating

a special configuration file for the

device. Both of these

techniques

are the same for the lìrst and third

stages. Refer to the section

in Chapter 5

entitled "Supplying Configuration Information

to the First Stage" for

descriptions of

these

techniques.

Bmtstrap lrader 6-7

WRITING

A CUSTOM THIRD.STAGE I)RIVER

If you

decide to create configuration files for

your

first-stage and third-stage drivers,

you

should

probably

use a single configuration file for each device and

link it to

both the first-

stage and third-stage

drivers. The device-specific information is the same for both drivers,

and keeping the

information in

a single

file

prevents you

from

giving

conflicting

information

to the two drivers. You can include the configuration file by editing BS3.CSD

to assemble and

link the configuration file to the third stage. Refer to Section 5.4.2 for an

example that shows

the similar first-stage

process.

6.7 USING MULTIBUS@

IITRANSPORT PROTOCOL

If the driver

you

are creating functions

within

a MULTIBUS

I environment,

you

need not

read this section. Skip

to Section 6.[ì,

If the driver you

are creating functions within

a MULTIBUS Il environment, you must

write

the driver code

to use the MULTIBUS II message transport protocol.

To help

you

accomplish

this task, Intel provides

snrall, single-thread

communication system

that

enables

Bootstrap Loader

drivers to communicate with device

controllers

within

MULTIBUS ll environment. This

system is called the Bootstrap

Loader Communication

System,

and is a subset of the

Nucleus Communication System.

Concerning adherence

to the MULTIBUS II transport protocol,

requirements

for

third-

stage device

drivers and first-stage

device tlrivers

are identical. Thus, you should refer to

Section

5.5 for an overview of the

Bootstrap Loader

Communication System, the availabte

Bootstrap Loader

Communication System

utilities, and guidance

writing

the device

initialization and

device read

proceclures.

Should

you

desire

a more complete clescription

of Bootstrap

Loader Communication

System concepts

similar to Nucleus Contmunication

System concepts,

reîer to the Extended

|RMX II Nucleus User's

Guide in

Volume

2 of

the iRMX II documentation

set.

6.8

CHANGING 853.A86 TO

INCLUDE

THE NEW

THIRD.STAGE

DRIVER

The device-specific

third

stage ohtains information

about the

device and its associated

device driver

from the

Bootstrap Loatler configuration

file 853.A86.

To support a custom

device

driver, you

must add to that

file a cZDEVICE

macro for each

unit on the device that

your

first-stage device

driver supports.

For example,

if two flexible diskette

drives are

attached

to the

device, you must add

two

oZDEVICE

macros to the

list

(one

for each

drive).

Chapter 4 describes

the syntax of the 9óDEVICE

macro.

6-8 Booastrap l.oader

WRITING A CUSTOM

THIRD.STACE DRIVER

Figure

6-1 shows

portion

of the 853.A86

file that was

changed to add

%DEVICE macros

for two

units supported

by a custom third-stage

driver. The arrows

in the figure indicate

the

changes. The

new units have numhers

0 and

1, and their physical names

are YZ\ and

YZl, respectively. (These

physical

names must

match the names used

in the

VoDEYICE

macros

in the first-stage

configuration

file BSl.,{86

or BS1MB2.A86.) The

name of the

custom

driver device

initialization procedure

is NEWDEVICEINIT,

and

the name of the

device

read

procedure

NEWDEVICEREAD.

The

public

name of the driver

data

seqment

DATA NEWDEV.

ginclude (

:fl:bs3enf. inc

)

Ídevice (0,w0, device ini tmsc gen,

devicereadnsc gen,

data_msc)

fdevice (1,w1 ,

devlce in i tms cgen, devicereadns c gen,

data_rnsc

)

ldevice (

wfO

devic e ini rnsc gen,

devic ereadnscgen, data_msc

)

ldevlce (9,wfl,deviceinitmscgen,devlcereadmscgen,data_nsc)

ldevice (0, ba0, deviceinit264, devi ce

data_264)

--> Idevlce(0, yz0, newdevicelnlt, newdeviceread, data_newdev)

--> ldevice(1, yzl, newdevicelnft, nevdevlceread, data neudev)

;

;int1

Z lnt 3

;halt

%cpu_board (286/12)

lend

Figure

l. Changing the tsS3.A8ó File

6.9 GENERATING

A NEW THIRD

STAGE

CONTAINING

THE

CUSTOM DRIVER

Once you have written the custom

device driver and changed the Bodstrap Loader

Configuration

files, you must

genenrte

a device-specific

third stage that includes the

custom

device driver. To do so, perform the following

steps. (These steps assume that you

use

an iRMX system to develop your

code.)

l. Compiìe or assemble

the third-stage device

initialization and device read procedures.

For example, the following

command assembles device read and

device initialization

procedures

that reside in the file NEWDRIV3.A86.

Bootstrap [íader ó-9

WRITING

CUSTOM

THIRD-STAGE T)RIVER

- asn86 newdrív3. a86 obj ect

(nesdrlv3 . obj

)

iRlD{ rr 8086/87/L86 MACR0 ASSEMBLER, V2.0

copyrighr 1980, r981, 1982, INTEL CoRP.

ASSEMBLY COMPLETED, NO ERRORS FOUND

Insert the object modules for the device read and the devìce initialize procedures

into the Bootstrap Loader object library. This library is named BS3.LIB and

normally resides in the directory

/RMX8ó/BOOT or /RMX286/BOOT. The

following commands add the object modules

generated

in Step l.

- LIBS 6

iRMX II 8086 LIBMRIAN V2.O

CORPORATÍON

*add newdriv3. obj to /rnx2B6/boot/bs3.1ib

3. Attach the directory

containing the Bootstrap Loader configuration files as the

current

default directon .

- attachflle

/rnx286 /t>oot ,

/rnx286 /boot

.fl-,.}la; Aq q

Generate

a new third sta_qe by invoking the

SUBMIT file named

BS3.CSD.

Chapter

3 describes the

details of invoking BS3.CSD.

As an example, the

following

command

names the new third stage "NEW3STG,"

and

locates it at memory location 08C000H.

This step

assumes that you

have macle any appropriate

changes to the BS3.CSD file

that are required

to support trny configuration

files

you

might

have designed.

10 B(x)tstrap

k)ader

CHAPTER

ERROR

HANDLING

7.1 INTRODUCTION

If the

bootstrap

process

is unsuccessful,

the

Bootstrap

[-oader ìnitiates

error-

handling

procedures.

Notification

ol lailures

occurring

during the

loading process

clepends

the configuration

the first rrnrl

thirri stl,qes.

This

chupter

describes the

Bootstralt

Loader's error

handling

fncilities.

7.2

ANALYZING

BOOTSTRAP

LOADER

FAILURES

The

Bootstrap

Loader

can disp|rl

ntess:tges

at the termin.l when

bootstriìp

loacìing

unsuccessful.

As discusscd

in Cìhaptcr l. rhc

.I.CONSOLh,

.;T'EXT.

and

_cÉLIST macros

in the

BSERR.AE(I

filc

dcterminc *hcthcr or

not nìcssiìges

irre riispllyerJ when

crrors

occur

during the

first and secolrd

stlr-sts.

how detirilcd

the ntessages

are, and under what

circumstances

thev

are displayed.

As Cìhlpter

-l

explains.

the third stlqe

automaticllly

determines

if a

monitor is prescnt.

:rncl

il so.

displavs crror

messages

at the terminal

regardÌess

of the

first stage

coniigunttion.

The following

sections

describe whrrt

h;rp;rcns u

hen a bocttstrap

loutlinq

error occurs ancì

how to analyze the

errclr. Therc arc two situations

described: error anulvsis

when

nlessu_lllcs

are displayed,

and error

analvsis when

rnessaqcs are

displayccl.

7.2.1

Actions

Taken

by the

Bootstrap

Loader

After

an Error

After responding

to an

error hy pushing

a word

onto the stirck

and optionally

displaying a

message, the

Bootstrap

Loadcr cithcr

tries again, passcs

control

to a monitor,

or halts. lf

the

error ìs detected

in the

first or sccond

stlrqe,

the action

taken depends on whether

vour

BSERR.Atì6

file contains

fiA(lAIN. .;lNTl, .-;lN'fl, or _ciHALT

macro. If rhe errcl

is detected

ìn the third

stage, rhe acrion

r:rken

depends on whether your

BS3.A8ó

BC3.A8ó

file

contains an

cllN'f I, cilN'l']. or c.,iHALT

macro.

The only diffèrcnce

between the

clcvicc-spccilic

and

generic

third stagcs

is that the generie

third stage

never generates

the crror

codc "Dcvicc

Not Supported"

(rcler

to error code J.l

later

in this chapter),

becausc the

qeneric

third

stage supports

all the devices supported

lry

the

first stage.

you

invoke

the tsoorstrtrp

Loader

with

a device name that is not

supported by the

first staqe,

the

gcncric

third stage will

never

even

get

Ìoaded into memory.

Brxrtstrap

l-oader 7-l

ERROR HANDLING

7.2.2 Analyzing

Errors With

Displayed

Error Messages

If your

BSERR.A86

file contains

the

o/cCONSOLE,

ToTEXÎ,

or a/oLIST

macro, then

the

Bootstrap Loader

displays

an error message

at the terminal

whenever a failure occurs

the

bootstrap loading

process. The

message consists

of one or two parts. The

first

part,

which

always displayed,

is a numerical error

code. The second

part is a short description

of the error. Although

the second

part is always displayed

for third stage errors,

it is

displayed for first

and second stage

errors only if the T,ITEXT

or ToLIST

macro

is included.

Each numerical

error code has

two digits.

'l'he

first digit indicates, if possible, the stage

the bootstrap

loading process in

which the error occurred.

The second digit distinguishes

the types

of errors that can

occur in a

particular stage. There are four

possible values for

the first disit.

First Digit Stage

Can't tell

First

Second

irtl

The error

codes, their abbreviated cìisplay

messages, and their causes and meanings

are as

folìows.

Error Code: 0l

Description: I/O error

An I/O error occurred

iìt some undetcrmined time during

the bootstrap loading

process.

If the ToCONSOLE

macro is inclucled. the Bootstrap [.oader

places a code in the high-

order byte of the

word

it pushes onto the stack, so that

you

can further diagnose

the

problem. This byte identifies the drivcr lìrr the device that produced the error,

follows:

Code

08H

l5H

18H

25H

5lH

54H

()EOH

other

(in

range A0H-DFtl)

Driver

20tì

MSC

(with or

without

2l8A)

218A on CPU

board

1861224A

25r

254 or 264

SCSI

driver for

your custom

11 Brntstrap Lrader

ERROR

TIANI)LING

Note that

this device

code

is oven'ritten

when

the

description

is printerJ

if the

o/r'l'EXT

or ToLIST

macro is

included.

The last

entry

in the

list of

device c.des

assumes

that you

have written

device driver

for your

device

and

have identified

the driver

by some

c.de in

the inclicated

range

other values

are

reserved

for Intel

drivers.

For

information

about

how to incorporirtc

this

code

into the

driver,

see

Cihapter

Error

Code:

Description:

Error

Code:

Description:

Error Code:

Description:

Error

Code:

Description:

'fhe specific

device

designatet{

for bootstrap

loatJing

is not reatly.

This error occurs

only when

your

BSERR.AIJíT

f ile does

not

contain the

fTAUTO macro.

Thcrcforc.

either

the operator

has specified

a particular

device

or only

one dcvice

is in thc

Bootstrap

Loader's

tlevice

list,:rntl

the device

not rearjv.

Device

not readv.

Device

does

not exist. (lf BSERR.AIJ6

cuntuins

the

TcLIST nracro,

the display

then shows

the list of known devices.)

No devicc

rcu dv.

File not

founrl.

The device

name

entered

at thc console

has no cntry

in the Bootstrap

Loader's

devicc

list.

This error

occurs

only

when

I'our

tìSERR.A8(r

lile contains

thc

gIMANUAL

macro and you

enter

a device

name,

but the

device

name

you

enter

is not

known to thc

Bootstrap

Loader.

After

displaying

rhe

message,

the Bootstrap

Loader

tlispÌays the

names

of the clevices

in its

tlcvice

list.

None

of the devices

in the

l]ootstrup

l,oader's

device list are

readv.

This error occurs

only when

your

BSERR.A8(r

lile contains

the

9óAUTO or

oZMANUAL

macro and

vou

do not

enter a

device

name at

the console.

The

Bootstrap

Loader

could not

find the indicuterl

file

on the dcsignlrted

bootstriì[l

device.

This is the

default file

if no p:ìthname was

entered at the

console . Othenlise,

is the

file

whose

pathname

rlas

entered.

In iRMX II syste

ms, the

Bootstrap

Loacìer

could

not find

the third staqc.

Brntstrap

hader

ERROR HANI)LING

Error Code: 22

Description: Bad checksum.

While trying

to load

the target file

(the

application

system

for iRMX I systems,

or the

third stage for

iRMX II systems),

the Bootstrap

Loader

encountered

a checksum

error.

Each file consists

of several

records.

Associatetl

with each record

is a

checksum

value

that

specifies the

numerical

sum

(ignoring overflows)

of the bytes

in the record When

the

Bootstrap

Loader loacls

a file, it

computes a checksum

value for each record

and

compares

that

value to the recorded

checksum

value.

If there is a discrepancy

for

any

recorcl

in the

file, it usually

mcans

thrtt one or more

bytes of the file

have been

corrupted,

so the Bootstrap

Loirder

returns this message

instead of

continuing

the

process.

Error

Code: 23

Description: Premature

end of lile.

The

Bootstrap Loader

did not fintl

the required

encl-of-file records at

the end

of the

target

file

(the

application

system

1i)r iRMX I

systems, or the third

stage for iRMX ll

systems).

Error Code: 24

Description: No start

address tìruncl

in input file.

The Bootstrap

Loader successlully

loaded thc target

file but

was

unable

to transler

control to the

file, because initiirl

CS itnd IP

values were not present.

Error Code: 3l

Description: File not

found.

The

third stage

was

unable to

finrl the turqet file on the

designated bootstrap device.

Regardless

of the way you invokecl

the Bootstrap Loader, the target file is

expected to

have a .286 extension.

Error Code: 32

Description: Bad checksu m.

The third

stage encountered a checksum error

while

trying

to load the target file.

Error Cotle: 33

Description: Premature end of file.

The third

stage reached end-of-file ea rlier

than expected

while

attempting to load

the

target file.

7-4 Boolstrap hadcr

ERROR IIANI)LING

Error Code: 34

Description: Device

not

supportetJ.

The specifietl device

is not supported

by the device-specific third stage.

That is,

there

is no

%DEVICE macro invocation

for this device in the BS3.Auó file.

Error

Code: 35

Description: Invalitl file t1,pe.

The

target file is not an 8028ó bootloadable

file

(usually produced

by BLD2lt6).

7.2.3

Analyzing Errors Without Displayed

Error Messages

In most cases, you

can determìne the cause of

a Bootstrap Loader failure by obsen ing the

behavior of the

Bootstrap Loader

whcn

it fails

to load the application successlully. You

can then take steps to correct the

frriìure.

'l'able

4-1 Ìists some common behaviors and

possible

causes for failure. The table

iìssunles that the Bootstrap Loader is set up to halt if

it detects :ìn error. Before haÌting. the Bootstrap Loader places the error code into the CX

reglsler.

Another

possible

cause oî îailure. the eltècts of

which

are unpredictlble, is that the device

controller block

(as

determined

by the device's

wake-up

atldress) can be corrupted. To

avoid this kind of failure, ensure thiìt

neither the Bootstrap Loader nor the target fiJe

overlans

the device controller block 1ìrr the device.

Brxrtstrap Inader 7-5

ERROR IIANDLING

Table 7-t. Postmolem

Anallsis of

Bootstrap Inader Failure

Behavior of Loader Possible Ceuses

Bootstrap Ìoading

fa ils ìn

the first

stage. The indicated device

is not ready or is

not

known lo

thc B(ìoî\trap Loader

An I/O error occurred during

the first stage

<lrcrat ion.

Bootstrap loading fails in

the second stage. The indicated file is not on the device.

The file has no end-of-file

record or no start

irdtlress.

The file contains a checksum error.

An I/O error is occurring

during the second

stiìue

operat r()n.

Bo()tstrap Loader enters

second stage, but does not

h:rlt

or pass control trl

the

file it loads.

1'he Bootstrap Loader is attempting

to load

the

svstem,

or third

stage, on top of the

second stage.

The

second

stage is attempting to load

the

lile into

nonexistent

memory.

Bootstrap loading fìils in

the third stage. t he designated file with a .2lJ(r extension

was

not found on the device.

The third stage reached an end-of-file earÌier

t hun erpected.

he fiìe contained a checksum error.

An I/O error occurred during the third stagc

opera t io n.

he Bootstrap Loader is attempting to load

the second stage

on top of the Protected

Nlode th ird

stage.

l -tr Btxrtstrap Loader

ERROR IIANDLINC

7.2.4 lnitiahzation

Errors

If an

error occurs

during the

initialization

of one of

the layers of the

iRMX I or II

Operating

System, an

error message will

be displayed

at the console.

The message

lists the

name

of the layer whose

initialization

failed,

and gives the

iRMX exceptional

condition

code

that indicates the

cause of

the taìlure.

The following

is an example of the

kind of

message

that

will

be displayed:

HI INITIALIZATION: 0021H

Incerrupt 3 at 02 80

54D8

The messages

you see will be similar

to this one.

Refer to the Operator's Guirle to tltc iR!+íX 86 Hunum lnterftrce or the Operator's Guida to

the

Ex.tended |RMX II Humctn Inte rlìtce

for more information about the

condition codes.

Brxrtstrap Loader

APPENDIX A

AUTOMATIC

BOOT DEVICE

RECOGNITION

4.1 INTRODUCTION

Automatic Boot Device

Rccognition (ABDR) allows

the iRMX I or iRMX II Operating

System

to recognize

the device from which

it was

bootstrap

loaded and to assign a logicat

name

(normally:SD:)

to represent thiìt

clevice.

If you

use this feature.

you

can

confirurc versions

of the Operating System that are device

independent, that is,

versions you

can

load and run from any device your system supports.

This

section describes

the ABDR teature

in tletail. It consolidates information

lirund in

other

iRMX I manuals

and answcrs the

following

questions:

. How does

Automatic Boot

Devìce Recognition work?

. How do

you

configure

version

of the Operating System

that includes this featurc'/

4.2 HOW AUTOMATIC BOOT

DEVICE RECOGNITION

WORKS

The

Nucleus, the Extended I/O System.

and the

Bootstrap Loader combine to

provide

the

Automatic Boot Device

Recognition ltature,

as lbllcws:

l. The Bootstrap Loader, aftcr

loliding the Operating

System,

places

pointer

in thc

Dl:SI register pair. This pointer

froints

to a

string containing the name of the devrce

from

which

the system

was

lorrcled.

The name it uses is the

one supplied as a

parameter in the

9óDEVICE macro when

the l3ootstrap Loader

was

configured.

2. The

Bootstrap Loader sets the

CX and DX registers to the

value

1234H. This value

signifies

that the

pointer

containetl ìn the DI:SI register pair is valid.

3. The root

job

checks

CX ancl DX and thcn, if both contain

12341{, uses the

pointer

DI:SI to obtain the device

nitnte.

'l'he

Root Job sets a Boolean variable to indicate

whether

it found

the nume of the boot device.

If CX contains 1234H and DX

contains

l235ll, the iRMX root

job

will

execute an INT3 instruction befbre any

other

code in the Openrting

Svstent is executed.

B{rctstrap

l,oader A-l

AUTOMATIC

BOOT DEVICE RECOGNITION

The Nucleus checks

the Root Jol;'s

Boolean

variable and, if true

(equal to 0FFH),

places

the

device name in

a segment and

catalogues

that segment in the root

job's

object

directory under

the name RQBOOTED.

If it is false

(equal to 0), nothing

catalogued in the Root

Job's directory.

The absence

of RQBOOTED from

the Root

Job's

directory indicates

the system

was

not

bootloaded or that ABDR was

not

selected.

The

Extended I/O System

looks up the name

RQBOOTED and, if successful,

obtains the device name

from the

segment catalogued there. If the

name

RQBOOTED is not catalogued

in the root

directory, the Extended I/O System uses

a default device name

specified during

the configuration of the Extended

I/O System

(DPN prompt of the "EIOS"

screen).

The Extended I/O System

attaches the device

as the system device, assigning

it the

logical

name that you must have

specified during the configuration

of the Extended

I/O System

(DLN prompt on the "EIOS"

screen).

A.3 HOW TO INCLUDE

AUTOMATIC BOOT

DEVICE RECOGNITION

This section describes

the operations

you

must

perform to include the ABDR feature in

your application. The operations include

. The ABR prompt

on the

"EIoS"

screcn

(Figure

A-1) affects

whether

the ABDR

feature will be included in

your

application.

If you

set ABR to "no," the Extended I/O

System does not attach a system

clevice. If you

set ABR to "yes," the Extended I/O

System automatically attaches

the system device. The ICU displays another screen

(shown

in Figure A-2) that lets

you

specify the characteristics

the system

device.

EIOS

-->(ABR) Autornatfc Boot Devlce Recognltlon IYes/No] Yes

(IBS) Incernal Buffer Size [O-OFFFFh] 0400H

(DDS)

Default lO Job Dírectory size [5-3840] 50

(ITP) Internal EIOS

Task's Priorities l0-2551 131

(PMI) EIOS Pool Mlnimum

IO-OFFFFHI 0180H

(PMA)

EIOS Pool Maxirnum

[0-0FFFFH] OFFFFFH

(CD) Configuration directory lL-45 charactersl :SD:RMX286/C0NFIC

Figure A-1. EIOS Confîguration Screen

(ABR)

A-2 Bootstrap l,0ad€r

AUTOMATIC BOOT DEVICE

RECOGNITION

. If you set

ABR to "yes,"

the ICU displays

the screen shown

in Figure A-2. On

this

screen, you

must speciry the

characteristics

of the system

device

via

the DLN, DPN,

DFD, and

DO prompts.

For the DLN,

DFD, and DO prompts, you

must

not supply

this information

later in the "Logical

Names" screen.

With

the DLN prompt, you

can specifo

the logical name for your

system device.

If you

change

this

value

from the default (SD),

you

must change all other

references to the

:SD:

logical name

to the new name you

speciff.

The Extended

I/O System creates the

logical name you

speci! only if you

set ABR to

"yes."

With

the DPN prompt,

you

specifo the physical

name of a device

that

you want

to use

as your system

device in case

the Extended

I/O System cannot find

the name

RQBOOTED

catalogued in the

root ohject directory.

This situation

normaÌly occurs

when

you

load

your

system using

a means other

than the Bootstrap

Loader. For

example, if you

transfer the Operating

System

your

target system via

the iSDM

monitor, there

is no bootstrap cievice.

In this case,

the Extended I/O System

uses the

device name specified

in the

DPN

prompt

as the system

devrce.

With

the DFD and

prompts,

you set

other characreristics

associated

with

the

system

device. For

most cases, the

defaults (DFD=Named

and DO=0000H) are the

nreferred

values.

(ABDR) Automatic Boot Device Recognitlon

-- ->(DLN) D,rfault Systen Device Logfcal Nane Il-12 chars] SD

-- ->(DPN)

D,:fault Systen Devlce Physlcal Nane [1-12 chars] rr0

--->(DFD) D,:fault Systen Device Flle Driver \P/S/N/R) Named

--->(DO) D,rfault Syster0

Devlce Osners ID [0-oFFFFH] 0000H

Figure

A-2. ABI)R

Screen

(DLN,

DPN,

DFD, DO)

. During configuration

of the Basic

I/O System, you

must specify device-unit

information for t

re devices you wish

to support.

One of the prompts on each "Device-

Unit lnformatior

screen (NAM) requires you

to specify the name

of the device-unit.

Another parameLer (UN) requires you

to specify the

unit number. (See Figure A-3 for

an example

of thr:se prompts.)

To enable the

ABDR lèature to

work

correctly, you

must assign device-unit

nantes and unit

numbers that match the device

names and unit

numbers

assignecl during

Bootstrap Loacler configuration.

. You assign the Br)dstrap

Loadcr dcvice

names and unit numbers by including or

motJifying

o/oDE\rICE

macros in the

first-stage configuration file

(BSl.A8ó

BS1MB2.Atl6). With

the lCU, you can

define device-unit names and unit numbers

other than those

that are

valid

tìrr the

Bootstrap Loadcr. But each Bootstrap Loader

device

name must have a

corresponding device-unit name, and the

unit numbers

must

the same.

Bootstrap Loader A-3

AUTOMATIC BOOT DEVICE

RECOGNITION

Before

you

can use the ABDR

feature,

you

must format

your system device using

the

FORMAT command.

The Guide to the Extended

|RMX Il lnteractive Configuratton

Utilirt^

describes

how to set up

your

system

device for use with the current release.

Figure A-3. Device-Unit Information Screen

(NAM

and UN)

(IMSC)

Mass Storage Controller Device-Unit lnformation

(DEV)

Device Name

[1-16 Characters]

--->(NAìl) Devlce-Unit Name

[1-14 chars]

(PFD) Physical File Driver Required IYesrzNo]

(NFD)

Named File Dríver Required lYes/Nol

(SDD)

Singlè or Double Density Disks ISingle/Double]

(SDS) Single or DoubIe Sided Disks ISingle/Double]

(EFI) 8 or 5 inch Disks l8l51

(SUF) Standard or Uniform Fornat lS

candard/Uni form

(GRA)

Cranularity [0

OFFFFH

]

(DSZ) Device Size [0

OFFFFFFFFH

]

- -->(UN) Unlt Number on this Devtce [O-OFFH]

(UIN) Unit Info Narne

lL-16 Charsl

(RUT)

Request Update Timeout l0-OFFFFHI

(NB) No. of Buffers Inonrarid : O/rand : 1-0FFFFH]

(CUP)

Comrnon Update lTrue/Fa

1s e

(MB) Max Buffers [0

OFFH

]

YES

DOUBLE

STANDARD

0100H

07c500H

0000H

0096H

0008H

TRUE

OFFH

A-4 Burtstrap Loader

AUTOMATIC BOOT DEVICE

RECOGNITIO\

4.4 HOW TO EXCLUDE

AUTOMATIC

BOOT DEVICE

RECOGNITION

configure a system that

does not include

the ABDR feature, set rhe

ABR prompt

in the

"EIOS" screen

"no" (see

Figure A-

1). This disables the

ABDR fèature.

When

you set

ABR to

"no",

the ICU will

not display

the ABDR screen. Therelbre,

you

must provide information

for the DLN,

DPN, DFD, and DO prompts as

input to the

"Logical

Names" screen. Figure A-4 shows

an example

of this screen after it has been filled

in to include a logical

name for the system

device. The underlined information

Figurc

A-4 is

the information you would

supply if you set the ABR prompt

in FigureA-l to

"no"

and you want

the system device

to be a flexible diskette drive

controlled by an iSBC 208

device

controller.

(LOCN) Logical Narnes

Logical Narne

: Iog_narne, devlce_narne,

fiÌe_driver, owners-id

[1-12 chars], [1-14 Chars], ÍP/S/N/R], [0-OFFFFH]

[1] Logical Name

: BB , BB , PHYSICAL, 0H

[2] Logical Name : STREAM , STREAI"f

, STREAM , 0H

[3] Logical Name

: LP , LP , PHYSICAL, 0H

--->[4] Logical Nane = SD , AFO , NAXED , 0H

Figure

A-,1. Logical Names

Screen

Bootstrap

[-oader A-5

APPENDIX

PROMMING

THE

BOOTSTRAP

LOADER

AND

THE

|SDM"

MONITOR

8.1 INTRODUCTION

chapter

2 stated

that one

of the ways

to prepare

the Bootstrap

Loader

for use is t'

combine

it with

one

of the Intel

monitor packages

and

burn the

combined

code into

PRoM. This appendir

suppÌies

intbrmation

about

combining

the Bootstrap

Loader and

the |SDM monitor. The iSDM

S;ver

n Debug

Monitor

lJser's

Guide also contains

information

about

this process.

8.2 INCORPORATING

THE

|SDM

MONITOR

This

section gives

the instructions

required

to place

the first stage

and

the iSDM monitor

into nvo

27128 EPROM

devices.

You

can modify

this example

to suit your

own purposes,

oryou

can follow

it exactly.

Refer

to the iPPS

PROM

PROGRAMMING

SOF|WARE

USER'S

GUIDE for detailed

inlìrrmation

about the commands.

The

step-by-step

procedure

is as follows:

1. Enter the

name

of the

(version

1.4 or later) software

used

with

the

iUpp Universal

PROM

Proerammer:

2. Specifo

that

the PROMs

irrc

2712R EPROM

devices:

3. Respond with

the

numbe r oî

the ciesired work

file drive:

This says

that drive :fl : * ill be usecl for creating temporary

IPPS workfiles.

4. lnitialize the file type

to be loacled:

This says that the

load file is an

li0lló Object

Module Format file (which the first

stage and the

iSDM monitor are).

Bff)tstrap k)ader B-l

PROMMING

THE BOOTSTRAP

LOADI]R ANI)

TTIE iSD]\I' MONITOR

5. Specify that

the even-numbcred

bytes of the BS

I (lirst stage) file

are to

go into

EPROM

0 and the odd-numbered

hytes

are to

into EPROM l. (The

address

FE400H is

an example

value

which

is compatible

with most configurations

the

iSDM R3.2 monitor.

The upper bound

of the format range is

OFFF7FH,

the highest

memory location the Bootstrap

Loader

can use when combining it

with

the iSDM

monitor. The upper

bound also applies

to all previous

versions of the iSDM

86 or

iSDM 286 monitors.

Always check

the monitor and Bootstrap

Loader memory

maps

before

burning the addresses

into the PROM devices.

Also, be sure that

the

addresses

you

use

do not collide. l'he numbers

3, 2, and I match IPPS

prompts

for

defining the information.)

6. Tell the software to

progriìm onc EPROM with even-addressetl bytes. Use

the

following

formula to determine the adilress to use:

a<ldress

= ((address of first stage)

- (start

address

of EPROM

ptk))12

Therefore:

address

= (FE400H-Fti000Il)/2

= 32001{

The IPPS command is as lbllows:

7. Do the same for the odd-numbered bvtes.

8. Exit the IPPS

program.

As a further example for step number sir above, the formula below determines the address

to speciff

when

using 27512 EPROM devices:

address

= (FE400H-0E0000H)/2

= 0F2000H

B-2 Btx)tstrap Iîader

INDEX

VoAgaín 3-27,29

VÒAufo 3-14

TaAuto_configure_memory

3- I 0

VoB208 3-32

7o8215 3-32

VoB218A 3-33

VoB220

3-32

VoB251 3-35

o/a8254

3-36

%B264 3-36

%BIST 3-8

%BMPS 3-11,4-5

TaBSCSI 3-37

o/oBSERR.A86

3-27

o/cClCO

3- 18

%Clear_SDM_extensions

3-18

TaConsole 3-14,

27, 28, 7

-1,,

EaCPU 3-rt, 4-5, 10

VoDefaukfile 3-17

VoDev tce 3

-24,

-6,

5-34, 6-8

VoEnd 3-27,31, 4-5, 12

%H^lt 3-27,30,4-5, l0

EA\APX 186 INIT 3-13

%lnstallition 4-5, t t

%lNTt 3-27,29,4-5,9

o/olN'î3

3-27, 30, 4-5, 10

ToLtst 3-27,28,7

-1,2

%Loadfl.e 3-16

VoManual 3-14

EÒR.etries 3-17

%SASl_unit_info 3-39, 4-7

%Serial_channel 3- 19

VaText 3-27,28,7-1,2

Bootstrap l,oader Index-l

INDEX

Actions taken

by the

Bootstrap

Loader after an error 7- I

Automatic

boot device recognition A- l, 2, 5

Automatically configuring memory 3- 10

8208.48ó 3-2,3l

82l5.A8ó 3-2,31,4-2

82l84.A86 3-2,31

B251.486 3-2,3l

8254.A86 3-2,31

8264.A86 3-2,3r,

4-2

BG3.A86 4-2

Default file 4--5

Editing

4-3

Excluding macros 4-3

BG3.CSD 4-2

Dethult file 4- 14

Invocation

4- 15

Modification 4-

Board-scan algorithm 5-32

Boot device recognition

A-1

Booting iRMXo

I and iRMX@ II Operating Systems from the same volume

1-4

Bootstrap

Loader communication system 5-8,

(r-lì

Bootstrap

Loader driver COMPACT sub-system 5-3I

Bootstrap Loader failures 7-1. fi

BS$BROADCAST

.5-20,21

BS$GET$INTERCONNECT .5-22,

BS$RECEIVE 5.IIì

BS$SEND

5.15, 16

BS$SEND$RSVP

5-1I. 12

BS$SET$INTERCONNECT

5-22, 26, 21

BSl.A86 3-1, 2, 5-33

Custom drivers

5-33

Editing

3-7

BSI.CSD 3-2,41

Default file 3-42

Invocation 3-4(r

Mo<lification

3-44

BS3.Atì6 4-2, 6-8

Editing 4-3

Excluding

macros 4-3

Modification 6-8

Index-2 Bu)tstrap l-{)ader

BS3.CSD

4.2, 13

Default file 4- 13

Invocation

l-5

Modification

4- 14

BSCSI.A86

3.2, 3I

BSERR.A86

3-I,7-I

Built-ln

Self Test (BIST)

3-8

Chip

mode

configuration

3- l3

Choosing

a third

stage

2-ó

CI routines

3- lll, l9

Clearing

iSDM

monitor

command

extensions

3-llJ

routines

3- 18, l9

Condition

codes

BS$BROADCAST

5-22

BS$GET$

INTERCONNECT

5-2Ó

BS$RECEIVE

.5-20

BS$SEND

5.1I.ì

BS$SEND$RSVP

5-I5

BS$SET$INTERCONNECT

5-30

Configuration

3-1,4-1

CPU board 4-

Files

3-31

Files for cuslom

driver:

-5-5

Firsl stage

Memory

3- 1t)

Message

passing syste

m 3-

| l, ,l--5

Processor

board type .1-

Third stage

4-l

Controlling

error

message displav

3-28

Conventions

CPU board

configuration

4-l(l

CPU type

3-11,4-10

CS register

integrity fi-7

INI)EX

B(x)tsl rap l/)ader lndcx--ì

INDEX

Custom

drivers

5-1,6-7

BS1.A8ó

alterations

5-33

BS3.A8ó

alterations

6-li

Configuration

files

-5-5

Determining

processing

mode

(r-2

Device

initialize

5-2,

Device

read 5-3, 6-4

First stage

configuration

5-4

First stage

considerations

5-30

First

stage requirements

5-1

Generating

the first

stage

5-34

Generating

the third

stage

6-9

Hard-coded

configuration

5-4

MULTIBUS@

II transport

protocol 5-8.6-tl

Protected

mode

6-fi

Third stage configuration

6-7

Third

stage requirements

ó-2

Debug

option 2-3

Default

BG3.All6 file 4-5

Default

BG3.csd file 4- l4

Default BS I.CSD 3-42

Default

BS3.CSD file

4- 13

Default

BSERR.A86

file 3-27

Default load

file 3- 17

Defining

bootable devices

First stage

3-24

Third

stage 4-(r

Defining

SASI bus initialization

sequences

l-39, 1-8

Device

driver I

-2,

7, 8

Code

considerations -5-3t)

Configuration

files 3-3 I

First stage 3-25

Device initialization

Requirements,

first stage

5-2

Requirements, thircì

stage

6-3

Procedure 5- l, 2,

ó-l,3

Device

read

Procedure 5- 1, 3,

6-1,.1

Requirements,

first stage 5-J

Requirements, third

stage 6-5

Dev

i.'e-specif ie third

strgv l-5

lndex-.1 Burtstrap Loader

Displayed error messages 7-2

Displaying error messages 3-26

Displaying

the load file

pathname

3- ló

Drivers, custom 5-l

Editing BSl.,486 3-7, 5-33

Errors

Analyzing 7-2, 5

Bootloading 3-27

Code 0l 7-2

Code I I 7-3

L,OOe tl /- 1

Code 13 7-3

LOOeZI /--t

Code 22 7-4

Code 23 7-4

CorJe

24 7

-4

Code 3 1 7-4

Co<le 32 7

-4

Code

33 7-4

Code 34 7-5

Code

35 7-5

Controlling message d isplay

ì-2ll

Handling 7- I

Initializatìon 7-7

Message display 3-28

Procedures 3-1, 8, 27, 1

-l

ES register integrity 6-7

Examples

Boa rd-scl n iìlgorithm 5-.1:

BS$BROADCAST 5-21

BS$GET$INTERCONNECl' 5-2.}

BS$RECEIVE -5.19

BS$SEND 5-I6

BS$SEND$RSVP 5-13

BS$SET$INTERCONNECT

5-2II

Maintaining DS register inte-urity

6-o

Modified BSl.A8fi file 5-l'l

Excluding a device

driver 3-26,45

Excluding automatic boot device

recognition A-5

Excluding BS 1.A86 macros 3-7

INI)EX

Bootstrap [,oader Indcx-5

INI)F],X

Failures 7-l

First stage l-1,2

BSI.CSD fíle 3-42

BSERR.A86

file 3-27

Configuration 3-1

Custom drivers 5- l, 3(l

Defining a hootable rlevice l-2,1

Device driver configuration

liles l-2

Device drivers 1-7

Device initialization 5-

1, 2

Device read 5- 1, 3

Error procedures 7- l

Fa ilure 7-(r

Generation 3-41

Generation for custonì drivers 5-3.1

Halting the boot 3-30

I nitialization re qu

ireme nts 5-2

iSDM' monitor inclusion B- |

Location l-2, fì,9, 3-17, 1-|ó

Placing in memory

2-4

Read requirements

5-3

Seconcl stage identilìcation

3- 1.1

Size l

-2

Steps when supplying your

own tlrivcrs 3-,10

Supported device drivers J-25

User-supplicd drivers

3-40

Generaîion

First stage containing a

custont devicc driver

-5-3.1

Third stage 4-

Third stage

(custom

device

cìrir.cr)

6-9

Generic th ird

stage l-4

Halting the Bootstrap

l-oader durinq errors

First stage

3-30

Third stage 4-

I{ard-coding custom

driver configuration information 5-.1

How to configure

the first stage l- I

How

to configure the

third stage

,l-1

How to define a device

to boot from. first sttrge

3-24

Index-6 B0otstrap L{rader

How to display

the load

fìle parhname

3-ló

How

to exclude

automatic boot

device

recognition

A-5

How to

include automatic

boot clevice

recognition

A-2

How to indicate

a default

load file 3-17

Identifying

the serial

channel

J- lt)

Including

automatic

boot device

recognition

A-2

Incorporating

the iSDM"

monitor B-

lnitialization

errors 7-7

Intel-supplied

BG3.A86 file 4-5

Intel-supplied

Bootstrap

Loader

cievice clrivers

l-tl

Intel-supplied

device

drivers 3-3

Intel-supplied

first

stage drivers

3-l-5

Intel-supplied

third stage

drivers

,1-7

Intel-supplied

third stage

files 2-7

lnterconnect

space 5-22

Interrupt

INTI 3-29, 4-9

INT3

3-30,4-10

Invocation

from the

iSDM monitor

2-2

Invoking

the BG3.CSD

submit files

4- 1-s

Invoking

the

BS I.CSD submit

file 3-4(r

Invoking

the BS3.CSD

submit

f ilcs

.1-

iSBCo

208 Driver 3-25

iSBC@

215 Driver 3-25.

4-7

iSBCo

251 Driver 3-2-5

iSBC@

254 Driver 3-25

iSBC@

2ó4 Driver 3-25, 4-7

iSBX@ 218A

Driver 3-25

iSDM*

monitor B-

iSDM"

monitor

command extensions,

clearing 3-l13

Load

file l

-5

Device

3- 14

Pathname

specification

2- I

the Bootstrap

Loader into

memory 2-.1

Location of

first stage 1-2

Location of second

stage l-3

INI)EX

Bootstrap

I-rnder Index-7

I\I)EX

Manual

oven'iew

iii

Memory

locations usecl

by the

BootstrlìP l-oacler

l-8, 3-47,

'1-

ló

Message

broadcasting

5-20

Message

passing system contigurrition

l- I l, 4-5

Message

types

5- l0

Modifying

the BG3.CSD

subrrit

fii,:s {- l1

Modifying

the BSl.CSD

submit file l--1.1

Modifying

the BS3.CSD

submit f ilcs

.l-

l.l

Monitor

entry after

third stagc

-1

MULTIBUS@

II environntent

5-i0.

6-]

MULTIBUS@

II trlnsport

protocol 5- l.

8, 6-2, ll

Naming

the Ìoad f

ile 1-5

Naming

the third

stage

1-5

Operator's role

2- l

Placing

the Boot:itrap Lolcjer

into mcnrorv l-.1

Product oven'iew iii, l-1

Program

matically loading the first

stagc 2--5

Promming the Bootstrap

l-oader uncl thc iSDM' monitor B- l

Protected mode

considerations

o-o

Reader level iii

Receive transaction model 5- l-5

Request/response

tnrnsaction model 5- 10

Retries

for ready devices 3-17

SASI

bus initializatìon sequence definition

l-39,4-u

SASI

controller 3-39, 4-7

SCSI controller

3-39, 4-7

SCSI

driver 3-25

Searchìng for a ready

device 3- l7

Index-8 Brxrlstrap Loadcr

Second stage 1-1,3

Error

procedures 7-

Failure

7-ó

Location 1-3, 8, 9, 3-47, 4-lrr

Size 1-3

Send transaction model 5- 15

Serial channel identification 3- 19

Serial communication

Base

port 3-20

Baud counter 3-21

Counter base

port 3-21

Counter

type 3-21

Flags 3-22

Serial communication 3-20

Error messages 3-23

Serial controller device 3-20

Software interrupt

(lNT1)

3-29,

,1-9

Software interrupt

(lNT3)

3-30,

4- 10

SS register integrity 6-7

Stages

1-2

Supplying con figu rat ion inform;rt ion

First stage driver 5-4

Third

stage

driver 6-7

Supplyingyour

own

device

driver

3-,10,4-l2

Supported 5.25-inch

diskettes 3-2ó

Supported

ll-inch diskettes 3-2(r

Supported tlevice drivers 3-2-5, J I

Supported

devices 1-8

Third stage l-2, 4

BG3.CSD file 4- 1,1

BS3.CSD file 4-

Choosing 2-(r

Configuration

files

.1-2

Custom

drivers fi- 1, fi-tì

Defining

a bootable devìce

.1-6

Device drivers l

-7

Device

initialization 6-3

Device

read 6-,1

Device-specific

l-5, 4- I

Error

procedures 7- l

rallure /-o

Generation 4- l3

INI)EX

Brxltstrap

l,oader Index-9

INDEX

Third stage

(cont.)

Generation for custom drivers 6-9

Generic 1-4, 4- 1

Halting the boot 4-10

lnitialization requirements 6-3

Intel-supplied 2-7

Location l-4, 8, 9, 4-16

Naming l-5

Read requirements 6-5

Steps for supplying your won drivers 4- 12

User-supplied

drivers 4- l2

Transaction ID value

5-22

Transmission

Modes

5-22

Status

5-22

User-supplied

drivers 3-40, 4- l2

Using

the Bootstrap Loader

2- I

Using the

iSDM debug option 2-,1

Writing a custom

first stage driver -5- I

Writing a custom

third stage clriver 6-

Index-10 Bff)tstrap l,oader

intel

EXTENDED

iRMX@II

SYSTEM

DEBUGGER

REFERENCE

MANUAL

lntel

Corporatlon

3065

Bowers Aven

u e

5anta Clara, Ca1 fornra 95051

1988, Intel

Corporation, A I Rights ReservedCopyright

PREFACE

INTRODUCTION

The iRMX II System Debugger

is a memory-resident extension

of the iSDM'r System

Debug

Monitor and the D-MON3li6 Monitor.

The System Debugger

gives you a

strìtic

debugging

tool that can recognize and display

all iRMX II objects. It enables

you

examine

your

iRMX II system interactively so

you can find and correct errors.

READER

LEVEL

This manual is intended

for applicatìon engineers familiar

with

the concepts

and

terminolory introduced in the E.ttended |RMX II Nuclcus

User's Guide

and system

programmers implementing clevice

tlrivers, olrject ntanagers,

and operating

systent

ext ensr ons.

MANUAL OVERVIEW

This manual consists of the followins

chanters:

Chapter I INTRODUCTTON--This

chapter describes the features

of the

System Dehugger, illustrates

how the System

Debugger relates

to EPROM-based clebugging

tools, and

explains how to use

the

System Debugger.

Read this chapter

you

are

going

through

the manual lbr thc first

time.

SYSTE,M DEBTJGG

ER COMMANDS--This

chapter contains

detailed descriptions

of the System Debugger

commands,

presented

alphabetical order.

When debugging

your system,

refèr to this chapter

for specific inlbrmation

about

the fìrrmat

and narameters of

the commands.

Chapter 2

System

Debugger

Chapter 3

Appendix A

Appendix B

CONVENTIONS

This manual uses

the follou'ing format conventions:

. User input

appears in one of the lbllowing forms:

iRMX@ II SYSTEM

DEBUCGER

OVERVIEW

SAMPLE DEBUG

SESSION--This chapter shows in a step-by-

step

1ìshion how to use System Debugger feetures. The

chapter

contains a sample debugging session clemonstrating how to use

iSDM monitor and System Debugger cclmmands to lociìte an

application-code error, correct it, and test the change. Discrete

examples showing

additional debugging techniques are also

included.

Use this chapter as a hands-on introduction to the

System Debugger.

iSDM MONITOR COMMANDS--This appendix brielly

describes the function of all basic iSDM monitor

commands.

Use this appendix as a quick

reference to the iSDM monitor.

For more information see the

iSDM Si.rtern Debu7 Monitor

User's Guide.

D-MON386 MONITOR COMMANDS--This

appendix briefly

describes the function

of all basic D-MOr..*3iìfi

monitor

commands. For more information.

refer to the D-MON-18ó

Dehup lvlonitor

for

the 80.18ó User's

Guùlc.

as bolded text withln a screen

The

text

> appears where

you

must enter a carriage

return. When pressing

the

carriage return

key, the text

> does not

appeîr on the console.

Although

all syntax

diugrams show uppercase

Ìerters (e.g., VR), you

can also use

lowercase

letters.

The

manual refers

to the iRMX II Operating System

as the opcrlting

syslem.

All numbers

unless otherwise

stated

are assumed to be decimal.

Hcxaclecimal

numbcrs

include

the "H" radix

chlracter (for

example, OFFH).

Darker shaded

text appelrring

over shaded

text within figures

or screen

displays does

not actually

appear on the screen.

The

text

within

the darker

bor supplies

information

that is

helpful in

understancling

the figure or screen

displav.

System Debugger

CONTENTS

CHAPTER

iRMX@

SYSTEM

DEBUGGER

OVERVIEW

CHAPTER 2

SYSTEM

DEBUGGER

COMMANDS

PAGE

System Debugger

CONTENTS

CHAPTER

SAMPLE

DEBUG SESSION

APPENDIX

ISDM"

MONITOR COMMANDS

APPENDIX B

D.MON386 COMMANDS

PAGE

vl System

I)cbugger

CONTENTS

APPENDIX

(continued) PAGE

FIGURES

FIGURE

1À

z-)

System Debugger vll

CONTENTS

FIGURE

2-7

2-8

2-9

2-10

2-11

2-t2

2-13

2-14

2-16

2-ltì

2-19

2-20

2-21

2-22

2-26

2-28

2-29

2-30

2-ll

l--)I

2-34

2-35

3-1

3-2

3-3

PAGE

Format

VJ Output

................ .......... ... . .2-

iRMX@ Il

Job Tree............. ..

............-..

.. .2-20

........,..............

F-ormat

VO Output

................ ........ ....

.2-24

Format

VR Output................. .-.........

. ..2-28

Format

VS Output ................ ..'. ..

... .....2-32

Format of

VT Output:

Job Display.........,...... .......

...............2-37

Format

f Output:

Non-lnterrupt

Task........ ................2-39

Format of

VT Output:

Intcrrupt

Task ................ .. ..... . . ..2-39

Format

Output:

Miìill)ox

with

Qucue.. -- ...... ... .2-42

Format

VT Output:

Mailbox

with Task

Queue

... .. .. .......

- -----.. ................2-42

Format

of VT Output:

Mailbox

with Ohjcct

Queue.......

.. .. .. .. . ....

..... . ...2-43

Format

of VT Output:

!f irillxrr

riith

Data

\'lcssirte

Queue..

. ..

.. .. . . ..

....l-13

Format

Output:

Se nrrrlthttre

u'ith No

QucLre

.... .. .. ........

. . .. .. . .. .

..2-'11

Format

VT Output:

Sennphore

* ith

Tlsk

Queuc...

.. . . . ..

. .. .. .. .. .. . 2-.l-5

Format

V'f Output: Region

u'ith

Que

ue.. ....... . .... 2-1-5

Format

of VT Output:

Rcqion

with Task

Queue.................

---.... .... .......

.......2'46

Format of

VT Output: Exte

nsion

()trject.................. ...... ..

.2-17

Format

V'f

Output:

Scgmcnt............................ ..... .. .. .. .2-'16

Format of

(lutpLrt:

Compositc

Otrject Othe

r Than 8IOS.......

.. .. . . .....2-11Ì

Format

of VT Output:

fillOS LJscr Oltjcct

Compc1site.............................

. 2-'19

Format of

Output:

BIOS Physical

File Conncction...................

.. .... . ...2-19

Format of

VT Output: IìlOS

Stream File C-Ìtnnection..................

.. . .. .. ..,...2--51

Format

Output:

13lOS Nunretj

frile Connection

...........................

... .. 2--5'1

Format

Output:

IìlOS Rcnrote

[ìile Connectitln.............................

.. .2-56

Format of

Output:

Sign:rl Prolocol

Port .....................................................2-51

Format of

Output:

Diìtir

'l'ransport

Prtttctcol

Port ......................-.............2-5ft

Format

of VT Output:

Data lntnsport Pr(}tocol

Port ....................................2-5lJ

Format of

V'f Output: Bufler Pool....................

. .................2-60

Format of

VLJ Output ................ ................2-63

Exampf

e PL/M-286 Applicltion

(lnit).................... ................3'2

Example

PL/M-286 Applic:rtron

(Alphonse)......... ................3-5

Example

PL.IM-286 Application

(Claston)............. ......,,........3-7

MOVW in Gaston

(ìrdc..... . .

. . . . . . . . . . . . . . . . . . . . . l

Ylll System

l)ebugger

IRMX@

SYSTEM

CHAPTER

DEBUGGER

OVERVIEW

1.1

INTRODUCING

THE

|RMX@

SYSTEM

DEBUGGER

When

you

develop

application

svstems, you

need debugging

capabilities

on your

development

system.

In addition

to the

iSDM

System Debug

Monitor

or the D-MoN3Err

Monitor,

Intel provides

rhe iRMX

System

Debugger

(SDB)

îor

debugging your

iRMX

I I-based

application

system.

NOTE

The remainder

of this

manual

uses

thc term',monitor',

to reler to

both the

iSDM System

Debug

Moniror

and

rhe

D-MON3lì(r

Monrror.

The System

Debugger

a memory-resident

extension

of the

monitor;

thereforc,

vou must

have the monitor if you have thc Systent

Debugger

confi{ured into

your system.

The

monitor provides

code

disassembly,

execution

breakpoinrs,

memory cJisplay,

and pro_qran.l

download

capahiÌities.

The

Systen

Debuqqer

extends

the monitor's

disassembly

funitions

by interpreting

iRMX II calls,

data

structurcs,

and

stacks.

Monitor

and

System

Debugger

conrmands

are

entcreci

in rcsponse

the isDM Monitor's

protected-mode

prompr

(..)

or rhe

D-MONl8(r

Moniror's prompt

(> ). When you

invoke

the

m.nitor,

both

the operating

systcm

and

y.ur applicati.n svstem

are li.zen. As vou

use

monltor

commands

to set ltreakpoints

while

the

application

code is executed,

you

can

inspect

system

objects,

change

systcm

call

parameters

and

regisrers,

and test chrrnees.

Refer

Appendix

A for

more information

iSDM M.nit.r commands

and

Appcndix

tor D-MON3tì6

Monitor

cornmanos.

System Debugger l-I

iRI\TX@

II SYSTEI\Í

I)EBTJGGER

OVERVIEW

1.2 SUPPORTING

THE

SYSTEM

DEBUGGER

To use the

System Debugger,

you must

have one of

the following

hardware

configurations

with all the required

support

hardware:

o An Intel MicrocomPuter

ctlnnected

to an

8021ì6- or 386-based

board

. A terminal connected

directly

to lrn

802iì(r- or 386-bltscd

lrortrtl

. An Intellec@

Development

Svstenì

connected

to an

E1)21ì(r- or 386-based

lxlard

In adclition

to the above

hardware, vou

must

have both

of the following:

o The

E,PROM

portion o1

the iSDM

System Debug

Monitor or

the D-MON3fì6

Monitor

. At least

the minimal

confisuration

of the

iRMX II Nucleus

1.3 CONFIGURING

THE SYSTEM

DEBUGGER

You

cannot use

the System Debuqqer

until ytttt inclutle

it in

vour s1'stem through

the

Interactive

Configuration

Utiliti,(ICLJ).

'fo include

the System Debugger,

begin

invoking

the ICU. Next,

provide

the following inlbrmation

the I(ìtJ

requires to

configure

the System Debuggcr:

1. In

the ICU's

"Sub-Systems"

screcn, respond

"yes" to the SDB

prompt.

2. In the ICU's

"System Debuqqer"

screcn,

set the interrupt

lcvel

vou

want

to use

invoke

the monitor

manually

(bv pressinq a hardware

interrupt button).

To use the

Non-Maskable Interrupt

(NMI) for debug-qing

tlevice drivers,

see the

Ertended |RMX II Hardn'are and Softv'are lrtstalloliott CLtitle.

For detailed information

on configurint

thc System Dehuggcr,

consult the Extenfud

iRlvIX II Interactive Confrguration

l.ltilif Rtftrotcc ltlartuttl.

1.4 INVOKING

THE

SYSTEM

DEBUGGER

You must enter the monitor

to use the Svstem Debu[qer.

You can invoke the

monitor in

tnree

ways:

l. Use a hardware switch

physically

connected to the

interrupt lcvel

you

specified

during

configuration. Activating

this su'itch halts the rrpplication

svstem, saves the

system's

contents, antl passes control

to thc nronitor.

2. Use the Human lntcrlìrcc

DEtsUG commrtnd. DEBUC loatls

y'our

specified

application

progriìm

into

main memorv and triìnslcrs

colìtrol to the monitor.

l-2 System

I)cbugger

iRMX@ II SYSTE]\Í DEBUGGER

O!'ERVIElV

3. Use

the Bootstrap Loader

DEtsLJG switch. When

you specify rhis switch,

the monitor

comes

up after the system

is loucled but

befìtre the system starts

running. Thc CS:lP

points

to the

first instruction

of the application

system. At this point

the system hus not

been initialized;

therefctre, you

can run only

monitrtr cctmmands.

Using the MAP2IJ(I

output, you

can identily where

vou

want

insert breakpoints. (For

more infitlnlttion

on BIND,

MAP, and OVL,

sec the

AI,X 286 Utilities

U.ser's Guitle

fttr

|RMX l/.$urlnr.r).

Use the break

address parameter

the monitor's

(G)

command to set breakpoints

in the application

systcm

cocle. When you

enter "G

<CR>",

thc system starts anLi is

initialized. The monitor

is invoked when

the CS:lP

reaches the breakpoints.

Iìor more

information on booting with

DE,BUG,

consult rhe

Extended |RMX II Bootstntp Loudcr

Reference Manual.

When you

invoke the

monitor, the

application system stops

running itnd all systerl activir\

freezes.

The appropriate

prompt

itppears

(the

".."

for the iSDM Monitor or thc "

for the

D-MON3tl6

Monitor), anci

you

cun bcqin entering

Systent Debuggcr and

moniror

commands

to exirmine

system objccts.

1.5

USING THE

SYSTEM DEBUGGER

The

System Debugger

uscs ntonitor

Jlrocedurcs

to parse

the command lino and to outltut

lo the console;

therefore, you

run both System

Debuggcr untl monitor comm:rncls

fì-orn the

monitor. The syntax for System Debugter

communds is a "V" or "v"

followed bv another

letter, an optional space,

und un optionirl

panìmeter.

The twelve System

Debueeer commirnds (described

in Chaptcr 2) fall into three cirteqorics:

. Eight commands extend

thc nronitor

mcmory display functions

by displaying ilìMX ll

data structures and

ot!ccts.

. Three commands extcnd

thc ntonitrtr

disasscmbly functions bv

rccognizing and

displaying iRMX II cals.

. A help command provides

a short description

of all the conìrnancls.

All commands cither display

inlìrrmation

as hexadecimal numbers or

try to intcrl)ret tlìe

information.

If the

System Debuucr clìnnot

interpret the information, it dìsplays

the

actual heradecimal value,

followed

by tu,o question

marks.

iRMX II provides

two features that e nable

vou to leave the monitor

without

rijsctting your

system: warm-start

and Cl-l-restart.

The

\ìarm-start

leature reinitialìzes the systent and

returns control to the

Human Intcrface.

The Cl-l-restart feature deletes the current

jotr

then returns control

to the flommlrntl [-ine

Interpreter. Refer to Chapter 2 for ntore

information on these

tèatures.

System

Debugger l --l

iRMX@ II SYSTENI

I)EBUGGER OVERVIEIV

1.6

RETURNING

YOUR

APPLICATION

When

you

have

finished

debugging

your application

system

with

the

System Debugger,

or if

you want to test the

changes

you made to

the apPlication

code, use

the monitor's

command

(G)

to resume

execution

of the

application.

l-4 System

l)ebugger

SYSTEM

DEBUGGER

CHAPTER

COMMANDS

2.1

INTRODUCTION

This

chapter

contains

detailed descrìptions

of the iRMX II System

Debugger contnlrnds.

Commands

appear

in alphabetical

orclcr, with

the îirst rrcurrence

euch command

appearing

in at the top

oI the page.

A directory

of the commands,

divicletl

into

lunctional groups,

precedes

the commrnd

descriptions.

This ehapter

uses

the [ollouin-[

\.(,n\(.nti(ìn\:

. "CS:lP"

is the Code

Segmcnt:lnstruct

ion Pointer--Thc

pointcr

to the instruction

thlt

would

be executed

next iî thc rrpplication

svstenì \r'cre

running.

vouspecifvirn Ip

value (one

fbur-digit

hexirciecirrrrl

number)

but not

iì CS

vlrlue,

the

Systenì Debuq,qcr

uses

the current CS

as thc delìtult

base.

o "SS:SP"

is the Stack

Segment:slrrck

Pointer--'['he pointer

to the

current stack

location.

. Entering zero (0)

as a

valuc

lirr an optional pirritnìetcr

is the sanre

as omitting the

parameter;

the defìrult vaÌuc

o1 thc pirrirmeter

uscd.

. All terminal

examples

assunle thrìt

the iSDM System

Debuq Monitor

is beinq usecl.

Thus, example

input

line s shou, rhe

iSDlvl monitor prompr (..).

2.2 CHECKING VALIDITY

OF TOKENS

Manv

System Debug-{er

communds

usc iRNIX

II tokcns îs plrameters

or display tokens

irs

part

the command output.

The

ilLMX II Operating Svstent

mirintains toke ns in rloublv

Ìinked

lists.

When

you enter

u token

its u plrulmeter,

the Svstem

Dcbugger chccks the

validity

the token by looking

at the tìrruarci

rnd backward

links of the token.

If one

of the links is bad,

thc Svstenr

l)ebuggcr genenìtes

Íìn error message along with the

standard command

output.

The token

vou

enter

as a

paranletcr

alw;rys

appcars lts the

center

value

each line of

the tokcn tlisplal'.

The displays for fìrru,arcl- and blckuald-link

erroÍs are as

lbllows:

Forward

link ERROR: .1

I I l--

>.lF.E5 .1ll

--.+trlJ-5--

4 155 'IFFFF<--,ll-s5

tsackward

lìnk E,RROR:

4lll-->110F'l 4 I I I

--4E85--

4 l5-5 4El.ì-5<--.1155

System

Debugger

System

Debugger

Commands

Arrows to the left indicate

backward links; arrows

to the right indicate forward

links. A

question

mark before or after

a value signifies a forward

or backward link

error,

respectively.

Ifboth links are bad,

the System Debugger

considers the token

invalid. A token

may also

be invalid if it belongs

to an object in the deletion

process, if an incorrect token

is entered

as a

parameter

in a system call, or if a deleted or unused

token is entered as a

parameter.

When the token is invalid, the

System Debugger displays

the following message:

*** lNvALlD ToKEN ***

A link error indicates that iRMX II data structures have

been corrupted. The

most

common reason

for this problem is

a task might have accidentally

written over

part of the

system data structures. However,

the iRMX II protection mode feature

protects against

such overwriting

under normal circumstances.

Data structure corruption

can also occur

you

are using the Non-Maskable

Interrupt

(NMI). The Nucleus

may have been

interrupted

while

was

setting up the links.

(The

NMI is a hardware interrupt.

For more

information on the NMI, see the

80286 Hardware Reference Manual or the 8038ó Hardware

Reference Manual.)

2.3 PICTORIAL REPRESENTATION OF SYNTAX

This chapter

uses a schematic device to illustrate command syntax. The

schematic consists

ofwhat looks

like an aerial

view

of a model raiìroad,

with syntactic

elements

(appearing in

circles) scattered along the track. To construct a

valid

command, imagine

that a train

enters the system at the far left, travels from left to right only

(backing up is not allowed),

chooses one branch at

each

fork, and finally departs at the far right. The command

generated

consists of the syntactic elements it encounters on its

journey.

The following

schematic shows two valid seouences: AC and BC.

2-2 System

Debugger

System

Debugger

Commands

These schematics do not show

spaces as elements, but you

may include one or more spaces

between

the command and parameter.

For example,

even though the syntax for VR is as

follows:

The following

command is

valicl:

The

space

between "VR" and "xxxx"

is optional.

2.4 LEAVING

THE MONITOR

Two features enable you

to leave the monitor

without

resetting your system:

wrrm-strrrt

and

CLI-restart.

The warm-start

feature is the

process

of starting a systcm without reloading it from

secondary storage.

Warm-start

rcinitializes

the

system,

that is, it begins executing

the

application system

at the same

point

whcre the Bootstrap Loader passes control to the

system.

warm-start

the system from the iSDM monitor, enter

the following command:

To warm-start the system from the

D-MON3lì6 monitor, enter the following commancl:

If no system code or data segments were

corrupted, the system reiniîializes. If segment

corruption has occurred, the application system will not run; you must reboot the system.

your

system contains a Command

Line Interpreter,

and running

your

application

program

causes an exception that brcaks to tht: monitor

(for

example, a General

Protection

exception), enter the following commlìnd to

CLI-restart the system from

the

iSDM monitor:

sagmenl

token

System Debugger 2-3

Systern

Debugger

Commands

Enter the following

command to CLI-restart

the system from the D-MON3lì6 monittlr:

These commands

causes the system to attempt

to delete the

job tree of the running task. If

the running task is

part of the

application's

job (not a subsystem

task running on behalf of

thejob) control returns to the Command

Line Interpreter. Otherwise,

you must reboot

the

system.

2.5

COMMAND

directory

ofjob "2280".

Enter

the following

command:

The

System

Debugger

responds with

DirecÈory slze: 000A

S 2228

R?IOUSER 2?OO

RQGLoBAL 2280

Entries used: 0003

The

symbols

'$", 'R?IOUSER",

and "RQGLOBAL"

are the names

of objects rhc sysrem

creates;

their

respective tokens

are 2228,2200,

and 2280.

There are no

waiting

tasks

invalid

entries.

System Debugger 2-13

The VF command

displays the

number

of free Global

Descriptor

Table

slots

available

the user.

PARAMETERS

The

VF command

has no parameters.

DESCRIFIION

The VF command displays

the number of free Global Descriptor

Table (GDT) slots

available

to the user, in the format shown in Figure2-4.

Number of free slots : xxxxxxxx

Figure 2-4. Format oflT Output.

2-14 System

Debugger

!T'..DISPI,AY NUMBER OF FREE

SLOTS

ERROR

MESSAGES

Syntax Error An

error was made

in entering

the command.

2-15

System

Debugger

The

VH command

displays and

briefly describes

the twelve

System

Debugger

commrrnds.

PARAMETERS

This command

has no

parameters.

DESCRIPTION

The VH command

lists all of the

System Debugger commands,

along

with their

parameters

and descriptions.

ERROR

MESSAGE

Syntax

Error An error

was

made

in entering the

command.

EXAMPLE

If you

enter

the following command:

2-16 System

Debugger

VH--DISPLAY

HEI.P

IN FORMAI]ON

The

System

Debugger responds

shown

in Figure

2-5.

Extended iRllx II SYSTEM

DEBUGGER,

Vx.y

vb <Dev

Narne> Displays DùlB for physical device.

vc [<POINTER>] Display sysrern

call.

vd <Job TOKEN> Display job,s objècr direcrÒry.

vf Dispì-ays

number

of free slots available ro user.

vh Display help inforrnation.

vj [<Job TOKEN>] Display job hierarchy from specified 1evel.

vk Display ready and sleeping rasks.

vo <Job

TQKEN> Display list of objects for specified job.

vr <Seg

TOKEN> Display I/0 RequestlResulr Segmènr.

vs [(count)] Display stack and syscem

caLl informaLion.

vt <TOKEN> Display iRMX

tl object.

a'u <task TOKEN> Unwind task stack, displaying system calls.

Figure

2-5. I'ormat

Output

Angle

brackets

surround

required variable

fields.

Square and

an_ule brackets

surround

optional fields.

NOTE

The system

uses default values

vou

speci|r

zero (0)

for any of the

optional

parameters

Figure 2-5.

LJsing zero

for requirecl

parameters causes

the

system

to display

the following

messrìge:

System Debugger 2-t7

The

VJ command

displays

the portion

of the

job

hierarchy

that descends

from

the

level

you

sDecifu.

PARAMETER

job

token The token

of the

job

for

which

you want to display

descendant

jobs.

If you

not specify a

job

token, or

you specifu zero

(0), VJ

displays

the root

job

and its descendant

jobs.

the

job

has more

than 44

generations ofjob

descendants,

the

System Debugger

disconîinues

the display

at the 44th

descendant

level, displays an error

message,

and prompts

for

another

command.

DESCRIPTION

The

VJ command displays

the token of the

specified

job

and

the tokens of all

its

descendant

jobs.

It also

displays the tokens

ofjobs

(and

their

descendants) at

the same

level as the

specified

job. The

tokens lbr descendant

jobs

are indented

three spaces

show their

job's

position

in the

hierarchy. Figure 2-6

shows the format

of the

job

hierarchy

disolav.

iRMx@ Il Job Tre e

tokenl

token2

token3

token4

tokent

token,

Rooc

Job

Hurnan I ntè rface

Command Line Inte rpre ter

App I lca

tí on

EIOS

BIOS

2- l8

Figure

2-6. Formal of VJ Oulput

Sysfem

Debugger

VJ-.DISPI-AY

JOB IIIERARCTIY

The fields in Figure 2-6 are

tokenl The token you

specified as

job

token

(recall that the rootjob

token is the default).

token2...token6 The tokens for the descendant

jobs

of token

In Figure 2-6, the Human Interface,

EIOS, and BIOS Jobs are indented

three spaces to

signify that they are children of the Root Job. Similarly, the Command Line Interpreter

Job is the child of the Human Interface Job,

and

the Application Job is the child of the

Command

Line

Interpreter

Job.

ERROR MESSAGES

Syntax Error An error

was

made in entering the

command.

TOKEN is not a Job A valid

token

was

entered that is not

ajob token.

TOKEN *** The

value

entered for the token is not a

valid token

(as

defined in

"Checking

Validity of Tokens" earlier in this

chapter).

SDB

job

nest limit The specified

job

(or

the

default

job)

has

exceeded more than 44

generations

ofjob descendants.

EXAMPLES

Ifyou want to examine the hierarchy of the root

job,

enter the following

command:

Suppose the System Debugger responds

with

the following

job

tree:

lRMx@ II Job Tree

0258

0F38

1670

2460

088 8

0E00

Figure 2-7 shows this

joh

tree:

System

Debugger 2-19

VJ--DISPL{Y

JOB

HIERARCHY

Root Job

(

0258

)

lluma

n Interface

(

0F38

)

C ornnand

Line Interpreter

(1610)

E IOS

(

0888

)

Figure

2-7. iRMXo ll Job

Tree

AppI icat ion

(2460)

If you

want

to display the descendant

jobs

"0E88", enter the following command:

2-20 System

Debugger

VJ..DISPT.4,Y

JOB HIERARCTIY

The System

Debugger displays

the following:

Note that

the tokens for alljobs

at the same

level as the specified token

(0E00

and 0F38),

and

their descendants (1ó70

antJ 2460),

are also displayed.

2-21

ÍR-ì{XO II JOb

0E88

0E00

0F38

1670

2460

Tree

System

Debugger

The VK command displays

the

tokens for tasks

in the ready

and

sleeping states.

PARAMETERS

This command

has no

parameters-

DESCRIPTION

The VK command displays

the tokens for tasks that are ready

and asleep, in the

format

shown

in Figure 2-8.

Ready casks: xxxx xxxx

Sleeping tasks: xxxx xxxx

Figure 2-8. Format ofVK Output

The fields in Figure 2-8

show the following:

Ready

tasks The tokens

for all tasks in the ready

state. The first token

in this

lìst represents

the running task

Sleeping

tasks The

tokens for all tasks in the sleeping

state.

ERROR MESSAGES

Syntax Error An error

was

made

in entering the command.

Ready tasks: Can't

locate The system is corrupted.

Sleeping tasks: Can't locate The most common reason for

this type of

error

not initializing the Nucleus. To recover

from this

error,

reinitialize

the system.

2-22 System

Debugger

VK..DISPI-AY READY

AND SLEEPING TASKS

EXAMPLE

To display

a iist of all the

ready and sleeping

tasks in your

system,

enter the following

command:

The System Debugger

responds

with the following:

2-2i

Ready tasks:

Sleeping taeks:

2F00

26F0

2020

20D0

2588

1FF8

0300

2688

2698 2200

2238 2180

2118 2090

2668 2588 2050

2638 27 68

System Debugger

The

VO command displays

the tokens for the

objects in the specified

job.

PARAMETER

job

token The

token of the

job

for

which you want

to display

objects.

DESCRIFTION

The VO command lists the tokens for a

job's

child

jobs,

tasks,

mailboxes,

semaphores,

regions, segrnents, extensions,

composites, and buffer pools in the format shown in

Figure

t_o

Child Jobs

Tasks :

Mailboxes:

S ernaphores

Segnents:

Extens ions

Cornposites

Buffer Pools:

XXXX

xxxx

XXXX

xxxx

XXXX

xxxx

XXXX

xxxx

XXXX

Figure 2-9. Format

of VO Output

The fields

in Fizure 2-9 are as follows:

Chiìd Jobs

Tasks

Mailboxes

The tokens for the specified

job's

offspring

jobs.

The tokens for the tasks in the specified

job.

The tokens for the mailboxes in the

job. An "o" following a

mailbox token means

that one or more objects are

queued

at the

maìlbox. A "t"

following a mailbox token means that one or

more tasks are queued at the mailbox.

2-24 System

Debugger

VO..DISPLAY

OBJECTS

IN A

JOB

Semaphores The tokens

for the semaphores

in the specified

job. A "t,'

following

a semaphore

token

means that

one or more tasks

are

queued

at the

semaphore.

Regions The tokens

for

the regions in the

specified

job. A,'b"

(busy)

following

a region

token means

that a task has

access to

information

guarded

by rhe region.

Segments The tokens

for the

segments in the specified

job.

Extensions The tokens

for the extensions

in the specified

job.

Composites The tokens

for the

composites in the specified

job. A ,'s,'

following

a composite

sigrifies a port with a signal

waiting. An

"m"

signifies

port

with

a message waiting.

A "t" signifies

port

with

a task waiting.

Buffer Pools The rokens

for the buffer pools

in the specified

job.

ERROR MESSAGES

Svntax Error I:J.T:Tff:Jff:ffil?',lTJ*command

or an

TOKEN

is not a Job A valid

token wa,

.nt"."dlho*"uer, it is not a

job

token.

... INVALID TOKEN *** The value

entered

for the token is not

valid

token

(as

defined.in

"Checking

Validity

of Tokens" earlier

in this

cnaDter

ì.

System Debugger ,-)<

VO.-DISPI-AY

OBJECTS

IN A JOB

EXAMPLE

If you

want

to look

at the objects

in the

job

having

the token

"1670", enter

the following

command:

The System Debugger responds

with the following:

This display

shows the tokens for the

childjobs, tasks, mailboxes,

semaphores, regions,

segments, extensions, composites,

and buffer

pools

in thejob. It also tells

you that tasks

are

waitins at four mailboxes and

one semaphore.

Child j obs

Tasks :

Mailboxes:

Sermphores

RegÍons:

Sègnents:

Extens ions

Conposites

Buffer pools:

2460

1688 t178 1788 1940 1950 2FF8

L720 1128 1738 r 1740 r 1760 r 1768 r

17A0 17A8 r

16D8 1750 1958 1960 2FE8 2Fc8

1690 16F0 1710 1828 1848 1980

2-26 System

Debugger

The

VR command

displays

information

about

the iRMX ll Basic I/O System I/O

Request/Result

Segment (IORS)

that

corresponds

the segment

token

you

enter.

PARAMETER

Segment

token The token

for a segment

containing

the IORS you want

display.

If this segment

is not

an IORS, the VR

command

returns

invalid

information.

To obtain

a list of the segment

tokens in

iob.

use

the

VO command.

DESCRIPTION

The VR command

displays

the

names and values

for

the fields of a specific

IORS.

The

contents

of the IORS reflect

the

most recent

I/O operation

in which

this IORS was

usec.

Except

for ensuring

the specified

segment

is between

45 and 65 bytes

long, the

System

Debugger

cannot determine

whether

the segment

contains

valid

IORS, so you

must

ensure

that it does.

If the parameter

valid

segment

token for a segment

contain

ing an

IORS,

the System

Debugger

displays informarion

about

rhe IORS as shown

in Figure

2-10.

For more

information

on l/O Request/Result

Segments,

see the Extended |RMX

II Basic

I/O System

User's Guide.

For

more detailed

information

about the

IORS contents,

see the

Extended |RMX II Device

Diven User's Guide.

System Debugger 2-27

VR..DISPT-AY

I/O REQUEST/REST]LT

SEGMENT

l/O Request Result Segment

Status xxxx Unit status xxxx

Device xxxx Unit xx

Function xxxxxxx Subfunction xxxxxxx

count xxxx Actual xxxx

Device location xxxxxxxx Buffer pointer xxxx:xxxx

Resp mailbox xxxx Aux pointer xxxx:xxxx

Link forward xxxx:xxxx Link backward xxxx:xxxx

Done xxxxx Cancel ID xxxx

Connection token xxxx

Figure

2-l{ì. Format of

Output

The

fields in Fisure 2- l0 are as follows:

Status The

condition

ctrtF for the l/O operation.

Unit status Additional status

information.

The contents

of this field

are

meaningful

only

when

the

Status field is

set to the E$lO

condition

(0028H). lf the Status

field is not set

to E$lO,

the

Unit Status

field displays

"N/A"

The number

of the device for

which this I/O request is

intended.

The number

of the unit for

which this l/O request

is intended.

The operation

performed by the Basic I/O System. The

possible functions

are

Device

Unit

Function

Reaci

Write

Seek

Special

Att Dev

Det Dev

Open

Svstem Call

RQ$A$READ

RQ$A$WRITE

RQ$A$SEEK

RQ$A$SPECIAL

RQ$A$

PH YSICAL$ATTACH$DEVICE

RQ$A$ PHYSICAL$DETACH$DEVICE

RQ$A$OPEN

RQ$A$CLOSE

If the Function field contains

an invalid

value,

the

System

Debugger

displays the actual

value

in this field,

followed

by a

space and

two question marks.

2-28 System

Debugger

VR.-DISPI-AY I/O REQUEST/RESULT SEGMENT

Subfunction A further specification

of the function

that applies only when the

Function field contains

"Special"

from

the BIOS

RQ$A$SPECIAL

system call. Possible

subfunctions lnci their

descript ions are

Subfunction Description

For/Que Format

or Query

Satis! Stream file satisfy function

Notify Notify funct ion

Device char Device characteristics

Get Term

Attr Get

terminal attributes

Set Term Attr Set terminal attributes

S ignl l Signal function

Rewind Rewind tape

Read File Mark Read file

mark on tape

Write

File Mark Write

file mark on taoe

Retention Trpe Take up slack on tlpi

Set Font Set character font

Set Bad

Info Set

bad track/sector information

Get Bad Info Get bad track/sector

information

If the Function field doesn't contain

"Special,"

thcn thc

Subfunction field contains "N/A." If the Subfunction field

contains an invalid value, the System Debugger displays the

valuc

of the field followed by a space and two

question marks.

Count The number of bytes of data called for in the I/O request.

Actual The number of bytes of data transferred in response

to the

requ(st.

Device location The eight-riigit hexadecimal address of the byte or logical block

where

the I/O operation began on the specified device.

Buffer pointer The adclress

the

buffer

the

Basic

I/O System read frcm, or

wr(ìtc

t(ì. in response to the request.

Resp mailbox A token for the response mailbox to

which

the device

sent thc

IORS after the operation.

Aux pointer The

pointer

to the location of auxiliary

data, if any. This field is

significant only

when

the Function field

contains

"Special."

Link

forward The adclress of the next IORS in the

queue

where

the IORS

waited

to be

processed.

Link

backward The address of the

IORS

in the

queue where the IORS

waited

to be orocessed.

Systern

Debugger 2-29

VR--DISPT-AY I/O REQUEST/RESULT SECMENT

Done This field is always

present but applies only to IORSs

for I/O

operations

on random-access devices.

When

applicable,

indicates

whether

the I/O operation has been

completed. The

possible values are TRUE (0FFH)

and FAI-SE

(00H).

Cancel ID A word used by device

drivers

to identi! I/O requests

that need

to be canceled. A value

of zero

(0)

indicates

a request that

cannot

be canceled.

Connection token The token for the file connection used to issue the request

for

the I/O ooeration.

ERROR

MESSAGES

Syntax Error No

parameter

was specified for the command or an

error

was

made in entering the command.

TOKEN is not a SEGMENT The token entered is

valid

but not a segment token.

*** INVALID TOKEN *** The

value

entered for the token is not a

valid

token

(as

defined in

"Checking Validity

of Tokens" earlier in this

chapter).

SECMENT wrong

size

- The specified segment is not berween 45 and

not an IORS 65 bytes long, so it is not an I/O Request/Result

Sesment.

2-30 System

Debugger

The

command identifies

system calls

(as does the VC

command) and displays the stack.

PARAMETER

A decimal

or hexadecimal value

that specifies the number of

words

from the stack to be included in the display. A suffix of T,

as in l6T, means decimal.

No suffix or a suffir of H indicates

hexadecimal.

If you

do not specify

a count, or you specify a count of zero (Lr,

the number

ofwords in the display depends on the number of

parameters

for

the system call at the CS:IP. Or, in the case

when CS:IP

is not

pointing

to a system call, the entire contents

of the stack

is disolaved.

DESCRIFTION

The

command identifies

iRMX II system calls for all

iRMX II subsystems

(as

does

the

VC command) and interprets the system

call

parameters

on the stack. If the stack does not

contain

system

call, the

command

displays either the number of stack elements

you

specifu or all of the stack

contents,

whichever

is least. If a

parameter

is a string, the System

Debugger displays the string.

For additional system call

information, see the appropriate

iRMX II Volume

3 system call

manual.

The VS command interprets

the CALL instruction

at the current CS:IP. If you want

interpret a CALL instruction

at a different

CS:IP

value, you

must move the CS:IP to that

value.

To move the

CS:lP using the iSDM monitor,

use the GO (G) command or the

EXAMINE/MODIFY REGISTER command (X with

CS or lP specified as

the

80286

80386 register). If you

are using the D-MON386 monitor, use only the GO command.

If the instruction is not a CALL instruction, VS

displays the contents

of the words on the

stack and no message. If the instruction is a CALL but

not a system call

(for

example, a

PLIM-286

call to a

procedure), VS

displays the stack contents and a message informing

you

that the CALL was

not a system call.

System Debugger 2-31

VS..DISPT.AY STACK AND SYSTE]IT

CALL INFORMATION

The

VS command uses current

values of the SS:SP

(Stack

Segment:Stack

Pointer) registers

to display

the current stack values. If the instruction

is an iRMX ll system call,

VS displays

the system call

and the stack information

as shown in Figure 2-11.

gare /INNNN

xxxx:xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx xxxx

XXXX:XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX XXXX

(

subsys tem)

system call

lparameters I

Figure 2-ll. Format of VS Output

The fields in Figure 2-l l are as folÌows:

xxxx:xxxx The contents of the SS:SP

(stack

memory addresses).

)oofi Values (tokens)

currently on the stack. The number of stack

values varies,

depending on the number

parameters in the

system call.

parameters The names of the stack

vaìues.

The parameters correspond to

the stack

values

directly above them.

The maximum number of

displayed para meters is 24.

The

three remaining fields in Figure 2-11 are

identical to those in the VC command:

gate

#NNNN The

gate

number associated with

the system call.

(subsystem) The iRMX ll Operating System layer that

the system call is

part

of.

system call The name of the

iRMX II system call.

) -7) System

I)€bugger

VS--I)ISPLAY

STACK

AND

SYSTEM

CALL INFORMATION

ERROR

MESSAGES

Syntax Error An error

was

made in entering the command.

Not a system CALL The CS:IP is pointing to a CALL instruction

that is not an

iRMX II

system call.

Unknown entry code This message indicates that one of two infrequent

events has

occurred. One is that the System Debugger

has mistaken an

operand belonging to some instruction

in the object code for the

FAR CALL instruction. The other event

is that a software link

from user code into iRMX ll code has

been corrupted. To

recover from system corruption, reboot the system.

EXAMPLES

Suppose you determine that

the SS:SP is

'1906:07CA

(using the iSDM Monitor's X

command, for example) then use the

command by entering

the following command:

The System Debugger

responds

with

the following:

gate /10360

1906:07cA 0808 1980 1EA8 1980 1980 0000 0800 1908

1906:07DA 19A0 0820 0s80 1EA8 1EA0 1EE8 0000 0000

(Nucleus) delete mailbox

. .excep$p. .

.rnbox.

The

parameter names identifo the stack

values

directly

above them. That

is, the

"excep$p"

parameter name signifies that the first two

words

represent

pointer (1980:0808) to the

exception code. Similarly, the

"mbox"

parameter

signifies

that the third

word

(18A8)

the

token for the mailbox being deleted.

Now, suppose that

you

move the

SS:SP to 2906:07D0. If you invoke the

VS command

entering

the following command:

System

Debugger 2--l-l

VS.-DISPLAY

STACK

AND

SYSTEM

CALL

INFORMATION

The System

Debugger displays

the following stack and a

message informing you that the

instruction

is a CALL instruction but

not an iRMX II system

call:

When

an iRMX II system call is executed,

its parameters

are pushed

onto the current

stack, and

then a CALL instruction

is issued with

the appropriate

stack address.

If the call

has more parameters

than will

fit on one

line, the System

Debugger automatically

displays

multiple

lines of stack values,

with corresponding

multiple lines of parameter

descriptions

directly below

them.

For example,

suppose

you

use the VS command

follows:

This

display indicates

thar the CALL instruction

a Nucleus

Re$CREATE$JOB

system

call with

18 parameters.

The names

of these parameters

are shown

between

the

vertical

bars (

| ). The words

on the

stack correspond

to the

Darameters

directlv below

them.

2906:07D0 2980

2906:0780 27 C8

Not a systen CALL

2980

27 C8 0000

25C8 0600

25C8 2908

25C8 29 A0

25C8 0020 1s80

25C8 25C8

gate i10310

zlcc:QF9A 015

8 2 0C8

27cc:OFAA 20E8 0028

27CC:0FBA 2608 tA58

(Nucleus) create job

0000

1AF8

20c8 20c8

0000 20C8

2608 0000

0000 0600 l1c8

OOEO 2FF8 2FF8

0000 0000 0000

l...excepgp...

l..cs..l..pri.

lpoolm-x

lpoolrnn

t$ flgs .

param.

stkszel..sp.

. exp$

info$p .

olrs 1z

. .

. . ds

. .

maxpri

Inaxtsk I

maxobj

2-34 System I)ebugger

VS--DISPI-AY

STACK

AND SYSTEM CALL INFORMATION

The following display shows that the

CALL instruction is a Basic I/O System

(BIOS)

RQ$A$ATTACH$FILE system

call

with

five parameters. The

"subpath$p"

parameter

points to a string seven

characters long: the word "example."

gate /10500

27CC|0F4E 0F88 17c8 25F8 0000 2600 29AO 0000 2600

27CC:0F5E 2608 1C10 2600 1320 26D0 0F78 0DF8 2FF8

(BIos) aÈtach fi 1e

l....excep$p...

l.rnbox. l..subpath$p.. l.prefixl.userl

subpath-

-) 07' exarnple'

The following

display indicates that the CALL instruction at CS:IP is an Extended I/O

System RQ$S$RENAME$FILE system call with

three

parameters. Two of the parameters

have strings: the

"new$path$p"

parameter points to a string

four

characters long

("XY70");

the "path$p" parameter points

to another string four characters long

("temp").

gate /f

06E8

27AC:0F98 0148 20c8 0858 20E8 0640 2088 0000 0600

27CC:0F48 17c8 2088 0028 1320 0000 20c8 0008 2600

l . . excepgp . . l . .

newgpathgp

. . l . . .

path$p

. . .

new

path-

-> 04

'XY70 '

paEh

- -> 04' teurp

NOTE

If a string is more than 50 characters long, the System Debugger displays

only

the first 50 characters. If the pointer is pointing to a nonreadable segment,

the

System Debugger does not display the string.

System

Debugger 2-35

The

VT command displays information

about the iRMX II object associated

with the token

you

enter.

PARAMETER

token The

token of the object for

which

you want to display

information.

DESCRIPIION

The VT command determines the type of iRMX II object represented by the token and

displays information about that object. Both the information and the

format

in which the

System Debugger displays the information depend on the type of object.

The following sections are divided into display groups illustrating the

display

format for

these iRMX II objects:

. Jobs . Segments

. Tasks o Extensions

. Mailboxes . Composite objects (six types)

r Semaphores . Buffer Pools

. Regions

ERROR MESSAGES

Svntax Error }:ffixTil::Jtr:i:;il:1i"JJ*comman'lr

or an

*** INVALID TOKEN +** The value entered

for the token is not a valid token

(as

defined in "Checkins Validitv

of Tokens" earlier in this

chapter

2-36 System

Debugger

VT--DISPI,AY

iRMX@

II OBJECT

JOB

DISPI,AY

If the parameter you specify is a

valid

job

token, the System

Debugger displays information

about the

job

having

that token, as Figure 2-12 shows.

Objecttype:1Job

Current tasks

Current obj ects

Directory s ize

Except handler

Pool min

Borro!.red

XXXX

xxxx : xxxx

XXXXX

Max tasks

Max obj ects

Entries used

Except rnode

PooI max

xxxx Max priority xx

xxxx Paraneter obj xxxx

xxxx Job flags xxxx

xx Parent job xxxx

xxxxx Initial size xxxxx

Bvte

ranse

44H

81-!H

200H

200H-

1K- 2K

2K-4K

4K- 8K

8K- 32K

Number chunks

xxxxxxxx

XXXXXXXX

xxxxxxxx

XXXXXXXX

xxxxxxxx

Largest chunk

XXXXXXXX

xxxxxxxx

XXXXXXXX

xxxxxxxx

Total memory

XXXXXXXX

xxxxxxxx

XXXXXXXX

xxxxxxxx

XXXXXXXX

xxxxxxxx

Figure 2-12. Format ofVT Output: Job

Display

The fields

in Figure 2-12 (from Ieli

to right) are as follows:

Current

tasks The number of

tasks currently existing

in the

job. If the Max

tasks is not 0FFFFH

(no limit), the number

of Current

tasks is

equal to the

Current tasks of

this

job

plus all

of its children

Max

tasks.

The maximum

number of tasks

that can exist

in the

job

simultaneously.

This

value was set

when the

job

was created.

The maximum

(numerically lowest)

priority allowed

for any one

task in the

job. This

value

was set when the

job

was created.

The

number of

objects currently

existing

in the

job.

The maximum number

of objects

that can

exist in the

job

simultaneously.

This

value was set

when thejob

was

created.

Max tasks

l\{a-r

priority

Current

objects

Max

objects

System

Debugger 2-37

W..DISPI,AY iRMX@ II OBJECT

Parameter

obj The token for

the object that the parentjob passed

to this

job.

This

value

was

set

when

the

job

was

created.

directory

listing the

functional

groups

and page

references

precedes

the

command

dev:riptions.

For

examples

and more

detailed

information

about

the commands,

see

the

D-MONJ86

Debug

Monitor

for the 8038ó llser's

Guide.

8.2 ENTERING

COMMANDS

To enter

D-MON386

commands,

the gui<Jelines

below:

o Terminate

command

line by pressing

rhe

ENTER key

or the

RETURN

(

)

key.

A command

line can

consist

of one or more

commands.

. Separate

multìple

commands

on a single

line using

a semicolon

(;).

o Continue

commands

from one

line to

another by

entering the

slash

(/) just

before

terminating

the line with

rhe

ENTER key

or RETURN

key.

. Enter

commands

using

upper or

lower case

characters.

o Use

CTRL-C (pressing

the control

key down while

at the same

time pressing

the C

key)

to abort a command

being constructed

on the

command line.

D-MON3Eó

System Debugger B-l

I)-MON386

COMMANDS

8.3 COMMAND

directory

files

volume free space map

free fnodes map

bad blocks

map

volume

label file

DESCRIPTION

DISPI-AYDIRECTORY displays a list of

files contained in the specified directory, along

with

their fnode numbers and tvoes.

You can then use other DISKVERIFY commands

examine the individual

files.

ERROR MESSAGES

argument error A nonnumeric character

was

specified in

the fnodenum

parameter.

fnodenum

fnode not The number specified for the fnodenum

allocated parameter

does not correspond to an

allocated fnode. This fnode does

not

represent an actual file.

<fnodenum>,

not a directory The number specified for the

fnodenum

fnode parameter is not an fnode for a directory

file.

fnodenum

fnode

out of range The number specified for the fnodenum

parameter

is larger

than

the

largest fnode

number on the

volume.

Disk Verification 2-21

DISPLAYDIRECTORY

EXAMPLE

The following command lists the files contained in the

directorv

whose

fnode is fnode

*DISPIAYDIRICTORY

6 <CR>

FILE NAME FNODE TYPE FILE NAME

R?SPACEMAP OOO1 SMAP R?FNODEMAP

R?VOLUMEU,BEL OOO5 VTAB R? SAVE

M1TILE OOO9 DATA YOURFILE

FNODE

TYPE FILE NAME FNODE TYPE

OOO2 FMAP R?BADBLOCKMAP OOO4 BMAP

0007 DATA Rlfl(286 0008 DIR

OOOA

DATA ONEFILE OOOB DATA

) -)7 Disk Verification

This command

displays the fields

associated

with an fnode. You

can abort this

command

by typing

a CONTROL-C. The format

of the DìSPTAYFNODE

command

is as follows:

INPUT PARAMETER

fnodenum Number

of the fnode to

be displayed.

This numbercan

range from

0 through

(max fnodes

- l), where max fnodes

is the number of

fnodes defined

when the

volume

was

orisinally

formatted.

OUTPUT

In response to

this command, DISPIAYFNODE displays

the fields

of the specified

fnode.

The format of the

display is as follows:

Fnode nuuber - <fnodenurn)

pach nane: <pathnarne>

flags

tYPe

t.. ^ l --^^

LLL- ÉLdtt/

OIJTìE T

create ,

access,mod t imes

t^È^r Ltr.-

bl-ock pointer (1)

block pointer (2)

hl nrlz nnJ nrpr /?\

block pointer (4)

t'l^-L ^^i-r-r /5\

hl nrlz nai ntar l6ì

block pointer (7)

block pointer (8)

this size

id count

accessor (1)

aeeessor (2)

accessor (3)

n..ahÈ rh or lz <r tm

aux (* )

<f1gs>

<tYP>

<gran>

<oLrn>

<crtine>, <acctine>,

<blks>, <blkptr)

<count>

<access), (id)

(access), (id)

Disk Yerification t-t1

DISPLAYFNODE

where:

fnodenum

> Number of the fnode being displayed. If the fnode does not

describe an actual

file

(that

is, if it is not allocated), the following

message appears next to this field:

*** AILOCATION STATUS

BIT IN THIS FNODE NOT SET

***

In this case, the fnode

fields are normally set to zero.

pathname

> FulÌ

pathname

of the file described

the

fnode. This field is not

displayed if the

fnode does not describe a file.

flgr

> A word defining the attributes

of the file. Significant birs of

this word are

as follows:

Bit Meaning

0 Allocation status.

This bit

is set to 1 for

allocated fnodes

and 0 for free

fnodes.

1 Long or short file attribute.

This bit is set to 1

for long

files and 0 for short files.

5 Modification

attribure. This bit

is set to 1

whenever

a file is modified.

ó Deletion attribute.

This bit is set ro 1 to

indicate a temporary

file or a file to be deleted.

The DISPLAYFNODE

command displays

a message

nexr to this

field to indicate whether

the file is a long

or short file.

typ

> Type

of file. This

field contains

value

and

a description

which

displayed

next to the value.

The

possible

values

and descriptions

are as follo\À's:

Value Descriptions

00 fnode

file

01 volume

map

file

02 fnode

map file

03 account

file

04 bad block

file

06 directory

file

08 data

file

09 volume

label file

gran

<own>

File granularity,

specified as a

multiple of the volume granularity.

User ID of the owner

of the

file.

2-24 Disk Verification

DISPLAYFNODE

<crtime> Time and date of file creation, last

access, and

acctime

> last modification. These vaiues are expressed

<modtime> the time, in seconds, since January 1, 1978.

totsize

> Total size,

in bytes, ofthe actual data in the fiìe.

<totblks> Total number of volume

blocks used by the

file, including indirect

block

overhead.

blks

>, <

blkptr

> Values

that identify the data blocks of the file. For short files, each

blks

> parameter

indicates the number

of volume blocks in the

data block, and each

<blkptr> is the number of the first such

volume

block. For long files, each

<blks> parameter indicates the

number of volume blocks pointed to by an indirect block,

and each

<blkptr > is the block number of the indirect block.

thissize

> Size in bytes of the total data space allocated to the

file, minus any

space used

for indirect blocks.

count

> Number of user IDs associated

with the file.

access

, <

> Each pair of fields indicates the access

rights for the file and the ID

ofthe user

who

has that access

ID. Bits in the

field are

set to indicate the following access

rights:

Data File Directory

Bit Ooeration Operation

0 delete delete

1 read list

2 append add entry

3 update change entry

The first ID listed is the owner's

ID.

<prnt > Fnode number of the directory file

that contains the file.

<checksum> Checksum of

the

fnode.

<auxbytes> Auxiliary bytes associated

with the file.

Appendix A contains a more detailed description of the fnode fields.

DESCRIFTION

Fnodes are system data structures on the

volume that describe the files on

the volume.

The fnode structures

are created when the

volume

is formatted. Each

time a file is

created on

the volume, the iRMX II Basic I/O System allocates

an fnode for the

file and

fills in the fnode fields to describe the fiìe. The

DISPI-A.YFNODE command

enables

you

to examine these fnodes

and determine

where

the data for each

file resides.

Disk Verification )-r\

DISPLAYFNODE

ERROR MESSAGES

argument error The value entered for the fnodenum

parameter was not a legitimate fnode

number.

fnodenum

>,fnode

out of range The number

specified for the fnodenum

parameter is larger than the largest

fnode

number on the

volume.

The pathname specified could not

retrieved. Possible causes of

this error

are seek error, I/O error, or invalid

parent.

Unable

to get pathname

reason

EXAMPLE

The

following example displays fnode 10 of a

volume.

This fnode represents a directory.

XDISPIAYFNODE 10 <CR>

Fnode number : I0

nr rh n.mo /M\'nTP

flaoc

tyPe

ollTte r

create ,

access,mod times

cotal size, total b locks

hl ^.L n^ínrar / I I

block polnter (2)

hl anlr nni nrar t ìl

Ll^^1. -^i-+^- //,\

9rvL^ P9llrLq! \Y/

h l arlz nni ntar r ( \

h l nalz nnJnrar i'At

hìnnlr nnintar /7\

h1 nnL -^i ^t-r / e\

this s ize

fd count

ecno<<nr / l \

accessof (2)

accessof (3)

n.ranr aha alz c' '-

aux(*)

0025

:>short fi Ie

06:)directory fl le

FFFF

I02L9017

, 10219E58,

00000360,

00000001

0001

, 000050

0000,000000

00000400

00 01

OF,

FFFF

00,0000

0006,

0000

000000

10219Es8

2-26 Disk Verifìcation

This command is

identical to DISPI-AYFNoDE, except

the DISPLAYSAVEFNoDE

takes

the fnode

information from the R?SAVE file,

and displays the

fnode as saved.

R?SAVE must

have been reserved

when

the

volume was formatted.

(That

is, the

RESERVE option in the FORMAT command

must have been

specified.) The format of

the DISPT-AYSAVEFNODE

command is as follows:

0212

ERROR MESSAGES

argument

error

fnodenum

fnode out of range

no save area

was

reservetl

when

volume was formatted

Unable to

get pathname

reason

When the command

was

entered,

argument

was supplied.

DISPTAYSAVEFNODE

requ ires

designation of

the fnode number.

The

number specified

for the fnodenum

parameter

larger than the largest

fnode

number on the

volume.

The

volume was not formatted

to support

backup fnodes.

This means the

RESERVE option

was

not

specified

when

the

volume

was

formatted.

The

pathname specified

could not

retrieved. Possible

causes of

thrs error

are seek error,

I/O error,

or invalid

parent.

fnodenu m

DISPLAYSAVE FNODE

Disk Verífication 2-27

This command displays the

"next"

volume

block.

(The "next" volume block is the block

immediately following the block currently in the

working

buffer.) The display

format can

be either WORD or BYTE. The utility remembers the mode

in which

you

displayed the

volume

block currently in the

working

buffer, and it displays the next block in that format.

So, if you

used DISPI-AYBYTE to display the current

volume

block, the next

volume

block appears in BYTE format; if you used

DISPLAYWORD, the next

volume block

appears

WORD

format. DISPLAYNEXTBLOCK uses the BYTE format as a default

ifyou have

not

yet

displayed a

volume

block. You can abort this command by typing a

CONTROL-C. The format of the DISPTAYNEXTBLOCK command is as follows:

0.205

OUTPUT

In response

to the command,

DISPI-AYNEXTBLOCK

reads the "next" volume block into

the

working

buffer and displays it on the

screen.

DESCRItrTION

The

DISPI,AYNEXTBLOCK

command copies

the

"next"

volume

block from rhe

volume

to the

working

buffer and displays it at your

terminal.

It destroys any data

currently in the

working

buffer.

Once the block

is in the

working

buffer,

you

can use

SUBSTITUTEBYTE

and SUBSTITUTEWORD

to change

the data in the block.

Finally,

you

can

use the WRITE command

write

the

modified block

back out to the

volume.

NOTE

If you

specifo the

DISPI-AYNEXTBLOCK

command

ar rhe end

of the

volume,

the utility'Vraps

around"

and displays the

first block

in the

votume.

I5PLAY N

EXTE LOCK

CARRIAGE RE-TU RN

2-28 Disk Verification

This command is identical to DISPLAYNEXTBLOCK

except

that it displays the

volume

block preceding the current block in the

working

buffer.

The format of the

DISPI-AYPREVIOUSBLOCK

command is as follows:

0206

2-29

Disk Verification

This command allows you to edit

values within

a specilìed fnode. It can be aborted by

enterins

CONTROL-C. The format of the EDITFNODE command is

INPUT PARAMETER

fnode Number of the

fnode to edit. This number

can be in the range of 0

through (max

fnodes

- l), where

max fnodes is the

number of fnodes

defined when

the

volume

was orisinallv

formatted.

OUTPUT

When

EDITFNODE

is invoked it displays the following

message:

Fnode nurnbe r - nnnn

where

nnnn is the number

of the fnode

you

want

îo edit.

The first field of

the fnode is

displayed with

its current value,

as follows:

f lags

(xxxx)

where

poo<

is the

current

value

of the flags field.

From this point

on,

you

can

edit the

fnode fields,

one at a time. After the last

fnode field has

been edited

or a',e,'has been

entered while

in edit

mode, the following

query

appears on the

screen and

the modilìed

fnode

is disolaved.

Write back?

A response

of "Yes"

causes

the fnode with the modified values

to be

written on the

volume

and the following

message

to be displayed:

Fnode has been updated

2-30 Disk Verification

EDITFNODE

Any

other response

causes the fnode

to remain unchanged

and

the following

message

be displayed:

Fnode not changed

DESCRIPTION

EDITFNODE

is used to change

values within a

specified fnode.

When it is invoked,

displays the message

shown above.

Once you receive

the invocation

message,

you can

edit

the fnode, one

field at a time. The

first field, flags,

is displayed

upon invocation

(as shown

above).

The current

value of each field

is displayed

followed by a

colon. EDITFNODE

then

waits for one of

the following responses

from the terminal.

Response Meaning

> No modification

to the field.

numerical

value

> The new

value to be assigned.

This

value is always

interPreted

as hexadecimal.

Quit

or Q or

> Skip

the remaining

fields

and

display

the

query.

Any response,

other than those

listed above,

causes the field

to remain

unchanged,

and

the next field

to be displayed.

Once the fnode

has been updated,

you can

use DISPLAYFNODE

to examine

the

contents of

the fnode and

the changes

you made. Changing

the

contents of

an fnode

causes it to have

a bad checksum.

Use FIX with the NAMED1 option

to correct

it. For

more details,

see

the ex?lanation

of FIX later

in this

chapter.

ERROR MESSAGES

argument

error The option

specified

is not

valid.

<fnode

num>, fnode

out of The fnode

number

specified

was

larger

range than

the largest

fnode

number

on the

volume.

Error

in Input Invalid input

was

entered

while editing

entry.

Disk Verification 2-l t

EDITFNODE

EXAMPLE

The following

example illustrates using EDITFNODE to edit fnode

10.

*edltfnode 10 <CR>

fnode nurnber - 10

flags(0025):<CR>

type(0006):<CR>

flle gran/vol gran(01) : <CR>

owner(0FFFF): 0 <CR>

créatè time(1O2I9CR2): q <CR>

Encering "q'r causes the modified fnode to be displayed.

fl ags

tYPe

s.:1^ -,-.^

r r rE ó!drrl vur ÉLdrr

OIJTìE

create

access,

mod tines

totaL si"ze,

total blocks

block poínter (1)

block pointer (2)

block pointer (3)

block pointer (4)

block pointer (5)

hl oelr nai nror /6 t

block pointer (7)

hl ó.L n^int ar 1R\

this s ize

i.d count

accessor (1)

accessor (2)

accessor (3)

nr rén t_ eha r lz <"-

aux

(

l,lrice back? yes <CR>

Fnode

has been updated

0025 -)short fi Ie

OA:>rlirartnrrr fí1a

0000

10219C82,

10219CC8,

10219 CC8

00000360,

00000001

0001, 0000s0

0000, 000000

0000,000000

0000,

000000

0000,

000000

0000,000000

0000, 000000

00000400

0001

OF, FFFF

00, 0000

0006,

0000

000000

2-32 Disk Verification

EDITSAVEFNODE

is identical

to EDITFNODE,

except

that it allows

you

edit an

fnode from the

R?SAVE file.

(R?SAVE

must have

been reserved

when

the

volume

was

formatted.)

In addition, it designates

the fnode

as saved

when displaying

the

fnode

number. You can

abort this command

by entering

CONTROL-C.

The

format

of the

EDITSAVEFNODE

command

ERROR MESSAGES

The

error messages

are the same

as in EDITFNODE

with the

addition

of the following

messaqe.

The

volume was not formatted

to support

backup fnodes.

This means

the RESERVE

option

was

not

soecified

when the

volume

was formatted.

save area

was

reseryed

when volume

was

formatted

Disk Verification 2-33

This command exits

the Disk

Verification

Utility and returns control to the Human

Interface command level.

The format of the EXIT command

is as follows:

r o20t

This command

is identical to

the

QUIT command.

NOTE

Although you

can use DISKVERIFY

verify

rhe sysrem

device (:sd:),

note that all connections

to this

device are deleted

by the operating

system.

After exiting, you

must reboot

the system

or use the warm start

feature

(see

the Ertended

iRMX II System Debugger

Ret'erence Manual).

2-34 Disk Verification

This command

verifies

the volume in the same way as the VERIFY command to

determine if the data on the volume

is consistent. In addition,

this command

"fixes"

various

kinds of inconsistencies discovered

during

verification. You can abort this

command by entering CONTROL-C. (CONTROL-C

is ignored

when FIX is writing to

the

volume

in order to prevent inconsistencies on the volume.)

Because FIX and

VERIFY perform

the same

verification

functions

and generate the

same

error messages, the command description

given

below

describes only the additional

functions of FIX. For a complete explanation

the veriff functions, see the

VERIFY

command described later in this chanter. The format of the FIX command is:

Disk Verification 2-35

Ftx

INPUT PARAMETERS

NAMED1 or N1

NAMED2 or N2

NAMED or N

PHYSICAL

LIST

ALL

Performs NAMEDl verification and fixes

the following

inconsistencies:

. Fixes

bad checksums

. Attaches orphan

fnodes to their

parents. An orphan

fnode is

fnode contained

within a directory and

whose

parent field

does not

point back to this directory.

If the

parent field of the

specified

fnode points to a second valid directory,

and the

second

directory

also points to the fnode,

no fix is

performed

since the specified

fnode belongs to an existing directory. This

is a case of multiple

references

(discussed in NAMED2).

If the parent field

does not point to a

valid parent, the

parent field

is fixed to point to the directory that

contains this fnode in its

fiìe

list.

Performs NAMED2 verification and fixes the followins

inconsistencies:

. Removes

fnodes from their iilegal parents. If there

is a multiple

reference

to an fnode, the fnode is removed from

the

directories

that it does not

point

to (if FIX was performed

with

NAMEDl, the

fnode

should now point to one

valid parent).

r Saves fnode and block bit maps

on completion of NAMED2.

Performs

both the NAMEDI and NAMED2

verification

functions

on a named volume and fixes the inconsistencies defined for

these

options.

Performs all operations appropriate to the

volume.

For named

volumes,

this

option performs both the NAMED and PHYSICAL

verification functions. For physical

volumes,

this option performs

only the PHYSICAL

verification

function. For both NAMED and

PHYSICAL

volumes,

ALL performs the fixes for the relevant

verifications.

Performs PHYSICAL

verification

and saves the bad block bit man.

Lists the

file information displayed

in Figure 2-3 for any

verification that includes

NAMED l.

2-36 Disk Verilication

FIX

OUTPUT

FIX

produces

the same output as the

VERIFY

command

(see

Figures

2-3, 2-4, and 2-5)

with

additional

messages displayed when an inconsistency is fixed. NAMEDl output

includes these messases.

Checksum Fixed

fnode nnnn was attached to parent nnnn

The first message

appears after a bad checksum is fixed. The

second message is displayed

when

the

parent field of an

fnode

modified

point

to a

valid parent.

NAMED2 displays

this

message

when an fnode with multiple references

is removed

from

the directory.

fnode rernoved frorn this dlrectory

If an fnode exists on a disk and is marked

allocated, but has not

been referenced,

FIX

issues a

warning

message and asks

if you want to save the bit

maps. This

prevents SAVE

from freeing

this fnode and its blocks and

possibly causing a file to be

lost.

2-37

Disk Verification

This

command designates

fnodes and

volume blocks as free

(unallocated). It also

removes

volume blocks from the

bad blocks file. The format of the FREE

command

is as

follows:

INPUT PARAMETERS

fnodenum Number of the fnode to free. This number can range from 0

through

(max

fnodes

- l),

where

mar fnodes is the number of

fnodes

defined when the

volume

was originally

formatted.

Two

fnode

values

separated

comma

signify a range of fnodes.

Number of the

volume

block to free. This number can range from

0 through

(max

blocks

- 1), where

mar blocks is the number

volume

blocks in the

volume.

Two block numbers separated by a

comma signif a range of block numbers.

OUTPUT

Ifyou are using FREE to deallocate fnodes, FREE displays

the following message:

blocknum

<fnodenutr>, fnode narked free

where

is the number ofthe fnode that the utilitv desisnated

as free.

If you are

using FREE to deallocate volume

blocks, FREE displays the following message:

<blocknun>, block marked free

where

blocknum

> is the number of the volume

block that the utilitv desisnated as free.

2-18 Disk Verification

FREE

Ifyou are

using FREE to designate

one or more

"bad"

blocks as

"good,"

FREE displays

the following message:

<blocknun>, block marked good

where

blocknum

> is the number of the volume

block that the utilitv desisrated as

"good."

FREE

checks the allocation status of

fnodes or blocks before freeing them. Therefore, if

you

specify FREE for a block

or fnode that is already unallocated, FREE returns one of

the

following messages:

<fnodenuo>, fnode already marked free

(blocknum>, block already marked free

(blocknun>, block already marked good

DESCRIPTION

Free fnodes are fnodes for

which

no actual

files

exist. FREE designates fnodes as free by

updating both

the F[-{GS field of the fnode and the free fnodes map file.

Free

volume blocks

are blocks that are not part of any file; they are available to be

assigned to any new or current file. FREE designates volume blocks as free by updating

the volume free space

map.

When you

use the FREE command

to designate one or more

bad blocks as "good," it

removes the block number

from the bad blocks file. However. FREE BADBLOCK

does

not designate the blocks as free. To update the volume free space map and designate

these blocks as free, use

the FREE BLOCK command.

ERROR MESSAGES

argùment error A syntax error

was

made in the command

or a nonnumeric character

was

specified

in the blocknum

or fnodenum

Darameter.

blocknum

, block out of range The

block number specified

was

larger

than the largest

block number in the

volume.

fnodenum

fnode out of range The fnode number specified

was

larger

than the largest fnode

number in the

volume.

Disk Verification 2-39

FREE

no badblocks

file The

volume does not have a bad blocks file. This message

could

appear

because an earlier

version

of the

Human Interface

FORMAT command

was used when the disk

was

formatted.

not a named

disk FREE

was performed on a

physical volume.

2-40 Disk Verification

This command displays the volume's bad track information. It can be aborted

by entering

CONTROL-C. The format of GETBADTRACKINFO is

INPUT PARAMETERS

None.

OUTPUT

The

GETBADTRACKINFO command displays

the volume's bad

track information as

written

the manufacturer

the

Human

Interface FORMAT command.

The output

displayed by the GETBADTRACKINFO command is

compatible

with

the format

required by the Human Interface FORMAT command

when writing bad track

information on the disk. To use the output as input to FORMAT,

remove the first

two

lines, leaving only the actual bad track information

data. The display is as

follows:

Bad track information:

L^-r

L-/ !

cccc hh ss

where

cccc is

rylinder

number, hh is the head number

and ss is the sector number

(always

zero for all devices

supported

this

release

of the operating System).

x.1599

Disk Verification 2-41

GETBADTRACKINFO

As mentioned

above, the output of

the GETBADTRACKINFO

command

can be used as

input to the FORMAT

command

when

creating the

bad track information

file. The

example

below shows how to use GETBADTRACKINFO this way.

-atÈachdevlce wnfdxo as :v: <CR)

-dlskverlfy : sd: to :v:bad.llsÈ

*getbadtracklnfo <CR>

*exLt <CR>

<cR>

After exiting DISKVERIFY

and rebooting the system, edit :w:bad.lst and remove

the

header lines. The file

can then be used as inDut to the bad track information

file created

by the FORMAT command.

ERROR

MESSAGES

I/O error while trying to read bad An I/O error occurred

while

reading the

track information bad track information.

No valid

bad track info found Bad track information is not valid and

cannot be displayed.

No bad track info found The area designated for bad track

information is emDtv.

2-42 l)isk Verification

This command lists all available Disk Verification Utilify commands and

provides a short

descrintion

of each command.

The format

of the HELP command is

F 0214

OUTPUT

In response to this command, HELP displays the following information:

2-4i

*heIp

aLlocace/free

backup/restore fnodes (bî /r î)

Control C

di sk

display byte/vord (

d, db/dw)

display directory (dd)

display fnode (df )

display next block (>, dnb

)

display previous block (<,dpb)

dlsplay save fnode (dsf)

exÍ t, qui t

list bad blocks (lbb)

read (r)

restore volune label (rvl)

save

substltute byte/word (s, sb/sw)

ver ify

\,Iri te (Lr)

edit fnode (ef)

edi t save fnode (esf)

fix

get bad track info (gb)

nisc connands -

address

lock

hex/dec

add,

+, sub, - ,

nul ,

*, div, /, rnod

a1l-ocate/free fnodes, space blocks, bad blocks

backup/restore Inode file to,/from save area

abort the comnand in progress

display disk at tr ibute s

display the buffer in (byte/word format)

display the directory contents

display fnode information

read and display 'next' volune block

read and display 'previous' volume block

display saved fnode information

^..: c r.'^1,..^-:f-,

gur L ursF wE!t!)

list bad blocks on the vol.ume

read a disk block into the buffer

copy volurne 1abel from save area

save free fnodes, free space & bad block naps

rnodify the buffer (byte/word format)

..^-: 8.. ÈL^ r i -1.

,rite to the disk block from the buffer

edit an fnode

edit a saved fnode

perforn varlous fixes on the voluue

get the bad track info on the volume

convert block nurnber co absolute address

convert absolute address to block nurnbe r

display number as hexade c imal/de c imal nurnbe

afithmetic operations on unsigned nurnbers

Disk Yerification

This command displays

all the bad

blocks on a named

volume. You can

abort this

command

by tlping a CONTROL-C.

The format

of the LISTBADBLOCKS

command

as follows:

0208

OUTPUT

In response to

this command, LISTBADBLOCKS displays up to eight columns

of block

numbers that

you specified as

"bad."

Figure 2-2 illustrates the format of

the display.

Badblocks on

I ocknurr>

(b I o cknurn)

locknurn>

<bLockn!u>

Volune: volumenurn

<blocknuÈ <blocknlu) <blocknuD <blocknlrn>

(blocknurn) (blocknr.uÈ (blocknurn) (blocknurn)

(blocknum> <blocknurp <Ul octnum> <blocknum>

Figure 2-2. LISTBADBLOCKS Format

lf none

of the blocks have been marked as "bad", LISTBADBLOCKS

displays

the

following message:

2-44

no badblocks

NOTE

Bad tracks and bad blocks

are different. Bad tracks are handled

the

device drivers

in conjunction

with

the hardware, whereas, bad

blocks are

handled by the iRMX II Basic I/O System.

Disk Verification

LISTBADBLOCKS

ERROR MESSAGES

badblocks fiÌe The

volume

does not have a bad blocks file. This message could

appear

because an earlier version

of the Human Interface

FORMAT command

was

used when the disk was

formatted or

because the

disk is a

ohvsical

volume.

2-45

Disk Verification

The

following

commands

provide

you

with

the ability

to perform

arithmetic

and

conversion operations

within the Disk

Verification

Utility. The commands

perform

the

operations on unsigned

numbers

only

and do not report

any overflow

conditions.

When

the number is

displayed in

both hexadecimal

and decimal

format, it appears

hexa<lecimal

format first,

followed

by the decimal number

parentheses. For

example:

( 19r)

ADD

This

command adds

two numbers

together. Its format

wnere:

arg 1 and arg2 Numbers

the command

q{ds

together. The

value

of each

argument

cannot be

greater

than 2-'4-1.

In response, the

command displays the unsigned

sum of the two numbers in both

hexadecimal

and decimal format.

ADDRESS

All memory in a

volume

is divided into

volume

blocks,

which are areas of memory the

same size as the volume granularity.

Volume

blocks are numbered sequentially

in the

volume,

starting

with

the

block containing the smallest addresses (block 0). The

ADDRESS command converts

a block number into an absolute address

(in

hexadecimal)

on the

volume,

so that

you

don't have to

perform

this conversion by hand.

The format of

this command is

<@tx::*r.rì

2-46 Disk Verification

where:

blocknum

MISCELLANEOUS

COMMANDS

Volume

block number that ADDRESS converts into an absolute

address in hexadecimal.

This

parameter

can range from 0 through

(mar blocks

- 1),

where

max blocks is the number

volume blocks

in the

volume.

In response.

ADDRESS displays the following information:

absolute address - <addr>

where:

< addr >Absolute address in hexadecimal that corresponds

to the

speciîied

block number. This address

represents the number of the byte

that

begins

the block and can range from 0 through (volume size

- 1),

where volume

size is the size, in

bytes,

of the volume.

BLOCK

The BLOCK command

is the inverse of the address command. It converts a 32-bit

absolute

address

(in

hexadecimal) into a volume block number, so that you don't have to

perform

this conversion

by hand. The format of this command is

where:

address Absolute address in hexadecimal that BI.OCK converts into a

block number. This parameter

can range

liom 0 through (volume

size

- 1),

where volume

size is the size, in bytes, of the

volume.

In response, BLOCK dispÌays

the following information:

block nunber : <blocknurn>

where:

blocknum

>Number of the volume block that contains the specified absolute

address in hexadecimal. The BLOCK command determines

this

value

by dividing the absolute address

by the volume block size and

truncatinq the result.

Disk Verification 2-47

MISCELLANEOUS COMMANDS

DEC

This command

finds the decimal equivalent of a number.

Its format is

<'-y'--'<1:,->

where:

arg Number

for

which

the command finds the decim-al equivalent.

The

value of the argument cannot be greater than2'"-1. The

default

base is in

hexadecìmal.

In response, the command displays the decimal equivalent of the specified number.

DIV

This command divides

one number by another. Its format is

where:

argl and arg2 Numbers on

which

the command operates.

It divides-argl by arg2.

The value of each argument

cannot be

greater

than 2rz- 1.

In response,

the command displays the

unsigned integer

quotient

in both hexadecimal

and

decimal format.

2-48 Disk Verification

M ISCELLAN

EOUS

COMMANDS

HEX

This command

finds

the hexadecimal

equivalent

of a number.

Its format

<3>1-r->

where:

arg Number

for

which

the

command finds

the hexadecimal eouivalent.

If you

are speci$ring

a decimal

number, you must

spgify i "f'

The value

ofthe argument

cannot be greater than2)z-1.

In response,

the command

displays the

hexadecimal equivalent

of the specìfietl

number.

MOD

This

command finds

the remainder

of one number

divided by another. Its format

uoo ,/--- -e' -.,'1] ! ''c'?

where:

argl and arg2 Numbers

which

the command

operates.

It performs

the

operation argl modulo

arg2.

The

value

of each argument

cannot

be greater

than 2-'z-l.

In response,

the command displays

the value

argl modulo arg2

in both hexadecimal

and

decimal

format.

Disk Verification 2-19

MISCELLANEOUS

COMMANDS

MUL

This command

multiplies

two numbers

together. Its

format is

where:

argl and arg2 Numbers the

command multiplies

lo^gether.

The

value of each

argument

cannot be

greater than 2'tz- 1.

where:

argl and arg2 Numbers on

which

the command operates. The command

subtracts arg2 from argl. The value of each argument cannot be

ereater

than 2''z- 1.

In response,

the command displays

the unsigned

product of the two numbers

in both

hexadecimal

and decimal format.

SUB

This command

subtracts one number

from another. Its

li)rmat is

In response,

the command displays the unsigned difference in both hexadecimal and

decimal format.

2-50 Disk Verification

MISCELTANEOUS COMMANDS

ERROR MESSAGES

The following error

messages may be returned by any of the Miscellaneous Commands:

argument error A syntax error

was

made in

the

command,

a nonnumeric value for one of

the arguments

was

specified, or a

value

for a block number

parameter

that

was

not a

valid block number

was

soecified.

blocknum

block out of range lf the command was an ADDRESS

command, the

block number entered

was

greater

than the number

of blocks in the

volume.

address

address not on the If the command

was a BLOCK command,

disk BLOCK converted the address to a

volume block number, but the block

number

was

greater

than the number of

blocks in the

volunrc.

EXAMPLES

*l{ul, 134î, 13î <CR>

6cE ( 7142T)

*+ 8, 4 <CR>

0c ( 12r)

*suB 8884, 256 <CR>

862E

(34350r)

*l{oD

1225, 256T <CR>

25 ( 31r)

*HEx 155T <CR>

*ADDRESS

15 <CR>

absolute address

- 0A80

*BLoCK

2236 <CR>

block nunber

- 44

Disk Verification 2-51

This command exits the

Disk

Verification Utility and

returns control to

the

Human

Interface

command level. The format of the

QUIT command is as follows:

This command is identical

to the EXIT command.

) -<, Disk Verilìcation

This command reads a

volume block from the disk into

the working buffer. The

format of

the READ command is

argument

error

blocknum

block

out of range

FFFFFFFF. block out of

ranee

Number

of the

volume

block to read.

This number

can range from

0 through

(max

blocks

- 1),

where max blocks is

the number of

volume blocks in the

volume.

A nonnumeric characterwas

specified

the blocknum

parameter.

The block

number specified

was

larger

than

the largest block

number in the

volume.

block number

was

specified

and no

read request

was executed

this

volume.

INPUT PARAMETER

blocknum

OUTPUT

ln response to the command,

READ reads the block into

the

working butlèr and displays

the following message:

read block nurnber: <blocknuÍ>

where <blocknum> is the number of the block.

DESCR]PTION

The READ command copies a specified

voÌume block from the

volume to the

working

buffer. It destroys any data currently in the working buffer. Once the block is in the

working buffer, you can use

DISPTAYBYTE and DISPTAYWORD to display the block,

and

you

can use SUBSTITUTEBYTE and SUBSTITUTEWORD to change

the data in

the block. Finally,

you

can

use the WRITE command

to write the modified

block back

the

volume

and repair

damaged

volume

data.

ERROR MESSAGES

2-53

Disk Verification

This command copies an fnode

or a range of fnodes from the R?SAVE file to the fnode

file. Before changing the fnode file,

RESTOREFNODE displays the fnode number to be

changed and prompts you to confirm

(by

entering a "y") that the fnode is to be restored.

R?SAVE must have been reserved

(the

RESERVE option of the FORMAT command

must have been specified) when the

volume was

formatted. The format of the

RESTOREFNODE command is as follows:

INPUT PARAMETER

fnodenum The hexadecimal number of

the fnode to be restored. This number

must be greater

than or equal to

zero and less than the m.tximum

number of fnodes defined when

the

volume was

fbrmatted.

The

initial

hexadecimal fnode number

in a range of fnodes to be

restored. This number must

greater

than

or equal to zero and

less than or equal

to the final fnode number

in the range

lfnodenum2l.

The final hexadecimal fnode

number in a range of

fnodes to be

restored. This number

must be

greater

than or equal to the initial

fnode

number in the range (fnodenuml)

and

less than the

marimum number

of fnodes defined when

the

volume

was

formatted.

fnodenum I

fnodenum2

OUTPUT

When

the fnode is

restored (the response

to the confirmation

query

"Y"

or "y"):

restore fnode

resÈored fnode

(

fnodenurn) ? Y <CR>

nunber : ( fnodenr.un)

fnodenumREsTORÉFNODE

fnodenum

1fnodenum2

2-54 Disk Verification

RESTOREFNODE

When the fnode is not restored

(the response to the

confirmation

query is not

"Y"):

restore fnode (

fnodenur) ? <CF>

DESCRIFTION

The

RESTOREFNODE

command

enables

you

to rebuild

a damaged fnode

file, thereby

re-establishing links to data

that

would

otherwise be

lost. RESTOREFNODE

copies

fnode or a range

of fnodes from the R?SAVE

file (the fnode

backup file) to the fnode file.

Before each

of the specified fnodes is copied,

RESTOREFNODE

displays

query

prompting

you

confirm that the indicated fnode

is to be restored.

You must

reply to

this

query with the letter "Y"

(either "Y" or "y") to restore

the fnode. If you enter any

other response,

RESTOREFNODE

will not restore the

fnotle and

will pass on to the

fnode

in the range.

Since RESTOREFNODE

operates on

the R?SAVE file,

you

must have

reserved this

file

when the volume

was

formatted.

(You

reserve R?SAVE

by specifuing

the RESERVE

parameter when you invoke the FORMAT command

to format

the

volume.) lf the

R?SAVE

file

was

not reserved

when the

volume was formatted,

RESTOREFNODE

will

return

an error message.

CAUTION

When using this comrnand, be sure

that any

fnode

you

restore

represents

a file that has not been

modified

since

the last

fnode backup.

RESTOREFNODE overwrites the specified

fnode in the

fnode

file with the

corresponding

fnode

in the

R?SAVE file. Ifthat fnode has

not been

backed

up since the last

file modification, a valid fnode may be

overwritten

with

invalid

data,

Thus, all

links

to the

associated

fìle will be

destroyed,

and YOU WILL LOSE

ALL OF

THE DATA IN THE FILE.

ERROR MESSAGES

argument error When the command

was entered,

argument

was supplied. This

command

rctluires

an argument.

no save

area

was

reserved

when The

volume

was not formatted

to support

volume was formatted backup fnodes.

This means

the

RESERVE

option

was

not

specified

when the

volume

was formatted.

Disk Verification 2-55

RESTOREFNODE

not a named disk

fnode num

fnode out of

range

allocation

bit not set for saved

fnode

restore fnode <

fnode

num>?

The

volume specified

when

the Disk

Verification Utiiity was

invoked is a

physical volume,

not a named

volume.

The fnode number specified

is not in the

range of 0 to

(maximum

fnodes

- 1).

The fnode

you

specified has not been

backed up in the R?SAVE file. If you

respond to the query with

"Y",

THE

DATA IN THE FILE ASSOCIATED

WIT]] THE ORIGINAL FNODE WILL

BE LOST.

EXAMPLE

super- dfskverlfy :

sd: <CR>

iRl{X II Disk Verify Utility, Vx.x

Copyrlght <year) Intel Corporatlon

:sd:, outstanding connections to device h&ve

*resÈorèfnóde 9,08 <CR> or rf 9,0B <CR)

restore fnode 9? Y <CP>

restored fnode number: 9

rescore fnode 0A? Y <Cl>

restored fnode nurnber: 0A

restore fnodè 0B? Y <CR>

rescored fnode number: 0B

been de1èted

2-56 Disk Verification

This command copies the

duplicate

volume

label to the volume label on track 0. The

duplicate

volume

label must have been constructed when

the

volume was

formatted.

(That is, the RESERVE

option of the FORMAT command must have been specified

when

the

volume was

formatted.)

The format of the RESTOREVOLUMEII,BEL

command

is as follows:

021 1

INPUT PARAMETERS

None.

OUTPUT

volume

label restored

DESCRIPIION

The RESTOREVOLUMELABEL

command enables

you

to rebuild a damaged

volume

label,

thereby re-establishing

links

data that

would

otherwise be lost.

RESTOREVOLUMEI-ABEL

copies the

duplicate

volume

label to the

volume

label offset

on track 0. When you

use the

Human Interface FORMAT command to create the

duplicate

volume

label (by specifying

the RESERVE

parameter),

the

volume

label is

automatically

copied to the end

of the R?SAVE file. Because the contents of the

volume

label

do not change, no other volume label

backup is required.

If a duplicate

volume

label has been reseryed

a volume,

the Disk

Verification

Utility

can access that

volume

as a Named volume even

if the

volume label

is damaged.

When

the

original

volume

label is corrupted, the Disk Verification Utility attempts to use the

duplicate volume

label. If the backup label is used, a

"DUPLICATE

VOLUME I-ABEL

USED" message appears

when

the utility is invoked.

If the duplicate volume label was not reserved when the voiume was formatted,

RESTOREVOLUMEI-ABEL will return an error messase.

Disk Verification 2-57

RESTOREVOLUMELABEL

ERROR MESSAGES

argument error

no save area

was

reserved

when

volume lvas formatted

not a named disk

When the command

was

entered,

argùment was supplìed. This command

does not accept an argument.

The volume has not been formatted

support

volume label backup.

The

volume specified

when

the Disk

Verification

Utility

was

invoked is

physical volume,

not

a named volume.

2-58

EXAMPLE

supèr- diskverlfy : sd: <CR>

IRMX Il Dlsk Verify Utility, Vx.x

Copyrlght <yèar> lntel Corporation

:sd:, outstandlng connections to device have been deleted

DUPLI CATE VOLUME

U.BEL USED

*restorevolune labe I <CR> or rvl <CR)

volune 1abe1 rès tored

Disk Verification

This

command

writes

the reconstructed

free fnodes

bit map,

volume

free space bit map,

and

the bad blocks bit map to

the

volume

being verified. (The

NAMED2 and

PHYSICAL options

of the

VERIFY command originally created the

maps.) The format

of the SAVE

command is

OUTPUT

response to this command,

SAVE displays the lbllowing

message:

save fnode roap?

Ifyou want

write

the

reconstructed free fnodes

map

the

volume,

enter Y,

y, or YES.

Otherwise,

enter any other character

or a carriage return.

lf you

enter

YES, SAVE

writes

the free fnodes

map to the

volume

and displays

the following message:

free fnode nap saved

fn any

case. SAVE next tJisplays

the following messagc:

save space rnap ?

Ifyou want

write

the reconstructed

free space map to the

volume,

enter Y or YES.

Otherwise, enter any

other character or a carriage

return. Ifyou enter YES, SAVE

writes

the

volume

free

space

map to the volume and

displays the following message:

free space map saved

SAVE displays the

following message if the bad blocks map is reconstructed:

save bad block rnap?

If you want

write

the reconstructed bad

blocks map to the

volume,

enter Y,

y, or YES.

Otherwise,

enter any other character or a carriage return. If you

enter YES, SAVE

writes

the

volume

bad blocks map to the volume

and displays the following

message:

bad block map saved

Disk Verification 2-59

SAVE

DESCRIPTION

Whenever you perform a VERIFY function

with

the NAMED2 option

(refer to the

description of the

VERIFY command for more information),

VERIFY creates its own

free fnodes map and

volume

free space map. It does this by examining all directories

and

fnodes on the

volume,

not by copying the maps that

exist on the volume. To create

lhe

free fnodes map, it examines every

directory on the volume to determine

which

fnodes

represent actual files. To create the

volume

free

space

map, it examines

the

POINTER(n) fields of the fnodes to determine

which volume

blocks the files

use.

If the volume has a bad blocks file and

you perform

VERIFY function

with

the

PHYSICAL option

(refer

to the description of the

VERIFY command for more

information), VERIFY creates its own bad blocks map. It does this by examining every

block on the volume, not by copying the maps that exist on the votume.

VERIFY then compares the newly created maps

with

the maps that exist on the

volume.

If a discrepancy exists, VERIFY displays a message indicating this.

The SAVE command takes the free fnodes map, the

volume

free space map, and the bad

block

map created during the

VERIFY operation and

writes

them to the

volume,

replacing the maps that currently exist.

ERROR

MESSAGE

nothing to save No bit map

was

constructed prior to

invoking SAVE. (Bit

maps

are constructed by

NAMED2 or PHYSICAL verifications.)

EXAMPLE

The following example

illustrates the format of the

SAVE command after

you

use

VERIFY and the NAMED or NAMED2 ootion.

*VERTFY NAIIED2 <CR>

,NAI4ED2'

VERIFICATION

BIT MAPS O.

*sAvE <cR>

savè fnode map? y <CR>

free fnode map saved

save space nap? y <CR>

free space map saved

2-60 Disk Verification

This command enables you to interactively change the contents

of the working buffer (in

byte format). You can abort this command by typing a CONTROL-C.

The format of the

SUBSTTUTEBYTE command is

INPUT PARAMETER

offset Number of the first byte, relative

to the start

of the

working

buffer,

that

you want

to change. This number

can range from

0 to (block

size

- l), where block size is the size of a

volume block

(and

thus

the size of the

working

buffer). If you omit this parameter,

the

command assumes

a value of 0.

OUTPUT

In response

to the command, SUBSTITUTEBYTE displays

the specified

byte and

waits

for

you

to enter

a new

value.

This display appears as

<offset>: val

where

offset

> is the number of the byte, relative to

the start of the buffer,

and val is the

current value of the byte. At this point,

you

can

enter one of the following:

. A value

followed by a carriage return.

This causes SUBSTITUTEBYTE

to substitute

the new

value for the current byte. If the

value you enter requires more

than one byte

of storage,

SUBSTITUTEBYTE uses only the low-order

byte of the

value. It then

displays the next byte in the buffer and

waits for further input.

. A carriage

return alone. This causes SUBSTITUTEBYTE

to leave

the current

value

as is and display the next bytc in

the buffer. lt then

waits for further input.

SUASrrÌUl€BYrE

Disk Verifìcation 2-61

SUBSTITUTEBYTE

. A value

followed by a

period

(.) and a carriage return. This causes

SUBSTITUTEBYTE to substitute the new

value

for the current b]'te. It then exits

from the SUBSTITUTEBYTE

command and gives the asterisk

(*) prompt,

enabling

you

to enter

any

DISKVERIFY

command.

. A period (.) followed by a carriage return. This exits the SUBSTITUTEBYTE

command and

gives

the asterisk

(*) prompt,

enabling

you

to enter any DISKVERIFY

command.

DESCRIP'TION

With the

SUBSTITUTEBYTE command

you

can interactively change bytes in the

working

buffer. Once

you

enter the command, SUBSTITUTEBYTE displays the offset

and the value

the

first byte. You can change the byte by entering a

new

byte value,

you

can leave the byte as is by entering a carriage

return. The command then displays the

next byte in

the

buffer.

In this manner,

you

can consecutively step through

the buffer,

changing

whatever

bytes are

appropriate.

When

you finish changing

the buffer,

you

can

enter a period followed

by a carriage return to exit

the commantl.

The SUBSTITUTEBYTE command considers

the

working

buffer to be a circular buffer.

That is, entering a carriage return when you

are positioned at

the last byte of the buffer

causes SUBSTITUTEBYTE to display the first byte of the buffer.

The SUBSTITUTEBYTE

command changes only the values

in the working buffer.

make the changes

in the

volume,

you must enter

the

WRITE

command

write

the

working

buffer back

to the

volume.

ERROR

MESSAGES

argument

error A nonnumeric character was

specified in

the offset parameter.

<offsetnum>,

invalid

offset An offset

value

larger than the

number of

bytes

in the block

was

specified.

2-62 Disk Verification

SUBSTITUTEBYTE

EXAMPLE

This example changes several bytes in two

portions

of the working buffer. Two

SUBSTITUTEBYTE commands are used.

*SUBSTITUTEBYTE<CN>

0000: A0 - 00<cR>

0001: 80 - <CR>

0002

: E5 - <CR>

0003

: FF - 31<cR>

0004: FF - .<CR>

*SUBSTITUÎEBYÎE

4O<CR>

0040: 00 - E6<CR>

0041: 0O

- E6<cR>

0042: 00 - . <cR>

Disk Verification 2-63

2-64

This command is identical to SUBSTITUTEBYTE, except that it displays the buffer in

WORD format, and substitutes

word

values in the buffer. The format of the

SUBSTITUTEV/ORD command is

EXAMPLE

This example

changes several bytes in

two areas of the

working

buffer. Two

SUBSTITUTEWORD

commands are

used. In the first command the words

begin on

even addresses,

and in the second commanC,

they begin on odd addresses.

*SUBSTTTUTEgORD<CR>

0000

0002

0004

0006

0008

AOBO

8070

E51t-

FFFF

0000<cR>

<cR>

3111<CR>

. <cR>

*SUBSTITUTEi{ORD

3 5<CP>

0035: 0000 - E6FF<CR>

0037: 0000 - E6AB<CR>

0039: 0000 - . <CR>

Disk Veriffcation

VERIFY

NAMED

PHYSICAL

This command

checks the structures on the

volume to determine

whether

the

volume is

properly

formatted.

You can abort this command

by t)?ing a CONTROL-C.

The

tbrmat

the

VERIFY command is

0211

INPUT PARAMETERS

NAMEDl or Nl Checks

named

volumes to ensure that

the infìtrmation

recorded

the fnodes

is consistent and

matches

the information

obtained

from the

directories themselves.

VERIFY perfbrms the following

operations

during a NAMEDl verification:

. Checks fnode

numbers in the

directories

to see if they

correspond to allocated

fnodes.

. Checks the

parent lhode numbers

recorded

in the thodes

to see

if they match the information

recorded

in the directories.

o Checks the fnodes against

the files

to determine

if the thodes

specif the

proper

file

type.

. Checks rhe

POINTE,R(n)

structures

of long files

to see if the

indirect

blocks accurately

reflect

the number

of blocks

used by

the

file.

. Checks

each fnode

to see if the TOTAL SIZE, TOTAL BLKS,

and THIS SIZE

fields are consistent.

o Checks the bad

blocks file to

see if the

blocks in the

file

correspond to

the blocks marked

"bad" on the

volume.

o Checks

the checksum of

each fnode.

Disk Verilication 2-65

VERIFY

NAMED2 or N2 Checks named volumes

to ensure that the information

recorded in

the free fnodes map

and the

volume

free space

map matches the

actual files and

fnodes.

VERIFY performs

the following

operations during a NAMED2 verification:

e Creates

a free fnodes map by

examining every directory in the

volume.

It then compares

that free fnodes map with the one

already on

the

volume.

o Creates

a free space map by examining

the information in the

fnodes. lt then compares

that free space

map

with

the one

already on the volume.

. Checks to see

if the block numbers

recorded in the fnodes

and

the indirect blocks

actually exist.

. Checks

to see if two or more files use

the same volume block.

If so, it lists the files referring

to each block.

e Checks the volume

free space

map for any bad blocks

that are

marked

as "free."

. Checks to see

if two or more

directories reference

the same

fnode. If so, it lists

the directories

referring to each

fnode.

NAMED or N Performs both

the NAMEDI and NAMED2

ooerations on a

named volume.

If you

specify the VERIFY command with

option,

NAMED is the default.

ALL Performs all operations

appropriate

to the volume.

For

named

volumes,

this option performs

borh

the NAMED

and

pHySICAL

operations.

For physical volumes,

this

option performs

only the

PHYSICAL

operations.

PHYSICAL Reads all blocks

on rhe volume

and

checks for

I/O errors.

This

parameter

applies

to both

named and physical

volumes.

VERIFY

also creates

a bad blocks

map by examining

every

block

on the

volume.

LIST When you

speci! this option,

the

file information

in Figure

2-3 is

displayed

for every

file on

the

volume,

even if the file contains

errors.

You

can use this

option with

all parameters

that,

either

explicitly

or implicitly,

specify

the NAMED

I paramerer.

OUTPUT

VERIFY produces

different

kind of output

for each

of the NAMEDl, NAMED2, and

PHYSICAL

options.

The

NAMED and ALL options produce

combinations

of these

three

kinds

of outDut.

2-66 Disk

Verification

VERIFY

Figure 2-3 illustrates the format

of the NAMEDI output (\ùithout the LIST option).

DEVICE NAI'IE

: <devname) : DEVICE SIZE : (devsize) : BLOCK SIZE : <blksize>

NAì"ÍEDI' VERIFlCATION

FILE- (<f i lenarne), (fnodenurn)): LEVEL:<l-ev>: PARENT:<parnt>: TYPE:<typ>

FILE- (<f i lenarne), (fnodenr.un)): LEVEL:<1ev>: PAI{ENT:<parnt>: TYPE:<typ>

ffle- 1<fi tenarne>, <fnoden\rll>r: LEVEI--<1ev>: PARENT-<parnt>: TYPE:<typ>

Figure 2-3. NAMEDI Verification

Output

The following paragraphs

identifo the fields listed in Figure 2-3.

devname

> Physical

name of the device, as specified in

the

ATTACHDEVICE

Human

lnterface command.

devsize

> Hexadecimal

size of the

volume,

bytes.

blksize

> Hexadecimal volume

granularity. This

number is the size of a

volume

block.

<filename> Name of the

file

(l to

characters).

fnodenum

> Hexa<lecimal number of the file's fno<le.

<lev> Hexadecimal level of the file in the file hierarchy. The root

directory of the

volume

is the only level 0 file. Files

contained in

the root directory are level 1 files. Files contained

in level I

directories are level 2 files. This numberins

continues for all levels

of files in the

volume.

parnt

> Fnode number

of the directory that contains this file,

hexadecimal.

Disk Verification 2-67

VERIFY

<typ> File type, either DATA (data files), DIR (directory files), SMAP

(volume

free

space map), FMAP (free

fnodes

map), BMAP (bad

blocks map),

or VI-AB

(volume

label file). If VERIFY cannot

ascertain

that the file is a directory

or data file, it displays the

characters

r****ù

iÍr this field.

<error

messages> Messages

that indicate the errors associated

with

the

previously-

listed file. The possible error messages

are listed later in this

section.

Figure 2-3 shows, the NAMED1 option

(without the LIST option) displays

information about each file that is in error. Ifyou used the LIST option

wjth

the

NAMED I option, the file information in Figure 2-3 is displayed

for every file, even if the

file contains

no errors. The NAMEDl display also contains

error messages that

immediately

follow the list of the affected files.

Figure 2-4 i.llustrates the format

of the NAMED2 output. If VERIFY detects

an error

during NAMED2

verification, it displays one or more error messages in

place of the "BlT

MAPS

O.K.' messase.

DEVICE NAME

: (dermame) : DEVICE SIZE : (devsize> : BLK SIZE : (blksze)

'NA.t.fED2 ' VERI FICATION

BIT MAPS O. K.

Figure 2-4. NAMED2 Verificati{}n Output

The

fields in Figure 2-4 are exactly the same as the corresponding

fields in Figure 2-3.

Figure 2-5 illustrates the format of the PHYSICAL

output.

DEVICE NAl.fE

: <der.marne> : DEVICE SIZE : (devsize> : BLOCK SIZE : <blkslze>

PHYSICAL' VERIFICATION

NO ERRORS

2-68

Figure 2-5. PHYSICAL

Verification

Output

Disk Verification

VERIFY

The fields in Figure 2-5 are exactly

the same as the corresponding

fields in Figure

2-3.

If VERIFY detects an error during PHYSICAL

verification, it displays the message:

<blocknurn), error

in place of the "NO ERRORS" message.

lf you

specifu NAMED verification, VERIFY displays both the NAMED

1 and NAMED2

output.

If you specify the ALL verification for a named

volume, VERIFY displays

the

NAMEDl, NAMED2, and PHYSICAL

output. If you specify the ALL verification for

physical

volume, VERIFY displays the PHYSICAL

output.

DESCRIFTION

The VERIFY command

checks physical and named

volumes

ensure that the

volumes

contain

valid

file

structures and data

areas. VERIFY can

perform three kincls

verification: NAMEDl, NAME,D2,

and PHYSICAL. NAMEDI and NAMED2

verifications check the file

structures of named

volumes. They do

not apply to

physical

volumes.

A PHYSICAL

verification checks each data

block of the

volume for I/O errors.

PHYSICAL

verification applies to both named

and

physical volumes.

part of the NAMED2

verification, VERIFY creates

a free fnodes

map and a

volume

free space map,

which

it compares

with the corresponding

maps on

the volume. You

can

use the SAVE command

write

the

maps produced during

NAMED2

verification

to the

volume, overwriting

the maps on the

volume.

When

you perform a

PHYSICAL

verification on a named

volume,

VERIFY also creates

bad blocks map.

You can use the SAVE

command to

write the bad blocks

map

produced during PHYSICAL

verification to the

volume; this destroys

the

bad blocks map

already on the

volume.

ERROR MESSAGES

Four kinds

of error messages

can occur as a result

of entering

the

VERIFY command:

VERIFY command errors, NAMEDl errors,

NAMED2 errors,

and PHYSICAL

errors.

VERIFY Command

Error

argument error The

parameter specified is

not a

valid VERIFY parameter.

Disk Verilìcation 2-69

VERIFY

NAMED I Messases

The following messages can appear in a NAMED1 display, immediately after the file to

which

they refer.

. <blocknum

- blocknum

n>, block bad

The block numbers

displayed in this message are marked as

"bad."

. <blocknum

I - blocknum n >. invalid block number recorded in the

fnode/indirect block

One of the POINTER(n) fields in the fnode specifies block numbers larger than the

largest

block number in the

volume.

o directory stack overflow

This message indicates that a directory on the volume

lists, as one of its entries, itself

or one of the

parent

directories in its pathname.

If this happens, the utiliry, when

searches through

the directory tree, continually

loops through a portion of the tree,

overflowing an internal

buffer area. In this case, performing

NAMED2

verification

may indicate

the cause of this problem.

. file size inconsistent

total$size

= <totsize>

:this$size

= <thsize>

:data

blocks

= <blks>

The TOTAL SIZE,

THIS SIZE, and TOTAL BLKS fields of the fnode

are

inconsistent.

o <

filetpe >, illegal file type

The file type of a user file, as recorded in the

TYPE field of the

fnode, is not valid.

The valid

file types

and their descriptions are

as follows:

File Fpe Number Descriorion

SMAP 1 volume

free space map

FMAP 2 free fnodes map

BMAP 4 bad blocks map

DIR 6 directory

DATA 8 data

VI-AB 9 volume

label

file

. <fnodenum>,

allocation

status bit in this

fnode not set

The

file is listed in

a directory but the

flags field of

its fnode indicates

that fnode

free. The free

fnodes map may

or may not list

the fnode as

allocated.

. <fnodenum>,

fnode out ofrange

The fnode

number is larger

than the largest

fnode number

in the

fnode file.

2-70 Disk Verification

VERIFY

. <fnodenum>,

parent

fnode number does not match

The fi.le represented

fnodenum is

contained within a directory

whose

fnode

number

does not match the

parent

field of the file.

e invalid blocknum recorded in the fnode/indirect block

One of the pointers within the fnode or within the indirect block specifies

a block

number that is larger than the largest block number in the

volume.

. insufficient memory to create directory stack

There is not enough dynamic memory

available in the system for the utility to perform

the

verification.

. sum of the blks in the indirect block does not match

block in the fnode

The file is a long file, and the number of blocks

listed in a POINTER(n) field of the

fnode does not agree

with

the number of blocks

listed in the indirect block.

. total-blocks does not reflect the data-blocks correctly

The TOTAL BLKS field of the

fnode

and the number of blocks recorded

in the

POINTERIn)

fields are inconsistent.

. Bad Checksum, checksum is

: <number>

Checksum

should be: <number>

An invalid checksum has been calculated.

NAMED2 Messages

The following messages can appear in a NAMED2 display.

. <

blocknum I - blocknum2>, bad block not allocated

The

volume

free space map indicates that

the blocks are free, but they

are marked as

"bad"

the

bad

blocks

file.

. <blocknum>,

block allocated but not referenced

The

volume

free space map lists the specified

volume block as allocated, but no fnode

specifies the block as

part of a file.

r <blocknum>,

block referenced but not

allocated

An fnode indicates

that the specified

volume

block is

part of a file, but the

volume free

space

map lists the block as free.

Disk Verification 2-7 |

VERIFY

. directory stack

overflow

This message can indicate

that a directory on the

volume

lists, as one of its

entries,

itself

or one

of the parent directories in its

pathname.

If this happens, the utility,

when

it searches through the directory tree, continually loops

through a portion of the

tree, overflowing an internal buffer area. The

"Multiple

Reference" message

(explained

below) may help

you

find the cause of this

problem.

o Fnodes map indicates fnodes

> m:u$fnode

The free fnodes map indicates that there are a

greater

number of unallocated fnodes

than the maximum number of fnodes in lhe

volume.

r <fnodenum>,

fnode-map bit marked allocated but not referenced

The free fnodes map lists the specified fnode as allocated, but no

directory

contains a

file

with

the fnode number.

o <fnodenum>,

fnode

referenced but fnode-map bit marked free

The specified fnode

number is listed in a directory, but the free fnodes map lists the

fnode as free.

. Free space map

indicates

Volume

block

> max$Volume$block

The free space

map indicates that there are a greater

number of unallocated blocks

than the

maximum number of blocks in the volume.

. insufficient

memory to create directory

stack

Not enough

dynamic memory is available

in the system for the

utility to perform the

verification.

. insufficient memory to

create fnode and space

maps

During a

NAMED2

verification,

the utility tried to create

a free fnodes map and a

volume

free

space map.

However, not enough dynamic

memory is available

in the

system to create

these maps.

. insufficient

memory

to create bad blocks

map

During a PHYSICAL verification,

the utility tried to create

a bad blocks map.

However, not

enough dynamic

memory is available

in the system to

create the map.

o Multiple reference

to fnode

Path

name : <

full path

name

referring

fnodes:

fnodenum

> Path name:

full

path

name

Path

name:

<full

path

name>

The directories

on the

volume

list more than one

file associated with

this fnode

number.

2-72 Disk

Verification

VERIFY

. Multiple reference to block <

blocknum

referring fnodes:

Path name:

<full

path

name>

Path name:

full path name>

More than one fnode specifies

this block as

part

of a file.

PHYSICAL Messages

. <

blocknum

>, error

An I/O error occurred

when VERIFY tried to access the speciîied

volume

block. The

volume is probably flawed.

Miscellaneous Messases

The following messages indicate internal errors in the Disk

Verification

Utility. Under

normal

conditions

these

messages should never

appear. However, if these messages

(or

other undocumented messages) do appear during a NAMEDl or NAMED2

verification,

you

should exit the Disk Verification

Utility

and re-enter the DISKVERIFY command.

directory

stack empty

directory stack error

directory

stack underflow

EXAMPLE

The following command performs

both named and

physical verification on a named

volume.

*VERIFY ALL <CR>

DEVICE NAÌ'IE

: F1 : DEVICE

SIZE : 0003E900 : BLoCK SIZE : 0080

,NAI4EDI' VERIFICATION

,NA.I{ED2'

VERIFICATION

BIT },IAPS O.K.

PHYSICAL'

VERIFICATION

NO ERRORS

Disk Verification 2-7t

This command writes the contents of the workins buffer to the volume. The format of

this command is

0210

INPUT PARAMETER

blocknum Number of the volume

block to

which

the command

writes

the

working buffer.

If you

omit this parameter, WRITE writes

the

buffer back to

the block most recentlv

accessed.

OUTPUT

In response to

the command, WRITE

displays the following

message:

write to block <b

locknur*?

where

is the

number of the volume

block to which WRITE intends to write

the

working

buffer.

If you

respond

by entering Y or any

character string

beginning

with

or y, WRITE

copies

the

working

buffer

to the specified

block on the

volume

and displays

the following

message:

written to block nunber :<blocknun>

Any other response

aborts the write process.

DESCRIPTION

The WRITE

command

is used in

conjunction with

the READ,

DISPT-AYBYTE,

DISPI-AYWORD, SUBSTITUTEBYTE,

and

SUBSTITUTEWORD commands to

modify information

the

volume.

Initially you

use READ to copy a volume

block from

the

volume

to a working

buffer. Then you

can use

DISPTAYBYTE

and

DISPI-A,YWORD

to view

the buffer

and SUBSTITUTEBYTE and

SUBSTITUTEWORD

to change the

buffer.

Finally, you can

use

WRITE

to write

the

modified

buffer back to

the

volume.

By default, WRITE

copies

rhe buffer to

the block

most recently

accessed

by a READ or WRITE

command.

A WRITE

command

does

not destroy the

data in

the

working

buffer.

The data remains

the

same until the

next SUBSTITUTEBYTE,

SUBSTITUTEWORD.

or READ

command

modifies

the buffer.

blockn

2-74 Disk Verification

WRITE

ERROR

MESSAGES

argument

error A syntax error

was

made or nonnumeric

characters were specified

in the

blocknum parameter.

blocknum

block out of range The block number specified was

larger

than the largest block number

in the

volume.

FFFFFFFF,

block out ofrange No blocknum

was

specified and no

previous read request was executed on

this

volume.

EXAMPLE

The following command

copies the working

bullèr to the block from

which

was

read.

*I.RITE <CR>

wrire 48? y <cR>

wrltcen to block number: 48

Disk Verification 2-75

BACKING

UP AND CHAPTER

RESTORING

FNODES

3.1

INTRODUCTION

To access data on a named volume (such

as a disk), the iRMX Il Operating

System

uses a

mechanism common to virtually

all operating systems: it maintains an

index to

every

file

on the disk. This

index is created

when

the disk is formatted and

remains as a

permanent

structure at

a dedicated location on the clisk.

The index consists of a

system

pointers

that

indicate the location of the data

files on the disk. Thus,

when

data must be stored on

or retrieved from the disk, the operating

system can find the exact location of the

appropriate

file by looking

up the file name in the index.

In the operating system,

the index consists of the iRMX ll volume

label and an fnode file.

This

volume

label resides at the same

location in all devices and serues as the initial entry

point

into the device.

The fnode file can reside an).where on the disk

(specified

when the

disk is formatted) and contains

a series of individual structures called file dcscriptor nodes

or "fnodes."

There is one fnode

for each lle on the disk. The lnode contains information

essential

to accessing and maintaining the

respective file.

The iRMX II file structure for a named volume is organizerJ as a hierarchical tree. That

is, there is a root directory with

branches to other directories and ultimately, to files. The

organization

of the fnode file reflects

this hierarchical structure. The iRMX II volume

label contains a pointer

to the fnode of the file structure's

root directory. The root

directory

is always the starting address

for any fiìe or directory on the

volume.

It lists alÌ

the

first level files and directories on the volume.

First level directories point to second

level files and directories,

and so on, down the hierarchical structure.

previously

mentioned, each file or directory is represented by an fnode. The fnode,

along with other data describing the

file or directory, contains

pointers

blocks

on the

volume. If the fnode describes

a short file, these blocks contain the actual file data. If the

fnode describes a long file, these blocks contain pointcrs to other blocks containing the

actual data. If the fnode describes a

directory, these

blocks contain entries which describe

the contents of the directorv. Each entrv lists the fnode number and name of the

associated

file or directory,

The operating system creates the iRMX Il volume

label and the lìode file when the disk

is formatted.

Disk Verification 3-l

BACKING

AND

RESTORING FNODES

The number

of unallocated

fnodes in the

fnode file is

controlled by the FILES

parameter

of the FORMAT command.

In addition to

the unalìocated fnodes,

seven

(with

option

of eight)

allocated fnodes

are established

when the fnode file is created.

These allocated

fnodes represent

. the fnode file

. the

volume label file

- R?VOLUMEIABEL

. the

volume

free

space map file

- R?SPACEMAP

o the free fnodes map

file

- R?FNODEMAP

o the bad blocks file

- R?BADBLOCKMAP

. the root

directory

. the

space

accounting

file,

. Optionally,

the duplicate

volume

label lile

- R?SAVE

For a full description

of these files, see Appendix A "Structure

of A Named

Volume."

Thereafter,

when

files or directories are creiìted

directly subordinate to the root, the

operating system must adjust

a pointer

the root fnode to indicate the fnode number of

the new data file or directory file. Subserluently, clirectories subordinate to the root must

also have their

pointers

adjusted

when

they

become parents to a new data file or

directory.

This

method of storing

and

retrieving data on a disk has one major drawback. All access

to files on the disk is through the iRMX II volume

label and the fnode file. If either the

volume label

file

or the

fnode file is

damaged or destroyed,

there is no

practical way to

recover data on the disk.

The backup and restore fnodes feature enables some recovery of data

lost as a result of

damage to the fnode file or the iRMX II volume label. With

this feature,

you

create a

backup version of the volume

label and all the fnodes on the disk. The backup

version

stored

in one of the innermost tracks of the disk

where

the chance

of accidental loss of

data is minimal.

(In normal use, the disk

heads do not extend to the innermost tracks.)

To implement this feature,

the Human Interface FORMAT command

has been modified

to include

an optional parameter

RESERVE. This version

of the FORMAT command

creates a file named R?SAVE in the

innermost track of the

volume.

A copy of the iRMX

II volume

label is

placed

in the front (that is, the physical

end) of the file and an fnode is

allocated for R?SAVE

the fnode

file. (The

fnode for the R?SAVE file is allocated out

of the fnodes reserved through the

FILES

parameter

of the FORMATcommand. Thus,

ifyou specify

"FILES

= 3000" when you

format, only 2999 of those fnodes will remain

available after the R?SAVE fnode has been allocated.)

Finally, FORMAT copies the

fnode file into

R?SAVE.

a-) Disk Verifîcation

BACKINC

AND RESTORING

FNODES

Notice that

the FORMAT command creates a backup of the fnode file in its initialized

state. R?SAVE is not subsequently updated as files are

written

to or deleted from

the

volume. Therefore,

you will have to use the BACKUPFNODES Disk Verification Utility

command or the BACKUP option of the Human Interface SHUTDOWN command

back up the fnode file at regular intervals. If the

volume label or the fnode file become

damaged,

you

can attempt to recover liles on the

volume by using the Disk

Verification

Utility commands

(RESTOREFNODE

and RESTOREVOLUMETABEL)

to rebuild the

index.

assist in this process, the DISPI-AYSAVEFNODE Disk

Verification Utility

command enables

you

look

individual

fnodes stored in the R?SAVE file.

Since the contents

of the iRMX II volume label do not change, the

copy of the

volume

label in R?SAVE is always

valid.

Therefore,

you

can restore the

volume label at any time

regardless of

when

the R?SAVE file

was

last updated.

(When the Disk

Verification

Utility encounters

a damaged volume label, it automatically uses the

backup volume label

if the R?SAVE

file is present, however, it does not restore unless

explicitly instructed.)

CAUTION

One

note

of caution:

The fnode fìle is

changed

each time a

volume is

modified

(that is,

each time a fìle or directory

is created, written to, or

deleted from the volumel. Therefore. valid restoration can be assured

only

for fnodes whose associated files or directories

have not been

changed since the last

backup.

If the fnodes are not backed up after each

modificafion, the structure of

the R?SAVE

file will differ from that of the

fnode file. Some

fnodes in

R?SAVE

may not be assoriated

with the

same files as the corresponding

fnodes in the

fnode file. Attempting to

recover fnodes under these

conditions

is dangerous because the RESTOREFNODE command

will

ovenvrite what may be a valid fnode in the

fnode file.

While the backup and restore fnodes leature is a useful aid in attempting

to recover data

on a

volume, this capability is limited in scope. If you are troubleshooting

your system,

you may

want

to back up the fnodes on the

system disk before taking

any action that may

risk the disk's integrity. You may also decide to

back up the fnodes on

a routine basis

(before

or during each

system shutdown, for instance) so that

the R?SAVE file is always

relatively currcnt.

However, under normal circumstances,

where a

volume

accessed and

modified frequently,

backing up the fnodes after each modification

is not

practical. The

most

practical

solution is to back up

the fnode file once a

day using the BACKUP

option

of the SHUTDOWN

command.

Disk Verification J-J

BACKING

LIP ANI) RESTORING FNOI)ES

Note that this feature is not intencled to

provicle

comprehensive

protection from the loss

of data associated

with

damaged

iRMX Il volume

labels or fnode files.

Rather, it offers a

tool that, when properly applied, can be useful in maintaining

volume

integrity in

certain

situations. For comprehensive

protection against

loss

of data use the Human Interface

BACKUP command.

3.2 USING

FNODE BACKUP AND RESTORE

To use the fnode backup and restore feature,

you

must use

Version

L l (or

later) of the

I Iuman Interface FORMAT comnurnd anrl the Version 2.0

(or

later) of the Disk

Verification Utility. Used togethe r, these

versions

of the FORMAT command and the

Disk

Verification

Utility enable

you

. format

volume

to cre:ìte

the backup

file

(R?SAVE)

. back up the fnories of any fiìcs

written

to the

volume

. examine the contrìnts of thc hlckup

fiìe

(R'ISAVE,)

. restore damaged fnodcs

. restore the

volunie

label

. edit fnodes or save fnodcs

'l his section

describes hou, to perlìrrm each

of thcse operations. A brief overview

of the

openrtion

is followed by onc or nrore

examples of a typical implementation. ln the

exumples, blue or holded

text indicates an entry

you

make from

your

terminal. Standard

type (this

is standard type)

indicates system ourpur ro your rerminal.

3.2.1 Creating the R?SAVE Fnode

Backup File

Ilyou

intend to buckup the volume

lrrbel antl the liodes

on a

volumc',

you must first create

the RISAVE backup

file on the innermost tracks

of the

volume.

do so, you

must

invoke Version

2.0 oî the

Human Interface FORMAT

command, specifying the

RESERVE option.

NOTE THAT THE

FORMAT COMMAND OVERWRITES

ALL

OF THE DATA CURRE,NTLY ON

THE DISK. Thereftrre,

make a backup copy of any

îiles

you wish

to save

using the Human

lnterface BACKUP command.

Once the

volume

has been formtttecì, the

R?SAVE file

will

contaìn

a copy of the fnode

file

inclutling the allocated

liodes

(R?SPACE,MAP,

R?FNODEMAP,

erc.). Therefore,

you

need not back up

the lìode file immediately

after formatting

the

volume.

PROCEI)URE

From the Iluman Interface,

invoke the FORMAT

command, specifying

the RESERVE

Darameter.

3-,1 Disk Verification

BACKING UP AND RESTORING FNODES

EXAMPLE

Assume that

you

have booted your system from a flexible diskette to format the system

disk. The command listed below formats

the disk and creates the R?SAVE backuo file.

The initialized fnode fiìe is cooied

into R?SAVE.

-attachdevlce carbo as :nydlsk: <CR>

-fornat ;aaydlskr 1l - 4 ftles = 3000 reserve (CR>

volume ( ) will be fornatced as a NAÌ.IED

volurne

granularity - L,O24 nap start - 7,859

lnterleave - 4

files * 3000

extensionsize - 3

save area reserved - yes

bad track/sector Ínformation written - no

volume size : 15

984K

1lr t.L I r llr I r-t -L l-t I

vol,u.ne fornalted

The

disk has

now been

formatted. A file named R?SAVE has

been reserved in the

innermost tracks of the disk.

(If you

use the Disk

Verification

Utility

DISPI-AYDIRECTORY command

on the

volume

root

fnode

(fnode

6) or the Human

Interface DIR command

with

the invisible (l) option on the

volume

root directory,

you

will find an fnode listed for R?SAVE.)

R?SAVE

contains a duplicate copy of the fnodes

in the fnode file. That is, R?SAVE contains eight allocated fnodes

(R?SAVE,

R?SPACEMAP, R?FNODEMAP, etc.) and 2,999 unallocated fnodes.

(Remember, the

R?SAVE fnode is allocated out of the 3,000 fnodes specilìed through the FILES

parameter.)

3.2.2 Backing up

Fnodes

on a Volume

DESCRTPTION

To back up the fnodes on a

volume,

you must have

previously

reserved

the back up file

R?SAVE

when

the

volume was

lbrmatted. Thereatìer, any

modification to the

volume

(creating, writing

to, or deleting a file) requires that the

fnodes be backed up if the

R?SAVE

file

is to contain an accurate copy of the fnode file.

You can

backup the fnode on a

volume

either by:

. Using the Human Interface SHUTDOWN

command

wirh

the BACKUP

option

. Using

the BACKUPFNODES option of DISKVERIFY

(see

Chapter 2)

Disk Verification 3-5

BACKING

AND RESTORING FNODES

EXAMPLE I

This example shows how to backup the fnode file using SHUTDOWN with the BACKUP

option. The BACKUP option allows

you

to copy the

volume

fnode file to its duplicate

file, R?SAVE, on any attached

volume.

super-SHUTDoIIN B <CR>

***SYSTN{ I{ILL BE SHUTDOI.N IN 10 MINUTE(S)

:SD:, outstanding connections to device have been deletèd

***sl{uTDoI\rN ooMPLETED ***

R?SAVE now contains a duplicate copy of

all fnodes in the fnode file.

EXAMPLE

This example

shows how to use the BACKUPFNODE

command

of DISKVERIFY to

backup the fnode file. Assume that the system disk

is attached as logical device:sd:. The

initial contents of the :sd:

fnode file

were

copied

to R?SAVE by the FORMAT command.

A file

hasjust been

written

to the volume.

An fnode

for this file is entered in the fnode

file; however,

no corresponding entry

has been made in R?SAVE. The following

sequence

of commands will

copy all fnocles in

the fnode file into the

R?SAVE file.

super- dlskverlfy :

sd: <CR>

iRMX I1 Disk Verify Utility, Vx.x

:sd:, outstanding connections to device

*backupfnodes <CR> or bf <CR>

fnode flle backed up to save area

have been de leted

R?SAVE now contains

a duplicate copy

of all fnodes (allocated

and unallocated)

in the

fnode

file.

Note that in both cases you must reboot the

system after

backing up the

fnodes on the

volume,

3.2.3 Backing

the

Volume

Label

The

volume

label is initially

copied

to R?SAVE when

rhe

volume

is formatted.

Since the

contents

of the volume

label do

not change,

no other

volume

label backup procedures

are

reouired.

3-6 Disk Verification

BACKING UP

AND RESTORING

FNODES

3.2.4

Restoring Fnodes

DESCRIPTION

To restore fnodes on a

volume, you

must have

previously reserved the

backup file

R?SAVE

when the

volume was

formatted. If damage has

occurred to the fnode

fiìe,

you

can attempt to rebuild

the file (or portions of it) by using the Disk

Verification Utility

RESTOREFNODE

command.

RESTOREFNODE

enables

you

to restore a single

fnode or a range of

fnodes. You

designate the

fnodes to be restored by

entering the fnode numbers.

The specified

fnodes

in R?SAVE

are copied into the corresponding

fnodes in the

fnode file.

Before

restoring each fnode, RESTOREFNODE

prompts you

with

the message

"restore

fnode

number

?". To restore

the fnode,

you

must enter

"yes" or the letter

"Y"

(either

Y or

y). Ifyou enter any

other response, the fnocle

will not be restored.

When restoring fnodes,

you must be very careful to ensure

that

you

are not

overwriting

valid

fnode

in the fnode file

with

an invalid

fnode from R?SAVE.

Be sure the

volume has

not been modified

since the fnodes

were

last backed

up.

PROCEDURE

1. Invoke

the Disk

Verification

Utility,

using the logical

device name of

the volume

be backed

up.

2. When

you

receive

the Disk

Verification

Utility

prompt

(*), enter the appropriate

Disk

Verification Utiìity commands

(VERIFY, DISPI-AYFNODE,

etc.) to

examrne

the fnodes

file and determine

which fnode must

be restored.

3. Invoke

the Disk

Verification Utility RESTOREFNODE

command

to replace

the

damaged

fnodes. The Disk

Verification Utility

prompts you to confirm

that the

proper fnode is

being restored. Make sure

you have specified

the correct

hexadecimal

number

for the fnode,

then enter the letter

"Y" in response

to the

prompr.

4. RESTOREFNODE

returns the message

"restored fnode

< fnode

number

>" after

the fnode in

the R?SAVE file

has been

written

over

the corresponding

fnode

in the

fnode

file.

Disk Verification 3-7

BACKING

AND RESTORING FNODES

EXAMPLE I

Assume

that a disk

drive is

attached as

logical device :sd:. The

volume

:sd: contains

the

R?SAVE fnode backup

file. You have not modified the disk since

the fnodes

were last

backed up. You suspect the fnode file has been damaged, so

you

use the Disk

Verification

Utiliry to confirm

your

suspicions:

super- diskvetlfy : sd: <CR>

iRl,fx II Disk Verify Utility, Vx.

Copyrlght <year) Intel Corporation

:sd:, outsÈanding connections to device have been deLeted

*verffy

After using

the Disk

Verification

Utility

examine

the structure of

the disk, you find that

fnodes 9 through

0C have probably been destroyed.

You then use rhe

RESTOREFNODE

command

to recover these fnodes.

Fnodes

09 through

0C in the R?SAVE

file have been

copied

into fnode 09

through 0C

the fnode

file. Since the

disk has not been

modified since

the last

fnode backup,

restoring

the

damaged

fnodes should now

enable you to

recover the

data on

the disk.

*restorefnode

restore fnode

resÈored fnode

restore fnode

rescored fnode

restore fnode

restored fnode

restore fnode

restored fnode

9, 0C <CR> or

9? Y <CR>

nunbe r : 9

OA? Y <CR>

nurnber: 0A

OB? Y <CR>

nurnber: 0B

QC? Y <CR>

number: 0C

rf 9, 0C <CR>

3-8 Disk Verification

BACKING

AND RESTORING

FNODES

EXAMPLE

Assume

the same initial conditions as Example

1 with the following exception:

two files

have been modified

since

the last

time the fnodes

were

backed

up. ln the fnode file, the

new files are represented by fnodes 0D and

0E. Again,

you

suspect

that the fnode file has

been damaged, so

you

use the Disk

Verification Utility to check

the condition of data

the disk:

super- dfskvellfy :

sd: <cR>

iRf.fx I1 Disk Verify Utility, Vx.x

:sd:, outstanding connections to device have been deleted

Jcverlfy

After using

the Disk

Verification Utility to examine the

structure of

the disk,

you

find

that

fnodes 9 through 10

have probably been destroyed. You

decide

to use the

RESTOREFNODE command

to recover these fnodes.

You do not

wish to restore fnodes

0D and 0E

because they

were

not backed up. Since the data

fields of fnodes

0D and 0E

R?SAVE contain all zeros,

you would be destroying

possibly useful data in

the

corresponding fnodes. You then use

RESTOREFNODE

to restore a range

of fnodes

that

includes 0D and 08. However,

you intend to pass over

the restoration

of these two

fnodes

by responding to the

confirmation prompt

with

some

character

other than

"Y."

*restorefnode

restore fnode

restored fnode

restore fnode

restored fnode

restore fnode

restored fnode

resÈore fnode

resÈored fnode

allocation bit

restore fnode

allocation bit

restore fnode

festore fnode

restored fnode

restore fnode

restored fnode

9,10 <CR> or rf 9,10

9? Y <CR>

nunber: 9

OA? Y <CR>

nunber: 0A

OB? Y <CR>

nurnber: 0B

0c? Y <cR>

number: 0C

not sec for saved fnode

0D? <cR>

not set for saved fnode

0E? n (CR)

OF? Y <CR>

nunber: 0F

10? Y <CR>

number: 10

Disk Verification l-9

BACKING

UP AND RESTORING FNODES

Notice that because fnodes 0D and 0E

were

not allocated

when

they were backed up,

those

fnodes in R?SAVE are unallocated. Therefore, the Disk

Verification

Utility

returns the

"allocation

bit not set for saved fnode"

message. Since

you

do not

wish

restore this fnode, you

respond to the confirmation

prompt with

a character other than

The R?SAVE fnodes 09 through 0C and

fnodes

through l0 have been copied over the

corresponding

fnodes in the fnode file. Fnodes 0D and 0E were not restored.

3.2.5 Restoring the Volume

Label

DESCRIPTION

restore the

volume

label, you

must have

previously

reserved

the backup file R?SAVE

when

you

formatted the

volume.

If the volume

contains the R?SAVE

file, a backup copy

of the

volume

label already exists. The

FORMAT command automatically

places a copy

the volume

label

into R?SAVE when the file

is created. Thereafter,

the contents of the

volume

label do not change

and

you

can restore the

label

without

fear

of destroying data

in the existing

label.

To restore the volume

label, you must invoke

the Disk Verification

Utility using the

logical device

name of the appropriate volume.

If the

volume

label

is corrupted, the Disk

Verification

Utility attempts to

use the backup copy

of the

volume

label

in R?SAVE.

When

the backup label

is used, the Disk Verification

Utility

issues a message that

reads

"duplicate volume

label used." If this message appears when

the

Disk

Verification

Utility

is activated,

then the volume

label is damaged.

To restore the volume

label, enter

the

Disk Verification

Utility RESTOREVOLUMELABEL

command.

The current volume

label will

be overwritten with

the volume

label conv from

R?SAVE.

PROCEDURE

1. Invoke

the Disk Verification

Utility,

using the logical

device nante

of the volume

be backed

up.

2. If the "duplicate

volume

label used" message

appears,

the

volume

label must be

restored.

Enter the

Disk

Verification

Utiliry RESTOREVOLUMEI-ABEL

command.

3. When

the volume

label has been

restored,

the Disk Verification

Utility returns the

messape

"volume label restored."

3-10 Disk Verification

BACKING UPAND RESTORING

FNODES

EXAMPLE

Assume that a

disk drive is attached as logical device :sd:. The

volume :sd: contains

the

R?SAVE fnode

backup file. When you attempt to aocess files

on :sd:, the system returns

E$ILLEGAL_VOLUME

message. You

suspect that the

volume

label may

damaged. You

decide to check

your

suspicions using the

Disk Verification Utility.

super- dlskverlfy : sd: <CR>

iRMx I1 Disk Verífy Utility, vx.x

:sd:, outstanding connecÈions to device have been deleted

duplicate volune label used

The

"duplicate

volume label used" message confirms

that the

volume label has been

damaged.

You restore the

volume

label

usìng the RESTOREVOLUMEI-ABEL

command.

*re s torevohime labè I <cR>

volune labeI restored or rvl- <CR>

The original

volume label has been overwritten

with the duplicate

copy from the

R?SAVE

file. Attempts

to access files on volume :sd: should now

be successful.

3.2.6

Displaying

R?SAVE Fnodes

DESCRIPTION

Any fnode

(both allocated and unallocated)

in the R?SAVE

file can be examined

by using

the Disk

Verification Utility DISPIAYSAVEFNoDE command.

The Disk

Verification

Utility

wiÌl display

vital

information abouî the

fnode (total blocks,

total size, block

pointers,

parent node, etc.). The fnode is

displayed in the same

fbrmat used

by the

DISPIAYFNODE command.

To display an R?SAVE thode,

enter the DISPI-AYSAVEFNODE

command and

specify

the hexadecimal

number of

the fnode to be disnlaved.

Disk Verilication 3-11

tsACKING

UP AND RESTORING FNODES

PROCEDURE

1. Invoke the Disk Verification

Utility using the logical device name of the

appropriate volume.

2. When you

receive the Disk Verification

Utility

prompt

(*), enter

the Disk

Verification

Utility DISPI-AYSAVEFNODE command. Speci! the hexadecimal

number of

the fnode to be displayed.

3. The Disk Verification

Utility will return with an

fnode display.

EXAMPLE

Assume

that

you

cannot access

a file on a disk

attached as :sd:. You suspect

that the

fnode

file may be damaged.

By entering the Disk Verification

Utility and

displaying the

file's directory, you

find that the file you were

unable to access is represented by

fnode

3C8.

You use DISPT

AYFNODE to display

fnode 3C8, but you

are not confident of the

data

you

see.

Since the fnode

for the file has been

backed up since the

file was

last

modified,

you

decide to

use data in the R?SAVE

fnode to examine

the fnode file. The

following command

displays the

data for fnode 3C8

in R?SAVE.

3-12 Disk Verification

super- dlskverlfy : sd: <Cn>

iRHX II Disk Verify UEility, Vx.x

Copyrtghc <year> Intel CÒrporation

:sd:, outstandlng connections to devlce have been deleted

*displaysavefnode 3CB

Fnode nurobe r - 3C8 (saved)

path narnè: ^SER/I{YFILE

flags

cype

aí I ^ ^-^^ /-.^1 ---^

r r rE Ér d!,/

owîer

create ,

access

nod tixnes

total slze, total- blocks

hl nnlr nni nto r /1\

h ì anlr nninror /?\

}l I anlt naintpr 11\

uruLK PUrrrLr r \

+,,

block pointer (5)

hìnnL nninror l6l

hl.).k n.línrér l7l

hl oelr nai nrar lfl\

this size

id count

aecessor (L)

accessor (2)

accessor (3)

n4róht nha n1z <, rm

aux (*)

002 5

08 -> dara f1lè

0001

00000000, 00000000,

00000000

00002D01,0000000c

000c,004910

0000, 000000

0000,

000000

0000,000000

00003000

0001

0F, 0001

00, 0000

03c4,0000

000000

BACKING

AND

RESTORINC FNODES

You can modify the contents of the both the original fnode

file and the saved

fnode iile by

usins either the EDITFNODE or EDITSAVEFNODE

commands.

Disk Verification 3-r3

STRUCTURE

OF A APPENDIX A

NAMED

V-OL_UME

A.1 INTRODUCTION

This

appendix describes the structure

of an iRMX II volume that contains named

1iles. It

provided

as reference

information to help you

interpret output from the DISKVERIFY

commands or to help you

create

your

own formatting

utility

programs.

This appendix is for programmers u'ith

experience

in reacling and

writing

ircturrl

volume

information. It does

not attempt to teach these functions.

4.2 VOLUME

STRUCTURE

This appendix

discusses the structure

of named file

volumes

in cletail. It covers the

structure of

directory files and the concepts

of long and short lilcs. It also includes

information on

o ISO Volume

Lahel

. iRMX VoÌume l-abel

. fnode file

r volume

free space

map file

r free fnodes map file

. bad blocks

map file

o root directory

The blocks reserved for

the Bootstrap Loader

(Figure

A- I

) are not tiiscussed. Bootstrîp

Loader blocks are automatically

included on a new

volume when you

format a

volume

with

the FORMAT command. Refer to the FORMA'| command for a clescription of the

bootstrap option.

Figure A- 1 illustrates the general structure

of a named lile

volume.

Disk Verilication A-l

STRUCTURE OFA NAMED VOLUME

lso

lo rer reo srlsr, ,-.1,-. rsrrJrrra

x ti45

Figure A- l. General

Structure of Named Volumes

A.3 VOLUME LABELS

Each iRMX II named

volume

contains

ISO

(International

Standardization Organization)

label information

well

as iRMX II label

information and

files. This section describes

the structure of ISO

volume

labels and

iRMX II volume

labels. both of which must be

Dresent

on a named

volume.

A-2 Disk

Verifìcation

STRUCTURE OF A NA]\IED VOLUI\TE

4.3.1 ISO Volume

Labe!

The ISO

volume

label is recorded in

absolute byte

positions

761Ì through

895 of the

volume (for

example, sector

07 of a single-density

flexible diskette). The structure of thrs

volume

label

(in

PL/M notation) is:

DECI.ARE

1SO$VOL$TABEL

STRUCTURE(

T.ABEL$ID(3) BYTE,

RESERVED$A BYTE,

VOL$NAI"ÍE(6) BYTE,

VOL$STRUC BYTE,

RESERVED$B

(

) BYTE,

REC$SIDE BYTE,

RESERVED$C

(4) BYTE,

I LEAVE

(

) BYTE,

RESERVED$D BYTE,

ISO$VLRSION BYTE,

RESERVED$E

(48

) BYTE);

Where:

IABEUID(3) Label identifier. For

named file

volumes, this

f ield

contains the

ASCII characters "VOL".

RESERVED$A Reserved field containing the ASCII character

1".

VOL$NAME(6) Volume

name.

This field can contain up to

six printable

ASCII

characters, left

justified

and space filled.

A vaÌue

all spaces

implies

that the

volume

name is recorded in the iRMX II Volume

Label

(absolute

byte

positions

3lt4-393),

VOII$STRUC For named file volumes, this

f ield contains

the

ASCII character

"N",

indicatìng that this volume has a non-ISO file structure.

RESERVED$B(60) Reserved field containing 60 bytes

of ASCII

spaccs.

REC$SIDE For named file

volumes,

this field contains the ASCII character "l"

to indicate that only one side of the volume is to be recorded.

RESERVED$C(4) Reserved field containing four bytes of ASCII spaces.

ILEAVE(2) Two ASCII digits

indicating

the interleave fìrctor for the

volume,

decimal. ASCII digits consist of the numbers 0 through

9. When

formatting named

volumes, you should set this

field

to the sanìe

interleave factor that you use when physically formatting the

volume.

RESERVED$D Reserved field containing an ASCII space.

Disk Verification A-.1

STRUCTURE OF

A NAMED VOLUME

ISO$VERSION For

named file

volumes, this field contains

the ASCII

character

"l",

which indicates ISO

version number one.

RESERVED$E(48) Reserved

field containing

48 ASCII spaces.

A.3.2 IRMX@ llVolume

Label

The iRMX II Volume

Label

is recorded in absolute

byte

positions

384 through

5l I of the

volume

(sector

04 of a sing.le density tìexible

diskette). The sîructure

of thìs volume label

follows:

DECI-ARE

RMX9VOLUME9INFORMATION

STRUCTURE(

vOL$NA-Ì"IE

(

)

FI"AGS

FILE$DRIVER

VOL$CRAN

VOL$ S I ZE

MA.\$FNODE

FNODE$ START

FNODE$ S I ZE

ROOT$FNODE

DEV9CRAN

INTERLEAVE

TRACK$ SKEW

SYSTEM$ I D

SYSTEM$NA]'JE( l2 )

DEVTCE$SPECTAL(8)

BYTE

WORD

DWORD

WORD

DWORD

WORD

BYTE,

BYTE);

where:

voL$NAME(10)

FLAGS

Volume

name in

printable

ASCI I characters, left

justified

and zero

filled.

BYTE that lists the device charrcteristics for automatic devic"

recognition.

The individual bits in this BYTE indicate the

following characteristics (bit 0 is rightmost

bit):

Bit Meaninc

0 VF$AUTO

flag. When set

to one, this bit indicates

that the FI-AGS byte contains valid data for

automatic device recognition. When

set to zero, it

indicates that the remaining flags contain

meaningless data.

A-4 Disk Verification

STRUCTURE OF

A NAMED VOI,UME

1 VF$DENSITY

flas. This bit inclicates the

recording density òfthe

volume. When

set to one,

it indicates

modified frequency modulation

(MFM)

or tlouble-density recording.

When

set to zero, it

indicates frequency modulation

(FM) or single-

density recording.

2 VF$SIDES

flas. This bit indicates the number of

recorcJing sides

on the

volume. When set

to one,

indicates a double-sided volume. When set to zero,

it indicates a single-sided

volume.

3 VF$MINI

flau. This bit indicates the size of the

recording meAia.

When

set to one, it indicates

5 I

/4-inch

volume. When set to

zero,

it indicates an

8-inch volume.

4 VF$NOT$FLOPPY. This bit indicates the type of

disk you are using. When this and Bit 0 are set to l,

it indicates a

Winchester

disk.

5-7 Reserved

FILE$DRIVER Number of the file driver used

with

this

volume.

For named file

volumes.

this field is set to four.

VOLIGRAN Volumo granularity,

specilìed in bytes. This

value

must

be a

multiple of the device granularity.

It sets the size of a logical

device block, also calÌed a

volume

block.

VOII$SIZE Size of the entire volume, in bytes.

MAX$FNODE Number of fnodes in the fnode file. (Refer

to the next section for a

description of fnodes.)

FNODE$START A 32-bit value that represents the number of the first byte in the

fnode file (byte 0

is the first byte of

the volume).

FNODE$SIZE Size of an fnode, in bytes.

ROOT$FNODE Number of the fnode describing the root directory. (Refer to the

next section for further information.)

DEV$GRAN Device

granularity

of all tracks except track zero

(which contains

the

volume

label). This field is important only

when the system

requ

ires a

utomatic device recognition.

INTERLEAVE Block interleave factor for this

volume. This

value

indicates the

physical distance, in blocks, between consecutively-numbered

blocks on the

volume.

A value of one indicates that consecutively-

numbered blocks are adjacent. A value

ofzero indicates

unknown or undefined interleave factor.

Disk Verification A-5

STRUCTURE

A NAMED

VOLT]ME

TRACK$SKEW

SYSTEM$ID

SYSTEM$NAME(12)

Character

Offset, in bytes,

between the

first block on one

track and

the

first block on

the next track. A value of zero indicates

that all

tracks

are identical.

Numerical

code identifying

the operating

system that formatted

the

volume. The followìng

codes are reserved

for Intel

operating

systems:

Operating Svstem

iRMX

I, II

iRMX lt{i

iNDX

Currently, the iRMX

II Operating System

places a zero in this

field.

Name of the operating

system that formatted the

volume, in

printable ASCI I characters, left

justified

and space filled.

Zeros

(ASCIl

nulls) indicate

that the operating system

unknown. The iRMX Il Operating

System currently places

several

pieces

of information

into this field, as follows:

. The leltmost eight bytes of this field

contain the ASCII

chrìriìcters

"iRMX IL3' to identify the operating

system.

The iRMX IL I Operating System filled

this field

with

zeros.

. The next byte is an ASCII character

that

identifies

the

program that formatted the volume. The following

characters appÌy:

Formatting Program

Human Interlhce FORMAT command

iRMX I Files Utility

(used

prior to

iRMX r.7)

If the formatting

program

is unable to

provide

this information,

it places

an ASCII space in this field.

. The

Human Interlace FORMAT command that is

part

iRMX Il.3

places

the characters

"03 "

in the Ìast 3 bytes of

this field.

Code

0-(lFh

10h

lFh

20h

2Fh

A-6 Disk Verification

STRUCTURE OF

A NAMED

VOLU]\IE

DEVICE$SPECIAL(II) Reserved

for special device-specific information. When

device-specific information exists,

this field must contain zeros.

For example,

if the device is a

Winchester

disk

with

an iSBC

214

/215G

controller,

the iRMX lI Operating System imposes a

structure on

this field and supplies the following information:

SPECIAL STRUCTURE

(

CYLINDERS WORD,

FIXED BYTE,

REMOVABLE BYTE,

SECTORS BYTE,

SECTOR SIZE WORD,

ALTERNATES

BYTE);

where:

CYLINDE,RS Total number of cylinders on the disk

drive.

FIXED Number of heads on the fixed disk or

Winchester

disk.

REMOVABLE Number of heads

on the removable disk

cartridge.

SECTORS Number

of sectors

in a track.

SECTOR SIZE Sector size, in bytes.

ALTERNATES Number of alternate

cylinders

or spare

sectors on a track.

The remainder of the Volume Label

(bytes

440 through 5 I I

) is reserved and must be set

to zero.

Disk Verification A-7

STRTICTURE OF A NAMEI) VOT,T]ME

4.4 INITIAL FILES

Any mechanism

that

formats iRMX II named

volumes

must

place seven

files,

with the

option of an eighth file, on the

volume

during the format

process.

These files are

File

fnode

fiìe

volume

label file

volume

free space map file

free fnodes map file

bad blocks file

root directory

space accounting file,

Optionally, duplicate volume label

file

File Name

R?VOLUMELABEL

R?SPACEMAP

R?FNODEMAP

R?BADBLOCKMAP

R?SAVE

The first of these

fiìes, the fnode file, contains information about

all of the files on îhe

volume.

The

general

structure of the fnode

file is discussed first. Then all of the files are

cliscussed in terms of their fnode entries

and their functions.

A.4.1 Fnode

File

A data structure called

a file descriptor

node

(fnode)

describes each

file in a named file

volume.

AII the fnodes

for the entire

volume

are

grouped

together in

a file called the

înode file. When the

I/O System accesses

a file on a named volume,

it examines the

iRMX II Volume

Label (described

in the previous section)

to determine the

location of

the

fnode file, ancl then

examines the appropriate

fnode to determine

the actual location

of the fiÌe.

When

a volume

is formatted,

the fnode file

contains seven

allocated fnodes and any

number of unallocated

fnodes. The

original number

of unallocated fnodes

depends on the

FILES parameter

of the FORMAT command. These

allocated fnodes

represent the

fnode file,

the

volume

label

file, the

volume

free space

map file, the

free fnodes map file,

the

bad blocks file, the

root directory, and

the space accounting

file. (Later

sections

this appendix

describe

these lìles.) The size of

the fnode fiÌe is determined

by the number

of fnodes

that it contains.

The number of

fnodes in the fnode

file also determines the

number

of files that

can be created on

the

volume.

The

number of files is set when

vou

format the st.orage

mcdium

A-8 Disk Verification

The structure of an individual fnode in a named file volume

as follows:

DECIARE

FNODE

STRUCTURE

(

FIAGS WORD,

TYPE BYTE,

GRAN BYTE,

OWNER \IORD,

CR$TIME DitORD,

ACCESS$TIME

DWORD,

MOD$TIME DWORD,

TOTAL$SIZE DWORD,

TOTAL$BLKS DI,/ORD,

POINTR(40) BYTE,

THIS$SIZE DLIORD,

RESERVED$A WORD,

RESERVED$B

WORD,

rD$couNT \,roRD,

ACC(9) BYTE,

PARENT WORD,

AUX(*) BYTE);

where:

STRUCTURE

OF A

NAMED VOLUME

A WORD

that defines a

set of attributes for the file. The

individual bits in this

word

indicate

the followins attributes

(bit

0 is

the rightmost bit):

Meaning

Alìocation status.

If set to one, this fnode

describes

an actual file. If set to zero, this

fnode is

available for allocation.

When

formatting

a volumc. this bit is

set to one in

the six

allocated fnodes. In other fnodes,

is set to

zero.

FT-AGS

Bit

Disk Verilication A-9

STRUCTURE OF

A NAMED VOLUME

7-r5

TYPE

Long or short file attribute.

This bit

describes

how the PTR fields of the

fnode

are interpreted. If set to zero, indicating a

short file, the PTR fields identi$

the actual

data blocks of the file. If set to one,

indicating a long

file, the PTR fields identify

indirect blocks (described later in this

section). When formatting a

volume,

this

bit

always set

to zero, since the initial

files on

the

volume

are short files.

Reserved bit, always set to one

Reserved bits, always set to zero.

Modification attribute. Whenever a file is

modified, this bit

set

to one. Initially,

when a volume is formatted,

this

bit

set

zero in each fnode.

Deletion attribute. This bit is set to one to

indicate that the file is a temporary file or

that

the file

will

be deleted (the deletion

may be

postponed

because additional

connections exist to the file). lnitially,

when

the

volumc

f ormatted, this

hit

is srr rtl

zero

in each fnode.

Reserved

bits, always set to

zero.

Type of file. The following

are acceptable

qpes:

Tlpe

fnode file

volume

free space

map

free

fnodes map

space accounting

file

device

bad blocks

fle

directory

file

data file

voÌume

label file

During

system operation,

only the

I/O System can

aocess file types

other than F|$DATA and F-|$DIR.

These file

tvnes are discussed

later in this section.

Fiìe granularity,

specifìed in multiples

of the volume

granularity.

The default value

is L This value

can be ser

to anv multiole of the

volume

sranularitv.

3-4

Mnemonic Value

FT$FNODE O

F-T$VOLMAP 1

FT$FNODEMAP 2

FI$ACCOUNT 3

FT$BADBLOCK 4

FT$DIR 6

F-T$DATA 8

F'T$VLI,BEL 9

GRAN

A-r0 Disk

Verilìcation

STRUCTURE OF

A NAMED

VOLUME

OWNER User lD of the owner of the file. For

the files initially

present

the volume, this parameter is important

only for the root

directory.

For the root directory, this

parameter should specify

the user

WORLD (FFFFH). The l/O System

does not examine

this

parameter

for the other files

(fnode file, volume free space map

file, free fnodes map

file, bad blocks file,

volume

label),

so a

value

of zero can be specified.

CR$TIME Time and date

that the file was created, expressed

as a 32-bit

value.

This

value

indicates

the number of seconds

since a fixed, user-

determined

point

in time. By convention,

this

point in time is

12:00, January

l, 1978. For the files initially

present

the

volume,

this

parameter is important only

for the root directory.

zero can be specified

for the other files

(fnode file,

volume

free

space map file,

free fnodes map file,

bad blocks file,

volume label.)

ACCESS$TIME Time and date

of the last fi-le access

(read

wrìte), expressed as a

32-bit value. For the files initially

present on

the volume, this

parameter

is important

only for the root

directory.

MOD$TIME Time and date of

the last file modification,

expressed

as a 32-bit

value.

For the files initiatly

present on

the

volume,

this

parameter

is important only

for the root directory.

TOTAL$SIZE Total

size, in bytes, of the actual

data in the file.

TOTAII$BLKS Total number

of volume blocks used

by this file, including

indirect

block overhead. A volume block is a block

of data

whose size is

the

same

the

volume

granularity. All memory in

the

volume is

divided into

volume blocks, which are numbered

sequentially,

starting

with

the block containing

the smallest

addresses (block

0).

Indirect blocks are

discussed later in

this section.

POINTR(4O) A group of BYTES on

which the following

structure is imposed:

PTR(8) STRUCTURE

(

NUMSBLOCKS

WORD

BLK$PTR(3)

BYTE);

This structure identifies the

data blocks

of the fììe. These

data

blocks may

scattered

throughout the

volume, but together

they

make up a complete file. Ifthe file is

a short file

(bit 1 ofthe

FTAGS field

is set to zero),

each PTR structure

identifies

an actual

data bÌock. In this case. the

fields of

the PTR structure

contain the

followins:

Disk Verification A-ll

STRUCTURE OF A

NAMED

VOLUME

THIS$SIZE

RESERVED$A

RESERVED$B

ID$COUNT

ACC(e)

NUM$BLOCKS Number of

volume

blocks in the data block.

BLK$PrR(3) A 24-bit

value

specifying the number of the

first

volume

block in the data block.

Volume blocks are

numbered sequentially,

starting with the block with the smallest

address

(block

0). The bytes in the

BLK$trtR array range

from least

significant

(BLK$mR(0)) to most significant

(BLK$PrR(2)).

If the file is a long

file

(bit I of the FIAGS field is set

one),

each

PTR structure identifies

an indirect block (possibly consisting of

more than one

contiguous

volume

block), which

in turn identifies

the data blocks

of the file. In this case. the fields

of the PTR

structure conta in the

following:

NUM$BLOCKS Number of volume

blocks

pointed

to by

the

indirect block.

BLK$FrR(3) A 24-bit volume

block number

of the

indirect block.

Indirect blocks are discussed

later in this

section.

Size, in BYTES, of the total data space

allocated

to the file. This

figure does not include space

used for indirect

blocks,

but it does

include

any data space

allocated to the

file, regardless

of whether

the file fills that allocated space.

Reserved field, set

to zero.

Reserved

field. set to zero.

Number

of access-ID pairs

declared in the ACC(9) field.

A group

of BYTES on

which

the

following structure

is imposed:

ACCESSOR(3)

STRUCTURE(

ACCESS BYTE,

ID WORD):

This structure

contains the

access-ID pairs

that define

the access

rights

for the users of the file. By convention,

when

a file is

created, the owner's ID is inserted

in ACCESSOR(O),

along

with

the code for the access rights. The fields

of the ACCESSOR

st ructu

rc conta in the folkrwing.

A-12 Disk Verifìcation

STRUCTURE

A NAMED

VOLUME

ACCESS Encoded

access rights for the file. The

settings of the individual

bits in this field

grant (if set to one)

or deny (if set to zero)

permission for

the corresponding operation.

Bit

0 is the rightmost

bit.

Data File Directory

Bit Oneration Onerat ion

0 delete delete

I read list

2 append add entry

3 update change entry

4-7 reserved

(must

be 0)

PARENT

ID ID of the user

who gains the corresponding

access

perm ission.

Fnode number

of directory file

that lists this

file. For files initially

present on the

volume,

this

parameter is

important only fbr

the

root

directory. For the

root directory, this

parameter

should

specify the

number of the root

directory's

own fnode. For

other

files

(fnode

file,

volume free space

map file, free

fnodes map file,

bad blocks

file, volume label) the

t/O System

<loes not examine

this

field.

Auxiliary BYTES associated

with

the

file. The named

lile driver

does not interpret

this field, but the

user can access

it by making

GET$EXTENSION$DATA

and SET$EXTENSION$DATA

system calls.

The size of this field

is determined

by the size of the

fnode, specified

in the iRMX II Volume Label. If you use the

Human lnterface FORMAT command

or create

your own utility

format a

volume, you can make this field

as large as

you wish;

however,

a larger AUX field implies

slower file

access.

AUX(-)

Certain fnodes

designate special files

that appear on the

volume. The following sections

discuss

these fnodes and the associated

files.

Disk Verincation A-13

STRUCTURE

OF A NAMED

VOLUME

4.4.2 Fnode

0 (Fnode

File)

The first fnode structure

in the fnode file

describes

the

fnode file itself. This file contains

all

the fnode structures for the entire volume.

It must

reside

in contisuous locations in the

volume.

The fields of

fnode 0 must be set as follows:

. The bits in the FIAGS field

are set to the following (bir 0 is the rightmost bit):

Bit Value Descrintion

0 1 Allocated file

1 0 Short file

2 1. Primary

fnode

3-4 0 Reserved bits

5 0 Initial

status is unmodified

6 0 File

will

not be deleted

7-15 0 Reserved bits

. The TYPE field

is set to FT$FNODE.

. The

GRAN field

is set to l.

r The OWNER

field is set to

the ID of the

user

who

formatted

it.

. The

CR$TIME,

ACCESS$TIME,

and MOD$TIME

fields

are set to the

time the

system

was

formatted.

. Since the

iRMX II Volume

Label specifies

the

size of an

individual

fnode structure

and the number

fnodes in the

fnode file, the value

specified

in the TOTAL$SIZE

field of

fnode 0

must equal the product

of the values

in the FNODE$SIZE

and

MAX$FNODE

fields

of the iRMX II Volume

Label.

. The TOTAL$BLOCKS

field specifies

enough volume

blocks

to accounr

for the

memory

listed

in the TOTAI-I$SIZE

field. The product

the

value

in the

TOTAL$BLOCKS

field and

the

volume

granularity

equals the value

of the

THIS$SIZE

field, since

the fnode

file is a

short file.

. Since

the fnode

file must

reside in

contiguous

locations

in the volume,

only one

pTR

structure

describes

the

location

of the file. The

value

in the NUM$BLoGKS

field of

that

PTR structure

equals the value

in the

TOTALSBLOCKS

field. The BLK$pTR

field

indicates

the number

of the

first block of

the fnode

file.

. The ID$COUNT

field is set to

one.

A-14 Disk Verification

STRUCTURE

OF A

NAMED VOLUME

A.4.3 Fnode 1

(Volume

Free

Space

Map

File)

The second fnode, fnode 1, describes the

volume

free

space map file. The TYPE field for

fnode I is set to FT$VOLMAP to designate the file as

such.

The

volume free space map file keeps track of all the space on the

volume. It is a bit map

of the volume, in

which

each bit represents

one volume block

block of

space whose size

is the same as the

volume granularity). If a bit in the map is set to one,

the corresponding

volume block is free to be allocated

to any file. If a bit in the map is

set to zero, the

corresponding

volume

block is

already allocated to a file. The bits

of the map correspond

volume blocks such that bit n of byte m

represents volume block

. m) + n. The

bits

in the remaining

space

allocated

to the map file

(those that do not correspond

to actual

blocks of memory) must be

set to zero.

When the

volume

is formatted,

the

volume

free space map

file indicates that

the first 3328

bytes of the

volume (the label and bootstrap information)

plus any files initially

placed on

the

volume (fnode file, volume free space map file,

free fnodes map

file, bad blocks file)

are allocated.

A.4.4 Fnode 2 (Free

Fnodes Map File)

The third fnode, fnode 2,

describes the free fnodes map file. The TYPE field of fnode 2 is

set to FI$FNODEMAP to designate the lile as such.

The free fnodes map file keeps

track of all the fnodes in the fnodes

file. It is

a bit map in

which

each bit

represents an fnode. If a bit in

the map is set to one,

the corresponding

fnode is not

in use and does not represent an actual

file. If a bit in

the map is set

to zero,

the corresponding

fnode already describes an existing file. The bits in the

map

correspond

to fnodes such that bit n of byte m represents fnode

number

* m) + n. The

bits in the remaining

space allocated to the map file (those

that do not correspond

actual fnode structures) must be set to zero.

When

the

volume

is formatted, the free fnodes

map file indicates

that fnodes 0, 1, 2, 3,4,

5, and

6 are in use. If other files are initially

placed

the

volume,

the free

fnodes map

file must be set to indicate this as

well.

A.4.5 Fnode 3 (Accounting

File)

When

volume

formatted, fnode 3 is set up representing

a file

of type FT$ACCOUNT

The fnode is

set up as allocated, and of the indicated

type, but it does

not assign any

actual snace for

the file.

Disk Verification A-15

STRUCTURE

OFA NAMED VOLUME

A.4.6 Fnode 4 (Bad

Blocks Map File)

The fifth fnode, fnode 4, contains a map of all the bad blocks on the

volume.

The TYPE

field of fnode

4 is

set

to FfiBADBLOCK to indicate this.

The bad block map file keeps track of all the bad blocks on the volume. It is a bit map of

the volume,

which

each bit represents one

volume

block

block of space

whose

size is

the same as

the

volume granularity).

If a bit in the map is set to zero, the corresponding

volume

block has no bad blocks and may

be allocated to any file. If a bit in the map is set

one, the corresponding

volume

block is bad. If a block

is marked "bad", it must also be

marked allocated in the volume free space file. The bits of the map correspond to

volume

blocks such

that bit n of byte m represenîs volume block (8

* m) + n.

A.4.7 Fnode

5 (Volume

Label File)

This fnode contains

the first 3328 bytes of any volume.

The inlbrmation in this file

defines the volume

as a

whole.

The TYPE field of this

fnode is set to FTSVIABEL. You

cannot write

to this fnode.

4.4.8 Fnode

6 (Root

Directory)

The root directory

is a special directory

file. It is the root of the named

file hierarchy for

the volume.

The iRMX II Volume

Label specifies the fnode

number of the root directory.

The root directory

is its own parent.

That is, the PA RE NT field of its fnode specifies its

own

fnode number.

The root

directory (and

all directory files) associates

file names with

fnode numbers. It

consists of a

number of entries

that have the followins

structure:

DECI^ARE

DIR$ENTRY STRUCTURE

(

FNODE WORD,

coMPoNENT(14)

BYTE);

where:

FNODE Fnode number

of a file listed in the directory.

COMPONENT(

14) A string

of ASCII characters

that is the

final component of the

path

name identifying

the file. This

string is left

justified

and

null

padded

to 14 characters.

When

a file

is deleted, its

fnode number in the

directorv entry

is ser ro zero.

A-r6 Disk Verification

STRUCTURE OFA NAMED VOLUME

4.4.9 Fnode 7 (R?SAVE)

The R?SAVE is a

file

which

may

be optionalìy created by

the RESERVE option of the

FORMAT command. The

FORMAT command

creates a file named R?SAVE, which

contains

the duplicate volume

label, in the

innermost track of the

volume.

A copy of the

iRMX II volume

label

is placed in

the front (that is, the physical end)

of the file and an

fnode is allocated for R?SAVE in the

fnode file. (The

fnode for the R?SAVE

file is

allocated

out of the fnodes

reserved through the

FILES

parameter

of the FORMAT

command.)

The FORMAT command

creates a backup

of the fnode file in its initialized state.

R?SAVE is not subsequently

updated as files are written

to or deleted from the

volume.

Therefore, you will

have to

use the BACKUPFNODES

Disk

Verification

Utility

command

or the BACKUP option

of the Human Interface SHUTDOV/N

command to

back up the fnode

file at regular intervals.

4.4.10

Other Fnodes

When

formatting a volume,

no other fnodes

in the fnode file represent actual files. The

remaining fnodes must

have bit zero

(allocation

status) set to zero.

4.5 LONG AND

SHORT FILES

A file on a volume is not

necessariìy one contiguous string of bytes. In

many cases,

consists of several

contiguous blocks of data scattered

throughout the

volume.

The fnode

for the file indicates the locations and

sizes of these blocks in one of two ways, as short

files

or as long files.

4.5.1

Short Files

lf the file consists of eight or

less distinct blocks of data, its

fnode

can specify

it as

short

file. The fnode for a short file has

bit 1 of the FLAGS field ser ro zero. This indicates to

the I/O Systern that

the PTR structures of the fnode identify the actual data

blocks

that

make up the file. Figure A-2 illustrates an

fnode for a short file. Decimal numbers are

used

in the figure for clarity.

Disk Verilication A.-17

STRUCTURE

OF A NAMED VOLUME

tofaLlstzÉ

-l--l

d!,!b,oc\t]

l-t

P-rR (0)

-T ;-

LPrR

(rt

f--

'fxrsisrzE

Figure A-2. Shof File Fnode

As you can

see in Figure A-2, fnode 8 identifies the short file. The file consists of three

distinct data

blocks. Three PTR structures give

the locations of the data

blocks. The

NUM$BLOCKS field of each PTR structure gives the

length of the data block

(in volume

blocks),

and the BLK$PTR field points

to the first volume

block of the

data block.

A-18 Disk Verification

STRUCTURE

OF A NAMED VOLUME

The

other fields shown in Figure

A-2 include TOTAII|BLKS, THIS$SIZE, and

TOTAUSIZE. The TOTAT$BLKS

field specifies the number of volume blocks

allocated

to the

file,

which

in this case

is eight. This equals the sum of NUM$BLOCKS values (3 +

2 + 3), since

short files use all

allocated space as data space.

The THIS$SIZE field specifies the number

of bytes of data space allocated to the file.

This is the

sum of the NUM$BLOCKS values

(3 + 2 + 3) multiolied bv

the

volume

granularity (1024)

and equals 8192.

The TOTAI-i|SIZE field specifies the number of byes of data

space

that the file occupies

(designated

in Figure

A-2 by the shaded area).

you

can see, the file does not occupy

all the space allocated for it, so

the TOTAL|$SIZE

value

(tì000) is not as large as the

THIS$SIZE

value.

4.5.2 Long Files

where:

NBLOCKS

BLK$FTfR

If the

file consists of more than eight

distinct blocks of data, its fnode must specify it as a

long file. The fnode for a

long file has bit 1 of the FTAGS fieltl set to one. This tells the

I/O System that the PTR structures

of the fnode identify indirect blocks. The indirect

blocks identiîy the actual

data blocks that make up the file.

Each indirect block contains

a number of indirect pointers, which

are structures

similar to

the PTR structures.

However, an indirect block

can contain more

than

eight structures

and thus can point to

more than eight data blocks. In fact,

an indirect block

can consist of

more than one volume

block; however, all volume blocks of an indirect block must be

contiguous.

The structure of each indirect pointer

is as follows:

DECI.ARE

IND$PTR STRUCTURE

(

NBLOCKS BYTE,

BLK$PTR BLOCK$NUM);

Number of volume

blocks in the data block.

A 24-bit

volume

block number of the first

volume

block in the data

block. Volume

blocks are numbered sequentially throughout the

volume,

starting

with

the block

with

the smalìest address

(block

0).

The Operating System determines

how many indirect

pointers there are

an indirect

block by comparing the NBLOCKS fields

of the

indirect pointers

with

the

NUM$BLOCKS

field of

the

fnode. It assumes that the indirect

block contains as many

pointers

as necessary for the sum of the NBLOCKS fields to equal the NUM$BLOCKS

field.

Disk Verification A-19

STRUCTURE OF A NAMED VOLUME

Figure A-3 illustrates

an fnode for a long file. Decimal

numbers

are used in the

figure for

clarity.

Figure A-3. I-ong File FNODE

-.=>

F'1

i\[__l

r.1

rolume 9'!^ul!"ir i0?4

, l-l

r-r tl

L__l L_l

t '[",;i.

t-,1

loraLtsrzE

roraLSaLxs

pri ror

. :'

zol

rHrsssrzE

41ry

A-20 Disk Verification

STRUCTURE

OF A NAMED VOLUME

As you can see in Figure A-3, fnode 9 identifies the long file. The actual file consists of

nine distinct data blocks. One PTR structure and an indirect block

give

the locations of

the data blocks. The NUM$BLOCKS field of the PTR structure contains the number

volume blocks pointed

to by the indirect block. The BLK$PTR field points to the first

volume

block of the indirect block.

In the indirect

block, each

NBLOCKS field gives the length of an individual data block,

and

each BLK$PTR

field points to

the first

volume block of a data block.

Figure A-3 also lists the TOTAI-||BLKS, THIS$SIZE, and TOTAL$SIZE values,

which

are more complex than for a short file. The TOTAT$BLKS field specifies the number

volume

blocks allocated to the file,

which

in this case is 21. Of these 21, 20 are used for

actual data storage and 1 is used for the indirect block.

The THIS$SIZE field specifies the number of bytes

of data space allocated to the file,

and

does not include the size of the indirect block. This size is equal

to the NUM$BLOCKS

value

(20)

or the sum of NBLOCKS

values

in the indirect

block

(2 + | + 2 + 3 + 2 + 3 +

3 + 2 + 2 = 20) multiplied by the

volume granularity (1024) and equals 20480.

The TOTATJSIZE field specifies the number of bytes of data space that the file currently

occupies (designated in Figure A-3 by

the shaded areas). As you can see, the file

does not

occupy all the space allocated for it, so the TOTALJSIZE

value (20300) is not as large

the THIS$SIZE value.

4.6 FLEXIBLE DISKETTE FORMATS

The flexible diskette

device drivers supplied with the iRMX II Basic I/O System

can

support several diskette characteristics, listed in Tables A-1 and A-2.

Table A-1. 8-Inch Diskette Characteristics

S€ctor

Siz€ D€nsity Sectors

per

Track Devic€ Size

(in

bytes)

On€-Sided Two-Sid€d

128

256

5'12

1024

Single

Singl€

256256 512512

295168 s90848

314880 6n272

315392 630784

512

1024

Doubl6

Doubl€

Double

5@184 '10216€6

587264 ',l ',177600

626688 1255424

Disk Verilication A-21

STRUCTURE OF

A NAMED

VOLUME

For compatibility

with

ECMA (European Computer Manufacturers

Association) and ISO

(fnternational

Organization

for Standardization), the iRMX II device drivers,

when

called

by the Human Interface FORMAT

command, can format the beginning tracks of all

llexible diskettes in the same

way. A configuration option for each driver enables

you to

specify the following:

. For all 5 l/4-inch and 8-inch flexible diskettes,

the device drivers format track 0 of

side 0

with

single-density,

12fì-byte sectors,

with

an interleave factor of 1.

. For 8-inch, double-sided, double-density flexible diskettes, the device drivers format

track 0 of side I with

double-density, 256-byte

sectors.

The iRMX II device clrivers map the sectors on these beginning tracks into blocks of

device

granularity

size so that the Basic I/O System and the Bootstrap Loader can treat

ilexible diskettes as

if they contained a contiguous string of blocks, all of the same size.

However, this

mapping is not exact

when you

use 8-inch, double-sided, double-density

diskettes

and specify a device granularity of 512 or 1024. A problem arises

because

there

are 26 128-byte sectors

in a track,

which

is not an integral mapping for device granularities

of 512 or 1024. Thus, the device

driver combines the leftover 128-byte sectors of track 0,

side 0 with the first sectors

of track 0, side 1 to make a block of device granularity size.

This continues

throughout track 0, side l, but the same

problem

occurs with

the last 256-

byte sectors of track 0,

side

not enough sectors are available to make

a block of device

granularity

size.

When the

device driver tries to combine these leftover sectors

of track 0, side 1

with

the

first sectors of

track l, side 0, it finds that the sectors

track

1, side 0 are already of

device granularity

size. Therefore, since the

device driver cannot access

partial

sectors, it

is left with

one block

(the

leltover sectors of track

0, side l) that is less than device

granularity

size. When the device granularity

is 512, this small block is block

l9;

when

the

device granularity

is 1024, it is

block 9.

Table A-2. 5 l/4-Inch Diskette Characteristics

Soctor

Size Density Seclors

per

Track

Device

Size

(in

by,tes)

One-Sided Two-Sided

40 Tracks 80 Tracks 40 Tracks 80 Tracks

128

2s6

1024

Single

ingle

Single

81920 163840 163840 327680

91904 1840Ar 1840&1 3683&1

81920 163840 163840 3276€0

81920 163840 163840 3276É0

256

512

1024

Double

1617921 325632 325632 &53312

161792't 325632 325632 653312

1617921 325632 325632 653312

A-22 Disk Verification

STRUCTURE OF A NAMED VOLUME

If nothing is

done to exclude this smaller-than-normal

block from use, the device driver

will treat this block as a normal block, assuming it is of device

granularity

size. Thus, if

you try to write information to that

block, the driver will attempt to write an entire device

granularity block

of information into a block

that is much smaller, thereby losing

data.

To prevent

this situation, the Human Interface FORMAT command automatically

declares this smaller-than-normal

block as allocated

in the

volume

free space map when it

formats

the

volume. This prevents

the Basic I/O System from ever writing information

into this block. If you

wite your

own formatting utility, you

should also declare this block

as allocated.

Disk Verificotion L-23

< command 2-6, 29

<CR> command 2-6

> command

2-6,

5 ll4-inch diskette characteristics

A-22

8-inch diskette characteristics

A-21

Aborting commands 2-4

Add command 2-46

Address command

2-46

Allocate command 2-5, 8

Argument error 2-5

Automatic device recogrition A-4, 5

Backing up the

volume

label 3-6

Backupfnodes command 2-5, I I

Bad blocks 2-8,44,3-2

Bad blocks map file 2-9, 59, 60, 65, 66, 69,72,

, A-8,

Bad track information, displaying 1-3

BF command 2-5,

1 I

Block allocation

2-8

Block command 2-47

Block I/O error 2-4

Bootstrap Loader blocks A-l

Checksums 1-4, 2-31, 36, 65

Command options

All 1-5

Disk 1-3

Fix 1-4

Getbadtrackinfo

1-3

List 1-5

1ó

Disk Verification Indcx-l

INDEX

Command options

(cont.)

Named 1-4

Namedl 1-4

Named2 l-4

Physical 1-5

Veriff l-3

Commands

< 2-6,29

<cR> 2-ó

> 2-6,28

Aborting 2-4

Allocate 2-5

Backupfnodes

2-5

BF 2-5, 11

D 2-6, 16

DB 2-ó, 16

DD 2-6,20

DF 2-6,23

Disk 2-6, 13

Displaybyte 2-6, 16

Displaydirectory

2-6, 20

Displafnode 2-6, 23

Displaynextblock

2-ó, 28

Displaypreviousblock

2-6, 29

Displaysavefnode

2-6, 27

Displayword

2-6, 18

DNB 2-ó,28

DPB 2-6,29

DSF 2.ó

DSF command

2-27

DW 2-6, 18

E 2-6,34

Editfnode

2-6,30

Editsavefnode

2-6,33

EF 2-6,30

Error messages

2-4

ESF

2-6,33

Er/.J.r

2-6,34

Fíx 2-6,35

Free

2-6,38

GB 2-6,4r

Getbadtrackinfo

2-6, 41

H 2-7,43

Index-2 Disk Verification

Commands

(cont.)

Help 2-7,43

LBB 2-7,44

Listbadblocks

2-7, 44

Miscellaneous 2-7,

Names,

entering 2-2

Parameters

2-3

2-7,s2

Quit 2-'7,

R 2-7,53

Radices 2-3

Read 2-7,53

Restorefnode

2-7,54

Restorevolumelabel

2-7, 57

RF 2-7,54

P.VL 2-7,57

s 2-7,61

Save 2-7,59

sB 2-7,61

Substitutebyte

2-7,61

Substituteword

2-7,64

Summary

2-5

sw 2-7,64

Syntax

2-1

v 2-7,65

Yerlîy 2-7,65

w 2-7,74

Write 2-7,74

Conventions

D command 2-6,

1ó

DB command 2-6, 16

DD command

2-ó, 20

Dec command 2-48

DF command

2-6, 23

Directing output 1-2

Directories,

displaying 2-20

Disk command

2-6, 13

Displaybyte

command 2-6,

Displaydirectory

command 2-6,

Displayfnode command 2-6, 23

Displaying R?SAVE 3- 1

Displaynextblock

command 2-6, 28

INDEX

Disk VerilÍcation Index-3

INDEX

Displayprevious block command 2-29

Displaypreviousblock command 2-6

Displaysavefnod

e command 2-6,27

Displayword command 2-6,

Div command 2-48

DNB command 2-6, 28

DPB command

2-6, 29

DSF command 2-6, 27

Duplicate volume

label file 3-2,

A-8,

DW command 2-ó, 18

E command 2-6, 34

Editfnode

command 2-6, 30

Editsavefnode command 2-6, 33

EF command

2-6, 30

Error Messages 1-6, 2-4

Add 2-51

Address

2-51

Allocate 2-10

Backupfnodes

2-12

BF 2-12

Block

2-51

D 2-77

DB 2-17

DD 2-21

Den 2-51

DF 2-26

Displaybyte

2-17

Displaydirectory

2-21

Displayfnode

2-26

Displaysavefnode

2-27

Div 2-51

DSF 2.2'7

Editfnode

2-31

Editsavefnode

2-33

EF 2-3r

ESF 2-33

Free 2-39

GB 2-42

Getbadtrackinfo

2-42

Hex 2-51

Index-4 Disk Verification

Error Messages

(cont.)

LBB 2.45

Listbadblocks 2-45

Miscellaneous commands

2-51

Mod 2-51

Mul 2-51

R 2-53

Read 2-53

Restorefnode 2-55

Restorevolumelabel

2-58

RF 2-55

RvL 2-58

s 2-62

Save 2-ó0

sB 2-62

Sub 2-51

Substitutebyte 2-62

v 2-69

VeriS 2-69

w 2-75

Write 2-75

ESF command 2-6, 33

Examples

Add 2-51

Address 2-51

Backupfnodes 2- 12

BF 2-12

Block 2-51

D 2-17

DB 2-17

DD 2-22

Dec 2-51

DF 2-26

Disk 2-15

Displaybyte 2-17

Displaydirectory 2-22

Displayfnode

2-26

Displaysavefnode 3- 12

Displaying R?SAVE 3-12

Displayvord 2- 18

Div

2-51

DSF 3-12

DW 2-18

INDEX

Disk Verification Index-5

INDEX

Examples (cont.)

Editfnode

2-32

EF 2-32

H 2-43

Help 2-43

Hex 2-51

LBB 2.44

Listbadblocks

2-44

Miscellaneous

commands

2-51

Mod 2-51

Mul 2-51

Restorefnode

2-56

Restorevolumelabel

2-58

Restoring

fnodes 3-4, 8

Restoring the volume

label 3- 11

RF 2-56

RvL 2-58,3-11

s 2-63

Save

2-60

sB 2-63

Sub

2-51

Substitute word 2-64

Subsritutebyte

2-63

sw 2-64

v 2-73

Yertfy 2-73

w 2-75

Write

2-75

Exit command 2-6, 34

FiÌe descriptor

node (fnode) A-8

File sizes A-19,21

Fix command 2-ó, 35

Fixing

bad checksums

2-36

Flexible

diskette

formats A-21

Flexible

diskette

track

0 abnormalities

A-22

Fnode

Access

ID A-12

Altering 2-30

Auxiliary

byes A-13

Backing

up on a

volume 3-5

Index-ó Disk Verilication

Fnode

(cont.)

Creation time A-11

data block identification

A-11

Displaying 2-23

Flags 2-9, A-9

Freeing 2-38

Granularity A- 10

last file access A- 11

last modification A-11

Overview A-8

Owner A-11

Parent 2-65, A-13

Restoring 2-54,3-1,7

size

(byes) actual data A- 1 1

size (byes) data space

A-12

Structure A-9

Type A-10

Volume

blocks A-11

Fnode allocation 2-8

Fnode file 3-1, 2, A-14

Fnode file/space

map

file inconsistent 2-5

Free command 2-6, 38

Free fnodes map file 2-9, 39, 59, ó0, 66, 69,72,3-2, A-15

Free space A-15

Free space map frle 2-72

GB command

2-6,

Getbadtrackinfo

command 2-6, 41

H command 2-7,

Help

command

2-7, 43

Hex command 2-49

Illegal command error 2-4

Initial files A-8

Invocation 1-2

Error messages 1-6

Example 1-5

Interactive 1-6

Single command mode I

-5

INDEX

Disk Verlfication Index-7

INDEX

IRMXo II volume labels A-4

ISO

volume

label A-3

LBB command 2-7, 44

Listbadblocks cornmand 2-7, 44

Location of files 3-1, A-18, 19

l,ong files 2-65,3-1, A-'19

Manual overview iii

Marking bad blocks 2-8

Miscellaneous

commands 2-7, 46

Add 2-46

Address

2-46

Block 2-47

Dec 2-48

Div 2-48

}lex 2-49

Mod 2-49

Mul 2-50

Sub

2-50

Mod command

2- 49

Modes of operation

1-1, 2-1

Mul command

2-50

Named volume

structure

A-1

Named volumes 1-4

Not a named

disk error 2-5

Operational

modes

1-1, 2-1

Orphan fnodes

l-4,2-36

Parameters

2-3

Product

overview iii, 1-1

Index-8 Disk Verification

Q command 2-7, 52

Quit

command 2-7, 52

R command 2-7, 53

R?SAVE 2-t7, 14, 27, 33, 54, 55, 57,3-2,5, 11, A-17

Radices 2-3

Read command 2-7, 53

Reader kvel iii

Reading

volume

blocks 2-53

Restorefnode command 2-7, 54

Restorevolumelabel

command

2-7,

Restoring fnodes 3-1

Restoring the

volume

label 3-10

RF command 2-7, 54

Root directory A- 16

RVL command 2-7,

S command 2-7, 6l

Save command 2-7,59

SB command 2-7,

Seek error 2-5

Short files 3-1, A-17

Size of files 2-65, A- 19, 2l

Space accounting

file 3-2, A-15, A-8

Structure of a named

volume

A- I

Sub command 2-50

Substitutebf e command 2-7,

Substituteword command 2-7,

SW command 2-64

Syntax error 2-4

Track 0 Abnormalities.

flexible diskettes A-22

INDEX

Disk Verilication Index-9

INDEX

V command 2-7, 65

Verifo

command 2-65

Volume

attributes, displaying 1-3, 2- 13

Volume blocks, freeing 2-38

Volume

free space map file 2-9, 39, 59, 60, 66, 69,3-2, A-8, 1-5

Volume label

backing up 3-6

iRMXO

II A.4

ISO A-3

Restoring

3-10

Volume

label frle 2-57,3-1,2, A-8, l6

Volume

structure

Named A-2

W command 2-7, 74

Working

buffer,

changing contents 2-62

Write

command 2-7, 74

Index-10 Disk Verification

intel

GUIDE

TO TH

EXTENDED iRMX@II

INTERACTIVE

CON

FIG

U RATION

UTILITY

lntel

Corporation

306 5

Bowers Aven u e

nta

Cla

ra,

lrfornia

95051

Copyrìght 1988,

lntel

Corporatlon, All R

ghts

Reserved

PREFACE

INTRODUCTION

This manual

describes the Interactive Configuration

Utility

(ICU) and explains its use. It

does

not explain each screen displayed by the

ICU. For a description of the ICU screens

and

their parameters,

refer to the

Extended |RMX II Interactive Configuration Utility

Reference Manual.

READER

LEVEL

The manual assumes that you are

familiar

with

the monitor and

keyboard

from

which you

run the

ICU. It is also helpful if

you

are familiar

with

the tbllowing:

. The Extended iRMX II Operating System

. PL/M-286

r BND286 and

BLD286

MANUAL

OVERVIEW

This manual is organized as follows:

Chapter 1 This chapter provides introductory material

configuring

iRMX I I system using the Interactive Configuration Utility

(ICU).

Chapter 2 T)1is chapter describes

how

to generate a system.

Chapter 3 This

chapter describes how to

prepare application

jobs.

Chapter 4 This chapter

provides

overuiew infbrmation

on how to add users to

your

system. For detailed information on adding users,

ref-er to the

Extended iR'UX Operator's Guide to tlrc Human Interface.

Chapter 5 This chapter describes how to load and test

the system.

ICU

Useds

Cuide ul

PREFACE

Appendix A 'l-his

appendix

lists files created by the ICU.

Appendir B This appendix

shows an examplc configuration session.

Appendix C This appendix describes how to

program

generated

28(r-based

system into PROM devices.

Appendix

D This appendix describes how to

program

a 386/100-based

system

into PROM devices.

CONVENTIONS

This manual uses the following conventions:

. Information appearing as UPPERCASE characters when shown

keyboard

examples must be entered or coded exactly as shown. You may, however, mix lower

and uppercase characters

when

entering the text.

. Fields appearing as krwercase characters within angle lrrackets (< >

) when shown

keyboard examples

indicate

variable

information. You must entcr an appropriate

value

or symbol for

variable

fields.

o lJser

input appears in one of the following forms:

as bolded text wlthln a screen

. The term "iRMX ll' ref ers to the Extended iRMX Il.3 Operating System.

. The

term

"iRMX I'rclers to the

iRMX I (iRMX 86) Operating

System.

. All numbers unless othcrwise

stated are assumed to be decimal. Hexadecimal

numbers include the

" " radix character

(for

example,0FFH).

lv ICU User's

Guide

CONTENTS

CHAPTER 1 PAGE

ICU

Usefs

Guide

CONTENTS

CHAPTEB

1 (continued) PAGE

CHAPTER 2 PAGE

CHAPTER

3PAGE

CHAPTER 4 PAGE

YI ICU Use/s

Guide

CONTENTS

CHAPTER 5 PAGE

APPENDIX A

FILES

CREATED

BY THE ICU PAGE

APPENDIX B

EXAMPLE

SYSTEM

CONFIGURATION PAGE

APPENDIX

PROGRAMMING

A 2SSBASED

SYSTEM

INTO PROM

DEVICES PAGE

C.l Introduction ............................

C-l

C.2 Requirements

.........................- .............................

C-1

C.3 Configuring a ROM-Based System................ ................................C-2

C.4 Generating/Building

the System................. ....................................

C-9

C.4.1 Including the iSDM" Monitor and the Bootstrap

Loader

in the PROM

Devices............... .................. C-10

C.4.l.l Setting up the iUP 201 PROM

Programmer

........................................

C- 11

C.4.1.2

Formatting the Operating

System PROM

File ......C-12

C.4.1.3 Programming

the Operating System

into PROM

Devices...........,.....

C-14

C.4.1.4

Programming the

iSDM* Monitor

into PROM Devices.................-..

C'16

C.4.1.5

Programming the Bootstrap

Loader into

PROM Devices.

..........-.....

C-17

C.4.1.6

Starting the Operating

System in ROM

from the iSDM"

Monitor.. C-17

C.4.2

Creating a System

that is activated on Power-up....... ......

C-18

C.4.2.1

Formatting

the Operating System

PROM File .. ... C-19

C.4.2.2 Programming

the Operating

System lnto

the PROM Devices

.. .. .. C-20

C.4.2.3

Starting the Operating

System in PROM... ........'.'..C-23

C.4 Hardware

Jumper Modificatrons..................... .........-...................C-24

ICU

Use/s

Guide Ylr

CONTENTS

APPENDIX D

PROGBAMMING

A 386/lOO.BASED SYSTEM INTO PROM DEVICES PAGE

TABLES

TABLE

tî

l-3

Ylll ICU

Use/s

Guide

CONTENTS

FIGURES

FIGURE

1-1

'ta

].-4

1-5

1-6

J-l

B-1

B-2

B-3

B-4

B-5

B-6

B-7

B-8

B-9

B-10

B-11

B-12

B- l3

B-14

B-15

B- 16

B-17

B- 18

B-19

B-20

B-2"t

B-22

B-23

B-24

B-25

B-26

B-27

B-28

B-29

B-30

ICU

User's

Guide

CONTENTS

FIGURE

B-31

B-32

D-JJ

B-34

B-35

B-36

B-37

B-38

B-39

B-40

B-41

B-42

B-43

B-44

B-45

B-46

B-47

B-48

B-49

B-50

B-51

B-52

B-53

B-54

tl--))

B-56

B-57

B-58

B-59

B-60

B-61

B-62

B-63

ICU Usefs Guide

INTRODUCTION CHAPTER 1

TO CONFIGURATION

1.1 INTRODUCTION

The iRMX II Operating System is modular in structure, enabling

you

to include

or omit

subsystems according to

your

needs. It is also compatible

with a variety of peripheral

boards. The Interactive Configuration Utility

(ICU) is designed

to help you take

advantage of this flexibility.

This chapter

provides

an overview of the ICU. It explains

the configuration

process,

configuration

environment, ICU files, ICU commands, error messages,

the utilities that

comprise the ICU, and more. The chapter

is very comprehensive and includes

many

important

details

for

using the ICU. lntel recommends that

you

read

this chapter

carefully before

attempting to configure your system.

1.2 WHAT IS CONFIGURATION?

Configuration

is the process of selecting your application's hardware

and operating system

layers and then binding and building the entire operating

system. The tool used for

configuration is the Interactive Configuration

Utility

(lCU). The ICU is a menu-driven

utility

which presents

series

screens that

prompt you

lbr intbrmation.

The

information is stored in a definition file that is then used

senerate

the new

system.

The objective of running the ICU is to build

a definition file that contains

all of the

configuration information. This file contains

two kinds of information:

. Initializationparameters

o A set of

variables specirying which operating system layers

and device drivers are to

be bound together

with your

application software

Intel

provides six definition files you can use as a starting

point. If you

run

the UPDEF

Utility

supplied

with

this release,

you

can also use a

definition file from iRMX II.l. (It is

not necessary to run UPDEF if

you are using a definition

file from iRMX IL2.) As

you

perform

the configuration

process,

you

alter the

chosen definition file

to match your

target

system.

ICU

Uset's Guide l-l

INTRODUCTION

TO CONFIGURATION

1.3 WHEN

TO USE THE ICU

You should use the

ICU whenever

one of the following is true:

. You

want

generate

the

configuration files that describe your

system.

. You are

using a system other than

one described by an Intel-supplied

definition file.

o You

are changing an existing

system's hardware and/or

soffware

(e.g.,

adding a new

disk drive).

1.4

tCU LOCATTON

The ICU files are located in the

directory :SD:RMX286/ICU.

When working with

the

ICU, you

must use

the full

pathname

each command (see

Figure l-l) or

create an

ALIAS for the pathname.

Figure

1-1.

klcation

ofthe ICU Directory in an Intel-supplied

System

t-2 ICU

User's Guide

INTRODUCTION TO CONFIGURATION

1.5

THE

GENERAL

PROCESS

OF USING THE ICU

You configure a system

in three steps:

1. Intefactively modify a definition

file

(see

Figure 1-2). To do this, invoke the

ICU

and then supply information

to filì in screens that the

ICU presents. (This

step can

be omitted ifyour system

matches one ofthe Intel-supplied definition files.)

2. When you

finish configuring the operating system,

use

the

ICU to

generate

new

configuration files as defined in your

modified definition file

(see

Figure l-3). The

end

product

is a

group

of files that

define the system.

3. Exit from

the

ICU, and at the Human Interface level, execute the submit file

created by the ICU during the generate

step (see Step 2). This creates

the

new

version of

the operating system which can then be loaded and executed.

Figure l-2. First

Step:

Editing

Definition

File

QU€STTONS

Ntw

DrscRrPfroN

FILT

DEFAULT OR OIHER

OLD

DtSCRtPION

FIL E

ICU

User's Guide l-J

INTRODUCTION

CONFIGURATION

COMMANDS

Figure l-3. Second Step: Generating

a Subrnit File and Source Files

fINAL

DTSCRIPfION

FILE

CONFIGURAfION

SOURCE FILE

1.6

WHAT

TO DO BEFORE

INVOKING

THE ICU

Before you

invoke the

ICU, you

must

perform

checks

your

existing

system and make

several decisions.

The

following sections provide

the information you

need

to know

before

invoking

the ICU.

1.6.1

Configuration

Environments

You can run

the ICU on the followins svstems:

o An Intelle@ Series

IV Microcomputer

Development

System with

256K contiguous

bytes

of memory,

a hard disk,

and

version

2-8 or later of

the iNDX Operating

System.

r An iRMX Il-based system with

1 Mbyte

of RAM memory which

allows a user

partition

of 384K

bytes, a hard

disk, and the

iRMX I I Operaring System.

For

information

on changing the

amount

of memory allocated

your

terminal, see

the section

on editing

the :CONFIG:TERMINALS

file in Volume

l, Operator's

Guide to the Human Interface.

l-4 ICU

Usefs Guide

I n-TRODUCTI ON

CONFI

RATION

1.6.2 Ensuring

the ICU Files

are on

Your Hard

Disk

Contained

on the iRMX II Operating System release

diskettes or tape are

the files to run

the ICU. These

files must be on the hard disk before

you

can

invoke the lCU. Follow

the

instructions

in fhe Ertended |RMX II Hardware and Software

Installatiotl Guide

to copy

these files

to your system.

Table 1-1 lists all of

the

files

required to run the Interactive

Configuration Utility

for

iRMX II systems and for iNDX systems.

Check that

your

hard

disk contains all

of the

files required by

your system. If your hard disk does

not contain the

required files, return

to the instructions in the

Extended

|RMX II Hardware

and Soflware Installation

Guide.

Following

the directions in that manual

will place

all

the iRMX II files

into the standard

directorv structure.

ICU

Useds

Guide l-5

INTRODT]CTION

TO CONFIGURATION

Table I-1. |RMX@ ll ICU Files

Function Filename

tcu286

Scre€n Master File

f€mplate File for

System Gen€ration

Update D€finition

Utility

Usor Device

Support Utility

UDS Screen

Master

File

Template

example

(minimum

UDS

input file)

Template example

(UDS

input fÌle

containing user help

built into

help text)

ICUMRG

Utilily

Definition

File for an iRMX

Multi-User

System designed

to run

on the ìSBC

286/10(A) and iSBC

286/12

froards

Definition

File lor an iRMX

Multi-User

System designed to

run

on th6

SXM 386 AP Kir

Definition

File for an iRMX

Muhi-Us6r

System designed to

run on an |SBC

386

/2X aîdM/3X

ooaro

Definition

File lor an

iRMX ll

Multi'User

System

designed

run on an iSBC

286/100A

board

Definition

File for an iRMX

Mutti-User

System designed to

run on an |SBC

386/116 and

386/120

board

lCU286 (for iRMX ll

systems)

1CU286.86

(for

iNDX systems)

rcu286.scM

ICU286.TPL

UPDEF

(for

iRMX ll systems)

UPDEF.86

(for

iNDX systems)

UDS

(for

iRMX

ll systems)

UDS.86

(for

iNDX systems)

UDS.SCM

TEMPLATE-1,UDS

TEMPLATE

2,UDS

ICUMRG

(for

|RMX ll

systems)

lCUMRG.86 (for

iNDX systems)

28612,DEF

SXM

386.DEF

38620.

2861004.

D E F

3861m.DEF

l-6 ICU User's Guide

INTRODT]CTION

TO CONFIGT]RATION

1.6.3

Choosing

Your Definition

File

lf you have

never configured an iRMX-based system before,

you should

choose

one of the

Intel-supplied,

multi-user definition files

(listed

in Table 1-l) as input into the ICU. You

can build a definition

file

screen

by v:reen, but

you will

save time by starting

with a

standard

definition file. Details on the standard definition files are

qiven

in the Extended

iRMX II Hardware and Software Insnllation Guide.

If you

created

a definition

file using an iRMX II.l version

the ICU,

you

can use this file

input to iRMX II.3 of the ICU only after running the UPDEF Utility. Once

you create

a iRMX II.3 definition file, you cannot use it rs input

into

iRMX IL I of the ICU.

The Intel-supplied definition files define 80286- or 80386-based MULTIBUS

I and

MULTIBUS II systems.

These systems are fully configured

multi-user iRMX II

Operating Systems. Each layer implements all its system calls and most

of the features

and drivers provided by the iRMX ll Operating System. Multiple users can

communicate

with

the operating system interactively through a terminal or

via

an application

program,

and can access secondary storage. The definition files include UDI so that

you ciìn run

languages, such as PL/M-2t16, PASCAL, and FORTRAN.

To define your own system, modify the definition file that comes closest

to your needs.

To see the contents of a dcfinition filo, use thc LIST

command

(described

later

in this

chapter). Details of board configuration and interrupt

levels are

given

ìn the Extended

|RMX

II Hardware

and

Software Inslallatbn Guide.

1.6.4

Checking

Access Rights to Definition Files

Ifyou use the ICU on an iRMX II-based system, the operating

system makes sure

you

have the proper access to both the definition files and their rcspective

directories. This

check is performed in two instances:

when you invoke

the ICU and

when

vou enter the G

(generate)

command

(discussed

in a later section). If you do not have

proper access, onc

or more of the following:ituations

can occur:

. The ICU will be unable to read the input definition

file.

. The ICU will be unable to save

the

changes

you make tJuring the ICU session.

. The ICU will be unable to create the

generation files necessary

to complete the

configuration

process.

Following the

installation instructions in the Extendcd |RMX II Ilurdu'are

artd Software

Installation Galde ensures

that the user

WORLD can

senerate

a new

version of the

operating system.

ICU User's Guide t-7

INTRODUCTION

CONFIGURATION

To check your access

rights to directories and files contained

in directories, use the DIR

command

folÌowed

by the E[xtended] or

Llong] options,

For example,

you

can check

your

access

rights to the :SD:RMX286/lCU

directory and the 28612.DEF

file by using the

following commands:

DIR :SD:RMX286

E[xtended]

DIR :SD:

RMX286/ICU E[xtended]

For more information

on using

the Human Interface

commands, see the Operator's

Gui"de

to the futended |RMX II Human Interface.

The access rights

needed to use the ICU successfully vary

according

to the operations

performed.

all cases

where

the G (generate)

command

is to be used,

you

must

have

Add Entry

access to the directory

containing the definition

file and to the

directories

you

specify in the'Generate

File Names" screen.

In other cases,

the access

required depends

on the

kind of file (new or existing) and

whether

it is an input or output file. The

following paragraphs

describe

the access rights

required in different

circumstances.

. Ifyou specify

an existing <Jefinition

file as an input

file,

you

must have Read access to

the

definition file.

. If you

specifu an

existing definition

file as an output

file, you must

have Delete and

Write access

to the definition

file. You

must also have

Add Entry access

to the

directory

containing the

definition file.

. Ifyou specify

an existing definition

file as

the only definition

fiìe

on the command line,

the file serves as

both an input

and an output

file. In this

caser

you

must

have

Read/Write and Delete

access to the

definition file. (Refer to the Extended íRMX II

Interactive

Configuration

Utility

Reference

Manual fr>r more

information

about the

"Generate

File Names" screen.)

. If you

specify

a new file

as the only

file on the command

line, the

file serves as both

input file and

an output

file. In this

case, you

must have Add

Entry access to

the

directory

containing

the new

file.

Ifyou do not

have the correct

access

rights, the

ICU returns

the following

message:

0026: E$FILE_ACCESS,

while loadlng command

Additional information

about access

rights can

be found in the

\RMX II Extended I/O

System User's

Guide.

t-8 ICU

Usefs

Guide

INTRODUCTION

TO CONFIGURATION

EXAMPLES:

To use the G command

without causing an error,

you

must have Add/Delete

Entry access

to the directory in which you

are

working. This section

describes the

various ways

invoking the ICU and the access rights required.

- /RMX286/ICU /

ICU286 :HOME:NEW.DEF

where

:HOME:NEW.DEF Pathname of

new

definition file. The

ICU uses this file

both the input file

and the output file.

You must have

Add Entry access to

the directory

containing NEW.DEF

(:HOME:). If you

not have Add

Entry access, the ICU returns

the following message:

*** T,/n Frr^r in file HOME:NEI,J.DEF

0026: E$FILE_AccEsS

If the

directory does not exist,

the ICU returns

the

following message:

*** I/0 Error in file: :HoME:NEl,].DEF

0021: ESFILE

NoT EXIST

/RMX286/rcu

ltcu286

DIRi

oLD.DEF

where

DIR/OLD.DEF Pathname

of an existing

definition

file. The

ICU uses this

file as both an input

and an

output file. It can be

a new or

existing file.

You must

have Read/Write

and Delete

access

to save

changes

to OLD.DEF.

- /RMX286/ICU

I LCUZ86

/ RMX286

I3UIINPUT.DEF to

DIR/OUTPUT.DEF

ICU Usefs

Guide t-9

INTRODUCTION

TO CONFIGURATION

wnerc

/RMX286/lCU/INPUT.DEF Pathname of a standard definition file. The

ICU uses

this file as the input file

DIR/OUTPUT.DEF Pathname of the output definition

file. This file can be

a new or existing

file.

You must

have Add Entry access to the directory

containing

OUTPUT.DEF

(DIR). ln addition, if

OUTPUT.DEF is an existing

file,

you

must have Delete

access to lt.

1.7 DISTINGUISHING

ICU-GENERATED

FILES

Each time you generate

your system, the

ICU generates

a set of ICU files. To help

you

distinguish your generation

files from each other

and to determine which

input definition

fìle generated

the ICU files, you

can use one of these

options:

. Create a new directory

to contain

your

definition

file.

. Use the prefix

option supplied

by the ICU.

The followins

sections describe each

method in more

detail.

1.7.1

Creating Directories

for iRMX@

ll-Based

Systems

Intel

recommends that you

maintain the

default tlirectory

structure by placing

any new

system definition

files in a

new directory nested

your

:HOME:

directory. Before

invoking

the ICU, you

should creaîe

a copy of the

input definìtion

file in your working

directory

to avoid corrupting

the original

file. The

following example

illustrates how to do

this using the

28612.DEF

file as the starting

definition file:

Once

you

attach

the new directory (28612)

the

working

directory, you

will

need to use

the full pathname

to invoke

the ICU. For example

You may

wish

to creiìte an

ALIAS for the

complete

pathname

used

to invoke the lCU. A

convenient

convention

to use is to create

the

working

directory with the same

name as the

definition

file (without the .DEF extension).

The operating system produced

should

have

the same

name as the

definition

file (with a .286 extensionì.

l- l0 lCtl User's Guide

INTRODUCTION

CONFIGURATION

1.7.2 Using

the Prefix

Option

A second method

to distinguish

your

ICU generated files from

each other is to

use the

prefix

option

supplied by

the

ICU. You can select the

prefix option

when entering the

Generate

(G)

command.

The ICU then displays a

prompt

(see

Chapter 2 for the actual

screen) asking

you

for the

prefix letter you wish to assign

to the files created

by the lCU.

For

example, if

you

choose the

letter "Q" as

your prefix

option,

a "Q"

will precede all the

files

generated

when you enter the Generate command

on the menu screen.

In this case

the files

generated for the Nucleus

will be

QNTABL.A2S

QNUCDA.A2S

QNJOBC.A2S

The files created

for all other subsystems

will also be preceded

by the letter

"Q" as in the

example

above. Ifyou want to generate configuration

files for more

than one system,

choose a different

prelìx option each time. Intel

also recommends

that

your

input

definition file

start

with

the same

prefix letter you assign

to the generatetj

files. This

allows

you

to easily determine

which definition files

created each

set of output files-

you create a file

with a prefix that already

exists, the ICU over-writes the

previous file.

If you

do not

want to use the

prefix option, enter a carriage

return

when

you

are

prompted for the

prefix. This causes the ICU to generate

the output files

without a

prefir

(see

Appendix

A for

a complete list of the

ICU generate<J

files).

1.8 INVOKING

THE

ICU

This section lists

the syntax necessary

to invoke the ICU. When invoking

the ICU,

be sure

that

the ICU286.SCM

file and the ÌCU286.TPL

file reside in

the same directory

as the

ICU286 file that

you

are invoking.

The syntax

for invoking

the ICU is as follows

(brackets indicate

optional items):

lCU286

[input-file-name

TO] output-file-name

where

input-file-name Name of the definition

file from

which the

ICU obtains

configuration

information.

This

is typicaUy

an lntel-supplied

definition fiÌe

or a delìnition

file from

previous use of the

ICU.

output-file-name Name

of the definition

file to

which the ICU writes

updated

conficuration

information.

ICU User's Guide l-lI

INTRODUCTION

CONFIGURATION

The following guidelines

must be

followed

when

specifying

input and output

files:

input-file-name:

If both an

input-file-name and

an output-file-name

are specified,

the

input-file-name

must represent

an existing definition

file created by the ICU.

output-file-name

only: If the input-file-name

is omitted, you

enter only the output-

file-name, the ICU uses the output-file-name

as both

the input and output

definition

file. When

the ICU session is complete,

the ICU writes

the updated

configuration

intbrmation back

to the output-file-name.

The output-file-name

entered can

represent a new

or an existing

definition file. If

the output-file-name

specified

does not exist,

the ICU searches

the directory

containing

ICU for a file named

ICU286.DEF.

If ICU286.DEF

exists, rhe ICU uses

it as the input

fiJe. In any

case

where

an input

file does

not exisr, the ICU displays

the

following message

among the

main screen display:

NEW

CONFICURATION

FILE

and the session

starts with

the ICU default values.

After saving

or exiting, the

edited file

is stored in

the named outnut

file.

1.8.1

Invocation

Error

Messages

when issuing

the invocation previously

described,

a number

of error

messages can occur.

These

error

messages

are described

in the following

paragraphs.

Invoking

the

ICU with

no parameters

or invalid parameters

causes

the following

message

to be disolaved:

*** twALID INVoCATION

***

USACE: ICU286 [

input -

fí 1e T0l output -

fi 1e

Invoking

the

ICU with

a corrupted

definition

file,

or a lìle rhat

is not

a definition

file.

causes

the following

message

to be

displayed:

On invocation

the ICU validates

the file version

numbers.

ICU286.SCM,

ICU236.TpL,

and

each definition

file

have an

Intel Version

Number,

an UDdate

Version

Number.

and a

user Version

Numher.

The

Intel

version

numher

changes

*Leneuer

Intel upgrades

the

ICU to support

new

release.

The Update version

number changes whenever

the

ICU is

upgraded,

using the

ICUMRC utility,

to support

an update;

and

the User version

number

changes whenever

a user

device

is atlded (using

the

UDS

and ICUMRG utilities).

l-12 ICU

Usel,s

Guide

INTRODUCTION

TO CONFIGURATION

The ICU checks the

version

numbers

when

it is invoked.

If there is an inconsistenry in

the version

numbers of

either ICU286.SCM

or ICU286.TPL, the

ICU displays the

following

error message and

returns control

to the operating system:

*** ERROR

. INCONSISTENCY

IN THE VERSION

OF THE INTERNAL lCU FILES

Versions: lntel Update User

ICU286.SCM <Intel> + <rpdate> <User verslori>

ICU286.TPL <lntel + UDdate> <User versiorì>

If the inconsistenry is in

the definition file, the ICU displays the following

warning

message and asks for permission

to upgrade

the file or restore from the file. (The

upgrade process

is a simpler, faster

operation than restore and requires no additional

user

input.)

lf the

ICU needs to restore from a

file in order to use it,

you

will

prompted

as follows:

Do you lrant to restore frorn the fíl.e? y/lnl

A response of

"No"

causes the ICU to stop executing. A "Yes" response

means the ICU

will

restore the backup information stored in the

definition file

(discussed

later in this

chapter). If the Update version number

is higher than the ICU version

number, you are

probably

using the

wrong version

of the

ICU. In this case, the ICU displays this

warning

before

the restore

DromDt:

*** WAINING

- The DefiniCion File version is NEIIER

However,

if the ICU is able to use the file without restoring, it prompts with

Do you want to updace the flle? y/ln]

A response of "No" causes the

ICU to stop exccuting. A "Yes"

response causes

the ICU to

update the

file. Since the

ICU

processes

delìnition files

with

inconsistent

version

numbers,

you

can use all of the Intel-supplied definition fles as input for

your

own tailor-

made ICU.

*** WAIìNING. DEFINITION

FILE

ITS VERSION

IS:

VERSION EXPECTED:

VERSION

IS NOT CORRECT.

ICU Usefs Guide l-13

INTRODUCTION TO CONFIGURATION

The ICU issues

the restore

prompt if it discovers any

of the following in the

definition

file:

. Inconsistency

in the Intel

version number.

o Inconsistency

in the User

version

number, if the file contains user devices

a<lded

with

UDS and ICUMRG.

. Inconsistency

in the Update

version number, if the fi.le

version number is higher

(newer)

than the ICU version number.

The ICU prompts for permission to use the file

without restoring in the following cases:

. Inconsistency in the User

version number, if the file does not contain

user devices.

. Inconsistency in the Update

version

number, if the file

version number is smaller than

the ICU version

number.

1.9 WHAT TO DO AFTER INVOKING THE ICU

After

you

invoke the ICU, the main menu screen is displayed as follows:

iRMX I1 Interactive Configuratlon Uttlity For Extended iRMX lI,<v>

Copyrlght <years> lntel Corporat

ion

For general help ln any screen enter H <CR>.

The following cornmands are available

Change

Cenerate

List

S ave

qui È

Exit

Replace

Detail-Leve1

Backup

ENTER COMMAND :

In the screen shown

above is the main ICU menu, whenever

you see this screen you are in

command mode. The string

<v> represents the ICU version

number. The

string

<years>

represents the copyrighted years of the product.

t-14 ICU User's Guide

INTRODUCTION TO CONFIGURATION

Whenever you

are in command mode,

you

must enter one of the commands listed or an

"H"

for help. All ofyour responses should be

followed by a carriage return.

The ICU

regards all invalid input as a response of "H <

" and displays the "Help" screen until a

valid

response is entered.

The following sections

describe the choices on the menu screen.

1.9.1 Help Command

ENTER COI4ì.1AND : H <CR>

ICU

Use/s

Guide l-15

INTRODUCTION TO CONFIGURATION

Ifyou enter H (help)

and a carriage

return, the ICU will display the following

screen:

The Change (C) comnand allows you to specify the configuratlon

paraméters that define your syscen. To get to a specific

screen, Èype 'C screen$nanne'. C? gives you a list of all the

screen nanes

The Generate (G) connand creates the submit file and all Pl,!{

and assembler files required to create your Extended iRì,fX II

system.

The List (L) comnand shows you the current state of yóur

configuration flle. To copy the values thac define your

systen to a file, t)?e 'L file$name'.

Thè Quit (Q) comnand leaves the ICU wíthout saving any

changes.

The Exit (E) comnand leaves the ICU and saves all the

changes.

The Savè (S) comrnand saves all the changes lrithout leaving

the ICU.

The Replace (R) comrnand

replaces the current control

chatacter.

The Detail level (D) cornrnand

sets the leveÌ of detail.

The Backup (B) comrnand writes a backup fÍle.

TYPE

<CR> to Cont inue

1.9.2 Change

Command

ENTER COMMAND : G[hange] lScreen Abbrev] <CB>

l-16 ICU Usefs Guide

INTRODUCTION TO CONFIGURATION

The Change command enables

you to begin editing

the definition file. The syntax of the

Change command is as

follows

(the

elements inside the brackets are optional):

C[hange] [screen

abbrev]

where

C or Change Starts editing the definition

file from the first

screen (the

"Hardware"

rcreen). The first time

you

run the ICU you

should

use this option.

screen abbrev Begins editing at

specific screen.

For

example,

ifyou enter "C", a

space, the abbreviation of

existing screen, antl a carriage return,

the

ICU enables

you

to start editing

your

definition file from

that

particular

screen.

If you

enter a screen abbreviation incorrectly, the ICU displays a

screen containing all the screen names and abbreviations (see

Table l-2). The abbreviation enclosed in parentheses

indicates

what

must be entered for each screen.

? Causes the ICU to display a screen with all the screen names and

abbreviations.

Table 1-2 lists all the

possible

screen names. The screens are displayed in order from left

to right, that is the

"Interrupts"

screen is displayed after the

"Hardware"

screen. Device

drivers are listed at the end

of the table.

Ifyou did not invoke the ICU with

the name of an existing

definition file, you should start

your edit

with

the

"Hardware"

screen.

If you did invoke the ICU with

the name of an

existing definition file,

you

can start your edit with the name of any screen that the input

definition file has already defined.

lfyou enter

a valid screen name but that screen is not

configured into

your

definition file, the ICU displays the next "main" screen followed

this warnins:

***ltarning - The screen requested cannot be displayed

The ICU progresses from screen to screen in a logical orcler.

Refer to Figure 1-4 for

the

losical flow of the ICU.

ICU UseCs Guide l-17

INTRODUCTION TO CONFIGTIRATION

1.9.3

Generate

Command

ENTER CoMMAND

: G[enerate] <CR>

The

Generate command

creates all the ASM,

PL/M, build and submit

files required to

configure

the iRMX II system.

Refer to Chapter

2 for more information

generating

system.

Table l-2. Screen Names

--- Main screens:

--- (HARD)

Hardware (MBll)

Multìbus ll Hardware

(lNT)

Interupts (SLAVE)

Slave

Interrupt (MEMS)

Memory for

System

(MEMF)

Memory

for

FSM (SUB)

Sub-systems (OSEXT)

Extensions

(Hl)

Human Interface (HUOB)

Jobs (RES)

Resident/Recovery User

(PREF)

Prefìxes (HILOG)

Hl Logical (APPL)

Application Loader

(REM)

Remote file Access (REMFS)

Remote

Servers (EIOS)

EIOS

(ABDR)

Auto Boot Dev iLOGN)

Logical

Names (IOUS) l/O Users

(IOJOB)

l/O Jobs (BIOS)

BIOS (BCALL)

BIOS

System Calls

(IDEVS)

Intel Devices (USERD)

User

Devices (UDDM)

UDS

Device Driver

Mods

(SDB)

System

Debugger (NUC) Nucleus (NCOM)

Communication

Service

(USERJ)

User Jobs (USERM)

User

À4odules (ROM)

ROM Code

(INCL)

Includes and

Libs (GEN)

Generate

File Names (COMNT)

Comments

screen

-*- Device Drivers

--- (D214)

Mass

Storage Controller

Driver

(D8274)

8274

Terminal Driver (D8251)

8251A Terminal Driver

(D253O)

82530

Terminal Driver (D534)

534

Terminal Driver

(D544)

5444

Terminal

Driver (D8848)

Terminal

Comm

controller

(D286)

Line Printer

|SBC

286/10 (D350)

Line Printer

|SBX

350

(D220)

|SBC 220 (D218)

|SBX

21BA (D202)

|SBX 208

(D264)

iSBC 264 (D2s1)

|SBX 251 (DRAM)

RAM Disk Driver

(DSCSI)

SCSI

Driver (0224A)

|SBC 18f.1224A (D410)

|SBC 186/410

(D279)

iSBX 279

ENTER screen abbreviation:

l-18 ICU

Usefs Guide

INTRODUCTION

TO CONFIGURATION

1.9.4

List

Command

ENTER

CoMMAND

: L[ist] fname] <CR>

The

List command enables you

to list

the contents ofyour

definition file to a file or to a

device.

This command lists

the contents

of those screens that you

selected to define

your

system.

The

syntax

of the

List command is

as follows

(the

elements

inside the brackets

are

optional):

L[ist] [name]

where

L or List Lists the contents

of your screens.

name Specifies

an iNDX or iRMX II device

or file. If you

omit the name, the

terminal

(:CO:)

is assumed.

You should list the

definition file to a file

name rather than

to the terminal since

the display scrolls rapidly. If you

want

use your terminal

to review your definition file,

use the Change

command to view

just

those screens you want.

After the ICU has

listed the definition

file to the specified

filename, it notifies you that

the definition

file has been

listed and

returns to command mode. For

example, if

you

listed

the ICU screens

to a file called ICU286.I-ST,

the ICU would

display

The Definition File has been listed to file: ICU286.LST

followed by the

main menu screen.

1.9.5

Save

Command

ENTER

COMMAND : SIavel lname] <CR>

The Save command updates your

definition

file

with

all of the changes

you

entered during

the

current ICU session. The

syntax of the Save command is as

follows

(the

elements

inside the brackets are optional):

S[ave]

[pathname]

ICU

UsePs Guide l-19

INTRODUCTION

CONFIGURATION

where

S or Save

pathname

Saves

all the changes made

in this session.

Pathname

of a file to use instead

of the default output-file-name

save chanses

to the definition file.

When

the Save

command is entered

(followed

by a carriage return), the

ICU updates the

file

you specified as the output-file-name. After

the ICU updates the definition

file, it

notifies

you

that the

specified file has been updated and returns

to command mode.

For

example,

if you invoked the ICU using 28612.D8F as

the output-file-name, the ICU

would display this message followed

by the menu screen:

The Definicion Flle has been

written to fil-e: 28612.DEF

be sure

you

are updating the right file, use the List

command before you save

your

definition

file. The List command displays the name of the output definition

file at the

top of each ICU screen.

1.9.6

Quit

Command

ENTER COMMAND

: Qluitl <CR>

The

Quit

command

enables

you to stop your current ICU session without updating the

definition

file. The synta-r of the

Quit

command is as follows

(the

elements inside

the

brackets are optional):

Qluitl

After you enter the

Quit

command

(followed

by a carriage return), the ICU may display

the

prompt

"Do

you

want to quit without

saving

your

changes?

y/[n]"

to ensure that

you

did

not accidentally enter the

Quit

command. Your response to this prompt should be

either

"Yes"

or "No".

The ICU only displays this prompt

you

use the

Quit

command

after

making changes to an existing definition file or creating a

new

definition

file. If no

changes were made to the

definition file before the

Quit

command

was

entered, no

prompt is displayed.

l-20 ICU Use/s Guide

INTRODUCTION TO CONFIGURATION

1.9.7 Exit Command

ENTER CoMI{AND : EIxit] lpathnarne I <CR)

The Exit command exits the ICU and updates

the definition file

with

all of the

changes

from the current

ICU session. The syntax ofthe Exit command

is as follows

(the

elements

inside the brackets are optional):

E[xit]

[pathname]

where

E or Exit Exits the ICU saving

all the changes made

in this session.

pathname Pathname

of a file to use instead of the output-fiìe-name

to save

changes made

to the definition file.

You should always use either the Exit

or Save command after

using the Generate

command.

1.9.8 Replace Command

ENTER COMMAND : RIeplace] <CR>

The

Replace

command enables

you

to change

the control character

that the ICU uses in

the special editing commands.

The control character

precedes special editing

commands,

the default character is the caret

(^). lfyour terminal does

not support this character,

you prefer

a different

character, use R[eplace]

to change it to any

character of

your

choice. The syntax of the Replace

command is as follows

(the

elements inside

the

brackets are optional):

RIeplace]

ICU User's Guide 1-21

INTRODUCTION

CONFIGURATION

After you

enter the Replace

command

(followed

by a

carriage return), the ICU displays

the followins screen:

ENTER COMMAND

: R{eplace} <CR>

Input new control character :

Enter the

new control character you

select, followed by a

carriage return.

1.9.9

Detail-Level

Command

ENTER COMì,ÍAND

: DIetail-Level] <CR>

The Detail-Level

command

enables you

to set the level

of detail you want

in displaying

the

ICU screens. Thiscommand

provides

the option

of selective

v:reen displays.

Rather

than viewing

all the

screens, you

can elect to see

only screens

of a partìcular

t)?e. There

are four possible

levels you

may request:

All Shows all the

screens

Devices Shows only device

screens

Operating

System Shows all non-hardware

screens

Jobs Shows only

the

job

screens (such

as User,

ì/O and User

Modules

screen)

The syntax

of the

Detail-Level

command

is as follows (the

elements

insitle the

brackets

are

optional):

DIetail-Level]

l-22 ICU

Usefs Guide

INTRODUCTION TO

CONFIGURATION

After

you

enter the Detail-Level

command (followed

by a carriage return), the ICU

displays

the following screen:

If you

enter an invalid response, the ICU reclisplays

this

screen until it receives a valid

response.

1.9.10

Backup Command

ENTER COMMAND

: Blackupl fÍìe.name <CR>

The Backup command

writes

an ASCII backup file containing

a list oî all the

parameter

abbreviations and their current values.

The backup fi.le is used as

input to

the

ICU during

the restore

process (discussed

later in this chapter). Remember, the informaîion

in the

backup file is

part

of the definition

file. The advantage of creating a

backup file is that it

is in

ASCII

which

is easier and safer to use

with

other utilities or electronic mail.

The syntax of the Backup command

follows

(the elements insitle the brackets are

optional):

B[ackup] filename

where

B or Backup Writes

a backup file.

filename Name of the file that

wìll contain the backuo information.

The follorving levels

All

Devices

0perating- Sys ten

Jobs

EMER LeveÌ of Detail

of detaiÌ are available:

ICU

Useds

Guide r-23

INTRODUCTION TO

CONFIGURATION

When

the

backup command has completed, the ICU displays a message that

the filename

specified has been backed-up. It then returns

to command mode. For example, ifyou

backed-up

your definition file to a file named UPDATE.BCK,

the following screen

would

be disnlaved.

The Definition File has been backed-up to file: UPDATE.BCK

For general help ln any screen enter H (CR).

The following commands

are avallable

Change

Generate

Lls t

Save

Qui

Exi t

Replace

Detail -

Level

Backup

ENTER COMMAND

1.9.11 Aborting

ICU

Commands

The ICU enables

you

to abort an ICU process,

without

losing any information, by

entering CONTROL-C. If you enter CONTROL-C during

the execution of an ICU

command (Generate, List, etc.) the ICU stops

executing the current command, and

returns to the

main menu screen. The ICU handles CONTROL-C

differentlv for each

command.

. lf entered in command mode, or during

SAVE,

QUIT,

EXIT or BACKUP, it is

ignored.

e If entered during CFIANGE, it displays the

following message:

C Lo EXTT to the Main-Henu'

o If entered during GENERATE,

the ICU finishes

writing

the file being generated,

disnlavs

'**1t Process ABORTED.

and

returns to command mode

l-24 ICU Usef s Guide

INTRODUCTION TO

CONFIGURATION

If entered during

LIST, the ICU displays the Process ABORTED message, writes the

message to the file or

device specified in

the List command, and returns to command

mode.

[f entered during REPTACE or DETAIL-LEVE,L, the ICU returns

to command

mode.

If entered

while

restoring,

the ICU displays the following messiìge

and returns control

to the operating system.

'*** Process ABORTED

- The Definltion Flle rtras

not resl-ored.'

1.10

CHANGING

A DEFINITION

FILE

It is

possible

to change a definition

file by entering the

"Change"

command on the menu

screen.

The ICU then shows one screen of information

a time. Each screen pertains to

a specific

area of configuration. The information displayed on the screen consists of a

series of prompts and default values.

Any of the default

values

can

changed.

However,

the changes you make are

not immediately displayed on the screen. They are displayed

only when you

reshow the screen

using the editing command

^R (or R), discussed later in

this chapter, or

just

a carriage return.

Entering another carriage return alìer using one to

reshow

a screen causes you to proceed

to the next screen.

The changes are recorded in the definition file

when you

exit the ICU

using the "E" command or when you

enter the

"S"

command

while still in the ICU.

ICU

Usefs

Guide t-25

INTRODUCTION TO

CONFICURATION

1 .10.1 Explanation

the Basic Screen Elements

The following definitions

will

help

you understand the various parts of :r sc'reen. The

followins screen illustrates the defined terms.

(SCABV) The abbreviation enclosed in parentheses

identifies the

screen being

displayed. This abbreviation is used

with

the "Change" or "Find"

(discussed

later in

this chapter)

commands to access a screen.

SCREEN NAME The name of the screen.

(ABV) The abbreviation enckrsed in parentheses

identifies the

parameter whose

existing value can

be replaced.

PARAMETER DEFINITION This tjefinition

briefly describes the parameter

thar you

can cnange.

[range

ofvalues] This defines the range

of acceptable

values

for this

parameter.

XXX The value in the

current definition file. If the

existing

value

is not what you want,

replace it with

any other

value

within the

range of

values.

(SCABV) SCREEN NAME

(ABV) PAXAì,IETER DEFINITION [range of values] XXX

(ABV) PARAI'IETER DEFINITION Irange of values] XXX

Enter lAbbreviatíon - new

value / AbbreviatÍon ? / H ) :

t-26 ICU Usefs Guide

INTRODUCTION TO

CONFIGURATION

<prompt

line> This line

where

you enter changes

to the screen. The

cursor is located at the

begìnning of this line ready for you

to enter

one of the following:

. An abbreviation, an equal sign (

) and a new value

. An abbreviation

and a

"?",

if you

need

an explanation of

the

parameter

. A ^H (H), ifyou need general

help in understanding

the screen

types or editing commands

. A "?",

you

need an explanation

of the specific screen

Data you enter

on the

prompt

line should be

followed by a

carriage

return (. CR>

The following screen

ìs the first screen

displayed

when

entering

Change mode

with

a new

definition

file. All of the

features described

above are displayed. The screen

abbreviation

ìs (HARD) and the screen

name is "Hardware".

There are nine

(9)

parameter

lines

and a

prompt

line. Each par:rmeter

line includes a

range of legal

values which

may be entered if

the default value

does not meet your system

requirements. The bolded entries on the

following screen

illustratc how you would

use the prompt line to make changes to

two

narameter lines.

ICU

User's

Guide 1-27

INTRODUCTION

CONFIGURATION

The hardware

screen chapter

of. the Ertended

iRMX II Interactive

Confrguration

Utility

Reference Manual

explains how to respond

to the specific

prompts

shown in

this screen.

The

purpose of this section

is to explain how

to make entries on

this and other

types of

screens.

(HARD) Hardware

(DUS) System Bus Type [1 * t'lBI / 2 ^ llBÎÎi

(TP) 8254 Ttmer Port [0-0FFFFH]

(CIL) Clock Interrupt Level l0-71

(CN) Tiner Counter Number

[0,1,2]

(CIN) Clock Interval [0-65535

msec]

(CF) Clock Frequency

[0-65535

khz]

(TPS) Tiner Port separation [0-OFFH]

(NPX)

Nureric Processor Extenslon lYes/Nol

(If) Initialize On-board Functíons

[1.2,3,4,2No]

(BIP) Board lnitialization Procedure

l1-45 Charsl

Encer IAbbreviatlon : ner^' value / Abbrevlation ? / H

cll-4 <CR>

npx=no<CR>

<cR>

ODOH

L229

02H

YES

t-28 ICU Usef s Cuide

INTRODUCTION

TO CONFIGURATION

1.10.2 Entering

File Names, Address

Values,

and

Integer

Constants

You can enter several types ofvalues

in response to a

parameter line, depending

on the

range of

values

for the parameter. The kinds of

values you can enter

include

device/file name A device

file

name can be any device

or file name

acceptable to

the operating

system.

integer constants Constants must

be unsigned integers

that

you

can

enter in any of

three radices:

decimal, hexadecimal

or kilobyte. A trailing radix

character indicates the radix

of the number,

as shown in Table l-3.

The

default radix is decimal.

addresses Address

values must be entered in

the form

SELECTOR:OFFSET.

1'he radix

must be speciiìed

(either

explicitly or by default) for

both portions

of an address. For

example,

you must specify the

selector of

900H and an offset

address of 384H

as 900H:384H.

(llARD) Hardware

(BUS) System Bus îype [1 - M-BI

/ 2 - yIBIf-)

(TP) 8254 Timer PorE [0-0FFFFH]

(CIL) Clock lnterrupt Level [0-7]

(CN) Tixoer Counter Number

10,1,21

(CIN) Clock lnterval I0-65535

nsecl

(cF) Clock Frequency

l0-65535

khzl

(TPS) Timer Port Separation [0-OFF]Il

(NPX)

Nuueric Processor Extension IYes/No]

(IF) Initiallze On-board Functions [1,2,3,4/No]

(BIP) Board Initíalization Procedure Il-45 Chars]

ODOH

1229

02H

Enter I Abbreviation : ne!, value / Abbreviation ? / H )

Table l-3. Integer Constant

Formats

Rad ix TraiLng Character

D6cimal

Hexadecimal

Kilobyîes

None or D

Horh

Kork

ICU Usefs Guide l-29

INTRODUCTION

CONFICURATION

1.10.3 Help Messages

The ICU provides three

types of help messages to supply

information and save you time

as you are defining your

definition files.

. For HELP about parameters,

enter the parameter abbreviation

followed by a "?".

. For

HELP about the screen being

displayed, enter a ?

. For HELP about editing

screens, enter

^H or H.

After reading

the help messages,

enter a carriage return to

return to the screen you were

editing.

1.10.4

Screen Formats

Three basic

tlpes of screen

formats are used in the

ICU: the fixed screen,

the repetitive

screen,

and the

repetitive-fixed

screen. These screen

formats have

similar features.

1 .'l0.4.1 Fixed

Screen Formats

The

fixed screen format

enables you

to make changes by

entering the

two- or three-letter

abbreviation,

the equal sign (

=;, the new

value,

and a carriage

return. The "Hardware,,

screen shown

earlier in this

chapter is a fixed format

screen.

1.1

0.4.2 Repetitive

Screen Formats

Most screens

use the fixed

format to display

information.

However,

a screen

such as the

"Prefixes"

screen,

shown

below, uses a repetitive

screen

format. In a repetitive screen

format,

the same prompt

is repeated many times.

Each time

you

enter

information on

the

screen, you

define

new system

information. In the

example

below, each

time you enter

line of information,

you

define a logical

name for

a directory.

As you

can see from

the

example,

identifoing

numbers precede

each line

of intbrmation.

To make changes to

this

screen,

you should

enter

the line number,

the equal sign (

the

new value,

and a

carriage

return.

After

entering the

change, the

screen is

redisplayed.

l-30 ICU

Useds Guide

(

PREF)

Prefix

[2] Prefix

[3] Prefix

[4] Prefix

[5] Prefix

Prefixes

1-45 characrers

: PRoG :

: UTILS :

: SYSTEM:

I.ANG :

[Number : new valueEnter Changes ,/ "D Nunber / ? / 11

INTRODUCTION TO

CONFICURATION

1 .10.4.3 Repetitive-Fixed

Screen

Formats

The repetitive-fired screen format combines the features of the other two screen types.

repeats a full screen of information any number of times. In the following

example, the

"User

Jobs" screen, you define a userjob by entering inforrnation on the screen.

When

you

complete this

screen

or any repetitive-fired

screen,

one-line query screen is

displayed.

In this case the query screen

asks:

"Do

you have any/more User Jobs?".

If you

answer "yes" or "y", the ICU presents another "User Jobs" screen. Each

time you make

entries to one of these screens

you

define a new user

job. The ICU repeats this screen

until

you

respond

with

"no", "n",

and/or a carriage return

to the prompt.

ICU

User's

Guide l-31

INTRODUCTION TO

CONFIGURATION

(USERJ) User Jobs

(NA.l.t)

Job Narne [

14 Char ]

(ODS)

Object Directory Size [0-3840]

(PMI) Pool Mlnimrtln [20H-

OFFFFFH

]

(Pì,fA)

Pool Maxinuu [20H-OFFFFFH]

(UoB) tlaxinun objects [

1- OFFFFH

]

(MTK) Maxlnun Tasks (

0FFFFH

([PR) l.laximuxn Priority [0-255]

(EHS) Exceptlon Handler Entry Poinc [1-31 Chars]

(

EM) Exception Mode INever/Prog/Envi ron/All ]

(PV) Parameter Valldation IYe

srzNo

]

(TP) Task Pri.ority [0-255]

(TSA) Task EnLry Point Il-31- Chars]

(VAR)

PublÍc Variable Name

[0-31 Chars]

(SSA)

Stack Segnènt Address ISS:SPl

(ssl) stack size [0-OFFFFH]

(NPX)

Nuneric Processor ExtensiÒn Used [Yes/No]

Enter lAbbreviation- new value / Abbreviation ? / H ]

: <CR>

0 60H

OFFFFFH

OFFFF1I

OFFFFH

r29

NEVER

YES

155

0000

0000H

0300H

1.11 SCREEN EDITING

COMMANDS FOR THE ICU

Several special

commands are available to simplifu

the editing

process.

They are

summarized

in Table 1-4 and then explained

in detail in the following paragraphs.

The

commands are

initiated by entering the

caret

"^"

control character (or a character you

substituted for the

caret using the "R" command

in command mode) followed by one or

more characters. It is also possihle

to enter all of the commands,

except Insert, Copy, and

Delete,

without

the control character.

Ifyou try to use lnsert or Delete without

the

control character,

you will receive a

message explaining the correct invocation

of these

commands. Each

command sequence must be

terminated

with

a carriage

return.

l-32 ICU Usefs Guide

INTRODUCTION TO

CONFIGURATION

Complete descriptions of the special editing commands are

as follows:

^B or B Enables you to move backwards from the

current screen to the

screen. The ICU displays the

previous screen and enables

you to continue as usual. Moving backwards

beyond the beginning

of the definition file returns

you to command mode. This

command can be used

on all types of screens.

^C or C Returns

you

to command

mode from any

ICU rcreen. lt then

displays the main menu.

Enables

you

to delete

an entire repetitive-fixed

format screen. The

screen deleted is the current

screen.

Table

l-4. Special Editing

Commands

Command M6aning Scre€ns

Affected

Fix€d R€p€t-

rtrv€ Rep€t-

fixed

^BorB

^CorC

^D <

numb€r>

^F <scabv>

F <scabv>

^HorH

^l <

number>

^RorR

^NorN

or S <

sîring>

Eack up to

screen

R€turn

to command mode

Delete a screen

D€l6te th€ €lem€nt with this

number

Find

and display the specifred

screen

Display the list of special

commands that apply to the

current screen format

lns€rt an new screen in front

of the current scre€n

lnsert a new line

Copy

the curent screen

Redisplay the curent screen

to the next logical screen

the remaining scr€ens

for the specified string

ICU Use/s

Guide I --l-1

INTRODUCTION TO

CONFIGTIRATION

^D <

number

^F <

scabv

or F <

scabv

^HorH

^I <number>

or <number>

^co

^RorR

^NorN

Enables

you to delete a specific item in

a repetitive

screen. The

numbcr

you

cntcr identifies the cntry to be deletcd.

Finds and displays the screen indicated by the screen

abbreviation.

The syntax ofthe ^F

command is

lor F) screen-ahhreviat ion

where

the screen-abbreviation can be any

abbreviation listed rn

Table 1-2. This command

enables

you

tojump from one screen to

another. Ifyou specify a screen name

not

previously

defined, this

command

jumps

the next available screen, and displays this

warning

message:

*** WAI{NING

- The screen requested cannot be disol

Ifyou do not speciry a screen abbreviation,

the list of screen names

and abbreviations is displayed (see

Tahle 1-2) and you

are

prompted

for a screen abbreviation.

Ifyou want

to exit this

command

without

entering

an abbreviation, press the

carriage

return and continue to the

next logical screen.

Figure l-4 shows a

flowchart of

how

you

proceed from one

screen to the next ifyou

simply

enter a carriage return.

Displays the list of special

editing commands.

Enables you

to insert an additional

repetitive-fixed screen

in front

of the current screen.

Otherwise, the

command

^l has no effect.

Enables

you

to add a

new line to a repetitive

screen.

The

^I is optional.

Only the line

number and an equal sign

are

required.

Enables you

to insert an identical

copy of the

current screen in

front of the present

screen. This

command can

be used only

with

repetitive-fixed

screen.

Redisplays the

current screen, showing

any changes

made.

Entering

^R is the

same as

entering a null carriage

return.

The

default

or previously

entered

responses are displayed

until

you

enter the

command (or <

) to show

the changes y<tu have

made to this screen.

Ifyou

are in a help screen,

the command

returns

you

to the

last non-help screen

you were

on.

DispÌays

the next

logical screen.

For example,

you

are entering

data

on a unit-information

screen

and enter

^N.

the first DUIB

screen for that

driver is displayed.

If you enter

^N again, the first

screen

of the nexî driver

is displayed,

and so on. If you

enter

^N in

the

last screen. the

ICU returns

to command mode.

l-34 ICU Useds

Guide

string>

or S

string>

INTRODUCTION

TO CONFIGU

RATION

Searches

repetitive-fixed

screens

of the same

logical

tlpe for the specified

string. When

this command

is entered,

the

begins

in the

next screen

of that logical

type and

searches all

fields wìth

a character

range (for

example,

1-31 characters).

The

continues

until a match is

found. If no

match is found, the

cursor remains

at its

current position

and the

ICU displays the

following

message:

No next rnatch found

The syntax

for this

command is

(or

The following

example

shows how to use

the

command.

Assume you

have 20 DUIB screens for the

iSBC 214 driver

and

you want

to find

the screen that

defines the device

name as w0.

First, you would

get to the

first

"(I214)"

screen.

Then you would

enter

The ICU

searches all the

iSBC 214 DUIB screens

until it finos

"w0".

It then

displays that

screen.

1.1

1.1 Deleting

Data

on a Repetitive

Screen Format

To delete

information

from a repetitive

screen,

you

must

use the

^D <number>

command, where <number>

is the

number of the line

to be deleted. After

the line is

deleted,

the remaining

lines are renumbered

and the screen

is displayed again.

The ICU

does not allow you

to delete

a line that is

not displayed. To replace

a line

you

must first

delete the existing

line, and

then insert the

new line.

An example

of how to delete

data on a

repetitive screen follows.

Assume the "prefix"

screen

is defined as shown

below. The

cursor is positioned

under the

word

"Enter". Ifyou

wish

to delete line 6,

you

would

do so

as shown here.

ICU

Useds Guide 1-35

INTRODUCTION TO CONFIGURATION

(PREF) Prefixes

Prefix - 1-45 characters

[1] Preftx - : PROG:

[2] Prèfíx - :UTILS:

[3] Prefix - :SYSTEH:

[4] Preflx : :

IANG:

[5] Prefix - :$:

] Pref ix - :l.toRKl:

[7] Prefix - :TMP286:

[8] Prefix -

Enter Changes [Nurnber

* ne\t value / ^D Nunber / ? / H ]

: ^d 6 <CR>

After line ó is deleted, the screen is redisplayed

with lines 7 and 8 renumbered

to 6 and 7

as shown here.

(PREF) Pre fixe s

Prefix - l- 45 characters

[1] Prefix * : PROG:

l2l Prefix - :UîILS:

[3] Prefix - :SYSTEM:

I4l Prefix : : I,ANG:

[5] Prefix * :9:

[6] Preftx * :TMP286:

[7] Prefix -

Enter Changes [Number - new value / ^D Nurnber

/ ? / H ]

r-36 ICU

User's

Guide

INTRODUCTION

CONFIGURATION

1.11.2

Inserting

Data

on a Repetitive Screen

Format

To insert a line on a repetitive screen, enter the insert command

^l (optional), the line

number, an equal sigr

(

and the new value. When the new line number is inserted, the

ICU renumbers the

remaining lines and displays the screen

again. If the number you

enter is larger than the actual number of lines in the screen, the ICU inserts

the new line

as the

last line. Assume

you want

to insert a new

prefix on line 6 of the

"Prefix"

screen

displayed

previously.

You can enter

and the screen

will

be redisnlaved

with

the new

values as shown here.

Ifyou are entering numerical data on a repetitive

screen such as the

"Memory lbr System"

screen, you can enter the data in any order.

However, the ICU automatically arranges

your

data in the

proper

order and

displays it on the screen.

For example, if

you

enter the

following three insert commands

^rL-2oooH,4oooH

^r2=SooooH.gooooH

^r 3 = looooH, l2oooH

Prefix

] Prefix

Prefixes

l- 45 characters

:PRoC:

{21 Prefix : :UTILS:

: UTILS :

: SYSTEM :

: IANG :

:l:

CONFI

TMP2 86 :

[Nurnber

- new value / "D Nunber

Enter Changes /

ICU User's

Guide r-37

INTRODUCTION TO

CONFIGURATION

on the

"Memory

for System" screen (see fhe Extended |RMX II Interactive Confguration

Utility Reference Manual), the ICU sorts the data

in ascending order

and

redisplays the

lines

as follows:

2000H,

4000H

10000H, 12000H

80000H,90000H

1 .11.3 Deleting

a Repetitive-Fixed

Screen

The

^D command enables

you

to delete information

for an entire repetitive-fixed screen;

you delete the

current screen. You can use this command

to delete I/O Jobs, User Jobs,

OS Extensions,

and Remote File Servers, as well

as Intel and user devices. Ifyou want to

delete a device driver,

it is only necessary to delete the

Driver

screen

for that device. The

ICU automatically

deletes all the Unit and DUIB screens associated with it (see

the

Extended |RMX II Interactive

Configuration Utility Ret'erence Manual for more

information).

r-38 ICU

User's Guide

INTRODUCTION TO

CONFIGURATION

Figure 1-4. ICU Flowchart

l-39

ICU Usefs Guide

INTRODUCTION

CONFIGURATION

Q '.",,0" ,n" .,,""0ed r/o

sysrem Layé.?

l-4. ICU Flowchaf

(Continued)

l-40

Figure

ICU

Usefs Guide

INTRODUCTION TO CONFICURATION

Figure

l-4. ICU Flowchaf

lContinued)

ICU

Usefs

Guide l-41

INTRODUCTf

CONFIGURATION

1.11.4 Inserting a Repetitive-Fixed Screen

The

^l command

enables you

to insert

an additional screen of information between two

existing screens.

(This

can be used only

with

the repetitive-fired screen format.) Use this

command

on the screen you wish to precede. For example, ifyou have three User Jobs

and

wish

to insert a fourth

job

between the second and third

job,

use the

^I command on

lhe screen for the third

job.

The

copy command (^CO)

can

also be

used to insert an additional repetitive-fixed

screen.

The copy command inserts a copy of the current screen in

front

of itself.

The

only

difference between the insert command and the copy command is that the copy command

uses the current screen values rather than

the default

values.

1.12 ICU

ERROR MESSAGES

During the interactive portion of the

ICU process, two types of error messages can occur:

. interactive error

messages

r internal ICU errors

The interactive

messages are the most

frequently encountered, and are self-explanatory.

The ICU internal error messages should

not occur. The following sections explain

these

errors

in more detail.

1 .12.1 lnteractive

Error Messages

The

ICU accepts data that you

enter only

if it lies

within

the range of

aoceptable

values.

Usually,

the range of acceptable values

for

given prompt

appears in

brackets

"[]"

on the

prompt line. If you

speci! a

value

outside the range

of acceptable

values,

the ICU

displays

one of the following

messages, depending

on the kind of value

it requires (all of

these messages

are

preceded

**r ERROR

-):

. number

expected or number

too large

. number is not within

its

ranse

. address expected

o the selector

is not

within

its range

o offset in address

is not a number

. string

too long

. a prefix

of a legal string

expected

. "Yes

or No" expected

. the field is "Req";

cannot be changed

ta ICU

Use/s Guide

INTRODUCTION TO CONFIGURATION

. erroneous

delimiter

. the

line entered overlaps

When

an error occurs, the

ICU does not

change the current value

of the

parameter.

the

values

you speciff

lie within the

range of au:eptable values,

the ICU aocepts them

without

checking their reasonableness.

Therefore,

ifyou enter values

that cause the ICU

to generate

a nonfunctional version

the operating system,

neither the interactive phase

nor

the generation phase

ofthe ICU wili

flag these values

as errors.

When

the ICU leaves the change phase

and returns

to the initial menu screen, it performs

a number

of logical tests,

such as checking

that the memory locations

reserved for the

system

and the Free Space

Manager do not overlap.

If it detects a logical error, the ICU

issues a self-explanatory

error message.

You must then make the necessary corrections to

your

definition file or you will

not be able to generate

working

system.

1.12.2 Internal

ICU Errors

If during execution

the ICU encounters

an internal error such as the Screen

Master File

or the Template

file being corrupted, it displays

the following message:

*** ICU Internal Error - <number[.sl>

where

number[,s]

> can be either one number

or two numbers separated by a comma.

The numbers represent an

internal code for the ICU and are

not meaningful for the user.

Internal

ICU errors rarely occur, but

you

should receive this error message,

lbllow

these

guidelines.

1. First, assume

your

definition

file has become corrupted, and try running the

ICU

again

with

a new definition

file.

2. If Step I is not the solution, try

running the ICU with

a new Screen Master File and

a new Template

file. Default versions

of these files are kept in the directory

:CONFIG:default.

3. If neither of the above

solve the

problem.

contact

vour

local Intel sales office.

1.13

UPGRADING DEFINITION FILES

There

are three reasons

you

may have to upgrade definition files.

. To make iRMX II.1 definition files compatible with iRMX II.3.

. To add Intel-supplied changes

. To add user device drivcrs

ICU UseI,s Guide l-43

INTRODUCTION TO

CONFIGURATION

To upgrade definition

files created by iRMX II.l of the iRMX Il Operating

System,

use

the UPDEF Utility.

To upgrade

your iRMX II.3 definition files

to include Intel-supplied changes

or user

devices, invoke the ICU with

the definition

file

you want

upgraded

as input. iRMX II.3

definition files can have

two formats:

. ICU standard format

with

specific version number

o Backup format

(ASCII)

used by difl-erent

versions

The ICU checks the

version

numbers

(see section, "lnvocation Error Messages', earlier in

this chapter) and decides how

to proceed. If it is possible to upgrade the definition

file

without restoring the backup information, the ICU prompts

Do you want to update the fi le? y/[n]

A response of "Yes" causes the ICU to upgrade the file as

you

input it. You can

then

proceed with the ICU as usual.

If the ICU must

restore to upgrade

the

definition file

(for

example, if the ICU is invoked

with

a backup file or a definition file

whose

Intel

version

number differs from the ICU

version number), it invokes the restore process and prompts you as follows:

Do you want to restore from the file? y/[n]

A response of "No" causes the ICU to stop

executing. A "Yes" response means the ICU

should

restore the backup information contained in the

file,

and

create a new

version

the definition file.

Ifyou enter

"Yes"

and the input

file is the same as the output file, you are prompted

Enter new outDut file narne:

If the output file exists,

the ICU displays this message:

File <ourpur_f i1e> exlsrs . oVERi,tRlTE? y

/ l-r.,1

While

restore is operating,

the ICU displays a series of

asterisks

(*) on the screen. If the

restore

operation reaches completion with

no loss of data, the ICU displays

the main

menu and you proceed

as usual. However,

if an error is encountered, the

ICU displays

the folJowing

message and exits.

l-44 ICU User's Guide

INTRODUCTION TO CONFIGUMTION

*** Ezu{oR vhile restoring

The Definition File has been restored to file: <file-name>.def

lnspect the log file: <file-name>.1og

The ICU writes

the backup information that

was

not

restored to a log-file.

The log-file

lists each

screen name followed by any errors that occurred

while restoring that screen.

also lists abbreviations of fields

which were

not restored. The

log-file has the same name

as the output file but

with

".log"

extension.

The log-file makes it easy to compare

the

backup definition file and the restored file to see

which values were not restored. You

should then run the ICU correcting the fields in

error. After that

you

can

proceed as

usual.

Assume that

while

restoring from file

upO.def, the ICU was not able

to restore the

"CF'

parameter on the

"Hardware"

screen. The

log file would look like

this:

lCU286 <version number) Restorine from file : upO.def <date> <tirne>

Screen:HARD

nr.!Ìber expe c

te d

Screen:INT

In field : CF

The error messages

in the log-fiìe are the same as

the ICU interactive

error messages.

This example shows only

a portion of the log-file. Ilowever,

the actual file

lists all the

screen names. The

version number, date, and time in the

heading

are variables.

1.14 THE

ICUMRG

UTILIW

The

ICUMRG Utility supplied

with the ICU provides

the ability

to include configuration

support for new

drivers. The ICUMRG Utility allows you to

. Integrate new [ntel

device drivers

with

previous version of

the operating system

. Integrate user-written device

drivers into

the operating system

The

ICUMRG Utility combines

the main Screen

Master File

(ICU286.SCM)

and the

main Template File

for System Generation

(lCU286.TPL)

with the Screen

Master File

(SCM)

and Template

Files

(TPL)

for

the new driver.

ICU Uset's

Guide r-45

INTRODUCTION

CONFIGURATION

Ifyou are adding an Intel-supplied

driver, both

the SCM and TPL files are

supplied

with

the update

package. In addition to

adding

your

device

driver, the ICUMRG Utility

updates the

'Intel

Device"

screen to include the

new device, and changes

the help message

that lists all the screen

names. Upon completion,

ICUMRG updates

the Update

version

number.

If you are

adding a user-written

device, the SCM and

TPL files

were

previously generated

by the UDS Utility (see

the Extended íRMX II Device Divers User's Guide for more

information). Upon

completion, ICUMRG updates the

User

version

number.

After

running ICUMRG,

the version

numbers of the new ICU and

your

definition

files

are different.

To continue

using

your

definition

files, invoke the

ICU as usual. The

ICU

will check

for version

number consistency, and

if necessary

issue a

warning

and

prompt

(see section

"Invocation

Error Messages", earlier

in this chapter)

which you

should

respond

"Yes".

The ICU then

updates your definition

fiìes and

continues executing.

Figures

1-5 and

1-6

give

the logical

flow of the ICUMRG Utility when

adding

either an

Intel

device driver

or a user device.

Figure 1-5. Merging

Intel Device

Drivers

t-46 ICU User's

Guide

INTRODUCTION

CONFIGURATION

Figure

l-6. Merging

User Devices

1.14.1

Invoking ICUMRG

Before

invoking ICUMRG be sure

that the ICU286.SCM,

ICU286.TPL, and ICUMRG

fiìes are

in the same directory.

To invoke the

ICUMRC Utility enter

ICUMRG input-file(root)

TO newicu-file(root)

where

input-file(root) The input-file

name

without

the extension providing

the input to

ICUMRG. AIÌ extensions

included in the

pathname

are ignored,

and

replaced by SCM and

TPL. The ICUMRG Utilìty searches

the

input directory for

input-file.SCM

contains all information about the new driver and

the new "lntel

Device" screen.

input-file.TPL

contains information needed for

generation

of new

screens.

The ICUMRG Utility also uses ICU286.SCM and ICU286.TPL as

rnDut.

ICU User's Guide t-47

INTRODUCTION TO

CONFIGURATION

newicu-file(root) The

name of the wo updated files,

without

their extensions,

created

by the ICUMRG Utility. All extensions

included in the

pathname are ignored, and replaced

SCM

and TPL. ICUMRG

creates

newicu-file.SCM

contains the ICU Screen Master

File updated

with the new device driver.

newicu-file.TPL

contains the ICU Template File updated

with

the

new

device driver.

Be aware that the ICUMRG utility

always merges your .SCM and .TPL files

with the ICU

files ICU286.SCM and ICU286.TPL. If you plan

to add support for

several drivers to the

ICU, make sure that the ICU286.SCM and ICU286.TPL

files contain the latest

version of

your

merged

ICU files.

Otherwise,

ICUMRG will

merge

your

driver information

with

outdated ICU fiÌes.

NOTE

Before changing the name of any ICUMRG output fiìes to ICU286.SCM

and ICU286.TPL, save the original files

by copying them to other files

(such

as ICU286OLD.SCM and ICU286OLD.TPL). Although ICUMRG

allows

you

to add support for new drivers, once

you

add that support, there

is no

way

to remove it. If the device driver

you

added contains an error,

you

must revert back to the original

.SCM and

.TPL files.

1.14.2 ICUMRG

Example

The following example shows

how to add

a device

- D219.

The input

files

are ICU286.SCM AND ICU286.TPL

(located

in same

directory as ICUMRG)

D2l9.SCM and D219.TPL

The output files

are ICUNEW.SCM and ICUNEW.TPL

Upon completion the system prompt is displayed. You are

then ready to run the ICU and

generale your

system.

1-48 ICU UseCs Guide

INTRODUCTION TO CONFIGURATION

1.14.3 ICUMRG

Error Messages

The ICUMRG utility generates

an error message if one of the following occurs:

. it is not invoked correctly

. an I/O error occurs

o the

version

numbers are inconsistent

. either

the SCM or TPL files are not valid

Invalid invocation of

ICUMRG causes one of the following self-explanatory error

messages to

be displayed.

. paraneters required

USAGE: I CUMRG infile TO outfil-e

o nissing "To out fi le "

USAGE: ICUMRG infile To outfile

o nissing "TO"

USAGE: ICUMRG infile TO outfile

o nissing "outfile"

USAGE: I CUMRG infile T0 outfile

. coo many Pa

rame te rs

USAGE: ICUMRG infile TO outfile

In addition to the invocation error messages, ICUMRG issues the error messages [sted

below.

. *** UDI Error - <exception-code>,

(mnemonic)

An error

was

detected by the UDI. The mnemonic explains the cause

of the error.

For example,

you

can receive this error message if ICUMRG cannot successfully

change

the

extension.

. *** Error - input fi le same as output file

The input and output files cannot be the same.

. *** l/o Error ín file: <file narne)

<excep-code>, <mnemonic>

An I/O error occurred. For example, the ICUMRG utility

was

not able to create,

open, read,

write

or seek one of the specified files.

. *** Error - <fi1e narne> is not a valid SCM file

The data in

the SCM

file is

not valid.

. *** Error - <file name> is not a valid TPL file

The

data in the TPL file is not

valid.

ICU

Usefs Guide r-49

INTRODUCTION

CONFIGURATION

. *** Error - inconsistency in the version of the internal ICU files

Versions: INTEL UPDATE USER

ICU286.SCM <Intel> + <Update> <User

Version>

ICU286.TPL <Intel>

+ <Update> <User

Version>

There

is an inconsistenry

in the

version

numbers ofthe ICU286 SCM and

ICU286

TPL files.

. *** Error - inconsistency in the version of the internal ICU files

Versions: INTEL UPDATE USER

Input

Scm Fiìe <

Intel

> + <

Update

> <

User Version

Input Tpl File <

Intel

> + <

Update

> <

User Version

There is an

inconsistency

in the

version

numbers

of the input

SCM and TPL files.

. *** Error - (screen-abbr>

screen already exists in ICU286.SCM

Duplicate screen

names are

not allowed.

You are probably

merging the wrong

SCM

and TPL

files, thus

causing a duplicate

name to

be created.

. *** Error - unexpected

end of TPL file <file name>

An unexpected

end of file in

the TPL file was

encountered.

1-50 ICU

Usefs

Guide

GENERATING CHAPTER 2

YOUR

SYSTEM

2.1

INTRODUCTION

The

process

of generating

your

configured

system consists

of the following steps:

o Generating

configuration

files.

o Executing

a SUBMIT

file that compiles,

assembles,

binds, and builds all necessary

fi.les.

2.2

GENERATING

CONFIGURATION

FILES

By using the

ICU, you can define

the operating

system that best meets your

individual

needs. This

process takes

place

while

you are editing

your definition file. When you

have

completely

defined your

system, return

to command mode to

generate your configured

system as

follows:

1. Use the List command

to create a

file that records your system

configuration.

2. Use

the Generate command

to generate your

configuration files.

3. Use Exit to save your

changes

and exit the ICU.

The following screen

shows the results

of having used the

G[enerate] command to

generate

all the required configuration

files (assuming

the definition file used was

nen'file.del).

ICU

Usefs Guide 2-l

ENTER

COMMAND : I

ENTER a Ìetter tÒ be used as prefix:a

The prefix lettèr is: A

Beginning NUCLEUS Flle Generation

Beginnlng BI0S File Ceneratíon

Eeglnnlng EIOS File Generation

BegÍnning LOADER File Generation

Beglnning HI File GeneraLion

Beginning UDI Fil.e Generation

Beginníng SDB File Cenerat ion

Beginning Subnit FiIe Generati.on

Beginning Build File Generation

NoTE: îo GENERATE

your system submit NEI,IFILE.CSD

For general help in any screen enter H <cr>

The following cornrnands are available

Change

Cenerate

Lis t

Save

Quit

Exit

Replacè

DetalL

Level

Backup

ENTER COM},IAND

DONE

GENERATING

YOUR SYSTEM

The files listed in Table 2-l are the configuration files that define

your

system. The

system processes

these files during execution ofyour SUBMIT lile. The ICU creates the

SUBMIT file with the same filename as

your

definition file

(with

a .CSD extension). For

example, the definition file used in the previous screen

was

labeled NEWFILE.DEF.

Therefore. the SUBMIT

file

is called NEWFILE.CSD.

2-2 ICU User's Guide

GENERATING YOUR

SYSTENI

If you use

the prefix option,

be sure

to choose a unique prefir

each time you generate

your

system.

If a file of the same

name already

exists, the ICU overwrites

the old file with

the new

file.

Table

2- 1 shows

file names created

using no prefix (carriage

return only).

If you

enter any

character

other than

carriage return when

prompted

for a

prefix,

that character

is added

as the

nrefix

to the file names.

CAUTION

Changes

made

to the ICU definition file are

not reflected in your

configuration hles until you generate.

Table

2-1. Files

Crealed by

the Cleneratel Command

File Name Screens Used to D€fine th€ File

NTA8L.428

NUCDA-M8

NJOBC,A2S

IfABL.A2S

ICDEV.A2S and

ETABL.A2S

EDEVC.A2S

EJOBC.42B

HCONF.P28

LTABL,42S

tcoNF.P28

SDBCN.A28

UTABL.A2S

NROMC.A28

ITDEV.A2S

Nucleus

Nucleus, Hardware,

Interrupts,

Slave

Interupts,

Extensions, ROM

Code

OS Extensions,

User Jobs

BIOS

System Calls, Remote File Access

All Intel and user devices, Remote Fie Access

None

EIOS, Automatic Boot Device, Logical Names

l/O Users,

l/O Jobs

Human Interface, HlJobs, Resident

User, Preflxes,

Logical Names

None

Applicalion

Loader

System Debugger

None

Hard, MBll, Mems, ROM

ICU

UsePs Guide )_t

GENERATING

YOUR SYSTEM

2.3 EXECUTING

THE SUBMIT

FILE

After

you

exit

the ICU, execute lhe STJBMIT

file and

wait

for

your system to be

generated.

The SUBMIT file

assembles or compiles

any configuration fiÌes

generated by the ICU and

binds the object files

with any needed libraries

used by a subsystem. It then

builds the

system. The syntax for invoking

the SUBMIT file is

SUBMIT output-file[.CsD]

[to

filename]

[echo]

where:

output-file The name of

your

definition file.

filename A file that the system creates to contain the output

of the SUBMIT

command.

e[cho] Sends a copy of

the clata reacl to the screen.

For more information on the SUBMIT command, see fhe Operaîor's Guide

to tlte

Ertended |RMX Il Hunnn lnterftrce.

2.3.1 Assembling the Configuration Files

The SUBMIT file

generated

by the ICU identilìes the configuration files that must be

assembled

or compiled lbr each

of your subsystems. The

number

files assembled

varies

from system to system and depends upon the features that you choose. No errors should

be encountered during

this

phase.

Figure 8-36, in Appendix B,

gives

an example of

the

SUBMIT file output during this phase of the configuration

process.

2.3.2 Binding the

Individual Subsystems

As soon as ASM2ll6 generates

the object files lbr a

given

subsystem, the SUBMIT file

initiates BND286 to bind these object files together with any

libraries needed by

the

subsystem.

Any

warnings generated

during this phase should be ìgnored.

Explanations

the

various warnings

appear at the

en.i of this section. Figure B-3ó, in Appendix B, shows

some of

the output

generiìte(l

durin{r this phase

of the configuration

pnrcess.

2-1 ICU

User's Cuide

GENERÀTINC YOT]R

SYS'TEM

2.3.3

Warning

Messages

When

you

invoke the system

generation

SUBMIT

file,

a number of

warning

messages

may be issued

by BND286.

These

are normal

messages and

are not critical.

r IIARNING

151: UNRESOLVED

EXTERNAL SI'Ì'ÍBOLS

This

warning

is the

most

common. It indicates

that BND2l.l6

did not resolve all

the

external symbols

declared.

You may ignore

this

warning

since

the missing symbols are

resolved

only at build

time. It may appear when

binding the Nucleus

or after the first

phase

of binding

either

the Basic I/O Sysrem or the

Extendcd I/O System. It may

also appear

after the second

phase

of the EIOS,

you

are binding a

first-level I/O

job.

o WARNING

133: SEGMENT

LIMIT DECREASED DUE TO

SEGSIZE VALUE

This

warning

is expected in the Nucleus.

I t indicates that the size of the segment

named

is being decreased

because

of a SEGSIZE specification.

2.3.4 Building

the

System

After the

SUBMIT file

has completed

the assembling

and binding of each of the

subsystems,

it builds the system

by invoking

rhe BLD286 utility. The invocation

lbr

BLD286

is contained within

the SUtsMIT

fiJe. An cxample

of this can be seen in Figure

B-36.

Entering the Generate

command produces

a build

file

with

the s:tmc namc as

thc

definition file but with

the extension

BLD. This serves

as the inpur filc

to BLD286. 1'he

output

file created by BLD286

is the file

you

define in the

"Ceneratc

File Name" screen

(see

the

Extended iRMX II Interactive Conf.guration

lJtility Reference

Manual). No errors

should ocrur

during this phase

of the ICU. However, you

can expect one warning which

can be

ignored. The

warning

***WAI{NINC

269 (Line-number>, NIIAR

'CLI_DATA', SEGMllNT

SIZE REDUCED

This warning

appears after

the following

line of code in the build lile:

cli_code

(dp1:0), c1i_data(

limit:0, dpì:0)

ICU UsePs Guide 2-5

GENERATING

YOUR SYSTEM

2.3.5 Error

Messages

In addition to

warning messages, the

language utilities can return

error messages. Error

messages are not normal and

you should not ignore them.

They indicate serious

problems

that

prevent

the successful

generation

ofyour system.

The following error messages

can

appear.

o 0021: E$FILE_NOT_EXI

8042: E$NOT_CONNECTION

, command aborted by EH

One of these messages might appear

if you enter an invalid

pathname as input to the

ICU.

r 0026: E$FILE_ACCESS

This message may appear

if there

is no read access to the input file, no add entry

access to the directory, or no

write access to the output file.

. ERROR I18: INPUT SEGMENTS EXCEED TARCET MEMORY

The memory blocks

you declared in the "Memory for System"

screen are not large

enough for the system

you

delìned. ln this case, enter

the ICU again, increase the

system

memory,

and decrease the Free Space Manager memory. This error message

may result from installing an update

which

increases the size of the operating

system.

2-6 ICU

User's Guide

PREPARING CHAPTER

APPLICATION

JOBS

3.1 INTRODUCTION

Once you

have

prepared

your

application

jobs,

you

should locate your first system

RAM to facilitate testing

and debugging ofyour programs.

It is much

easier to test and

debug your

programs in RAM than it is to reburn

your

PROM

devices

when you

detect

errors. After debugging

in RAM, you

can locate the final system in

PROM/RAM or copy

it to a secondary

storage device

and load it with the

Bootstrap Loader.

Putting together a RAM-based system

consists of the following steps:

1. Using the ICU to define your

system

2. Preparing your

application

code

. Compiling

and binding the

application

jobs

4. Using the ICU to generate

the system

with

your application (not

needed if the

Application Loader loads your

application)

5. Loading and testing the system

This chapter describes how

prepare

your application

code, compile and bind it, and

build

a system

with your

application

jobs

(steps

2 through 4 above).

Both loading and

testing your system are described

in Chapter

5 of this manual.

3.2

PREPARING

APPLICATION

CODE

You

can

write

the code for your application

tasks in any language supported by

the

iRMX II Operating System.

This manual assumes that you are using

PL/M-286. In order

to use assembly language, you

must adhere to the PL/M-286 calling conventions

described

in the

ASM28ó Macro Assemhler Operating

Instrucrions manual. T\e Extended

|RMX II Programrning

Techniques manual also contains information to help you write your

application

code, especially assembly

language applications.

When writing your

application code there are additional instructions you should

order to use all the features

of the iRMX lI Operating System. The following

sections

nrovide this information.

ICU Use/s Guide 3-l

PREPARING APPLICATION

JOBS

3.2.1

Language

Requirements

Adhere

to the following

language requirements

when writing

your

task

code:

. Make

certain any utilities

you

use are linked

to the Extended

iRMX Il UDI libraries

. In

general,

you should designate

all of your tasks

as procedures. Designation

of initial

tasks

is the only

exception to this recommendation.

Refer

tct Ertended

|RMX II

Application Loader

User's Guide Îor

details about main

modules and

procedures.

. If

you

are compiling

your PL/M-21ì6 code using

any model other

than tARGE,

specify the ROM compiler control. This

causes the compiler

to place the CONST

segment in the CODE

class, where it can be more

easily loaded into

PROM. You do

not need to

specify the ROM control for those

programs

compiled

using the LARGE

model.

The compiler does this

automatically for the

TARGE model.

. Use the DATA and INITIAL PLIM-286 statements

with

care. The

DATA statement

valid only if

you

use the PL/M-21'ì(r

TARGE mociel

of segmentation or if

you specify

the ROM compiler control.

The INITIAL statement

cannot be used in a

procedure if

you put that procedure in PROM. [t clin be used, however,

vou

use the Bootstrap

Loader

or Application Loader

to load the procedure into

memory.

3.2.2

Include Files

A number of files must be

prtsent t n your microettmputer system to compile

your

application software ancl to

configure your operating system. The

"Includes

and Libraries"

screen, discussed

in the Extended iRll,lX II Interactive Configuration Utility Reference

Manual, selects files that must be

present

to configure

your

operating system.

This

section discusses the files needed

to compile

your

application software.

Any

program containing

iRMX II system calls must include an external declaration

of the

system

calls. The iRMX II Operating

System

provides

the declaration of the

system calls

for FORTRAN, PASCAL, and PL/M-286 in files called INCLUDE files.

When you

install the system as described in the Extended

iRMX I I Hardware and Software Installation

Guide, these fiÌes are located in directory

/RMX286/lNC. FORTRAN

system calls are rn

file RMXFTN.EXT,

PASCAL

system caìls are in RMXPAS.EXT, and PL/M-286 system

calls are in RMXPLM.EXT.

3-2 ICU

User's Guide

PREPARING

APPLICATION

JOBS

However, if

you

are programming

in PL/M and your system

does not include all the

subsystems, or if you

are trying to save

memory,

you

may want to use

a PL/M INCLUDE

file that contains system

calls only

for a particular

layer. These files are

Subsystem File Name

Nucleus NUCLUS.EXT

BIOS BIOS.EXT

EIOS EIOS.EXT

Application Loader LOADER.EXT

Human

Interface HI.EXT

UDI UDI.EXT

3.3

DETERMINING

MEMORY

LOCATIONS

An iRMX II system

must be located

either entirely in ROM or entirely in RAM. Intel

recommends

that you put your

system in RAM until you have completed

the testing and

debugging stages.

To determinc your

application's memory requirements, you should add

the

size of

your

application code to

the amount of memory required by the system. After

calculating your system's

memory requirements, you

must determine its

physical

location

in memory and enter

the starting and ending addresses on

the

"Memory

tbr System"

screen,

Some additional factors should be taken

into consideration

when

determining the physical

address of

your

system. AÌì systems have a m in

imum address at

which

they can start

depending on the elements comprising

the system. All systems must take the following

memory

locations into consideration:

. 088000H-0BFFFFH,

default addresses required by the second

and third stages of the

Bootstrap

Loader.

o the

top 32K bytes, if the system

includes the iSDM monitor and the first stage of the

Bootstrap

Loader

(the

top 25(rK bytes, if the system is a System 300 Series

Microcomputer).

In addition, ifyour system

includes either a RAM disk driver

or a

communication board,

you

must be careful not to include the board's

dual-port memory in

the

memory

you

declare for your system.

For example, if

your

system includes an MSC driver, you must

reserve 68 bytes of memory in

the lower megabyte

(in

an Intel-supplied system, the first

2000H bytes are reserved for such

data). After

you

have reserved

room

for

all the data

requiring fired locations, you can locate your application anpvhere within the l6M byte

memory of the iRMX II Operating System. For more inlbrmation on calculating the

exact

memory locations,

see

Chapter 2 of the Ertended

|RMX II Interactive Confguration

Utilin Reference Manual.

ICU User's Guide J-J

PRF],PARING APPLICATION

JOBS

Use the memory

screens to define the memory for the

system and the Free Space

Manager. Intel recommends

that first

you pad

the memory locations to

leave room for

any device drivers that may

be added or changes that may be made during development

After running BLD286,

you

can reduce

the memory to the actual size necessary by

re-

invoking the ICU and editing the memory

rcreens (see section "Minimizing the Memory

Address

Space", later

this chapter).

3.4

BINDING AND BUILDING YOUR APPLICATION

JOBS

Application

jobs

are include<l in the system by using BND286 and BLD286. You must

bìnd each application

job

with its offspring

jobs

and the interface libraries discussed later

this

section. The following sections describe the binding and buiìding

process, and

the

interface libraries in more detail.

3.4.1 BND286

The BND286 command

used as

shown below to bind

your

firstlevel application

jobs.

This command is described in detail in the LAPX

286 Utilities User's Guùle. 'îhe followinu

invocatìon of BND28ó applies to both

the iRMX ll and Series lV systems.

BND286 &

appjob.obj, &

interface.lib &

OBJECT(appjob.1nk) NoLoAD &

NOPUBLICS

EXCEPT(start_address,

public_variable, exc_handle r_addre s s

)

where:

appjob.obj Pathname of the file

containing the object

code for

your

application

job. You do not need

provide

this code in one file;

you

can bind

several files or libraries

at this point.

Pathname of

the file containing

the interface libraries

for

the

system calls included

your

jobs.

These

interface libraries are

described in later paragraphs

of this section,

Pathname

of the file in which

BND286

places

the module

containing your bound

application code. [Jse

this file as the input

file when

configuring

your application

job

the "User Modules"

screen.

The starting

address of your

application. The

Nucleus uses this

name to obtain

the selector and offset

ofthe initial

task. This must

be the same name you

entered as the

Task Start

Address on the

"User

Jobs" screen.

interface.lib

appjob.lnk

start address

l-4 ICU User's

Guide

exc handler address

PREPARINC APPLICATION

JOBS

The starting address ofyour

exception handler. You must enter

this

value

if the starting address

is not zero. The Nucleus uses this

name to obtain

the selector and offset of the exception handler.

This must be the same

name

you

entered as the Exception Handler

Start Address

on the

"User

Jobs" screen.

The PUBLIC name of

variable

in your data segment. The

Nucleus uses this name to

obtain the data selector number. This

must be the same name you

entered as the Public Variable Name

on the

"User

Jobs" screen. lf there is no data segment or the

application initializes

its own data segment, it is not necessary to

specifo this

parameter.

public_variable

You should be aware

of the following requirements when bindìng an application

job.

. Use the NOLOAD option

of BND286. This causes the System Builder (BLD286) to

combine

your

application

with

the sysrem

lo create a bootloadable file.

r Ensure that the output of BND286 includes

three PUBLIC names, one for the start

address, one for a

variable

in the

initial data segment of your application

job,

and one

for the exception handler (the

data segment and exception handler are optional).

These

names must be same as the names you

specified on

the "User

Jobs"

screen.

These public

names allow the system to create a

job

and start iÌs execution at the

correct

address

with

the corresponding data

segment intact.

o Bind the

appropriate interîace libraries to your application

job,

if you use any

iRMX2tl6 system

calls. The interface libraries contain routines that satisfo external

references to system calls. The name

of the library that

you

must bind in

with

your

application

code depends on

which

model of PL/M-286

segmentation

the

jobs

were

compiled under. Table 3- I shows the correlation between models

segmentation

and interface libraries. Specifu these libraries

as the last modules

in the

BND286

input list so that they can satisfy references from all bound modules. Notice that no

library exists for the SMALL model of PL/M-286 segmentation; except for Universal

Development lnterface (UDI) level applications, the iRMX II Operating System does

not support applications compiled in SMALL.

Table

3-1.

Interface Libraries

as a

Function

PL/M-286

Models

Subsystem SMALL COMPACT TARGE oT MEDIUM

All subsystems,

except

uDl

UDI UDIIFS.LIB

RMXIFC.LIB

UDIIFC.LIB

RMXIFL.LIB

DIIFL, LIB

ICU

Usefs Guide J-J

PREPARING APPLICATION

JOBS

After

you have bound your object

code using BND286 with the NOLOAD

option, you

should

1. Invoke the ICU. You may

want

to use

the Level of Detail option and

select Jobs

from the displayed menu

to see all the

job

screens that require changing.

2. Enter

the application

job

onto the "User Job" screen.

3. Enter the

pathname

of the object file, created

by compiling and binding the code,

onto the

"User

Module" screen.

4. Ensure

that

you

have

enough memory for the system, including

your

application

jobs.

5. Generate the system by entering the "G" command and submitting the output-

file.CSD.

(lnvoking

the ICU system

generation submit

file activates BLD2fló.)

The iRMX II Operating System does not allow

you

to build

your

application system in

separate bootload files. With BLD286 you build the system as a unit. Figure 3-l

illustrates the bind

and build

orocedure.

3.4.2 Minimizing the Memory Address

Size

When you

originally located your application

jobs,

you

may have included extra memory

to accommodate

changes during development. However, in the

final system, after binding

and building, you

can eLiminate some of the extra space. BLD28(r

creates a map file

with

the same

name as the system, but with the extension MP2,

part

of its output. By

looking at the MP2 file, you can find the exact starting

addresses of the clescriptor

tables,

the monitor,

and all the other constants in your system.

To tighten up memory,

change

the system

memory definition and generate your system

again using the

ICU.

3-6 ICU User's

Guide

PREPARING APPLICATION

JOBS

F ìRS I LEVEL ]O8

OB]

EC'I

COD€

IE RFACE

L BRARY

OF;SPR

JO8

OB] ECI CODE

IN TE RFACE

L SRARY

OFF5PR

]OB

OB] ECI CODE

BND 286

L NKED

APPI

CAT ON

É R5T

LEVET ]O8

8LD 286

EOOILOADABLE

Figure 3-1. Application

Job

Bind and

Build Procedure

f 05r8

3.4.3

Building

ROM-Based

System

Before

you

burn

your

system into ROM (PROM)

devices,

you should first be confident

that

your

code is fully debugged. You must also

know the size of all the code

and data

segments. In a RAM-based system, the amount of memory

needed by the code and data

segments is reserved for the system on the

"Memory

for System" screen.

The remaining

memory is available ior the Free Space Manager. However,

in a ROM-based system, it is

necessary

copy the Global

Descriptor

Table

(GDT),

Local Dercriptor

Table

(LDT),

Interrupt Descriptor Table

(IDT) and all

writeable segments into RAM. Therefore,

you

should subtract the amount of memory required

by the descriptor

tables and the

writeable

segments

from

the memory available for the Free Space Manager.

The actual area

to be

used for the system RAM is defined by the

"RAM Start Address"

parameter and the

size

of the RAM segments. Ensure that this area is not

reserved

for the system or the

Free

Space Manager.

ICU

Use/s

Guide

PREPARING

APPLICATION

JOBS

To determine the size ofyour

code and data segments, follow these

guidelines.

1. Bind

your

application using BND286.

2. Run the ICU to create

the generation SUBMIT file.

3. Invoke the

SUBMIT file.

4. Read the memory

map

(.MP2

file) created during the build

phase

to find the start

address for the GDT in ROM, the amount of ROM

your

system uses,

and the

amount

of RAM your system requires. Calculate the RAM memory required by

adding

the size of the IDT,

the

final GDT (the

number of GDT entries

multiplied

by 8), the final LDT, which is the same as the final GDT, and the sum of all the data

segments

with

the WRITEABLE attribute. To this number add 2700 bytes

which

are used as a

work

area during system startup.

5. Invoke the ICU and remove the size of the memory calculated in step 4 from the

memory defined on the "Memory for System" screen.

6. Rerun the ICU to generate

the final

SUBMIT

file.

7. Invoke this

system SUBMIT file.

The final file generated

after rerunning the ICU with

the correct parameters does not

include the start address

ofyour

system,

that is the initial JMP

at address 0FFFFF0H.

You must burn that

into ROM separately.

Ifyou specìfied

that the initialization code

resides

somewhere in the top 64K bytes (not

below address 0FF0000H),

then

you

can

burn a short

jump

to that address. Otherwise,

you

need a

FAR

jump,

which

may cause a

problem.

The tì02tì6 processor

resets the high 4 address

bits. This means

you

can only

jump

to the lowest

megabyte, but

your

ROM is usualìy

in the high megabyte. Boards such

as the iSBC 2tì6/ 12,

iSBC 386/2X, and iSBC 31ì6/3X

solve this problem by setting the 4

address

bits to one until a specific OUT command is

issued. This allows

you

perform

FAR

jump

to anyvhere

the

high megabyte.

The initialization

routine

resides in the segment NUCDAT.CODE_ROM,

and its entry

point

is at offset

12H. To obtain the entry point

address, add the entry

routine offset

(12H)

the address

of NUCDAT.CODE_ROM (which you

specified tJuring

ICU

configuration).

For

example, if the address of

NUCDAT.CODE_ROM

is 0FC0000H, the

address of the

ROM-initialization routine would

be 0FCO0l2H.

At location 0FFFFF0H

your

PROMs

burn a FAR

jump

to the address you

derived

for the ROM-initialization

routine.

Appendix

C provides

an example of how to place your

code

into PROM. It lists both the

hardware

and software

necessary to do this. Refer

to this appendix for

further

information.

3-8 ICU Useds Guide

ADDING

USERS CHAPTER 4

TO YOUR

SYSTEM

4.1

INTRODUCTION

To function correctly, a system configured with

the I{uman Interface requires information

about all users

(operators)

and terminals that

intend to access the system

via

the Human

Interface. Two t)?es of users

exist for

your

system: a resident user and non-resident

users.

4.2

THE RESIDENT

USER

The resident user becomes part ofyour

final

system

antl resides in memory along

with the

rest of the Operating System

(thus,

the term "resident user").

types of resident users

exist: a recovery resident user

and a non-recovery resident user. The recovery resident

user gains control only

if an initialization error occurs during initialization of the Human

Interface. Regardless of the

type, the resident user occupies one of the system terminals

and

is created before non-resident users.

The

Operating

System

can contain

information

about only one resident

user.

Including a resident

user tlpe in

your

system is called

resident

user configuration.

Resident user configuration

is accomplished by supplying information to the Human

Interface (HI) screen

during ICU configuration of the

Human

lnterface. Refer to the

Ertended |RMX II Interactive

Conftguration Reference Manual for tletailed information

needed

for resident user conficuration.

4.3 NON-RESIDENT

USERS

Non-resident users are users that

can

access

the

system using the Human Interface logon

procedure. Ifyour system is to

be a multiple-user

system, you need to define to the

Human Interface all the non-resident users that can access the system. Configuration for

non-resident users occurs

through the Human

[nterface PASSWORD command and

possible editing of several user definition files. These files define user names, limitations,

passwords, terminals,

and tcrminal charactcristics

to the system.

The process of adding non-resident users to your system ìs called

non-resident user

configuration. The files involved are called non-resident

configuration files.

ICU Usefs

Guide 4-l

ADDING

USERS TO YOUR SYSTEM

The system manager (who has user ID 0) can modify these files to add users or terminals,

delete

users or

terminals,

or change characteristics of users or terminals. Depending

the tlpe

of modifications made, the changes take effect either the next time the affected

user logs onto the system

or the next time the

system

is initialized. To

prevent

unauthorized

users from changing the system configuration, the system manager should

be the only user with change

access

to these files.

Refer to the

Operator's Guide

to the Ertended |RMX II Human Interface for detailed

information

on non-resident user confisuration.

4-2 ICU

Useds Guide

AND TESTINGCHAPTER

THE

SYSTEM

5.1 INTRODUCTION

After you

run the SUBMIT file generated

by the

ICU,

you

are ready to load the system

into RAM and test it. The system RAM code is conrained in the file

that

you

specified

while

running the ICU. There are several

diflerent ways in

which

you can

load

your

system into

RAM.

5.2 LOADING

YOUR

SYSTEM INTO

RAM

If you

are using a Series

lV development system,

use the iSDM System Debug Monitor to

load

your

system

from disk into RAM. The iSDM monitor is described in the rSDM

Systetn Debug

Monitor Reference Manual. Shctukl, you have a system that uses D-MON386,

you

load the system into RAM using

the D-MON3Iì6 B command (Bootstrap

Loader

command).

If you

are usingyour

System 300 Series

Microcomputer or a MULTIBUS II system as a

development

tool, use the

Bootstrap Loader to load your system into RAM. The

procedures

for using the

Bootstrap Loader are described

ín

the

Extended iRMX II

Bootstrap

Loader Reference Manual.

5.3 INITIALIZING

YOUR

SYSTEM

Aller you load your

system, you

must initialize it. Ifyou are using the Bootstrap

Loader

this process

takes

place

automatically.

lf you

did

not load

your

system using the Bootstrap

Loader,

refer to the appropriate

manual for instructions on how to initialize

your

systern

by starting execution

from the beginning

of the Root Job.

5.3.1 Initialization

An iRMX ll Operating System can be configured to include

your own code as a

first-level

job

or as a

first-level I/O job. When

created, such a

job

contains only a single task. That

single task creates or starts the creation

of all other objects required by the first-leveljob.

Thus it is referred to as the

initialization task lbr its

job,

even though it may

perform

other

functions as

well. You should synchronize

the operation of

each

initialization

task with

that of the root task to ensure proper

functioning of

your

applcation system.

ICU User's Guide 5-l

AND TESTING THE SYSTEM

The root task is

structured so that it creates the first-leveljobs one at a time. It contains a

programming

loop that in general performs

the following:

Repeac for each first-level job

Create first- 1eve1 job

Suspend root task (until resurned by a first-1eve1 job)

Untll finished

End

Each time the root task creates a firstJeveljob, the root task suspends itself

allow the

initialization

task in the new

job

perform

synchronous initialization. Synchronous

initialization consists of functions that must be performed

immediately, before some other

firstJeveljob

is created. Typically, this requires creating objects

or making resources

available

that tasks in first-level

jobs,

not yet created, expect

to be available

when

they

themselves are created. (For

example, the initialization task in

the Extended I/O System

job

must

create the entire Extended I/O System belbre it can allow the root task to create

other first-level

jobs

that might make use

of Extended l/O System functíons.)

When the

initialization task finishes its synchronous

inìtialization, it must

inform the root

task that it is finished, so

that the root task can resume

execution and create another first-

level

job. The

initialization task must always inform

the root task that it has completed

its

synchronous

initialization process by

making the following

procedure

call:

CALL

RQ$ END$ IN IT$TASK;

This procedure

call requires

parameters.

When you

calÌ this procedure,

the root task

resumes

execution, allowing

it to create the

next first-leveljob.

You must include a call to

RQ$END$INIT$TASK

in the

initialization task of each

your

first-level

jobs,

even if the

jobs

require

no synchronous

initialization. If one of

the firstlevel tasks

does not include

this call, the root

job

remains suspended

and cannot create any

of the remaining first-level

jobs.

The amount of synchronous

initialization

that an initialization

task must do

depends on

your

job

structure.

You may

require some of

your

initialization tasks

to create all of the

offspring

jobs

and a

number of other

objects before calling

RQ$END$INIT$TASK.

Some

others

may have to perform

only

one or two functions,

call RQ$END$INIT$TASK

and

then

resume the process

of initialization

asynchronously.

Still other

initialization tasks

may

not have any

synchronous initialization

requirements

and so can c:rll

RQ$END$INIT$TASK

before performing

any initialization.

You must determine

how

the

pieces

ofyour system interact,

and how they

must be synchronized.

5-2 ICU

Usefs Guide

LOADING AND TESTING THE SYSTEM

Another important factor in initialization

is the order in

which

the root

job

creates the

first-leveljobs (see

Table 5-l). The amount

processing your

initialization tasks must do

before calling

RQ$END$INIT$TASK

may depend on

which

jobs

the root rask has

already

created and

which

jobs

it has

yet

to create. The order in which the root

task creates first-

level

jobs

depends

on the order that you specify

thesejobs

while

running the ICU, not on

the priority

of the tasks in those

jobs.

You should always use RQ$END$INIT$TASK

as described in this section

in order to

perform your

synchronous initialization.

Otherwise, the root task cannot be resumed and

thus.

it cannot comnlete svstem initialization

in the correct order.

5.3.2

System

Initialization

Errors

If the system encounters an error during the initialization process, it places diagnostic

information in the processor registers and halts the processor. lf the "Report

Initialization Errors" entry on

the Nucleus

screen

"yes"

and

your processor

board

contains

the iSDM monitor, a hexadecimal code and a mnemonic are displayed at the

console indicating the layer that contains the

initialization

error. On encountering an

initialization error, the subsystem

containing the error returns control to the iSDM

monitor after

writing

a message with the

following

format:

<subsysteÈ lnitialization Error: (error code number>

This initialization error reporting is selected either for all subsystems or for none of the

subsystems. If "Report

Initia[zation Errors" is not configured into the system, the

exception code returned by the unsuocessful system call is

placed

in both the AX register

and the first

WORD

of the Nucleus data segment, NUCDAT. A code indicating the layer

that failed initialization is

placed

in the

second WORD of the Nucleus data segment. The

system then goes into a infinite error loop. (The codes lbr the

various layers are

1=Nucleus. 2=BIOS. 3=EIOS. 4=Human Interface.l

Table

5-1, Order of Initialization

Order Root

Job First-L€v€lJob l/O User Job

Root

Job System Debugger

Basic

l/O System

Enended

l/O System

User Jobs

Human lnterface

l/O

User Jobs

ICU

User's Guide 5-3

LOADINC AND

TESTING THE SYSTEM

The only subsystem that handles an initialization

error slightly different is the Human

Interface. In addition to the initialization

error described above, the Human

Interface

may issue the following

warning if it does not have enough memory to fill the

user's

recuest.

In such a case, the user is assigned whatever memory is available at the time.

5.3.3 Completing Initialization

Once initialization is complete, users can create and attach files on the

devices

specified

with the ICU. lf the

devices are olTline, an exceptional condition code

returned. If one

of these devices is switched from on-line to oifJine,

the Extended I/O System

automatically detaches the device, and aÌl

file connections on that device are marked

invalid

by the BIOS.

When

the unit is switched back on-line, the

Extended I/O System

automatically attaches

it the first time a user tries to create or attach

a file on the device.

The Extended I/O System performs

this service only for devices that

it attaches.

5.4 TESTING

YOUR

SYSTEM

The

normal development cycle

is to load your system, test it and

correct any errors, then

reassemble or recompiìe any appropriate program

code. Next, redefine

and regenerate

your

system using

the ICU, and load the system

again. You can

c<lntinue this

procedure

until

you

have created your

target system.

Once

you

have created your

final system,

minimize the

memory locations

allocated for the system by

editing the

"Memory

for

System"

rcreen

(see

Chapter

3). You can then copy your

final system to

PROM or use

the Bootstrap

Loader to load

it from secondary storage.

If you

are

going

to use the

Bootstrap Loader to

load

your

system, refer fo

Ertended iRMX

II Bootstrap

Loader Reference Manaal

for confìguration

information.

i *** WAIU{INC: THE SYSTEM

DID NoT HAVE YoUR MINIMUM

MEMORY REQUIREMENTS

I you wrLL coME

up wrrH ALL THE ì,rEMoRy rIIAT ts AVAI

TABLE rN THE

I sYsTEM, CONTACT THE SYSTEM MANAGER.

5-4 ICU Use/s Guide

LOADING AND TESTING THE SYSTEM

5.4.1 Using the Debugging

Tools

The development of every system

requires debugging

ancl^testing. To aid

you

in the

development of iRMX II-based application

systems, the IzICE In-Circuit Emulator, the

iRMX II System Debugger with

either the iSDM System

Debug Monitor or the

D-MON38ó

Monitor are available

from Intel. The System

Debugger extends the

capabilities

of the iSDM Monitor

and the D-MON386 Monitor. In addition

the

sysrem

debugging

tools, Intel has Soft-Scope

286/ to debug user programs loaded by the

Application

Loader. The following sections

describe the advantages of these debugging

tools.

5.4.1.1

Advantages

ol the iRMXo ll System Debugger

You can extend the capabilities of

the iSDM Monitor or the D-MON386 Monitor by

including

the System Debugger as part

ofyour operating system. In addition to retaining

the

features of the monitors, the System

Debugger

. Identifies and interprets iRMX II system calls,

. Displays iRMX II objects.

. Allows the user

examine the stack

of a task to determine

which

iRMX Il svstem

calls

it has made recently.

5.4.1.2 Advantages

of Soft-Scopeo 286

Soft-Scope is an interactive, source-level debugging tool designetJ to aid

the debugging

of user

programs

loaded by the Application Loader. It provides the following debugging

features:

. Source code interface and on-line

listings

o Access to program variables,

including arrays and structures

. High-levelbreakpoints

. Access to asscmbly level debugging

. iRMX II multitasking support

. iRMX II exception handling

o Access to iRMX Il objects such as mailboxes and tasks

. Abilitv to susnend and resume tasks

ICU

Usefs Guide 5-5

LOADING AND TESTING THE SYSTEM

5.4.1.3

Advantages ol the l2lCE" In-Circuit Emulator

The IzICE emulator

provides in-circuit emulation

for 80286 and 80386 microprocessor-

based systems, meaning that it

"stands

in" for the these microprocessors in

your target

iRMX II- or Distributed iRMX Ill-based

system. The in-circuit emulator allows

you to

. Get closer to the hardware level

by examining the contents of input pins and input

ports.

. Change the

values

at output

ports.

. Examine

individual

components rather than an entire board.

o Look at the most recent 80 to 150 assembly language instructions executed.

. Protect memory areas from being altered and trap on attempted access.

5.4.2 Debugging Application Jobs

While

you

are creating

your

application

jobs,

you will probably

use the following iterative

procedure

to remove bugs from

your

code:

1. Configure

your

system.

2. Generate

your

system using ICU generated

command fiÌes.

3. Test the system to find bugs.

4. If any bugs are

found,

modify the

application code to eliminate

the

bugs and go to

Step 2.

Once

you

have

performed

the entire configuration process, you

are ready to

load

the

system.

5-ó ICU

Use/s Guide

APPENDIX

FILES

CREATED

BY THE ICU

4.1 INTRODUCTION

The files listed in

this appendix are

created/recreated by

the ICU or as output of the

SUBMIT fiìe.

4.2 CREATED FILES

The table

below lists the

files that are created/recreated whenever you

issue the G

command from

the ICU and/or

invoke the lCU-generated SUBMIT file. The file

names

Iisted here do not

include the prefix

letter that may be added before generation.

Table A-1. Files

Created

by the

ICU

and SUBMIT

File

Subsystem Created

by ICU Created

SUBMIT

File

Nucl€us

Basic l/O System

NTABL.A2S

NUCDA.A2S

NJOBC,A2S

NROMC.428

ICDEV.428

ITABL.A2S

IIDEV,A2S

NTABL,OBJ

NIABL,LST

NUCOA.OBJ

NUCDA.LST

NJOBC.OEJ

NJOBC.LST

NROMC.OBJ

NROMC.LST

NUCl,LNK

NUC1.MPl

NUCLS.LNK

NUCLS.MPl

ICDEV.OBJ

ICDEV.LST

IfABL.OBJ

ITABL.LSf

ITDEV,OBJ

ITDEV.LST

IOSl.LNK

tosl.MP

IOS.LNK

IOS.MPl

ICU

Usefs Guide A-l

Table A-1.

Files

Created

By the

ICU

and

SUBMIT

File

(continued)

Subsystem Created

by ICU Created

SUBMIT

File

E),lendsd l/O

System

Appllcation

LOaO€t

Human

lnterfac€

UDI

System

Debugger

Others

EDEVC.A28

ETABL,42S

EJOBC,A2s

LTABL-428

LCONF.P28

HCONF.P28

UTABL.A2S

SDBCN.428

output-file

>.CSD

outputjile

>.BLD

EDEVC.OBJ

EDEVC.LST

ETABL.OBJ

EIABL.LST

EJOBC,OBJ

EJOBC,LST

Etos1.MP1

EIOS,LNK

Elos.MPl

EIOSl.LNK

LTABL,OBJ

LTABL,LST

LCONF,OBJ

LCONF,LSf

LOADR.LNK

LOADR,MPl

HCONF,OBJ

HCONF.LSI

HI.LNK

HI.MP1

CLI.LNK

CLI.MPl

UTABL.OBJ

UTABL,LST

UDI.LNK

UDI.MPl

SDBCN.OBJ

SDBCN.LST

SDB.LNK

SDB.MPl

boofloadable iRMX ll file

bootloadable-fi le>.MP2

FILES CREATED

8Y THE ICU

A-2 ICU

Use/s Guide

EXAMPLE

SYSTEM APPENDIX

CONFIGURATION

8.1 INTRODUCTION

This appendix contains

an example

illustrating

how to use the ICU to

modifo an Intel-

supplied

definition file. This example contains

the following

descriprions:

. The

configuration defined

by the lntel-supplied

definition file

(28612.de|).

r The target system,

focusing

on the differences

between it and

the supplied

configuration.

o The ICU changes

required to

convert the existing

definition lìle to one

corresponding

to the

target system.

8.2

THE INTEL.SUPPLIED

DEFINITION

FILE

The existing definition

file, named

28612.D8F, defines

the 80286-based mulrluser system.

This particular

system

configuration

has the following

charaeteristics:

. The CPU board is an

iSBC 286/10(A)

or an iSBC 286/12 board.

. Interrupt

levels are

assigned as

fbllows:

Level 0-SystemClock

Level I - System

Debugger

Level2 - Available

Level 3

- Used by the

Terminal

Communicarions

Controller

Level

4 - Available

Level 5

An MSC

controller

Level 6

An 8274

Terminal

Driver

Level 7

An 82594

slave

PfC

. Up to 8M bytes

of RAM, at addresses

20t)0lI through 07FFFFFH. Of these,

addresses

05A000H through OTFFFFFH

are allocateci to the Free

Space Manager.

. The system device

is :SD:.

. The

supplied, ready-to-bootstrap-load

file is

/BOOT/2t1612.286.

ICU

Uset's Guide B-l

EXAMPLE SYSTEM

CONFIGT]RATION

B.3

DIFFERENCES

BETWEEN

THE TARGET

AND START-UP

SYSTEMS

The differences

between the target

system and the 80286-based

multi-user system

dictate

how

you will

use

the ICU to alter

the definition file. These

systems differ in

the following

ways:

. Change

the reserved memory

address of the MSC driver to

prevent an address

conflict with the iSBC 220

,Jriver.

. An iSBC

220 SMD controller for

an 87M byte disk is an

addition to the 80286-baseo

multi-user system. This

controller uses interrupt level2,IlO address 120H.

. An iSBC 208 flexible

disk controller added to support

8-inch flexible disks. As

our

target system

will

not include

iRMX-NET, the iSBC 208

witl

placed on interrupt

level four and

will

use slave

I/O address 180H.

o A RAM driver is an addition to the 80286-hased

multi-user system.

. The

target system defines 4M bytes of RAM,3M bytes

are used by the system and the

Free Space Manager and

lM byte is used by the RAM disk.

. The target system resides in a bootloadable file named

/BOOT/SAM286.286.

The name of the new definition file for

the target system is SAM2ll6.DEF. Figure B-1

shows memory maps of the layout

of both systems: the 2tìfil2.def layout is on the left and

the target system layout

on the right.

8.4 STEPS PERFORMED TO

CREATE

THE TARGET

SYSTEM

The steps needed to modi! an existing definition

file to meet the target system needs are

outlined below.

. Add the iSBC 220 SMD Driver

. Add the iSBC 208 Flexible Disk Controller

Driver

. Add the

RAM Driver

. Change

the memory for the system and Free Space Manager to reflect the amount of

memory needed for operation of the

new devices.

As you proceed

through this example refer to the

Ertended

|RMX II Inleructive

Confguration

Utility Referent'e manual for more information about configuring each of the

above drivers.

B-2 ICU

User's Guide

EXAMPLE SYSTEM

CONFIGURATION

16 M bytes 16 M bytes

SDM Monitor

SDM Start Fc0000H

------O7FFFFH

Free Space Manager

- -

5 5000H

Sub

Sys

tems

RAM Drlver

3 M

bytes

SDM Monitor

FC0000H sDM S tart

Unused Address Space

4 M bytes

Free Space Manager

5FFFFH

Sub

Systems

I000H

- -

isBc 208

2C00H Reserved Memory

2690H

-=isBa]?I-

1210H Reserved Hemory

1200H iSBC 220 Wakeup

1180H MSC Reserved

1010H

1000H MSC Wakeup

SDM DATA

SA.ì{2 8 6 . DEF l,faD

2000H

MSC Reserved 12 00H

MSC \.Jakeuo 1000H

SDM DATA OH

28 612 . DEF Uap

Figure B-1. Memory

Maps for the 802tì6-Based

Systern

and

Target System

ICU Usef s

Guide B-3

EXAMPLE

SYSTEM CONFIGURATION

8.5 USING THE ICU TO DEFINE THE TARGET

SYSTEM

This section describes a dialogue between a user and the ICU. This dialogue

demonstrates the steps

needed

define the target system described in the previous

section. In the dialogue, user input is shown in either blue or bolded

text, followed by a

carriage return (

. CR

). Shoultl you

make an error in entering information as you

proceed

through this example, you can

re-type the information ifyou are currently

vìewing

the screen

which

the error

was

entered. If not, you

can use either the Backup

(b)

or Find

(l) command to access the screen you want

to change, then re-tlpe

the correct

information. If you

are new to the iRMX II ICU and do not want

to use these commands,

you

can delete the SAM286.DEF

file in the SAM286

directory and start over by entering

the last line of the command

sequence listed below.

Invoke the

ICU,

giving

the name

of the default file and the

desired name

of the modified

definition

file, as follows:

This

produces

the

display shown in Figure B-2. This

is the first screen

you

see each time

you

invoke

the ICU.

B-4 ICU

Userrs Guide

EXAMPLE SYSTEM CONFIGURATION

Figure B-2. Initial

ICU

Screen

The

first thing

to change in the target system is the MSC disk

and tape controller. To

th is,

to the

ntel

Device Drivers" screen by entering

idevs

C R

", as shown in

Figure B-2. This

produces

the screen shown in Figure

ts-3.

lRl4X I1 Interactive Configuration Urility For Extènded

Copyrighc <years> Intel Corporation

For general help in any screen entèr H <cr>.

The following cofiìnands are available

Change

Generate

List

Save

Qul

Exl t

Replace

De tai l -

Leve 1

Backup

ENTER

CoMMAND

: C ldevs <CR>

iRlO( II, <v>

ICU Usef s Guide B-5

EXAMPLE SYSTEM CONFIGURATION

(IDEVS) lntel Device Drivers

(S14) Mass Storage Controller [Yes/No] YES

(î74) 8274 Terninal Driver [YeslNo] YES

(T51) 8251A Terninal Driver [YesrzNo] NO

(T30) 82530 Terninal Driver [Yes/No] NO

(TCC) Termtnal Comm Controller [Yes/No] YES

(L86) Lfne Printer for 1SBC 286/fO lYes/No) YES

(L50) Ltne Prlntèr - iSBX 350 [Yes,zNo] NO

(s20) isBc 220 [Yes/No] N0 (X18) isBX 218A [Yes/No] N0

(s08) lsBc 208 [Yes/No] N0 (T34) lSBc 534 [Yes,zNo]

(T44) iSBC 5444 [YeslNo] YEs (s64) lsBc 264 [Yes/No] N0

(X5I) iSBX 251 [Yes,zNo] NO (RAM)

RAM Disk Driver [Yes/No] N0

(scs) scsl Driver [Yes/No] N0 (s24) isBc L86/224A [YeslNo] N0

(s10) isBc 1,86/4LO

[Yes/No] N0 (c79) isBX 279 [Yes,zNo]

Enter I Abbreviation - nevvalue / Abbreviation ? /Hl

: Sl4 - y <CR)

Figure B-3. The Intel Device

Drivers

Screen

The

"Intel

Device

Drivers" screen, shown in Figure B-3, lists all of the

available Intel

devices.

The "YES" or "NO' field shown to

the right of each device

indicates

whether

not it is part of

the current definition file. To add a device or go

to the first screen of an

existing

device, enter

its three-letter abbreviation

followed by "

y <

". The

abbreviation

for the

S14 is

"S14",

rype

"S14=Y

<CR>". This produces

the screen

shown

in Figure B-4.

The parameter

that must be changed

is the'IPA I/O Processor Block

Address"

parameter.

The memory

maps in Figure B-1 showwhy.

From these

mapsyou can see

that

there

would

be an address conflict

between the iSBC 220

SMD controller

and the

original

location of the

MSC disk and tape

controller. To

prevent

this conflict, one of the

devices

must be

moved. Moving the "IPA

I/O Processor Block

Address"

from 1200H to

1180H will

resolve

the conflict. Enter "ipa=

1180H

<CR>", as

shown in Figure

B-4.

check this

change, type "<CR>r'. This produces

the screen

shown in Figure

B-5.

B-ó ICU

Uset's Guide

(D214) Mass Storage Controller Driver

(DEV) Device Name

[1-16 Chars]

(IL) Incerrupt Level IEncoded

Level]

(ITP) lnterrupt Task Priority [0-255]

(wlP) Wakeup

I/0 Port [0-OFFFFH]

(IPA) I/O Processor Block Address [0-OFFFFFH]

EnÈèr I Abbreviation - neu_value / Abbreviation

: lpa-1180h <cR>

: <CR>

215-A

058H

130

0100H

01200H

/H)

EXAMPLE SYSTEM CONFIGURATION

Figure B-4 MSC Driver Screen

Figure B-5 MSC Driver Screen

To add

the iSBC 220 SMD controller, you return to the

"Intel

Device Drivers" screen by

entering

idevs

<CR>". This

produces

the screen shown in Figure 8-6.

(D2L4) Mass Storase Controller Driver

(DEV) Device Naue [1-16 Chars]

(TL) Tnterrupt Level IEncoded

Levell

(ITP) Interrupt Task PrÍority [0-255]

(l.tIP) Wakeup I/O Port [0-oFFFFH]

(IPA) I/O Processor Block Address [0-OFFFFFH]

Enter I Abbreviacion: new_value

/ Abbreviacion

: f fdevs <CR>

215

-A

058H

130

0100H

01180H

/H1

ICU

Use/s Guide B-7

EXAMPLE SYSTEM CONFIGURATION

(IDEVS) Intel Devlce Drivers

(S14) Mass Storage Cóntroller [Yes/No] YES

('174) 8274 Terrninal Driver [Yes/No] YES

(T51) 8251A Tèrninal Driver [Yes/No] No

(T30) 82530 TernÍnal DrÍver [Yes/No] NO

(TCC)

Terminal Conm Concroller [Yes/No] YES

(L86) Llne Printer for íSBC 286110 [YeslNo] YES

(L50) Line Printer - tSBx 350 [Yes,zNo] No

(s20) lsBc 220 [Yes/No] N0 (xl-8) isBX 2l8A [Yes/No] N0

(s08) isBc 208 [YeslNo] N0 (T34) isBc s34 [YèslNo] N0

(T44) iSBC 5444 {YeslNol YEs (s64) lsBc 264 [Yes/No] N0

(X51) iSBX 251 [Yes,zNo] N0 (

RAr'f

) RAM Disk Driver [Yes/No] NO

(SCS)

SCSI Drlver IYes/No] N0 (S24) lSBC 186/224A IYes/No] N0

(S10) ÍSBC 186/410 [Yes/No] No (c79) isBX 279 [YeslNo] No

Enter I Abbreviacion : ne*/value / Abbreviation ? /H]

: S20 - v <CR>

Figure 8-6. The Intel

Device Drivers Screen

The abbreviation for the

iSBC 220 SMD controller is

"S20",

so you type "S20=y

<CR>" at

the bottom

of the screen, as sho\,rr'n in Figure

8-6. This

will produce

the screen shown in

Fisure B-7.

Do you want any

/mo

y <cR> iSBC 220 DEVI CEs ?

Figure

B-7. Query

Screen

for the iSBCo

220 SMD Device

Figure B-7 shows

query

screen that

asks ifyou

want

to add a tievice.

To start the

process

of adding

the iSBC 220 SMD controller,

type

"y <CR>" as shown

in Figure B-7.

This

will produce

the

"iSBC

220 Driver" screen,

as shown in Figure B-8,

B-8 ICU

Uset, s Guide

EXAMPLE

SYSTEM CONFIGURATION

(D22O) ISBC 220 Driver

(DEV)

Device Name

[1-16 Chars]

(IL) Interrupt Level lEncoded

Levell 028H

(ITP) lnterrupt Task PrÍorlty [0-0FFH] 130

(wIP) Wakeup I/o Port [O-0FFFFH] 0120H

(IPA) I/O Processor Block Address [0,0FFFFFH] 01210H

(SB) Size of Buffers [O-0FrrrH] 01480H

EnEer I AbbrevÍation * new/va1ue

/ Abbreviatioa ? /H]

: dev-220 <CR>

: <cR>

Figure B-8. The

iSB@ 220 Driver Screen

The

minimum information

that must be entered on this screen

the "(DEV)

Device

Name"

field. Enter

"dev=220

<CR>", as shown in Figure B-8. Because

all of the

remaining

fields match the target system's

hardware configuration for the iSBC

220 SMD

controller, you

can use the default values.

Enter "<CR>" to reshow the screen with

the

name field completed.

This

produces

the screen

shown in Figure B-9.

(D22O) íSBC 220 Driver

(DEV)

Device Nane [1-16 Chars] 220

(IL) lnterrupt Level lEncoded

Levell 028H

(ITP) Interrupt Task Priority Io-0fFHl 130

(l.llP) Wakeup

I/O Port IO-OFFFFHI 0120H

(IPA) I/0 Processor Block Address [0-OFFFFFH] 01210H

(SB) Size of Buffers [0-OFFFFH] 01480H

Enter I Abbreviation : new_value / Abbreviatlon ? /H

: <cR>

Figure B-9. The

Completed iSBC@ 220 Driver Screen

Check that

you

have entered

the device name correctly. lf so, you are

ready to

add

the

iSBC 220 unit information.

Typing a "<CR>", as shown

in Figure B-9,

will

display the

query

screen shown in Figure B- 10.

ICU Uset's Guide B-9

EXAMPLE SYSTEM CONFIGURATION

Do you

<cP> want any/more 1SBC 220 DEVICES ?

Figure B-10. Query

Screen

for another iSBC€

220 Driver

As this application requires only one

iSBC 220 SMD controller, respond

with

a carriage

return

(<CR>) as shown in Figure

B-10. This tells the ICU that

you do not

want

another

iSBC 220 Driver

and causes the next screen to be displayed,

as shown in Figure

B-11.

Do you want ar,y

/mote

y <cR> iSBC 220 UNITS ?

Figure B-ll. Query

Screen

for iSB@ 220 SMD Controller Unit Information

Figure B-11 shows a query screen that asks ifyou

want to fill in Unit ìnformation for an

iSBC 220 SMD controller. This is the first time that an iSBC 220 SMD controller

has

been added, so such information

does

not

yet

exist. Respond

to this screen by entering

"y <CR>", as shown in Figure

B-l

l. This produces the

"iSBC

220 Unit Information"

screen shown in Fisure B-12.

B-10 ICU Usefs Guide

(V220) ISBC 220 Unit Information

(DEV)

Device Nane [1-16 Chars]

(

NAl,f

) Unit Info Name

[1-16 Chars]

(l'tR) Maxlmum Retries l0-0FFFFHI

(CS) Cylinder Size [0-OFFFFH]

(NC) Nunber of Cylinders [0-0FFFFH]

(NFH)

Nunber of Heads/Fixed Dlsk [0-OFFH]

(NRH)

Nunber of Heads/Rexlovab le Disk [0-OFFH]

(NS) Nurober of Sectors/Track [0-OFFFFH]

(NAC)

Nunber of Alternate Cylinders [0-0FFH]

(SSN) Starting Sector Nunber [0-0FFFFFFFFH]

(BTI) Bad Track InformatíÒn IYes/No]

09H

OTEH

O24DH

07H

012H

OBH

YES

Enter I Abbreviation : new/value

/ Abbreviatlon ? /Hl

: dèr:220 <CR>

: nan-ulnfo_22o <CR>

: <cR>

EXAMPLE

SYSTEM CONFIGURATION

Figure B-12. The iSBCo

220 Unit Information Screen

The

fields requiring information on this screen

are the

"(DEV) Device Name" and

"(NAM)

Unit Info Name" fields. Enter "dev=220

<CR>"

and

"nam=uinfo_220 <CR>",

as shown in Figure B-12.

The remaining fields need not be changed because the defaults

match

the target system. Reshow the "iSBC

220 Unit Inlbrmation"

screen

to ensure that

you

typed everything correctly by entering

", as shown in Figure B- 12. This

produces

the screen shown in Figure

B- 13.

ICU User's Guide B-ll

EXAMPLE

SYSTEM CONFIGURATION

(U220) ISBC

220 Unit lnformÉtion

(DEV)

Devlcè Nane [1-16 Chars] 22O

(NAM)

Unit Info Narne

[1-16 Chars] UINFO_220

(MR) Haximu:r

Rerríes [o-oFFFFH] 09H

(CS) CylÍnder Size [0-0FFFFH] 07EH

(NC) Nurnbe r of Cylinders IO-OFFFFH] 024DH

(NFH)

Nr:nber

of Heads/Fixed Disk l0-OFFHl 07H

(NRH)

Nunber of Heads/Renovable Disk [0-ofFH] 0H

(NS) Number of Seccors/Track [0-0FFFFH] 012H

(NAC) Nutrrber of Alternate Cylinders l0-OFFHl OBH

(ssN) starting sector Number

[0-OFFFFFFFFTI] 0H

(BTI) Bad Track Information [YeslNo] YES

Enter I Abbreviation - new/va1ue

/ Abbrèviation ? / H )

: <CR>

Figure B-13. Completed

iSBC€

220 Unit

Information

Scre€n

After checking the entries on the screen shown in Figure B-13, type a "<CR>" to

view

the

next screen.

Do you want

<cB> any/nore iSBC ?20 UN'fTs ?

Figure B-14.

iSBC€ 220

Unit

Query

Screen

Only one Unit is required for the iSBC 220 SMD controller,

so by entering a carriage

return (<CR>), as shown in Figure B-14, you

tell the ICU that

you

are ready to view

the

major screen.

Do you want any

/mote

y <cR> iSBC

220 DUIBs ?

Figure B-15. iSBC@

220 SMD DUIB

Query

Screen

To complete the

inclusion of the iSBC 220 SMD

controller, a Device Unit lnformation

Block (DUIB) must be completed.

Typing "y <CR>", as shown

in Figure B-15, causes

the "iSBC 220 Device-Unit

Information" screen

in Fìgure B-16 to appear.

B-12 ICU

User's Guide

EXAMPLE

SYSTEM CONFIGURATION

Figure B-16.

The iSB@ 220

Device-Unit Informatkrn

(DUIIì)

Screen

Once again the

default

values

match

the target system.

'I-he

only fieÌds that must be filled

in are

the "(DEV) Device

Name", "(NAM) Device-Unit

Name", and "(UlN) Unit Info

Name'fields.

Enter

"dev=220 <CR>",

"nam=sfO

", and "uin

uinfo_220

<CR>",

as shown

in Figure B- 16. To reshow the screen to

check

your

cntrics, ctìtcr a carriage

return (<CR>) as shown in Figure

B-16. This produces the screen

shown in Figure B- 17.

(1220) iSBC 220 Devlcè UniÈ Information

(DEV)

Device Nane [1-16 Chars]

(

NAÌ,f

) DevÍce-Unic Name

[1-14 Chars]

(PFD) Phystcal File Driver Required [Yes/No] YES

(NFD)

Naned Filè Driver Required [Yes/No] YES

(GM) Granularity [0

OFFFFH

]

(DSZ) Device Size [0-0FFFFFFFFH]

(UN) Unlt Number on this Dèvíce [0-0FFH]

(UIN) UnlÈ Info Narne

[1-16 Chars]

(RUT)

Request Update Tineout [0-OFFFFH]

0400H

0471F000H

064H

(NB) Number of Buffers [nonrandom : 0/rand - I-0FFFF]II 08H

(CUP) Comnon

Updatè [Yes/No ]

(UB) Max Buffers [0-

0FFH

]

Enter I Abbreviation = new_value

/ Abbreviation ? /H)

dev=220 <CR>

nan=sf0 <CR>

uln=ulnfo_220 <CR>

<c8>

YES

OFFH

ICU

Use/s Guide B-13

EXAMPLE SYSTEM CONFIGURATION

Figure B-17. Completed

iStsC€ 220 Device-Unit Information Screen

ìf all the entries are correct, all of the

steps to

include

the iSBC

220 SMD Controller

are

completed.

Note that adding the MSC disk and tape, the iSBC 220 SMD, and the iSBC 208 peripheral

devices requires changing the amount of memory available to both the system,

"(MEMS)

Memory for System" screen, and the Free Space Manager, "(MEMF) Memory for Free

Space Manager" screen. Each of these drivers requires RAM space in the

low

megabyte

of memory for

host/controller

communications

and, in the case of the iSBC 208 and iSBC

220, some I/O buffering. This memory

must

be taken

from the Free Space Manager and

given

to the system. This process can be performed before or after adding the driver

screens. For this example, all of the devices will be added, then the

memory

parameters

will

be changed to incorporate the new devices.

The next step, then, is to add the iSBC

20[Ì Flexible Disk Drive Controller. To begin,

return

to the "Intel

Device Drivers" screen by entering

idevs

<CR>" as shown in Figure

B-17.

(î220) 1SBC 220 Device

Unit Informacion

(DEV)

Devlce Name

[1-16 Chars] 220

(NAl'f)

Devlce-UnÍt Nane [1-14 Chars] SFO

(PFD) Physícal File Driver Required [Yes,zNo] YES

(NFD)

Named File Driver Required [Yes/No] YES

(CRA)

cranulartty [O-OFFFFH] 0400H

(DSZ) Device Size [0-0FFFFFFFFH] 0471F000H

(UN) Unit Nunber on this Device [0-0FFH] 0H

(UIN) Unit Info Name

[1-16 Chars] UINFO_220

(RUT)

Requesc Update Timeout IO-OFFFFH] 064H

(NB) Number of Buffers [nonrandom

- O/ranó - 1-OFFFFH]

08H

(CUP)

Comnon Updace lYes/Nol YEs

(MB) Max Buffers l0-OFFHl OFFH

EnÈer I Abbreviation * new_value / Abbreviation ? /H]

: f ldevs <CR>

B-14 ICU Usefs Guide

EXAMPLE CONFIGURATI

(

rDEVS

)Intel Device

Drivers

(

S1-4

) Hass Storagè Controller

(T7

4) 8274 TerminaL Driver

(

T51) 8251A Terrainal Driver

(T30) 82530 Terninal Driver

(TCC)

Terrnínal Conm

Conrroller

(L86) Line Printer for 1SBC 286110

(L50) Llne Prínter - iSBX 350

(s20) isBc 220 [YeslNo] N0

(s08) isBc 208 [Yes/No] N0

(T44) lsBc 544A lYes/Nol YES

(X51) ísBX 251 [Yes/No] No

(SCS)

SCSI Driver IYes/No] No

(s10) tsBc L86/4I0 [YeslNo] N0

Enter I Abbreviation : new/value

. g0g - y <cR>

lYes/Nol YES

[YeslNo] YES

[Yes/No] No

[YeslNo] N0

IYes,zNo ] YES

IYes/No] YES

lYes/Nol NO

(x18

) isBx 218A

(T34)

iSBC s34

(s64) isBC

264

(RAX)

RAM Disk Driv

(s24) isBC

L86/224A

(c79) isBX

279

/ Abbreviation ? /

IYeslNo

]

IYeslNo ]

IYeslNo

]

IYes/No ]

IYesrzNo ]

IYeslNo]

Figure

B-18. The

Intel Device

Drivers Screen

To add

any driver from

the

(IDEVS)

screen, you type

the device's three-

abbreviation

on6 "=y <cR>,,. The abbreviation

for rhe iSBC

209 Flexit

Controller

"S08",

you

type "S08

= y <CR>" as shown

in Figure

B-li

the

screen shown

in Fisure B-19.

Disk

Drive

This produces

vyou want any/nore

<cR> iSBC 208 DEVICEs?

Figure B-19. iSBCo

208 Device

Query

Screen

Figure

B-19 shows a query

screen

that asks users

if they

want

to add

a dr

process of adding

the iSBC

208 Flexible

Disk

Drive Controller, tlpe "y <

causes the

'iSBC

208 Driver"

screen,

as shown in Figure

B-20, to appear.

Usefs Guide

. To start the

". This

B-

ICU l5

EXAMPLE SYSTEM

CONFIGURATION

(D208

) iSBC 208 Driver

(DEV)

Devlce Nane

[1-16 Chars]

(IL) InÈerrupt Level [Encoded

Level] 048H

(ITP) Interrupt Task Priority [0-255] 130

(PA) Port Address [0-OFFFFH] 0180H

(MDV)

Motor Delay Value IO-OFFFFU] 050H

(BBA) Boundary Buffer Address [0-OFFFFFFFFH] 01600H

Enter I Abbreviation - ner^'-value

/ Abbrevi-atiol ? /H]

: dev=208 <CR>

: bba-2c00H <CR>

: <cR>

Figure B-20.

The iSB@208

Driver Screen

Because

the target system

matches most

ol this screen's default

values,

only

two fields

need

to be changed on this

screen. The

"(DEV) Device Name"

and the

"(BBA) Boundary

Buffer Address" fields.

Enter "dev

208

to fill in the

"(DEV)"Íìeld.

Because the

iSBC 220 driver

has memory located

at the default iSBC

208 address

(see Figure B-42)

the "(BBA)" field must

be changed. Enter

"bba=2C00H

<CR>"

to change this

address.

Enter a carriage return

(

) to reshow

the screen

(Figure B-2 1).

Figure B-21. Completed

iSBC-@ 20tl Driver Screen

The changes and

additions needed on this screen have

been made and checked;

the

"iSBC 208 Unit Information" screen

must now be filled in. To indicate to the ICU that

you are ready to

view

the next screen, enter

a carriage return

(

) as

shown in Figure

B-21.

(

D208

)iSBc 208 Dr ive r

(DEV)

Device Narne

[1-16 Chars]

(IL) Interrupt Level lEncoded

Levell

(ITP) Interrupt Task Priority [0-255]

(PA) Port Address [0

OFFFFH

]

(MDV)

Motor Delay Value [0-0FFFFH]

(BBA)

Boundary

Buffer Address l0-OFFFFFFFFHI

208

048H

130

0180H

50H

2C00H

Enter I Abbreviation : new_value / Abbreviatioi ? /H]

: <cR>

B-16 ICU User's Guide

EXAMPLE

SYSTEM

CONFIGURATION

Do you

<cR> want any/nore iSBC 208 DEVICEs?

Figure

B-22. Query

Screen

for another iSBCo 20E Driver

this application

requires only

one iSBC

208 flexible

disk driver, respond

with

a carriage

return as shown

in Figure

B-22. This tells

the ICU that

you

do not want

another

iSBC 208

driver

and causes

the iSBC

208 Unit query

screen

to appear, as

shown in Figure

B-23.

Do you

y <cR> L'ant any/more iSBC 208 UNITS?

Figure

B-23, Query

Screen for the iSB@ 208

Unit Information

Because

this is a newly

added

device, you must

complete all screens

to the

iSBC

208 Flexible Disk

Drive Controller.

Respond

ro rhis screen

by entering "y <CR>",

as shown

in Figure B-23

produce

the screen

shown in Figure

B-24.

ICU Use/s Guide B-17

EXAMPLE SYSTEM

CONFIGURATION

(U208) iSBC 208 Unit lnformation

(DEV)

Device Nane [1-16 Chars]

(NAM)

Unit Info Name

[1-16 Chars]

(MR) Maximun Rerries I0-OFFFFH] 09H

(cS) Cylinder Size [O-OFFFI1I1 0fA]t

(NT) Nurnber of Tracks per Side [o-oFFFFH] 04DH

(NS) Nurnber of Sectors/Track IO-OFFFFH] 01AH

(SR) Step Ratè [0-0FFH] 08H

(HLT) Head Load Tirne [0-0FfH] 028H

(HUT)

Head Unload Tirne l0-0fFHl 0F0H

Enter I Abbreviation : new_value

/ Abbreviation ? /H]

: dev-208 <CR>

: nan=ufnfo_2O8 <CR>

: <CR>

Figure B-24. iSBC@208 Unit

Information Screen

Because the target

system matches the defaults on this screen

the only fields

you

must

enter are the

"(DEV) Device

Name" and

"(NAM) Unit Info

Name" fields. Enter

"dev=208

<CR>"

and

"nam=uinfo_208

<CR>",

as shown in Figure B-24.

To reshow the

screen to check

your

entries, enter a carriage

return

(

)

u-r8 ICU User's Guide

EXAMPLE SYSTEM

CONFIGURATION

@Figure

B-25. Completed

iSBC@208 Unit

Information Screen

Figure

B-25 shows the completed

"iSBC 208 Unit Information" screen.

Aller checking

that the entries are

correct, enter a carriage return

(

) to continue completing

the

screens related to the iSBC 208

Flexible Disk Drive Controller.

Do you want

<cR> anylrnore iSBC 208 UNITs ?

Figure

8-26. iSBC€208 Unit

Query

Screen

This application

requires

only one Unit. To continue

completing

the screens

related to

the iSBC 208

Flexible Disk Drive

ControlÌer, enter a carriage

return

(<CR>), as

shown

in Fisure 8-26.

Do you

y <cR> want any/more iSBC 208 DUIBs ?

Figure B-27. The iSBC€

20E DUIB Query

Screen

To complete

the addition

of the iSBC 208 Flexible

Disk Drive

Controller,

you must

complete a Device Unit Information

Block

(DUIB). Typing

"y <CR>" causes

the

"iSBC 208 Device-Unit

Information" screen,

shown in Figure

B-28, to appear.

(U208) isBc 208 Unit InformatÍon

(DEV) Device Name

11-16 Charsl 2OB

(NAM)

Unit Info Nane [1-16 Chars] UINFo-

(l,R) Maxlmum Rerries I0-oFFFFHI 09H

(Cs) Cyllnder Size [O-0FFFFH] 01AH

(NT) Numbet

of Tracks per Sfde [0-0FFFFH] 04DH

(NS) Nurnber of Sectors/Track |0-0FFFFHI 0l-AH

(sR) Step Rate [0-0rFH] 08H

(HLT) Head Load Time lO-0FFHl 028H

(HUT)

Head Unload Tine [0-0FFH] 0F0H

Entèr I Abbreviation = nev_value / AbbreviatÍon ?

: <CR>

208

/H)

ICU User's Cuide B-r9

EXAMPLE

SYSTEM

CONFICURATION

Figure B-28.

The iSB@208

Device-Unit

Information

(DUIB)

Screen

The

default values

provided

on this rcreen

match the target

system

for this application.

The only

fields that

must be filled

in are

"(DEV)

Device

Name",

"(NAM) Device-Unit

Name",

and "(UIN) Unit

Info Name". Enter

"dev=208",

"nam

atdO,', and

"uin

uinfo_208",

as shown in

Figure B-28.

Reshow the

screen to

check your

entries by

enteringa

carriage return (<CRr).

(1208) 1SBC 208 Device-Unic lnformation

(DEV)

Devlce Naúe [1-16 Chars]

(NAì,f)

Device-Unic Narne

[1-14 Chars]

(PFD) Physical FíIe Driver Required [Yesr/No]

(NFD)

Named Flle Drlver Requlred IYes/No]

(SDD)

Stngle or Double Density Dlsks I

ingle,zDouble

]

(SDS)

Single or Double Slded Disks ISingle/Double]

(EFI) 8 or 5 lnch Disks [8/5]

(SUF) Standard or Unlform Format {

S tandard/Uni forru

(GRA) Cranularity [0

OFFFFH

]

(DSZ) Devlce Size l0

OFFTFFFFFH

(UN) Unit Nu.nber

on this Device [0-0FFH]

(UIN) Unit Info Name

[1-16 Chars]

(RUT)

Request Updatè Tirnèour [0-OFFFFH]

(NB) Number of Buffers fnonrandon * O/îand - 1-OFFFFH]

(CUP) Comrnon

Update [YeslNo ]

(MB) Max Buffers [0

OFFH

]

Enter I Abbreviation - new/value

/ Abbreviation ? /Hl

dev-208 <CR>

nan-afdo <CR>

uln-ulnfo_2O8 <CR>

<cR>

YES

DOUBLE

SINGLE

STANDARD

0100H

07c500H

064H

06H

YES

OFFH

B-20 ICU

User's Guide

EXAMPLE SYSTEM CONFIGURATION

Figure

B-29.

Completed

iSBCo208

Device-Unit

Information Screen

All of

the steps to include the iSBC 201ì flexible

disk driver

are completed.

You still,

however, must

adjust the system memory to

allow for the addition

of this device.

For

now, though, add

the RAM driver to complete

the addition

of all the devices

listed in the

changes. The first

step is to return to the

"lntel Device Drivers"

screen

by entering "f

idevs

" as

shown in Figure B-29.

(1208) 1SBC 208 Device-Unit Information

(DEV)

Device Name

l1-16 Charsl

(NAM)

Device-Unlt Naroe

[-14 Chars]

(PFD) PhysicaL Filè Driver Required [YeslNo]

(NFD)

Naued File Driver Required [Yes/No]

(SDD)

Stngle or Double Dènsity Disks ISingle/Double]

(SDS) Slngle or Double Sided Disks lSlngle/Doublel

(EFI) I or 5 Inch Disks [8/5]

(SUF) Standard or Uniforn Fornat I

S tandard/Uni form ]

(cRA) cranularity [0 -

OFFFFH]

(DSZ) Devíce Stze [0

OFFFFFFFFH

]

(uN) Unit Nu.rnber on this Device [0-0FFH]

(UIN) Unit Info Name

{1-16 Charsl

(RUT)

Request UpdaLe Timeóut I0-0FFFlîll

(NB) Nurnber

of Buffers lnonrandom

- 0/rand: I-0FFFFHI

(CUP) Coúnon Update IYeslNo ]

(MB) Max Buffers [0

0FFH

]

Enter I Abbreviation : new/va1ue

/ Abbreviacion ? /H

: f ldevs <CR>

208

AFDO

YES

DOUBLE

SINGLE

TANDARD

0100H

0 7c500H

UINFO-208

064H

06H

YES

OFFH

ICU Usefs Guide B-21

EXAMPLE SYSTEM

CONFIGURATION

(IDEVS) lntel Dèvice Drivers

(S14) Mass Storage Cóntrol1er [Yes/No] YES

(T74) 8274 Terninal Driver [YeslNo] YES

(T51) 8251A Ternínal Driver [Yes,uNo] NO

(T30) 82530 Terrninal Driver [YeslNo] NO

(TCC) Terrninal Comm Controller [Yes/No] YES

(L86) Llne Printer for iSBC 286110 [YeslNo] YES

(L50) Line Prlntèr - ISBX 350 [Yès//No] NO

(s20) iSBc 220 [Yes/No] No (X18) isBX 218A [Yes/No] No

(S08) ISBC

208 [Yes/No] N0 (T34) tsBc 534 [Yes//No]

(T44) iSBc 5444 [YeslNo] YES (s64) lsBc 264 [Yes/Nol N0

(X51) ISBX 251 [Yes/No] N0 (RAM)

RAtl Dlsk Driver [Yes/No] NO

(SCS)

SCSI Driver [Yes/No] No (s24) isBc 186/224A [Yes/No] No

(s10) isBc 186/410 [Yes/No] N0 (c79) isBX 279 lyeslNo] No

Enter I Abbreviation - nelvalue / Abbreviarion ? /H]

: raro=v <CR>

Figure B-30. Intel Device Drivers

Screen

To add the

RAM driver, you

type the device's

threeletter

abbreviation

from

the

(IDEVS)

screen

and "=y <CR>". The

abbreviation for

the RAM Disk is "RAM',,

you

t)?e

"ram=

y <CR>" as shown

in Figure B-30. This produces

the screen

in Figure

B-31.

Do you I'ant any

/more

y <cR> RAl,l Disk Driver DEVI

CEs ?

Figure

B-31. RAM Disk Device

Query

Screen

To start

adding

the RAM disk, tlpe "y <CR>". This entry produces

rhe',RAM

Disk

Driver"

screen

as shown

in Fisure

B-32.

B-22 ICU

Use/s Guide

EXAMPLE SYSTEM CONFIGURATION

(DRAM) RAI{ Disk Dríver

(DEV)

Device Name

[1-16 Characters]

Enter lAbbreviation = new_value

/ Abbreviation ? / H ]:

: dev-ran <CR>

: <cR>

Figure B-32. Default RAM Disk Driver Screen

The only information to enter on this screen is the "(DEV) Device Name" field. Enter

"dev= ram <CR>", as shown in Figure B-32. Enter a carriage return

(<CR>) to

redisolav

the

screen with the

new data.

(DRAì4) RAM Disk Driver

(DEV)

Device Narne

11-16 Charactersl RAI1

Enter [Abbreviation: new_va1ue

/ Abbreviation ? / H ]:

: <CR>

Figure B-33. Inserted RAM Disk Driver Screen

Figure B-33

shows that the

necessary change has

been made; therefore, simply

enter a

carriage return

(

) to

view

the next

query

screen

as shown in Figure B-34.

Do you want

<c8> anv/more RAI'Í Disk Driver DEVICES ?

Figure B-34. RAM Driver Query

Screen

Because

you have only one RAM disk driver to add, enter

a carriage return (

) to

view

the RAM driver Units query screen as shown in Figure

B-35.

ICU User's Guide B-23

EXAMPLE SYSTEM CONFIGURATION

Do you want any/nore

y <cll> RAl,t Disk Driver UNITs ?

Figure B-35. RAM Unit Query

Screen

Because the Unit information does not

yet

exist in our definition file, type

"y <CR>".

This

produces

the

"RAM Disk Driver Unit Information' screen as shown in Figure 8-36.

Figure 8-36. RAM Disk Driver Unit Information Screen

The fields that

must be filled in on this screen

are "(DEV) Device

Name", "(NAM) Unit

Info

Name", and "(BMA) Base

Memory Address".

The base memory address value is

chosen by selecting

an address above

the default memory reseryed

for the system and the

Free Space Manager

in the memory map

shown in Figure B-42.

Enter

"dev=ram",

"nam

uinfo_ram", and

"bma

300000h".

To check your entries,

enter a "

". This

action produces

the

screen shown in Figure

B-37.

(URAI{) Ml'f Disk Dri.ver Unit Infornation

(DEV) Device Name

[1-16 Characters]

(NAM) Unit Info Name [1-16 Chars]

(BMA) Base Memory Address l0-OFFFFFPHI

(WP) Write Protected IYes/No ]

0100000H

Enter lAbbreviatlon: ner^r_value

/ Abbrevlation ? / H I :

dev-ran <CR)

nan*ulnfo_ram cP>

bna-300000h <cR>

<cR>

B-24 ICU

User's Guide

EXAMPLE

SYSTEM CONFIGURATION

(UR-AX) RAM Disk Drj.ver Unit Infornation

(DEV)

Device Name

[1-16 Characters] RAM

(NAì4)

UniÈ Info Nane [1-16 Chars] UINFO_RA.I{

(

Bl'lA) Base Memory

Address IO-oFFFFFFH] 300000H

(IJP) lJrite Protected [Yes/No] NO

Enter [Abbreviation - new_va1ue / Abbreviation ? / H | :

: <cR>

Figure B-37. Inserted RAM Disk Driver Unit Information Screen

After checking the entries on the screen shown

in Figure B-37,

ty?e a

"<CR>" to view the

next screen.

Do you want

<cR> anvlnore RA-t,f Disk Driver UNITs ?

Figure B-38. RAM Unit Query

Screen

Only one Unit is required for the RAM Disk, so by entering a

"<CR>", as shown in

Figure B-38,

you

continue the

process

adding the RAM Disk.

Do you want any/mo]ie

y <CI{>

RA.|4 Disk Driver DUIBS ?

Figure

B-39. RAM DUIB

Query

Screen

To finish adding the RAM disk, you

must complete a DUIB. To begin, enter "y <CR>"

as shown in Figure B-39. The ICU then displays the "Ram Disk Device-Unit Information"

screen. as shown in Fisure

B-40.

ICU

Use/s Guide B-25

EXAMPLE

SYSTEM CONFIGURATION

Figure B-40. RAM Disk Device-Unit Information Screen

The fields that must be

filled in on this screen are "(DEV) Device

Name",

"(NAM)

Device-Unit Name", and

"(UIN) Unit Info Name". The remaining

fields can use the

default values.

Enter

"dev=ram

", "nam

r0", and

"uin

uinfo ram <CR>". To

check

your

entries, type Figure B-41 shows

the inserted

"RAM Disk Device-

Unit Information"

screen.

(

IRAI4) RAM Disk Device-Uni! Infornation

(DEV)

Device Nane [1-16 CharacÈers]

(NAl'f)

Devlce-Unit Narne

l1-14 charsl

(PFD) Physical Fí1e Driver Rèquired [Yes,zNo] YES

(NFD)

Narne File Driver Required [Yes/No] YES

(GM) Granularíty |0-OFFFFHI 0200H

(DSZ) Devlce Size |O-OFFFFFFFFHI 0100000H

(UN) Unit Ntrnbèr of this Device [0-0FFH] 0H

(UlN) Unit Info Narue

Il'16 Chars]

(RUT)

Request Update Timeout IO-OFFFFH] 0H

(NB) Nr.ruber of Buffers [nonrandom - O/rand - 1-OFFFFH] 02H

(CUP)

Conmon Update [Yes/No] YES

(MB) Max Buffers |O-OFFH] OFFH

Enter lAbbreviation - new_value / Abbreviation ? / H ) :

dev-ran <CR>

nan=ro <CR>

uln*uinfo_ran <CR>

<cR>

B-26 ICU

User's Guide

EXAMPLE SYSTEM

CONFIGURATION

Figure B-41.

Inserted RAM Disk

DUIB Information

Screen

As mentioned earlier, adding

certain devices requires adjustments to the memory

for the

system

and the Free Space

Manager. Use the memory map in Figure B-42 to determine

where you will

increase the

memory locations for the system

and decrease the memory

locations

for

the

Free Space Manager.

Figures B-43 through B-4tì show these

changes.

You will

notice that

you

cannot simply insert the memory

locations nee<Jed. First

you

must delete the current

reserved memory

locations,

view

the screen again to enter the

new values,

then

view

the screen

a third time to check the

changes. This

procedure

necessary

because the ICU does not accept addresses

that could cause overlapping

memory locations.

Enter "f

mems

to view

the

"Memory

for System" screen

shown in Figure B-43.

(

IRA.I'!

) RAÌ.t Disk Device-Unit Informarion

(DEV)

Device Narne

[1-16 Characters]

(NAl,f)

Device-Unit Name

l1-14 charsl

(PFD) Physlcal File Driver Required IYeslNo]

(NFD)

Nane FiIe Driver Required [YesruNo]

(GM) Cranulartcy [0

OFFFFH

]

(DSZ) Device S ize [0-0FFFFFFFI1I]

(UN) Unit Nunber of this Device lO-0FFHl

(UlN) Unít Info Narne

(1-1-6

Charsl

(RUT)

Request Update Timeout [0-0FFFF!]

(NB) Nunber of Buffers [nonrandom : O/rand - ],-0FFFFHI

(CUP) Common

Update [Yes/No ]

(MB) Max Buffers [0

OFFH

]

Enter [Abbreviation - new_value / Abbreviation ? / H ]

: f nens <CR>

RAM

YES

0200H

0100000H

UINFO-RAI'I

02H

YES

OFFH

ICU

UseIJs Guide B-27

EXAMPLE SYSTEM

CONFIGURATION

16 M bytes 16 M bytes

SDM Monitor

SDM

Start Fc0000H

- - -

OTFFFFH

Free Space Manager

----55000H

Sub

Sys terns

2000H

MSC Reserved 1200H

CnM M^6 i r^r

FC0000H SDM S tart

Unused

Address Space

4 M bytes

RAI'f Dr iver

I M bytes -

I'rao Qnenp M,n.oèr

5FFFFH-

Sub

Sys tems

I000H

- -

isBc 208

2C00H Reserved Memory

2690H

-------I3Ba-f7-

1210H Reserved Memory

1200H iSBC 220 l,,takeup

1180H MSC Re served

1010H

1000H MSC l.Iakeup

SDM DATA

SAUz86. DEF

XaD

MSC tJakeuo 1000H

SDM DATA OHOH

28612 . DEF

Map

Figure B-42. The Original and Modified Memory Maps

B-28 ICU Usefs Guide

EXAMPLE SYSTEM

CONFIGURATION

(MEMS) Menory for Sys tem

sYs - ìow l0-OFFFFFFHI,

high [0-OFFFFFFH]

[1] sYS - 02000H, 059FFFH

[2 ] sYs

Enter Changes [Nurnber

: new_value / ^D Number / ? / H ) :

: ^d I <cR>

Figure B-43. Memory for System

Screen

To delete

the default

values

rype

"^d

1 <CR>". This entry produces the screen shown in

Fisure

B-44.

(MEMS) Memory for Sys t em

sYs * low {0-OFFFFFFHI,

hÍgh l0-OFrFFrFHl

[1] sYS

Enter Changes lNumber

: nevr_value

/ ^D Nltnber / ? /H]:

: I - 3000h,5ffffh <CR>

Figure B-4.1.

Changing the Memory for System Screen

From the memory map in Figure

B-42,

you

find the lower and upper addrcss

limits for

system

memory and configure them

by entering'l

3000h,5ffffh

<CR>", as shown in

Figure B-44.

This

produces

the

"Memory

for

System"

screen

containing these changes,

shown in Fìgure

B-45. Note that the upper value (5FFFFII)was

selected to ensure

adequate

memory space. If saving

memory is a concern, cxamine the .mp2 file producecl

during system

generation

(G[enerate]

command) to find out the actual system size. Once

the

actual system size is determined,

adjust this address accordingly.

ICU User's Guide B-29

EXAMPLE SYSTEM CONFIGURATION

(MEMS) Menory for systèn

SYS - 1ow IO-oFFFFFFH],

hlgh Io-oFFFFFFH]

[r] sYs - 03000H, o5FFFFH

[2] sYs

Enter Changès [Number * ner,r_value / ^D Nunber / ? / H I :

: f nenf <CR>

Figure

B-45. New Memory for System Screen

Now,

you must change the memory

for the Free Space Manager.

Enter "f memf

to view the

"Memory

for Free

Space Manager" screen as

shown

in Figure

8-46. Follow

the steps for changing

memory addresses, as shown

in Figures 8-46 through B-48.

(MEMF) Menory for Free Space Manager

Fsu - low [0-OFFFFFFH],

high IO-OFFFFFH]

[1] FsM : 05A000H, O7FFFFzu

[2 ] FsM

Enter Changes

[Nurnber

* ne\{_va1ue

/ ^D

Nunber

/? /H):

: ^d 1 <cP>

Figure 8-46. Memory for Free

Space

Manager

Screen

(MEMF) Memory for Free Space Manager

rsll - 1ow

[0-OFFFrFrH],

high lO-0rrFFFHl

[

] rs],f

Enter Changes

[Number

: new_va1ue

/ ^D

Nunber

/? /Hl:

: I - 600O0h,02fffffh <CR>

Figure B-47. Changing the

Memory for Free

Space

Manager

Screen

B-30 ICU

Usefs Guide

EXAMPLE

SYSTEM

CONFIGURATION

(MEilf) Menory for Free Space Manager

FsM - low [0-0FFFFFFH],

high [0-OFFFFI1{]

[1] FSr.f - 060000H, o2FFFFrir

[2] FsM

Enter Changes

[Number

: new_value

/ ^D

Nurnber

/? /H]:

: f gen <CR>

Figure B-48. New

Memory for Free

Space

Manager

Screen

Now that

the system and Free Space

Manager memory for the 80286-based

multi-user

system have been

changed to match the target

system, you are ready to generate the

system.

produce

the "Generate

File Names" screen, type "f gen

<CR>" as shown

Fisure B-48.

(CEN) cenerate File Nanes

File Narne

[1^-55

Characters]

(ROF) ROM Code File Nane

/BoOT/RMX2

Rol,r

(RAF) RAl,f Code File Narne

/Boor /28612

.286

Enter fAbbrevlation: new_vaLue

/ Abbreviatlon ? / H ] :

' wf-/boot/ saxo28 6 . 28 ó <cR>

: <CR>

Figure B-49. Generate File Names Screen

On the

"Generate

FiÌe Names"

screen, sho\ryn in Figure

B-49,

you must specify the

pathname

of the new bootloadable

file you will be generating. For this application, the

file

is SAM286.286, and

will

be a RAM code file name. Enter "raf

/boot/sam28ó.286

<CR>". To

produce

the changed "Generate

File Names" screen

(shown

in Figure

B-50),

enter

a carriage return

"<CR>"

You are

now

ready

start

the

generation phase

of the ICU. To do this

you

must first

return to the ICU menu screen.

Enter

<CR>" on the screen

shown

in Figure

B-50.

This

entry

produces

the ICU menu screen shown in Figure B-51.

ICU Usefs Guide B-31

EXAMPLE SYSTEM CONFIGURATION

(CEN) Cenerate File Names

File Narue

[1-55 Characters]

(ROf) ROM Code File Name /Bo0T/RMX286

. Ror.r

(RAF) RAM Code File Name /Roor/sM286.286

Enter lAbbreviatíon: new_value / Abbreviation ? / H ) :

: c <cB>

Figure B-50, New

Generate

File Names

Screen

For general help in any screen enter H <cR>.

The following commands

are available

Change

Generate

LisÈ

Save

Qul

Exit

Replacè

Detail-Level

Backup

ENTER

COMMAND

: g <CR>

Figure B-51. ICU Menu

Screen

Entering the G command on the ICU menu screen

produces

the screen shown in Figure

B-51, starting the

generation process.

shown in Figure B-52, the display

prompts you

for the prefix you

wish

to assign to all the files

generated by this submit file. For this

example, type

". The ICU echoes

the prefix and informs

you of the progress of

the

generation process.

B--ì2 ICU Usefs Guide

EXAMPLE SYSTEM CON

FIGU RATION

ENTER a letter to be used as prefix: s <CR>

The preffx letter is: S

Beginnlng NUCLEUS File Ceneration

.....,..DONE

Beginning BIOS file GeneratiÒn

;;;i;;i;;';ióirii.c""..";i;; "'" D.NE

........DONE

Beglnning LOADER

flle Generation

;;;i;;i;;';i iii" c"""."iion " "D.NE

" :

" ..::

:: :

' ^ "' ''' DoNE

Beginning UDI FiIe Genera t ion

;;;i;;i;;';;; Fii; ó;;;;;;i;; ' "' D'NE

:'': ': ''^.'': -:-"^ ""' DoNE

Beginning Subní t Fi 1e Cenerati on

Beginning Build Fíle ceneration ........DONE

NOTE: To Generate your systern subnit SAM286.CSD

For general help in any screen enter H <CR>.

The following comrnands are available

Change

Gènerate

Llst

S ave

QuiÈ

Exi t

Replace

Deta i I -Leve1

Backup

ENTER

COMMAND

: e <cR>

Figure B-52. Generation Phase ICU Screen

ICU

Usef s

Guide B-33

EXAMPLE SYSTEM CONFIGURATION

When

the

generation process is completed, the ICU displays the name of the resulting

submit file. In this case,

the submit file is SAM286.CSD. The ICU then continues

automatically to the ICU menu screen

where you should enter "e <CR>" to exit the ICU

antl save the definition file. Upon receiving the Exit command, the ICU informs

you that

the

definition file has been

written. It issues the following message before returning

control to the command lìne:

The Deflnition File has been written to file: SAM286.DEF

You are

now ready

invoke

the SUBMIT file

SAM286.CSD. You do this by

entering

The SUBMIT

file

assembles

all

the

configuration files

generated

by the ICU and binds

the

object files

with

all the libraries required by the subsystems.

It then builds the system.

Figure B-53 shows

a listing of the output from the SUBMIT file. You

may

notice

warning

messages. The

warning

messages are normal

and can be ignored. Only error messages

must be heeded.

B-34 ICU

User's Guide

Figure B-53. Output of Submit

File for SAM28ó.CSD

EXAMPLE SYSTEM CONFIGURATION

NUCLEUS

- :IANG:ASM286 SNTABL. A2I

TRI'ÍX

II iAPX286 MACRO ASSEMBLER,

AS SEI.ÍBLY

COM?LETE, NO I.'ARNINCS

, NO ERRORS

- : IANG: ASM286 SNUCDA.A2E

iRMX II IAPX286 MACRO ASSEMBLER,

Vl ,3

copyrighÈ 1982 Incel Corporation

ASSEMBLY

COMPLETE, NO WARNINGS, NO ERRORS

- :IANC:ASM286

SNJOBC . A28

IRMX II IAPX286 MACRO ASSEMBLER, Vl .3

Copyrlght 198 2 Intel Corpóration

ASSEMBLY COMPLETE, NO WARNTNGS, NO ERRORS

- :IANG:BND286

**OBJECTiSNUCI.LNK)

NODEBUC

NOTYPE SEGSIZE(STACK(2OO)

) &

** NoLOAD NoPUBLICS EXCEPT

(RQ_ni1_os_ext , &

iRMX II iOPXZEE

BINDER, V3,2

PROCOSSING

COMPLETED, 2 WARNINGS, O ERRORS

- :I-ANG:

BND286 &

**OBJ

ECT

(

SNUCLS .

LNK) NODEBUG NOTYPE &

** NoLOAD

SECS rZE

(

STACK( 200

) )

iRMX

II IAPX286 BINDER,

V3.2

Intel corporation

PROCESSING

COMPLETED. 1 WARNING, O ERRORS

ICU UseCs Guide B-35

nînc

- :IANG:ASM286

SITABL. A28

1RMX II 1APX286 MACRO ÀSSE},IBLER, V1.3

Copyrtght 1982 Intel CorporaÈlon

ASSEI,ÍBLY COMPLETE, NO IIARNINGS, NO ERRORS

- :IANG:ASU286 SICDEV. 428

iR}D( II iAPX286 MACRO ASSEMBLER, V1.3

ASSEMBLY

COMPLETE, NO WARNINGS, NO EPAORS

- :I-ANG:AS[286 SITDEV.A2S

iRMX II iAPX286 MACRO

ASSEHELER,

V1.3

ASS

EI,IBLY COMPLETE, NO Í.IARNINCS

, NO ERRORS

- :LANG:bnd286

**OBJECT (SIOSI.LNK) NODEBUG NOTYPE &

** NOLOAD

NOPUBLICS

EXCEPT

(rqaiosinittask , &

iRMx rr iepxzeo

BTNDER,

v3.2

CopyrighÈ 1982, 1985 Intel Corporarion

PROCESSING

COMPLETED, 1 I.IARNING, O ERRORS

- :IANG:bnd286

**OBJECT

(STSC.LITK)

NODEBUG NOTYPE

SECSIZE(STACK(O)) &

** NOLOAD

NOPUBLICS

EXCEPT( TSCINITIO, &

iR},lX II iETXZSO

BINDER, V3.2

Copyrlght 1982, 1985 Incel Corporarion

PROCESSING

COMPLETED. O IIARNINCS, O ERRORS

EXAMPLE SYSTEM

CONFIGURATION

Figure B-53.

Output

of Submit File for

SAM286.CSD

(continued)

B-36 ICU UseIJs

Guide

- :LANG:bnd286

**OBJECT

(SIOS.LNK) NODEBUG

NOTYPE SECSIZE(STACK(O)

) &

** N0L0A! NoPUBLICS EXCEPT

(rqaiosinittask , &

1RMX

II iEPXZEE

BINDER, V3.2

PROCESSING

COMPLETED. O I.JARNINGS, O ERRORS

- : EIOS

- :I-ANG:

ASM2 86 SETABL.A2S

tRIO( I1 1APX286

MACRO ASSEI"IBLER,

ASSEMBLY

COMPLETE, NO WARNINGS, NO ERRORS

- :LANG:ASM286

SEDEVC .

A2 8

iRMX II 1APX286 MACRO

ASSEì'IBLER,

V1 ,3

Copyrlght 1982 Intel Corporation

ASSEMBLY

COMPLETE, NO IIARNINCS, NO

ERRORS

- :IANG:ASM286

SEJOBC .428

iRMX

II iAPX286

MACRO ASSEMBLER,

Copyrlght 1982 Intel Corporation

ASSEMBLY

COMPLETE, NO

WARNINCS, NO ERRORS

- : LANG:BND286

**OBJECT(

SEIOSl.LNK)

NOLOAD NODEBUG

SEGSIZE(STACK(O))

** NOPUBLICS

ExcEPT(rqeiosinittask , &

íRMX II iAPX286

BINDER,

V3.2

PROCESSING

COMPLEîED. 1 WARNING, O ERRORS

EXAMPLE SYSTEM

CONFIGURATION

Figure B-53. Output

of Submit

File

for SAM2116.CSD

(continùed)

ICU

Uset's

Guide B-37

EXAMPLE

SYSTEM

CONFIGURATION

- :IANG:BND286

**OBJECT( SEIOS.LNK) NOLOAD NODEBUG

SEGSIZE(STACK(O)

)

iRMX II 1APX286

BINDER, V3.2

PROCESSING COI{PLETED. O I.IARNINGS, O ERRORS

- ; I,OADER

- :lANc:ASl'f286 SLTABL.A2S

iR!.o(

II 1ApX286 MACRO

ASSEUBIER, V1

Copyrlght 1982 Intel Corporarlon

AS SEI'TBLY

COMPLETE, NO WARNINGS, NO ERRORS

- :I,ANG: PLtl286 SLCONF.

P28

1RMX II PL/N-286 COUP1LER

V2.5

PL/t4-286 CoMPIIATTON

CoMPLETE. 0 ITARNTNCS, 0 ERRORS

. :I,ANG:BND286

**oBJECT (SLOADR.

LNK) NOLoAD

NODEBUC

SEGSTZE(STACK(0)

) &

** NOPUBLICS

EXCEPT

(asynchload, &

tRMx

rr iarxzas

BTNDER, v3.2

Copyrighr 1982, l-985 lnrel Corporation

PROCESSINC

COMPLETED. O WARNINGS, O ERRORS

I.T T

- irolrc,

pr-Mzee

sHcoNF.

p28

íRlo( II PL/tt-286 CoMPILER V2.5

Copyrlght Intel Corporarion

1982, 1983, 1994, 1985

PL/\I-286 CoMPITATIoN

CoMPLETE. 1 WARNTNC, 0 ERRORS

Figure

B-53. Output of Submit File for SAM2E6.CSD

(continued)

B-38 ICU

Use/s Guide

- :l3NG:BND286 &

**OBJECT( SHI .II.IK) NOLOAD NODEBUG SEGSIZE(STACK(O)

) &

** NoPUBLICS EXCEPT

(

rqhÍ lni ttask, &

rRlo( rr iepxzee

BTNDER, v3.2

PROCESSINC COMPLETED. 1 WARNING, O ERRORS

CLI

IANG:BND286 &

**OBJECT(SCLI

.LNK) NOLOAD NODEBUG &

**SEGSIZE

(sTAcK(02400H)

) NoPUBLICS EXcEPT

(hcl iinit)

1RMX II íAPX286 BINDER, V3.2

Copyrlght 1982, 1985

lnlel Corporacion

PROCESSINC

COMPLETED. O WARNINCS, O ERRORS

-i UDI

- ;

IANG: ASI'Í286 SUTABL.A2S

IR},IX II 1APX286 I.IACRO ASSE},ÍBLER, VI , 3

Copyrtght 1982 lntel CorporaÈion

ASSEMBLY COI'IPLETE, NO LIARNINGS, NO ERRORS

- :IANG:BND286 &

**OBJECTi SUDI . LNK ) NODEBUG NOTYPE

SEGSIZE(STACK(O)

) &

**NoLOAD

NoPUBLIC S EXCEPT

(U_Allocete , &

IRMX II iAPX286 BINDER,

V3.2

PROCESSINC

COMPLETED. O WARNINGS, O ERRORS

EXAMPLE SYSTEM CONFIGURATION

Figure B-53. Output of Submit

File for SAM286.CSD

(continued)

ICU Useds

Guide B-39

EXAMPLE

SYSTEM CONFIGURATION

-i sDB

- :I,ANG:ASMz86 SSDBCN.

A28

iRMX 1I iAPX286 MACRO ASSEMBLER, Vl.3

ASSEMBLY COMPLETE, NO WARNINGS, NO ERRORS

. : I.ANG: BND286

**oBJECTi SSDB. r,Ì.rK) ss(STACK(0)

) NOI,OAD &

**NOPUBLICS

EXCEPT

(

rqsdb ini ttask )

iRMX II íAPX286

BINDER,

V3.2

PROCESSING

COMPLETED. O I.'ARNINGS, O ERRORS

- ; BUILD

- :IANG:BLD286

ì** orincr 17ru,rxz

B6/rcu/sùi2f,6

/ s$'r286

.286 ) NoDEBUG

NorypE &

** BUI LDFILE

(

SA.I{2

86 . BLD)

iRMX

11 iAPX286

SYSTEM BUILDER,

V3.2

CopyrÍght 1982, 1985 Intel Corporarion

PROCESSING

COMPLETED. 1 WARN]NG, O ERRORS

- END SUBMIT

sam286.

CSD

Figure B-53.

Output of Subrnit File for

SAM286.CSD

(continued)

This ends the

output from

the SUBMIT

file SAM286.CSD.

To bootstrap load

this

system,

prepare

a third-stage

bootstrap loader

by entering

This places

a copy

of the

device-specific third-stage

bootstrap

loader

in a boot file named

/BOOT/SAM286,

which

required ro bootstrap

load

the bootable

file for this example

confisuration.

B-40 ICU

User's

Guide

EXAMPLE SYSTEM

CONFIGURATION

If conserving memory is a consideration,

you

can minimize

the memory assigned

to the

system by examining the segment map of file /BOOT/SAM28ó.MP2 created during the

build process.

By adding

the segment limits in the segment

map you can calculate

the

precise memory addresses required by the system and

the Free Space Manager.

Remember

that

when you

configured the ICU, you estimated the memory required,

leaving extra

room for any changes made during

development. Now

with

the exact

addresses available

you

can minimize

the memory you have reserved. For

the rest of this

example assume that this calculation resulted in

a system that can reside in

addresses

3000H to 59FFFH. To minimize

the memory,

you

must invoke

the ICU with the

definition file you havejust

created. Invoke the ICU by entering

iRMX

II Inreractive Configuration Utility FÒr Extended iRMX 1I, <v>

CopyrlghÈ <years> Intel Corporation

For general help in any screen enter H <CR>.

The fol-lowlng conrnands are availabl.e

Change

Generate

Llst

Save

Quit

Exl t

Replace

Detell -

LeveI

Backup

ENTER

COMI'ÍAND : c nems <cR>

Figure B-54.

Initial ICU Screen

This entry

produces the initial

ICU screen shown in Figure B-54.

Entering

mems

<CR>" takes

you to the

"Memory

for

System" screen,

shown in Figure

B-55,

where you

can adjust the memory

reserved for the

system. Using

the MP2 file

you can determine

that the system

requires less

memory than you had

previously

reserved, leaving

memory for the Free

Space Manager.

Consequently,

you must change

the memory

screens, as

shown in Figures B-55

through 60. Remember

that

the ICU does

not accept

overlapping

memory addresses.

Therefore,

you

must

perform the separate

steps of

deleting the

existing memory locations,

making

your

changes,

and

viewing the new

screen.

ICU Usefs Guide B-41

EXAMPLE SYSTEM

CONFIGURATION

(MEMS) Memory for systèm

sYs : 1ow [0-0FFFFFFH],

high [o-OFFFFFFH]

[1] sYs - 03000H, 05FrFFH

[2] sYs

Enter Changès [Nurnber

: new_value / ^D Nunber / ? / H ] :

:^d I <GR>

Figure B-55. Memory for System Screen

(MEMS) Mènory for System

sYs - 1ow [O-0FFFFFFH],

high I0-OFFFFFFH]

[

1] sYS

Enter Changes [Number - new_value / "D Nurnber

/ ? / H ] :

;l- 3000h,5Bfffh <cR>

Figure

B-56. Adjusting

the Memory for System

Screen

(MEMS) Menory for System

SYS : Lolr I0-OFFFFFFH],

high IO-0FFFFFFH]

lrl sYs - 03000H, 059FFFH

[2] sYs

Enter Changes [Nurnber

: ner{r_value

/ ^D Nurnber

/ ? / H ] :

:f nenf <CR>

Figure

B-57. Final Memory

for System Screen

Once you

have

changed the "Memory

for System"

screen, you

are ready to

change the

"Memory

for Free

Space Manager"

screen.

Once you

know the

system memory

requirements,

the Free

Space Manager gets

the

rest of the

memory.

you can assign the

Free Space

Manager

more memory than

you

had originally

assigned since your

system

was

smalìer than you

expected.

Change

the "Memory

for Free

Space Manager',

screen, as

shown in Figures B-58

through

8-60.

B-42 ICU Usefs Guide

EXAMPLE

SYSTEM CONFIGURATION

(MEUF) Memory For Free Space Manager

FsM - low [0-OFFFFFFH],

high [O-OFFrrm]

[1] rsu * 060000H, o2FFFFFH

[2 ] FsM

Enter Changes [Nurnber

: nelr_value / ^D Nurnber

/ ? / H ] :

^d I <cR>

Figure B-58. Memory for Free Space Manager Screen

(MEMF) Memory

For Free Space Manager

FSM - low lO-OFFFFFFHI,

high IO-0FFFFru]

[1] FsM

Enter Changes lNurnber

- neu_value / ^D Nlunber

/ ? / H ) :

:l - 5C00Oh, 2fffffh <CR>

Figure B-59. Changes to the Memory for Free Space Manager Screen

(MEì,fF) Menory For Free Space Manager

FSM - low [0-0FFFFFFHI,

high [0-0FFFFFH]

[1] FsM : 05A000H, O2FFFFFT

[2 ] rsM

Enter Changes [Nunber - new_value / "D Nunber / ? / H ) :

c <cI>

Figure 8-60. Final Memory for Free

Space

Manager

Screen

After you have made all the necessary changes to your definition file,

you can save the file

and exit the lCU. However, first you must return to the ICU menu screen

(shown in

Figure

8-61)

by entering "c

<CR>"

as the final entry in Figure 8-60. As an extra

precaution before exiting, you should list the contents of our definition file

to a file or to a

device.

The

List command lists the contents of the screens in the

system you have

just

generated

and enables

you

to ensure that

you

have the correct

parameter

values

before

saving

the files.

To use the List command, enter "l <file

name>

<CR>"

in Figure 8-61,

which produces the screen displayed in Figure B-62.

B-43

ICU User's Guide

EXAMPLE SYSTEM CONFIGURATION

For general help in any screen enter H <CR>.

The follor.llng commands

are available

Change

Generate

Lis t

S ave

QuiÈ

Exi t

Rèplace

Detail -Level

Backup

ENTER COMMLND

:l san286.lst <CR>

Figure 8-61. Entering the List Command

îhe Definltlon File has been listed to file:

For general help in any screen enÈer H <CR>.

The following commands are available

Change

Generate

Lls È

Save

Quit

l!,x 1c

Rep Iace

Detall-Leve1

Backup

ENTER

COMÌ,IAND : g <CR>

SAM286

LST

Figure 8-62. ICU Menu

Screen

Enter the G command

on the ICU menu

screen to start the generation process,

shown in

Figure 8-62.

shown

in Figure 8-63, the

display prompts you

for the

prefix you wish

assign to

all the files generated

by this submit file. For

this example, type "s

<CR>". The

ICU echoes the

prefix

and informs you

of the progress

of the

generation

process.

B-44 ICU

Use/s Guide

EXAMPI-E SYSTEM

CONFIGURATION

Figure

8-63. Generation

Phase

ICU Screen

Now that

you

have L[isted]

the definition

file and G[enerated]

the system

configuration

files,

you

are ready

to exit the ICU by entering

<CR>", as shown

in Figure

8-63

B-45

ENTER

a letter to be used as prefix: s (CR)

The

prefix letter is: S

Beginnlng NUCLzuS File Generation ........DONE

Beginning BIOS

File Generation

,"ói""i"e eiói nii" ò"""i';i;; " 'D.NE

nnÀtP

Beginning L0ADER

Fi.le Generation ........DONE

Beglnning HI Ftle GeneratÍon

Beglnning UDI File CeneraÈlon

" "" DONE

Beginning SDB File Generation

;;;i;;i;;';;-i; Fii; ;;;;;;i;" "' D.NE

''"" DONE

Beginning BuÍ1d File Ceneration

"ói;; i; ;;;"r.."

y"",

"y;;;'

;;;i; i*rà;.::it

For general help in any screen enler H <CR>.

The following cornmands are available

Change

Generate

List

Save

Qui t

Exi t

Replace

Detal1-l,eve1

Backup

ENTERCoMMAND:e(CR)

ICU User's

Guide

EXAMPLE SYSTEM CONFIGURATION

When

the ICU has successfully saved

the definition file, it exits after issuing the following

messaqe:

The Deflnfrlon File has beén eritten to file: SAU286.DEF

You are now ready to invoke the SUBMIT file SAM286.CSD.

Do this by

entering

The SUBMIT file assembles all the configuration

files generated

by the ICU and binds

the object files with all the libraries

required by the subsystems.

It then builds the system.

Refer

again to Figure

B-53 for a listing of the

output from the

SUBMIT file. You may

notice warning

messages.

The

warning

messages

are normal and

can be ignored. Only

error

messages must be

heeded.

When

the SUBMIT

file is completed your

entire system

has been

built.

The bootfile named

/BOOT/SAM286.286

contains

the entire svstem.

You are now readv

to bootload your

new executable

system.

B-46 ICU User's

Guide

APPENDIX C

PROGRAMMING A 286.BASED

SYSTEM INTO

PROM DEVICES

C.1 INTRODUCTION

This appendix

provides

examples of the

procedures

used to

place

the iRMX II Operating

System

into ROM of a 286-based system. All software

generation

described assumes

you

are using an Intel System 300 Series Microcomputer. In this appendix,

one version of the

operating system is created, but two examples of how to

proglam

it into ROM exist.

The

first

example

places the iSDM monitor and the iRMX II Bootstrap Loader

in ROM

along

with

the generated operating system. A system such

as this executes the iSDM

monitor code during the initial

power-up

sequence. This

example includes the iSDM

monitor and iRMX II Bootstrap Loader for several

reasons. First,

while you

develop

the

ROM-based system,

you

can bootstrap load RAM-based

versions of the operating system

rather

than having

to switch PROM devices if you are using

one processor board. Second,

the

iSDM monitor,

while not allowing breakpoints in PROM DEVICEs, does allow

you to

disassemble

and examine memory in both ROM and RAM. You can use this feature

determine correct code is in correct locations.

The second example eliminates

the iSDM monitor and the Bootstrap Loader

from the

PROM devices. A stand-alone system such as this allows the operating

system to be 32

Kbytes larger than in

the first example. In this example, the operating

system receives

control during initial

power-up

or reset.

C.2 REQUIREMENTS

To use the procedures outlined in this appendix,

you must have the

following hardware

and software:

. A system defined during configuration as residing in RoM.

. The iRMX IL3 and iPPS

V1.4

lor newer)

software. The

iPPS software runs

on an

Series-IV

Development System.

ICU Usefs

Guide c-1

PROGRAMMING

A 286-BASED SYSTEM INTO PROM DEVICES

. A 286-based system and a Series-lV Development

System connected

via

the iSDM

monitor.

o An iUP-200/201 Universal

Programmer

with

'FAST

27/K' module with

27512

support.

. Four 27512 EPROM devrces.

C.3 CONFIGURING A ROM.BASED

SYSTEM

Before you

can

program

your system into

PROM DEVICEs, you

must modify a number

parameters

your

definition file. These examples assume that you

start

with

the Intel-

supplied

definition file 286l2.DEF

locared in directory

/RMX28ó/ICU.

To begin the example, you

should make

a copy of the definition

file in a separate

directory.

To do this,

create a new directory

which

to do the

system

generation.

The

definition

file should

have a .DEF extension,

the boot-loadable

system should have

a .286

extension, and

the system

to be loaded into ROM

should have

a .ROM

extension.

Entering the

three following

commands creates

a new directory

calted ROMSYS, attaches

you to

that directory,

and invokes the

ICU

placing

a copy

of the definition file

28612.D8F

into

the new directory.

(This example

assumes

your :HOME: directory

your

current

default directorv.l

part

of the

configuration process,

you must perform

the following three

things in order

fit the iRMX II system developed

in these

examples into

ROM:

. Delete the System

Debugger

from the system.

. Replace

the iRMX

II.3 CLI with

the iRMX II.l CLL

. Delete all Intel

device

drivers except the

8274 MPSC

and MSC device

drivers.

Having invoked

the

ICU,

you

now can

begin to

make the necessary

configuration

changes.

Start by

modifying

the memory screens

to define

the ROM

memory locations

the system

requires.

Do this

by first selecting

the

"Memory for System"

screen with

the following

command:

c-2 ICU

Use/s Guide

PROGRAMMING

A 286.BASED

SYSTEM

INTO PROM DEVICES

Entering

the

previous command

causes the

"memory

for

System"

screen to appear

follows:

(MEMS) Menory for Syscen

SYS

- los IO-OFFFFFFH],

hrgh IO-0FFFFFFH]

[rl sYs - 010000H, 059FFFH

[2] sYs

Enter Changes lNurnber - new-value / "D Nurnber / ? / \ I I

Begin the alteration

by deleting line I by entering

the following

command:

After the screen reappears,

enter the low

and high

addresses

to indicate

the location

the system in ROM as follows:

In this example,

the

system resides

in locations

0FC1000H

to 0FF7FFFH.

These

locations

allow the iSDM

monitor and

Bootstrap

Loader

to reside

at locations

0FF8000H

to OFFFFFFH in ROM. After

entering the

new memory

locations,

the

"Memory

for

System" screen

appears

as follows:

(MEUS) MerDory

for SysEen

SYS

- low [0-0FFFFFFH]

, high [O-0FFFFFFH]

[1] sYS - 0Fc1000H, 0FFTFFTH

[2 ] sYs

Enter Changes [Nurnber

* new-value / "D Nwrber / ? / H 1 :

<cR>

Ifyou were

not

to include

the iSDM

monitor

and Bootstrap

Loader,

you could

use

locations

0FC1000H

0FFFFEFH.

ICU Use/s

Guide c-3

PROGRAMMING

A 2Iì6-BASEI)

SYSTEM INTO PROM

DE\TCES

Now, display

the "Memory

for Free Space

Manager" screen

by entering "<CR>', as

shown

in the previous

screen. You

must also

adjust this memory

screen as a ROM-based

system

uses different

memory

locations than

the RAM-based

system defined

in the

definition

lile. Change

the "Memory

lbr Free Space

Manager"

screen to contain

the

memory

locations 45000H

ro IFFFFFH. The

following screen

shows the

"Memory

for

Free Space

Manager" screen

after

making the changes:

After making changes

to the memory

screens,

request

the

"Sub-systems',

screen

entering

the

following

commlrnd:

Here,

you

must

delete

the Systcm

Debugger

because

size considerations.

Derete the

SDB

entering

the

following

command:

(MEMF)

FSM

: Iow

[1] FSM

] FsM

Enter Changes

Memory For Free Space Manager

[0-0FFFFFFH], high [0

0FFFFFH

]

O45OOOH, O1FFFFFH

fNurnber

- new_value

/ ^D Number

/? /H):

(suB) Sub

sys

tems

(UDI) Universal Developmenr

Interface Iyes/No]

(HI

) Human

Inrerface Iyes/No]

(AL) Application Loader IYes/No

]

(RFA) Renore File Access lyes/Nol

(EIo) Exrended l/0 System [yes/No]

(BIO) Basic I/0 System

Iyes/No]

(SDB)

System

Debugger IYes/No]

(OE) OS

Extension IYes/No]

YES

REQ

YES

Enter fAbbreviation : new_value

/ Abbreviation ? /H ] :

c-4 ICU

Use/s

Guide

PROGRAMMING

A 28ó.BASED

SYSTEM INTO PROM

DE\TCES

Next,

request

the

"Human

Interface"

screen by enteríng

the following

command:

Change

the resident

initial program

(CLI) by

entering the

following command:

Both

the iRMX II.3

CLI and the iRMX II.2 CLI are

considerably larger

than the iRMX

II.1 CLI and

cannot be used

in this example

due to size restrictions.

Next,

request the "Intel

Device

Driver" screen by

entering the following

command:

Delete

all device

drivers except the 8274 and

MSC drivers by entering

the following

commands:

Do you want any/more iSBC 544A DEVICEs?

Do you ltant any/more Terninal Corununications Controller Devices?

Do you want any/more Line Printer for iSBC 286/10 DEVICEs

Now,

request the

"Nucleus"

screen by entering

the following command:

You must define

the number

of Global Descriptor

Table

(GDT) entries

your

ROM-based

system

needs. Because

ROM space

is limited, the

numberyou enter should

be the

minimum

number. Enter

the number

oî real GDT entries

required

when

the system is

copied

and expanded

in RAM using

the

"ROM

Code" screen.

Also, because the System

Debugger was previously

deleted

from the configuration, you

must change the

Default

Exception Handler parameter

to something

other than SDB.

ICU

UsePs Guide c-5

PROGRAMMING

A 2E6-BASED SYSTEM

INTO PROM DEVICES

Chanse the

"Nucleus"

screen

as follows:

Once you have updated the "Nucleus" screen,

view the "ROM

Code" screen to

change the

parameters to

match the ROM-based

system. Set the RAG

parameter

to FC1000H

match the starting address defined on the

"Memory for System" screen. Always

place the

GDT at the

first

memory location reserved for the

system.

Set the RAS

parameter to

2000H to allow enough memory for the controllers in

the

system. Controllers

are always

assigned addresses below 2000H. Finally, set the RIA parameter

to FC0000H,

the

starting address of

processor

board ROM. Change the

"ROM Code" screen as

follows:

(MJc

)Nucleus

(NGE) Nr.[nber

of GDT

Entries [4a0 - 8190]

(NIE) Nunber of lDT Entries 10-256)

(PV) Parametar Validation IYesr/No ]

(RoD) Root objéct Dítéctory Size f0 38401

(DEH) Default Exception Handler [Yes/No/SDB/User

]

(NMI

) Nl.f l Exception Handler I

Yes/No/I gnore

/ J ob

/ SDIIN

seî I

(NEB)

NHI Enable Byte [0-255]

(STK) Exception Handler for stack Exception, Bad TSS and

Double Faulc [Yes/No/JoblsDB ]

(NEH)

Nane

of Ex Handler ObJect Module [1-55chs]

(EM) Excèptión Mode INever/Program/Environ/Al l ]

(LSE) Los GDT/LDT Slot Excluded from FSM

[440-8189H/None:0]

(HSE)

High CDT/LDT Slot Excluded fron FSM

1440-8189/None-01

(RRP)

Round

Robin Priority Threshold l0-2551

(RRT)

Round Robln Time Quota [0-255]

(RIE) Report Inltlalization Errors IYeslNo]

(MCE)

Maxinuxn Data Chain Elenents [0-OFFFFH]

(CS) Nucleus CoÍununicatíon

Service [Yes/No]

Enter [Abbreviacion - new_value

/ Abbreviation ? /H):

460 <CR>

Job <CR>

<cR>

2000

128

REQ

SDB

ICNORE

JOB

NEVER

140

YES

080H

YES

:nge -

:deh

f rorn

c-6 ICU

Uset's

Guide

PROGRAMMING

A 2E6-BASED

SYSTEM

INTO PROM DEVICES

(R0ì,1) R0!{ code

(SYR) System ln ROM

[Yes/No] N0

(MG) ROM Address of Master-GDT

I0-OFFFFFFH] 0H

(NSG)

Nunber Slots in Real CDT

[440-81901 7024

(RAS)

RAtf Start Address for Systen IO-OFFFFFH] 0H

(RIA) RoM lnítializatlon Code Address [0-OFFFFFFH] 0FF0000H

(RIP) RoM Inítlalizaclon Procedure IL - 45 chars]

Enter [Àbbreviatlon - nes_value / Abbrevlatlot ? / H ):

: syr-yes <CR>

: rag:fcloooh <cR>

: ras-02000h <CR>

:rla-fc0000h <CR>

Now, request the

"Generate

File Names" screen by entering the following command:

The "Generate

File Names" screen is where

you

define the

pathname

of the file

containing the ROM-based system. Enter the pathname :$:ROMSYS.ROM

as shown

below:

Next, enter

<CR>" to

return

to the ICU menu screen.

(cEN

)Generate File Names

File Name

Il- 55 Characters]

(ROF) RoM Code File Name

(RAF) RAM Code File Narne /Boor/RMX286

RoM

/Booî/28612.286

Enter [Abbrevlation: new*value / Abbreviatlon ? / H ) :

rof-: $:

ronsys,ron <CR>

: c <cIì>

ICU

Uset's Guide c-7

PROGRAMMING

A 286-BASED SYSTEM TNTO PROM DEVICES

c.4 GENERATTNG/BU|LD|NG

THE

SYSTEM

You are now ready to generate the definition files and build the system. The last step oî

the previous

section caused the ICU main screen to appear. From this screen, enter the

Generate

(G)

command to

generate

files.

For general help ln any scteen enter H (CR).

The followlng commands are avallable

Change

Generate

List

Save

Qul

ExiE

Replace

Detail-Level

Backup

ENTER

COMMAND

:C <CR>

After entering

"G <CR>" with

prefix,

the ICU informs

you

as each layer is generated

(see

Figure B-35 for an

example). When the system

has been generated,

the ICU returns

to the

main menu screen.

Enter the Exit

(E)

command to write the

definition file and

exit the ICU as follows:

After entering

this command,

the ICU informs you

that

the definition

file has been

written. It issues

the following

message before returning

control to the

command

line:

The dafinítion file has been \rritten to file: ROMSYS.DEF

You are

now ready

to invoke the SUBMIT

file ROMSYS.CSD

that

builds the system.

The ICU created

this SUBMIT

file as

part

of the generation process.

Execution

of the

SUBMIT

file generates

the application

system

with

the pathname

:$:ROMSYS.ROM.

Execution

of this SUBMIT

file also generates

the map

file ROMSYS.MP2, which

conrains

information

crucial

to configuring

"tight"

system.

The map file

ROMSYS.MP2 also

contains

the following warning which

you can

safely ignore:

c-8 ICU Uset's

Guide

I,IARNINC

119:

LOW ADDRESS:

HIGH

ADDRESS:

SEGMENTS

OVERTAP

00Fc0000H

00Fc0E04H

PROGRAMMING

A 286-BASED

SYSTEM INTO PROM DEVICES

After the

submit file completes

execution,

use the

DOWNCOPY command

to copy

the

resulting

file ROMSYS.ROM

to the file

:Fl:ROMSYS.ROM

on the

hard disk of the

Series-IV Development

System. This

assumes

you

have used the LNAME command on

the

Series-IV

system to define

the logical

name :Fl for rhe

directory into which you will

copy the file.

Now that the

system

has been generated, you

can either

program

the

PROM devices to

include only the

operating

system by itself (stand-alone)

you

can include the

iSDM

monitor.

The next sections

describe

these

different Drocesses.

C.4.1

Including the

|SDM"

Monitor

and the Bootstrap

Loader in

the

PROM Devices

This

section explains

how to

include

the iSDM monitor

and iRMX ll Bootstrap Loader as

part

of the operating

system that

resides in ROM. With this

type of system, the

iSDM

monitor code

executes

when

the system

is powered

up. In order to create

a system that

includes

the iSDM

monitor and

the Bootstrap

Loader you must prepare

two files; one

file

for each

piece

of software.

First you

must generate

a version

of the

iSDM monitor

for the iSBC

286/10(A) board.

The iSDM

monitor is normally

installed

on iRMX lI systems in the directory

/SDM.

Since

the Bootstrap

Loader is to

be included

in the PROM devices

along

with

the iSDM

monitor,

be sure

you

invoke

the BOOTSTRAP

macro

as follows when you

configure the

iSDM

monitor:

The iRMX II.3 iSDM monitor

is always

located at address 0FF8000H.

The iSDM

monitor places values

into the

reset

vector

and receives control

power-up

or reset.

Refer to the iSDM Systetn

Debug Mottitor

User's Guide

for more information

generating

the iSDM

monitor.

Next, generate a version

of the iRMX Bootstrap

Loader first stage. Assign your

current

default

directory to be the

Bootstrap

Loader directory by entering

the following

command:

ICU

User's Guide c-9

PROGRAMMING

A 286.BASED

SYSTEM

INTO

PROM

DEVICES

Due to the

limited

amount

of space

left over for

the Bootstrap

l-oader,

you can not

leave

all

available devices

selected

within BS1.A8ó.

Consequently,

you

must

edit

the

first stage

configuration

file,

BS1.A86

to contain

only the

driver included

in the

ROM system, the

MSC

device

driver. You

do not

need îo change

any other

parameters

in BS

1.A86. You

must

also edit

the first stage

configuration

SUBMIT

file

(BSl.CSD) to link

in only

the

MSC

file.

Execute

the Bootstrap

Loader

SUBMIT file

by entering

the following

command:

Complete

details on these

actions are available

in the Extended

|RMX II Bootstmp

Loader

Reference Manual.

At this

point, the files for

the iSDM monitor

and the Bootstrap

Loader

are generated.

Copy the resulting

files, BSI

and 28610A, to the files:F1:BSl

and

:F1:286l0A of

the hard

disk of the

Series-IV Development

System using

the DOWNCOPY

command. This

example assumes

you have used

the LNAME command

on the Series-IV

system to

define

the logical name

:F1: as the

directory into which

you will copy the files.

The following

commands move the two files:

The next

six sections describe how to program the PROM devices.

C.4.1.1

Setting Up

the iUP 201 PROM Programmer

Perform the following three

steps to set up the iUP 201 PROM Programmer:

1. Make sure that the RS-232A

line is connected from the iUP 201

programmer to the

Series-IV

system.

2. Insert the'FAST 27K'module into the iUP 201

28-pin socket and turn on the

power

to the iUP 201 Universal Programmer.

3 Press the ONLINE button

on the iUP 201 front

oanel.

WARNING

While

following the steps outlined in this section,

you

must

closely adhere

to any

warnings

or cautions given in the iUP-200/201 Universal Programmer

User's Gukle.

c-10 ICU

Uset's

Guide

PROGRAMMING A 286.BASED

SYSTEM

INTO PROM DEVICES

C.4.1.2 Formatting the Operating System PROM File

Invoke

the iPPS software and issue

the following commands to format the two PROM

image

files. Because this example includes

the iSDM monitor and Bootstrap

l,oader

part of the operating system,

the memory range for the operating system

goes

from

OFC0000H to 0FF7FFFH.

lf you were programming

only the operating system, the

largest

memory range for it would

range

from 0FC0000H to OFFFFEFH.

. IPPS <CR>

INTEL PROM PROGRAM},IING

SOFTI,JARE, VX.

years

PPS>type 27512 <CR>

PPS>lnltlallze 286 <CR>

PPs>format :fl:romsys.ron (0FC0000h,

0FFTFFFh) <CR>

LOGICAL

UNIT (

BIT:1 ,

NIBBLE:2

BYTE-3

N*BYTE-4)

LU -3 <CR>

INPUT

BLOCK SIZE (N BYTES)

N :2 <CR>

OUTPUT BLOCK

SIZE (N BYTES)

N -1 <CR>.

INPUT BLOCK STRUCTURE.

NUMBER OF INPUT LOGICAL UNITS :OO2

LSB

loo l01 |

**ri*-ot ourPUT LocrcAL

uNrrs

:ool

OUTPUT SPECIFICATION

(<CR>

TO EXIT):

*0 to ; fl: romsys

, evn <CR>

OUTPUT STORED

*L to : fl: ronsys .

odd <CR>

OUTPUT STORED

* <cR>

PPS>

The parameters in parcnthesis on the

FORMAT line

tell the IPPS software

what

memory

range of code

you wish

program

into PROM devices.

ICU

Use/s Guide c-ll

PROGRAMMING

A 2II6-BASED SYSTEM

INTO PROM DEITCES

C.4.1.3

Programming

the Operating

System

into PBOM

Devices

To actuaUy

place the

generated system into

the PROM devices,

begin by

inserting the first

PROM

device into the

active socket

of the PROM

programmer. Next,

enter the following

PPS commands

shown as

bolded text:

PPS>copy

:fl:ronsys.evn to Ptom <CR>

..,.CAUTION.. - -

PROGRAMI"IING

THE TULL LENGTH

REQUIRES

MORE THAN

ONE

PROM.

CHECKSUM*va1ue

FIRST INSTALL

THE NEW/NEXT PRO}4 AND

THEN CONTINUE.

coNTtNr.rE

- -YlN? Y

CHECXSUM:value

PPS>ex!È <CR>

During the copy, the IPPS software

automatically determines that the contents

of the file

require more than one of the

specified type of PROM devices to contain

the code. When

a new PROM device

is needed, IPPS

prompts you with

the following

message:

INSTALL THE NE\N/NEXT PROM AND THEN CONTINUE

Remove the first PROM device

ancl insert the second. Next, type "Y <CR>". When

the

checksum value appears on the screen, remove the second PROM device. These two

PROM devices

you

have removed contain the even

(or

low)

bytes

the WORD values

that compose the operating system. As you remove the PROM devices from the

programmer,

carefully label them; unlabeled PROM devices look

very

much alike. At a

later time, you will place

the first

programmed

PROM device in socket U41 and

the

second programmed

PROM

device

in socket U40 of an iSBC 286/10(A) board.

(Use

sockets

U2 and U3 of the iSBX 341 on an iSBC 286/12 board.)

Next,

you

need to

program

the PROM devices to contain the odd (or high) bytes of the

WORD values

that compose the operating system. Insert the third PROM device into the

active socket of the PROM

programmer

and enter the

following PPS commands

shown as

bolded text:

c-12 ICU

Useds Guide

PROGRAMMING

A 286.8A5ED

SYSTEM

INTO PROM DEVICES

PPS>copy :fl:ronsys.odd to prom <CR>

. . . . CAUTION

- . . . PROCRAì,IMING

THE TULL LENGTH

REQUIRES MORE T}IAN ONE

PROM .

CHECKSUM:value

FIRST INSTALL

THE NELT/NEXT

PROM AND THEN CONTINÙE.

coNTIN'rJE

- -YlN? Y

CHECKSUM:value

PPS>

Again, when

IPPS determines

it needs another PROM

device, it prompts you with

the

following

message:

INSTALL THE NEII/NEXT PROI,I

THEN CONTINUE

Remove the

third PROM device and

insert the fourth. Next, type "Y <CR>". When

the

checksum value appears

on the screen,

remove the fourth PROM device. These two

PROM devices contain the

odd

(or

high)

bytes of the

WORD values

that compose

the

system. As you

remove the PROM

devices from the programmer, carefully

label them;

unlabeled

PROM devices look very

much alike..

At a later time,

you will place

the third

programmed

PROM

device in socket U76

and the fourth

programmed

PROM device

socket U75 of an

iSBC 286/ l0(A) board.

(Use

sockets U5 and U6 of the iSBX

341 on an

iSBC 286/12 board.) The

next step

programs

the

iSDM monitor and the

iRMX Bootstrap Loader into

the fourth PROM device so do not install

it now.

C.4.1.4 Programming the

|SDM Monitor into

PROM Devices

This section describes how to program

the

iSDM monitor into the second and fourth

PROM

devices. To do this, insert

the second PROM clevice

and enter the followins

commands shown as boldetl text:

ICU User's Guide c-r3

PROGRAMMING

A 286-BASED SYSTEM

INTO

PROM DEVICES

PPs>forrnet :fl:28610a (0FF8000h, oFFFFFFh) <CR>

LOGICAL

UNIT (BIT-1, NIBBLE_2,

BYTE:3, N_BYTE-4

)

LU *3 <CR>

INPUT BLOCK SIZE (N BYTES

)

N :2 <CR>

OUTPUT

BLOCK SIZE (N BYTES)

N -l <cR>

OUTPUT SPECIFICATION

(<Cb TO EXIT):

*0 to :fl:286l0a.evn <cR>

OUTPUT STORED

*l to :fl:28610a.odd <CR>

OUTPUT STORED

<cP>

PPS>

PPS>copy

:fl:28610a.ewn to prom(0c000H) <CR>

CHECKSUM-va1ue

When

the

IPPS software prompts you

with

the following message, remove

the second

PROM device, insert the fourth, and enter the following command:

PPS>copy

fl:286Loa. odd to prom(0o000H)

CHEcKSUM:value <cR>

C.4.1.5

Programming the Bootstrap Loader into PROM Devices

This section describes

how

to program

the Bootstrap Loader into the second and fourth

PROM devices. To begin, insert

the second PROM device and enter the commands

shown as bolded text:

c-14 ICU UseCs Guide

PPs>lnltlallze 86 <cR>

PPs>format :fl: BSI (0FE400h, 0FFFTFh)

LOCICAL

UNIT

(BIT-I.NIBBLE:2,BYTE:3,N_

LU -3 <C8>

INPUT BLOCK SIZE (N BYTES)

N -2 <CR>

OUTPUT BLOCK

SIZE (N BYTES)

N :1 <CR>

OUTPUT SPECIFICATION

(<CR>

TO EXIT):

*0 to :fl:bsl.evn <CR>

OUTPUT STORED

*l to:fl:bsl.odd <CR>

OUTPUT STORED

<cR>

PPS>

PPS>copy : fl:bsl. evn to pron(0F200H)

CHECKSUM:va1ue

<cR>

BYTE:4

)

PROGRAMMING A 286.BASED

SYSTEM

INTO PROM DEVICES

When

the IPPS software displays the following prompt,

remove

the second PROM device,

insert the fourth

PROM device, and enter the following command:

PPS>copy

f1: bs1.

odd to prorn(0F200H)

CHECKSùM:value

PPS>exlt <CR>

<cR>

C,4,'1,6 Starting the Operating

Syslem

in ROM from the iSDM" Monitor

The four PROM devices now contain

the operating system, the iSDM monitor, and the

Bootstrap

Loader. Perform the following steps to slart the system:

1. Place the first programmed PROM device

in socket U4l of the iSBC 286/10(,4)

board.

Place the second programmed

PROM device in socket

U40 of the iSBC 286/10(A)

board.

Place the third

programmed

PROM

device in socket

U76 of the iSBC 286/10(A)

board.

Place the fourth programmed

PROM device in socket

U75 of the iSBC 286/10(A)

board.

ICU User's Guide c-15

PROGRAMMING

A 286-BASED SYSTEM

INTO PROM

DEVICES

Insert the iSBC 286/10(A)

board into the

system chassis and apply

power to

the

hardware.

Enter the following

command from

the

iSDM

monitor to activate

the iRMX ll

svstem:

The

code executed by entering the command

in step 6 above is the ROM initialization

procedure whose address

was

specified in

the ICU as 0FC0000H. The offset

ofthe

beginning instruction of this

procedure is 12H. The reason 0C000:12 is used

instead of

0FC000:12 is that, in real address mode,

the 80286 can only access up to 1 megab]'te

memory. Also,

in real address mode,

the

memory

decoding of the 286/10(A) board,

when

jumpered

for 2'7512 EPROM devices, places the memory addresses of the PROM devices

0C000:0 to 0FFFF:F. This addressing scheme results in execution of

the code at

0C000: 12 to occur first. The code at 0C000: l2 is the first

instruction of the ROM

initialization code.

C.4.2 Creating a System That is

Activated

on Power-Up

The

section explained how to

program

a system that included the operating

system, the iSDM monitor, and the Bootstrap Loader into PROM devices.

With

this type

of a system, the iSDM monitor receives control during the initial

power-on (or

reset)

sequence and is signed on. This requires that

you give

a command to the iSDM monitor

to start the operating system. This section explains how to program

only the operating

system

into

the

PROM devices. To create a PROM-based iRMX II system

which receives

control at

power-on,

you need to take certain steps. Before the following section

describes these steps, you should be made aware of the following:

. Most PROM-based systems are already "debugged" and have no need of the iSDM

monitor or the iRMX II System Debugger (SDB).

o The iSDM monitor has limited use in a PROM-based

svstem because it can't set

breakpoints

in code that executes from ROM.

. The ROM initialization code of the iRMX II Nucleus currently has no means of fully

initializing the iSDM monitor. Initialization code

can only inform the iSDM monitor

(if it is present and has been previously

initialized) that the 80286 CPU has been

s$,itched

to Protected Mode.

. Virtually

all PROM-based

iRMX II systems require that the system be initialized

immediatelv uoon Power Un.

c-16 ICU

Usefs Guide

PROGRAMMING A 286-BASED

SYSTEM

INTO PROM

DEVICES

For these

reasons, a standalone PROM-based

iRMX II Operating System has no reason

to include the

iSDM monitor, the Bootstrap

l.oader

or the SDB. With this in mind, the

following sections

explain how to program

such a system into the PROM devices and

detail

the additional steps required

to manually

program

the Reset Vector. (You must

manually program the Reset Vector

in order to have the operating system receive control

after

the initial power-on or reset

sequence.)

C.4.2.1 Formatting

the Operating System PROM File

To begin, you

must

prepare

twÒ

PROM image files: one for the even bytes and one for

the odd

bytes of the operating system.

To prepare

these files, invoke the iPPS software

and issue the following commands

shown as bolded text. Because you are now

programming

only the operating system

into the PROM devices, the largest

possible

memory

range for the system ranges from 0FC0000H to 0FFFFEFH. The

parameters in

parenthesis

on the FORMAT line tell

the IPPS software

what

memory range of code

you

wish

program

into the PROM devices.

Ifyour system

does not extend to 0FFFFEFH,

you

only

need to

specify

the address at

which

it does reach, although there is usually no

harm in specilying the entire

range.

The foÌlowing screen shows the

commands necessary and the response

you

receive at the

terminal:

ICU Uset's Guide c-r7

PROGRAMMING

A 286-BASED SYSTEM

INTO PROM DEVICES

- IPPS <CR>

INTEL PROM

PRoGRA.tfì,tING SOFTIIARE,

Vx. y

years

PPS>type 27512 <CR>

PPs>lnltlaLlze 286 <CB>

PPs>fornat :fl:ronsys.ron (0Fc0000h, 0rFFFEFh) <CR>

LOGICAL UNIT (BIT:1, NIBBLE:2

BYTE:3, N-BYîE-4)

LU -3 <CB>

INPUT BLOCK SIZE (N BYTES)

N -2 <CR>

OUTPUT BLOCK SIZE (N BYTES

)

N -1 <CR>

OUTPUT SPECIFICATION

(<CR>

TO EXIT):

*0 to : fl: roEsys, evn <CR>

OUTPUT

STORED

*1 to : fl: ronsys . odd <€R>

OUTPUT

STORED

* <cR>

PPS>

C.4.2.2

Ptogtamming

the Operating System Into the PROM Devices

This section describes

how to program

the two operating system files prepared in the

section into the PROM devices and how to

modify

the

Reset

Vector

jump

address.

^fwo

27512 PROM devices are

required to contain the even bytes of the operating system

and two

27512 PROM devices are required to contain the odd bytes

of the

operating

system. This example refers to these PROM devices

as one through four.

You can program the

first ofthese PROM devices with no

intermediate steps. Begin by

inserting

the first PROM device into the

active socket and enter the following command:

PPS>copy : fl :ronsys.ewn(0, oFFFFH)

CHECKSUM-value to Pron <cR>

After

the CHECKSUM

value

message appears, remove the first PROM device,

insert

the second PROM device.

and enter the followins command:

c-18 ICU User's Guide

PROGRAMMING A 28ó.BASED

SYSTEM

INTO PROM

DE\TCES

PPS>copy ifl:ronsys.evn(10000H,OIFFFFH)

to buffer <CR>

CHECKSUM:value

You

now need to modi$ the even bytes of the

Reset

Vector

jump

address. Use the iPPS

SUBSTITUTE command to change

the even bytes of the Reset Vector in the buffer as

follows:

OOFFFS: FF FF FF

FF FF FF FF FF

00FFF8: EA 00 C0

FF FF FF FF FF

After changing the values,

copy the buffer to a file by entering the following command:

copy buffer to : fl: temp

Now,

copy

the temp

file

the PROM devices by entering the following command:

PPS>copy : fl: tenp to pron

CHECKSUM:value <c8>

After the

CHECKSUM=value message appears on the screen, remove the second

PROM device. The first two PROM devices

now

contain the even

(or

low) bytes of the

WORD values

that compose the operating system.

you remove the PROM devices

from the programmer, carefully label them; unlabeled PROM devices look alike. Place

the first programmed PROM device in socket U41 and

the

second programmed PROM

device in socket U40 of an iSBC

286/ 10(A) board.

You can program the third and

fourth PROM devices

with

no intermediate

steps also.

Begrn by inserting the third PROM device into the active socket and enter the following

command:

PPS>copy :fl ;ronsys,odd(O, 0FFFFII)

CHECKSUM-vaIue

to pron <CR>

Aîter the

CHECKSUM

=value

message appears, remove the third PROM

device, insert

the fourth PROM device, and enter the following

command:

ICU

Usefs

Guide c-19

PROGRAMMING

A 2tt6.BASED SYSTEM

INTO PROM DEVICES

PPS>copy :fL:ronsys.odd(10000H,0IFFFFH) to bìlffet <CR>

CHECKSUM-value

You now need to modifu the

odd bytes of the Reset

Vector

jump

address. Use the iPPS

SUBSTITUTE command

to chanse the odd bytes

of the Reset Vector in the buffer

fbllows:

00FFF8: EA 00 C0 FF

FF FF FF FF

00FFF8: 12 00 FF FF FF

FF FF FF

After changing the

values,

copy

the

bufler

to a temporary file by entering the following

command:

copy buffer to : f1: tenp

Now, copy the temporary file to the PROM devices by entering the following

command:

PPS>copy :fl;tenp to prom

CHECKSUM:value <cR>

Afier the CHECKSUM=value message appears on the screen, remove the fourth PROM

device. The third and

fourth PROM devices now contain the odd

(or

high) bytes of the

WORD values

that compose the operating system.

you

remove the PROM devices

from the programmer!

carefully label them; unlabeled PROM devices look alike.

Place

the third programmed PROM

device in socket U76 and the fourth programmed

PROM

device in

socket

U75

of an iSBC 286/ l0(A) board.

The iPPs

SUBSTITUTE commands above provide

a FAR JUMP instruction to the ROM

ìnitialization procedure whose

address is specified

in the ICU as

0FC0000H. The offset

of the beginning instruction

of this

procedure

is l2H. The

reason

0C000: l2 is used

instead of

0FC000:12 is that, in real adclress

mode, the 80286 can only access up to 1

megabyte of

memory. Also, in real address

mode, the memory decoding of the

286/10(A) board,

when

jumpered

for 27512 EPROM devices, places

the memory

addresses of the PROM devices

at 0C000:0 to 0FFFF:F. This addressing scheme results

in execution of the code

at 0C000:12 to occur first.

The code at 0C000: 12 is the first

instruction of the ROM

initialization code.

c-20 ICU

Use/s Guide

PROGRAMMING A 286-BASED SYSTEM

INTO PROM DEVTCES

C.4.2.3 Starting

the

Operating System in ROM

The four PROM devices

now contain the operating system and the altered Reset Vector

jump

address. Perform

the following steps to start the system:

1. Place the first programmed PROM device in socket U41 of the iSBC 286/10(4.)

board.

Place

the second programmed

PROM device in socket U40 of the iSBC 286/10(A)

board.

Place the third

programmed

PROM device in socket U76 of the iSBC 286/10(A)

board.

Place the fourth programmed

PROM device in

socket U75 of the iSBC 28ó/10(A)

board.

Insert the iSBC 2U6/10(A) board into the system chassis and apply power to the

hardware. The iRMX ll system is immediately initialized and

sign on occurs using

the terminal(s) specified in :CONFIG:TERMINALS on the system

device.

C.4 HARDWARE

JUMPER

MODIFICATIONS

program

the system into PROM devices as in the above example, the following

jumpers

were changed on the

iSBC 2tl6/10(A)

board:

To specifu 4 27512 EPROM devices, set upjumpers 62 through 9l as follows;

Default Configuration

E62

- E63

870

- E72

E71

873

F.75

E76

Lt I

r:tó

E85

E87

886

888

E90

E91

Jumpers

to Set for 27512 EPROMS

E65

- 867

E68

- E70

E71

- E73

875

876

E80

882

E83

E85

E86

E88

E90

E91

To specify a starting memory address and memory size

for local memory, use

primary

decode

option 3. Thejumpers

required

are

Default Configuration

E2l8 - E2l9 installed

8220

- E221 removed

Jumoers for Primary

Decode Option 3

EZIS

- E219 installed

8220

- E22l installed

ICU

Uset's Guide c-21

PROGRAMMING A 286-BASED

SYSTEM

INTO PROM DEVICES

specify

memory/size/justification for local memory, use secondary option 3. The

jumpers

required are

Default Configuration

E5t - 859 removed

E50

- 858 removed

E49

- E57 installed

Jumpers

for Secondary

Option 3

851

- E59 removed

E50

- E58 installed

E49

- 857 installed

c-22 ICU UsePs Guide

APPENDIX D

PROGRAMMTNG

A 386/1 oo-BASED

SYSTEM INTO PROM DEVICES

D.l INTRODUCTION

This appendix

provides an

example of the

procedures used to place the iRMX II

Operating System into ROM for a 386/ 100-based system. All software

generation

described assumes you are using an Intel System 300 Series Microcomputer. In addition,

because

a Series-IV

Development System

required to run the PROM

programmer, the

iSDM monitor is

used

provide the serial link between the iRMX system and the Series-

IV system. In

this example,

one

version of the operating system is created.

The example consists of three

processes:

configuring

a ROM-based system,

generation/building of the system, and actually placing the system

into ROM. In this

example, the iSDM monitor and

Bootstrap Loader are not included

as part of the

generated system. This allows the operating

system to be 32 Kbytes larger. For

a system

generated in this manner, the operating system receives control

on power-on or reset.

The last section of this appendir describes the

configuration differences

existing when

programming a 386/ 100-based system and a 386/20-based

system into PROM

devices.

D.2 REQUIREMENTS

use the procedures outlined in this appendir, you must

have the following hardware

and software:

. A system defined during configuration

as residing in RoM.

. The iRMX II.3 and iPPS

Vl.4 (or

newer)

software.

]'he iPPS

software runs on an

Series-IV Development System.

. A 386/100-based system and a Series-lV

Development System

connected

via

the

iSDM monitor.

r An iUP-200/201

Universal Programmer

with

a'GUPI 27010'module.

o Two 27010 EPROM devrces.

ICU

Usefs

Guide D-l

PROGRAMMING

A 3E6/1OO.BASED SYSTEM

INTO PROM DEVICES

D.3

CONFIGURING

A ROM.BASED

SYSTEM

Before you can program your system into ROM, you must modi$ a number of

parameters

in your definition file. These examples assume that you start with the Intel-

supplied definition

file 386100.DEF located in directory

/RMX286/ICU.

To begin

the example,

you

should make a copy ofthe definition file in a separate

directory. To do this, create a new directory

in which

to do the generation.

Give the

directory

the same name as the definition file and the

output system. The definition file

should have a .DEF extension,

the boot-loadable system should

have a.28ó extension and

the system

to be loaded into PROM devices should

have a . ROM extension. Entering the

three following commands

creates a new directory

called ROMSYS, attaches

you

to that

directory,

and invokes

the ICU placing

a copy ofthe definition file 386100.DEF into the

new

directory. (This

example assumes

your :HOME: directory

your

current default

directorv.l

As part of the

configuration process, you

must perform the

following two things

in order

to fit the

iRMX II system

developed in this example

into PROM

devices.

. Delete

the System Debugger

and UDI from the

system.

. Replace the iRMX IL3 CLI with the

iRMX II.1 CLI.

Having

invoked the ICU, you

now can begin to make the necessary

configuration

changes.

Start by

modifying the

memory screens to define the ROM memory locations

the system

requires. Do this by

first selecting the "Memory

for System"

screen with the following

command:

D-2 ICU Usefs Guide

PROGRAMMING A 386/IOO-BASED SYSTEM

INTO PROM DEVICES

Entering the

command causes the

"memory

for System"

screen to appear as

follows:

(tfEMS) Henory for System

SYS

- low I0-OFFFFFFH],

high IO-0FFFFFFH]

lr] sYs = 010000H, 059FFFH

[2 ] sYs

Enter Changes fNumber - new_va]-ue / ^D Nr,nber / ? / H ) |

At this screen,

you

must configure the amount

of memory required for the

generated

system.

When

a 386-based system is

initialized, it moves

from ROM to RAM and then

begins execution. The area in RAM where

it resides

is the lowest block of memory

specified in the

"Memory

for System" screen. Thus,

you

must

speciry the lowest block

memory

with enough

space to fit the system. At this

point,

because

you

do not know the

exact size needed,

you would

normally supply a guessed

value

to replace

06FFFEH.

Then, after the real system is

generated, you

could

determine the actual

size using

information

given

in the.MP2 file created at

generation time. For

this example, however,

the amount of memory needed is known beforehand

as 10000H to 4FF00H.

Configure

the memory needed for the system using the

following two commands.

These

commands delete

the default

information

and add the new information.

ICU

Use/s Guide D-3

PROGRAMMING A 386/IOO.BASED SYSTEM INTO PROM DEVICES

After entering the memory

locations, the

"Memory

for System" screen appears as follows:

(MElfS) llenory for Systen

SYS

- low |0-OFFFFFFIII

, high |0-OFFFFFFHI

[1] SYS - 010000H, 4FF00H

[2] sYS

Enter Changes [Ntrrrber - new_value / ^D Nurnber / ? / H ) :

<Cn>

Now,

display the

"Memory

for Free Space

Manager" screen by entering'<CR>",

shown in

the

screen.

Because a ROM-based system

uses different

memory

locations than a RAM-based

system, you

must adjust this memory

screen. The memory

for the Free Space

Manager must

not overlay system memory

or the

writeable

data

segments, which

reside

just above

system memory. To ensure

that you speci! the correct

starting

address

for the Free Space

Manager memory, perform

the following

steps:

1. Calculate the sum

of the read/write

segment iimits found

in the .MP2 file.

2. Find the segment

with

the largest end

address.

3. Add together the

result of step

one and the address

found in step

two.

4. Use the result

of step three

for the minimum

start address

for the Free space

manager.

After determining

the start address

for the

Free Space

Manager, make

the changes by

entering

in commands

similar to the ones you

entered

to change

the',Memory

for System,'

screen.

The only difference

is use

memory locations

65000H

to TFFFFFH.

The following

screen shows

the "Memory

for Free

Space Manager"

screen

after making

changes.

(MEl{f) Menory For Free Spacè Manager

FSl,l

: lor.r [0-oFFFFFFH] , high [0-0FFFFFH]

[1] rsM : 6s000H, TFFFFFH

[2] FsM

Enter Changes [Nurnber

- new_value / ^D Number / ? / H] :

;f sub <CR>

D-4 ICU

Usefs Guide

PROGRAMMING

386/I()O-BASED

SYSTEM

INTO PROM

DEVICES

After making

changes to the memory screens, request the

"Sub-systems" screen using

the

command

"f sub

" shown in the

orevious

screen.

(SUB) Sub

systems

(UDI) Universal Development Interface IYes/No] YES

(HI) Hurnan Interface [Yes/No] REQ

(AL) Application Loader [Yes/No] REQ

(RFA) Rèmote Filè Accèss [Yes/No] NO

(EIO) Extended I/O Sysrern [Yes/No] REQ

(BI0) Basic l/O Systen [Yes/No] REQ

(SDB) Sysren Debugger [YeslNo] YES

(OE) 0S Excension [Yes/No] NO

Enter lAbbreviation: ner.r-value

/ Abbreviation ? / H ] :

: s

db-n <CR>

: udl:n <CR>

, 11_y <CR>

: f hl <CR>

Here, you must delete the System Debugger

and the UDI because

of size considerations.

You also select the Human

Interface for your

system

by setting ans\trering

yes to "hi". The

last command

above requests the

"Human

Interface"

screen

Change the resident initial

program (CLI) versions by entering

the following command:

Both the iRMX tl.3 CLI and the iRMX II.2 CLI are considerably larger

than the iRMX

II.1 CLI and

cannot be used in this example due to size

restrictions.

Next, request the

"Nucleus"

screen

by entering the following

command:

You now

must define the numtrer of Global

Descriptor Tables

(GDT) entries

your ROM-

based system

needs. Because ROM space is limited,

the number

you enter should

be the

minimum number of entries needed. The number

of real GDT entries required

when

the

system is copied and

expanded in RAM is entered on the

"ROM Code" screen.

You also must

change the Default Exception Handler

parameter to something

other than

SDB since the SDB

was

nreviouslv

deleted from

the confisuration.

ICU Usef s Guide D-5

PROGRAMMING A 386/IOO.BASED SYSTEM

INTO PROM I)EVICES

Enter

the

followins

commands to make the necessarv chances to the

"Nucleus Screen":

After making these

changes,

the "Nucleus Screen" appears as follows:

After updating

the "Nucleus"

screen, enter the

the following command

view

the "ROM

Code" screen:

(Mrc) Nuc leus

(NGE)

Nunbér of cDT Entries l4zr0 - 81901

(NIE) Nurnber of IDT Entries [0-256]

(PV) Paranèter Validation IYes/No ]

(RoD)

Root object Directory Size l0 38401

(DEH)

Default Exception Handler IYesrî.lolJob/SDB/Use

r ]

(NflI) NMI Exception Handler IYes/No/I gnore/J ob/SDM/User

]

(NEB)

NMI Enable Byte l0-2551

(STK) Exception Handler for Stack Exception, Bad TSS and

Double Fault IYe

s/No/Job/SDB

]

(NEH)

Name of Ex Handler Object Module [1-55chs]

(EM) Exeeption Mode lNever/Prograrn/Envi. ron/Al1 l

(LSE) Low GDT/LDî

Slot Excluded from FSM

1440-8189H/None:01

(HSE)

High CDT/LDT Slot Excluded frorn FSM

[440-8189/None-0]

(RRP)

Round

Robin Priority Threshold [0-255J

(RRT)

Round

Robin Time Quota [0-255]

(RIE) Report lnitíalization Errors lYes/Nol

(MCE)

Maxirnun Data Chain Elernents [0-FFFFH]

(CS

) Nucleus Communication

Service

Enter [Abbreviatíon: new_value / Abbreviatioa ? / H ] :

460

r28

REQ

JOB

IGNORE

JOB

NEVER

255

YES

080H

YES

D-6 ICU User's

Guide

PROGRA]\,IMING A

38ó/1OO-BASED

SYSTEM

INTO PROM DEVICES

The

rom <CR>" command causes the

"ROM

Code" screen to appear as follows:

(ROM) ROM

code

(SYR) Systern in ROM

[Yes/No] N0

(RAC)

ROM Address of Mastèr-cDT [0-OFFFFF!!] 0H

(NSG)

Number Slots in Real GDT

[440-8190] L024

(RAS)

RAM Start Address for Systern

IO-OFFFFFH] 0H

(RIA) ROM InitialÍzation Code Address [0-0FFFFFFH] 0FF0000H

(RIP) ROM lnitializatíon Procedure

[1 - 45 chars]

Enter [Abbreviation : new_value

/ Abbreviation ? /H):

Use the followinq

command to inform the ICU that

vour system is to reside in ROM:

I'he RAG field

provides the 2.1-bit physical a<ldress of the master

Global Descriptor Table

(GDT) as it is to be burned into ROM. For a 386/100-based

system, RAG also indicates

the starting address of ROM code and data that is copied

into RAM. For this

reason, you

should locate the GDT at

the start of ROM. ln this example,

are

using 27010 EPROM

devices so

you

should set the RAG field to 0FC0000H

using the following command:

The RAS field

gives

the starting address

where

the nucleus initialization

code is to begin

copying

writeable segments of

the

system into RAM. Consequently,

you must ensure that

the

writeable

blocks do not overlay system memory

specified in thc MEMS screen

or the

memory managed by

the

free

space

manager

specified in the MEMF screen. In this

example, the

system is copìed to RAM starting at address 010000H

to approximately

04FF00H. Thus to

place

the

writeable

segments

above the executable

code, assign RAS

to 04FF00H using the following command:

The RIA determines the 2,1 bit address of the nucleus

initialization

code. This address

must be located in

the first megabyte of RAM. Normally,

you would assign RIA to 0

when

you

build

the system the first time. After the system

buiìd,

you

could

then examine

the .MP2 file and see

where

the builder located

the initialization

code. Having obtained

the address

the builder used,

you would

then Assign

the base address

to RIA and

generate

the system again. By

relying on the builder to locate RIA,

memory fragmentation

minimized. Note, a

system generated with zero

(0)

assigned

to RIA does

not work. For

this example, however, assign 0l3A30H

to RIA using the

following command:

ICU

User's Guide D-7

PROGRAMMING

386/IOO.BASED

SYSTEM INTO

PROM DEVICES

Enter

a carriage return

<CR> and verify that the

"ROM Code"

screen appears as

follows:

(ROl'f

) ROM code

(SYR) Systen in ROM

(Yes,rNol YES

(RAC)

ROM Address of Master-CDT IO-0FFFFFFH] FC0000H

(NSG)

Nurnber

Slots in Real cDT [440-8190] LO24

(RAS) RAl{ Start Address for Sysien [0-0FFFFI1i] 4FF00H

(RIA) ROM Initializacion Code Address I0-oFFFFFFH] 0l3A30H

(RlP) ROM lnitialízation Procedure [1 - 45 chars]

Enter [Abbrevíation: new_va1ue

/ Abbrevlation ? / H l:

Now, request the "Generate File Names" screen by entering the following command:

Entering

the above command causes the "Generate File Names" screen to appear as

below:

(GEN) cenerate Flle Names

File Narne

[1-55 Characters]

(ROF) ROM Code Flle Narne

/Boor/Rro(286

. Rou

(RAF) RAM Code File Nane

/ROOî/386100.286

Enter [Abbreviation - new_value ,/ Abbreviation ? / H ]:

The "Generate

File Names" screen is where you

define the pathname

of the file

containing the

ROM-based system. Specify

the pathname by

entering the following

command:

D-8 ICU UseCs Guide

PROGRAMMING A

3Iì6/TM-BASED

SYSTEM

INTO PROM DEVICES

After making the change, the screen looks as follows:

(GEN) Generate File Narnes

Fíle Narne

[1-55 Characters]

(ROF)

ROM Code FiLe Name :$:Rol,tSYS.RoM

(RAF) RAI'! Code File Name

/Roo"t/386100

.286

Enter [Abbreviatíon: new_value / Abbreviacion ? / H ] :c <CR>

D.4

GENERATING/BUILDING

THE

SYSTEM

You are now ready

to generate

the definition files and build

the system. Entering a'C" as

the last step in the

previous section

causes the ICU main

screen to appear. From this

screen, enter the Generate

(G)

command to generate files.

For general help in any screen

The following commands are

Change

Generate

Save

Qul

Exi t

Replace

Detail-Level

Backup

ENTER CoMMAND :G <CR>

ENTER

a Ìetter to be used

enter H <CR>.

avallable

as preflx :(CR)

After enterìng "G <CR>", the ICU asks

you to enter a single letter

to be used as a

prefix

to the

generated

file

names.

Entering

a carriage reîurn causes

no prefix to be used.

After

responding

to the

prefix prompt,

the ICU informs

you of each layer as it is

generated (see

Figure B-35 for an example).

When the system has been

generated, the ICU returns

the main menu

scrce n.

ICU

User's

Guide D-9

PROGRAMMING A 386/1OO.BASED SYSTEM

INTO PROM DEVICES

Enter the Exit

(E)

command to

write

the definition file and exit the ICU as follows:

After entering this command, the ICU informs you that the definition

file has been

written. It issues the following message before returning control to the command line:

The deflnltlon flle has been wrltten to flle; ROI,ISYS.DEF

You are now ready to invoke the SUBMIT

file ROMSYS.CSD that builds the system.

The ICU created this SUBMIT file as

part

of the

generation process.

Execution

the

SUBMIT file

generates

the application

system

with

the

pathname

:$:ROMSYS.ROM.

Execution of this

SUBMIT file also

generates

the map file ROMSYS.MP2, which

contains

information

crucial to configuring a "tight" system. The

map file ROMSYS.MP2 also

contains the following

warnings

which you can

safely ignore:

*** IIAIINING 269: LINE 22, NEAR CLI DATA: Sesnent Size Reduced

LIARNING 119:

LOW ADDRESS

HIGH ADDRESS

SEGMENTS

OVERI^AP

FFT'FAOH

FFFFF2H

After

the submit file

completes execution, use

the DOWNCOPY

command to copy the

resulting

file ROMSYS.ROM to the

file :F1:ROMSYS.ROM

on the hard disk of the

Series-IV

Development

System. This assumes you

have used the

LNAME command on

the

Series-IV system

to define the logical name

:Fi for the directory

into

which you

will

copy the

file.

Now that the

system has been generated,

you must program

the PROM

devices to include

the

stand-alone system.

D.5 PROGRAMMING

THE

SYSTEM

INTO

PROM DEVICES

This

section explains

how to

pro$am

the operating

system into PROM

devices. To

create a PROM-based

iRMX II system which receives

control at power-on, you

need

take

certain steps.

Before the following

section describes

these steps, you

should be made

aware

of the following:

. Most PROM-based

systems

are already "debugged"

and have

no need of the

iSDM

monitor

or the iRMX II System Debugger (SDB).

D-IO ICU

User's Guide

PROGR.ÀMMING

A 38ó/TOO-BASED

SYSTEM

INTO PROM DEVICES

. The iSDM monitor

has limited use

in a PROM-based system because

it can't set

breakpoints in

code that executes

from ROM.

. The ROM initialization

code of the

iRMX II Nucleus currently

has no means of fully

initializing

the iSDM monitor.

Initialization

code can only inform the

iSDM monitor

(if it is present

and has been

previously initialized)

rhat the 80286 CPU has been

switched

to Protected Mode.

o Virtually all PROM-based iRMX II systems

require that the system be initialized

immediately

upon Power

Up.

For these

reasons, a standalone

PROM-based

iRMX lI Operating System has no reason

include the iSDM monitor,

the Bootstrap

Loader, or the SDB. With this in

mind,

the

following sections explain

how to program

such a system into PROM devices.

ICU

Usefs Guide D-I1

PROGRAMMING

386/IOO-IìASED

SYSTEM

INTO

PROM DEVICES

D.5.1 Formatting

the Operating System

PROM

File

lnvoke

the iPPS software

and issue the folÌowing

commands

(user

input

is in bold)

prepare

the four PROM

image files. The

parameters

parenthesis on the

FORMAT

line tell the IPPS

software

what

memory

range of code

you wish to program into

PROM

devices.

. IPPS <CR>

INTEL PROM

PROGRAI"IMING SOFTWARE,

Vx.y

years

PPS>type 27010 <CR>

PPs>lnltiallze 286 <cR>

PPs>fornat : fl :

ronsys

. ron (010000h, 04ff00h) <cR>

LOGICAL UNIT (BIT:1,NIBBLE:2,

BYTE:3,N_B\"IE:4)

LU -3 <CR>

INPUT BLOCK SIZE (N BYTES)

N *2 <CR>

OUTPUT BLOCK SIZE (N BYTES)

N :l <cR>

INPUT BLOCK STRUCTURE.

N'IÌHBER OF INPUT I,OC]CAI,

UN1TS: OO2

LSB

loo lol l

NUMBER OF OUTPUT

LOGICAL

UNITS : OO1

OUTPUT

SPECIFICATION

(<CR>

TO EXIT):

*0 to :fl: romsys. evn <CR>

OUTPUT STORED

*l- to : fl: ronsys. odd <cR>

OUTPUT

STORED

* <cR>

PPS>

D-12 ICU

Use/s Guide

PROGRAMMING

386/TOO-BASED SYSTEM

INTO PROM DEVICES

D.5.2 Formatting

the Copy Routine

This step involves formatting

the copy routine that actually

executes

in ROM. Enter the

following

commands shown in bold text

perform

this task:

PPs>fornat : f I : romsys. ron(0ffffaoh)

LOG]CAL

UN]T (

BIT:1 ,

NIBBLE-2

BYTE-3

N-BYTE:4

)

LU -3 <CR>

INPUT

BLOCK

SIZE (N BYTES)

N :2 <CR>

OUTPUT BLOCK SIZE (N BYTES)

N -1 <CR>

ouTPùT SPECÌFICATIoN

(<CR>

TO EXIî):

*0 to :fl: copyron.evn <cR>

OUTPUT STORED

*1 to :

fl: copyron. odd <CR>

* <cR>

D.5.3

Copying

the

Operating System and the Copy

Routing to

ROM

To copy the

system

and the

copy routine to ROM,

you

must copy even and odd bytes of

the system and the copy routine using the PPS copy command. First insert a PROM

device and use the PPS copy command to burn the even bytes of the system and the copy

routine into the PROM devices:

PPS> copy romsys.evn to PROU

CHECKSUM

_ VALUE

PPS> copy copyron. evn to PROU(lffdOh)

CHECKSUM

_ VALUE

ICU Uset's Guide D.I]

PROGRAMMING A 3116/I(n.BASED SYSTEM

INTO PROM DEYICES

Now

you

must burn in the odd bytes of the system and the copy routine.

Insert the

remainins PROM device and issue the folìowins two commands:

PPS> copy ronsys.odd to PRoX

CHECKSUM

' VALUE

PPS> copy copyrou, odd ro PRolr(l,ffd0h)

CHECKSUM

- VALUE

Notice that the copy

command for the copy routine is entered in the following form:

copy copyrom.)oo( to PROM(offset)

The value offset causes

the copy routine to be

physically placed

away from the system. To

determine the value

for offset use the following formula:

offset

= (start_address_of_copy_routine

- PROM_start_address)

/ 2

For this

example, offset is calculated as

follows:

offset

= (FFFFAOH

- FC0000H)

/ 2 = IFFD0H

D.6 BOOTING

THE

SYSTEM

After placing

the system into

PROM devices, you can boot the

system. In this example,

the system

included the

Human Interface subsystem. Consequently,

the system must also

include a system

device

(hard

disk drive

or llexible diskette drive).

If your

system does

not

include the Human

Interface, the system

does not have to include

a system device.

For systems that

include a system

device, you must perform

a system reset after initially

supplying power

to the system.

The reason for performing

a reset after power-up

because

the system

device needs time to reach

maximum spinning

speed before the

Human Interface

can successfullv

access files on the device.

D-14 ICU Use/s Guide

PROGRAMMTNG

A 38ó/lOO-BASED SYSTEM

INTO PROM DE!'ICES

D.7

CONSIDERATTONS FOR A

386/20-BASED

SYSTEM

If the system

you

are building is going

to run on a 38ó/20-based machine,

some

configuration differences exist.

The following list summarizes these differences:

. Because ROM is mapped to the lower megabyte of memory

when

the system is in real

mode,

you

must supply a different ROM address for the master Global Descriptor

Table in the

"ROM Code" screen. Assuming

your

system uses 27010 EPROM devices,

supply a

value

of 0C0000H for the RAG field in the

"ROM Code" screen during

configuration. This

value

causes the GDT to be

placed

at the start of ROM.

o You must configure the Initialize

On-board Functions

(IF) field in the "Hardware"

screen to 3 rather than 4. The

value

3 indicates the

board beins initialized is an iSBC

386/20

board.

ICU Uset's Guide D-r5

INDEX

Abbreviated screen

names l- 1o

Aborting ICU commands

l-24

Access rights to definition

files 1-7

Adding a RAM driver B-21

Adding an Intel-device driver B-15

Adding an Intel-supplied controller 8-6

Adding new device drivers

1-45,

46, 47

Adding

unit information B-10, 18

Adding users to your

system 4-l

Application code 3- I

Application

jobs 3-l

ASCII

backup files 1-23

Assembling configuration

files 2-4, B-34, D- 10

Backup

command l-23

Binding application

jobs 3-4, 7

Binding the subsystems 2-4,8-34. C-8, D-10

BND286 3-4

Bootstrap loading a system B-4[]

Bootstrap Loader inclusion C-v

Build files 1- 18

Building application

jobs 3-4, 7

Building the system 2-5, B-34, C-8, D- 10

Change

command 1-16, 25, B-41, C-2, D-2

Changing definition files l-17,

Changing the editing control

character 1-21

Changing system memory

B-29, C-2, D-2

Choosing a definition file 1-7

Code segment

size 3-8

Command mode 1- 14

ICIJ

Usefs

Guide Index-l

INDEX

Commands

Backup 1-23

Change 1- 16, B-41, C-2, D-2

Detail-level l-22

Exit l-27,2-1,B-34

Generate 1-18,2-1, B-32,44, C-8, D-9

Help 1- 15

List 1-19,2-l,B-44

Quit 1-20

Replace

1-21

Save 1-19,2-1

Communication board

3-3

Configuration

Environments 1-4

Files 2-2,

3, A-l

Generating fiìes 2-1

Configuring users into your system 4-l

Control-C

1-24

Conventions

Copy routine D-13

Copying the

current screen 1-33,34

Creating build and submit

files 1- 18

Creating directories for your systems

1- 10, C-2, D-2

Creating systems

that activate on power-up

C- 16

Data segnent

size 3-8

Debugging

application

jobs 5-6

Definition file 1-1,7,

B-1, C-8, D-10

Deleting

a repetitive-fixed

screen 1-38

Deleting

a screen 1-33,

Deleting

an element 1-33,34,

Deleting

data on a repetitive screen format 1-35

Determining memory

locations 3-3, 6

Displaying

the next screen 1-33, 34

Displaying

the previous

screen 1-33

Editing

a screen

1-29, 32,8-6,7

Editing

control character

1-21

Editing

definition files 1-17, 25

Elements

of a screen 1-26

Eliminating excess

space 3-6, B-41

Index-2 ICU

Uset's Guide

Ending an ICU session

1-20, 21

Errors

Assembling the configuration

files 2-6

Binding

the system 2-6

Building the system

2-6

ICUMRG I-49

Insufficient access rights

for the definition file 1-8

Interactive 1-42

Internal 1-43

Invocation 1-12

System initialization 5-3

Type of 1-42

Examples

Adding a RAM driver B-21

Adding an Intel-device driver

B-15

Adding

an Intel-supplied controller

B-6

Adding unit information

B-10, 18

Assembling configuration

files B-34

Binding the subsystems

B-34

Bootloading a system B-40

Building the system

B-34

Changing system

memory B-29,

C-2,D-2

Configuration C-2,

D-2

Deleting a

repetitive fixed screen

1-38

Deleting data on a

repetitive screen format 1-3ó

Deleting the System Debugger

from the system C-4, D-5

Deleting the UDI from the system

D-5

Editing a screen 8-6, 7

Formatting the copy

routine D-13

Formatting the operating system

PROM file C-11, 17, D-12

Generate 2-2, B-32,44,

C-8, D-9

ICUMRG 1.48

Inserting a repetitive-fixed

screen

1-42

Inserting data on a repetitive

screen format 1-37

Invoking the ICU 1-9, 10,

B-4

List command B-44

Loading a system into

RAM B-40

Memory adjustments

to include the Bootstrap Loader C-3

Memory adjustments

to include the iSDM" monitor C-3

Memory

for Free Space Manager Adjustments C-4, D-4

Memory map for 80286-based

system A-3, B-28

Programming a 286-based system

into PROM devices C-1

Programming a 386/100-based system into PROM devices D-l

INDEX

ICU

Use/s Guide Index-3

INDEX

Examples

(cont.)

Programming a 386/20-based

system into PROM devices D-15

Programming

PROM devices C-10, D-10

Programming

the Bootstrap Loader

into PROM devices C-14

Programming the iSDM" monitor into PROM devices

C-13

Programming the

operating system into PROM

devices C-12, lu, D-13

Removing

device drivers C-5

Starting the operating system in ROM C-21

Starting the operating system in ROM from

the iSDMa* monitor C-15

System configuration B-l

Exit command 7-25,2-1, B-34

File locations 1-2

File version numbers

1-12,44,46

Files of the ICU l-2, 5, 6, 2-3, A-1

Finding a screen 1-33, 34

Fixed screen formats

1-30

Formatting the copy

routine D- 13

Formatting the

operating

system

PROM file C-11, 17,D-12

Formats of screens 1-30

General ICU use 1-3

Generate command

1-18, 2-1,B-32,44, C-8, D-9

Generated files 2-3, A- 1

Generating

configuration fiìes 2-1, C-8, D-9

Generating the system

2-1, B-31

Getting

help l-15, 30, 33, 34

Hardware

requirements l-4

Hardware

screen 1-28

Help command

1- 15, 30

Help

for special editing commands

1-33, 34

How to choose

a definition

file l-7

I2ICE" In-Circuit Emulator

5-ó

ICU flowchart

1-39

ICUMRG Utiliry 1-45

Include

files 3-2

Index-4 ICU User's

Guide

Including

the Bootstrap

L,oader C-9

Including the iSDM" monitor C-9

Initialization routine

3-8

Initializing your

system

5-1

Inserting a new line 1-33,34,37

Inserting a

new screen 7-33,34,42

Inserting

a repetitive-fixed screen 1-42

Inserting

data on a repetitive screen

format 1-37

Intel-supplied definition files 1-7

Interactive errors 1-42

Interface libraries 3-5

Internal errors 1-43

Invocation errors 1-12

Invoking the ICU 1-9,

10, 11, B-4

ISDM* monitor

inclusion C-9

Language requirements when

writing application

cocle 3-2

Level of detail for screens

1-22

List command 1-19,2-1,

B-44

Listing

a definition file 1-19

I-oading

the system into RAM 5-1, B-40

Location of ICU files 1-2

l-og-file 1-45

l,ogical

flow of the ICU 1-39

Main menu screen 1-14,

B-5

Manual overview iii

Memory locations 3-3, 6,

B-29

Minimizing memory address size

3-6, B-41

Naming ICU-generated files l-1I

Non-resident

users 4-1

Parts

a screen 1-26

Pre-configuration requirements 1-4

Prefix option 1-11,2-3

Preparing a RAM-based system 3- 1

Preparing application code 3-l

INDEX

ICU Uset's Guide lndex-5

INDEX

Product overview 1- 1

Programming PROM devices

C-1, 10, D-10

Programming the Bootstrap

I-oader into PROM devices C-14

Programming the iSDM" monitor

into PROM devices C-13

Programming the

operating system into PROM devices C-18, 12, D-13

Quit

command 1-20

RAM disk driver 3-3

RAM-based systems 3-1

Reader level iii

Redisplaying the current screen 1-33,34

Repetitive

screen formats 1- 30

Repetitive-fixed screen formats 1-31

Replace command

1-21

Resident user 4-1

Restoring from af e 113,23,44

Returning to command mode 1-33, C-7,

D-9

ROM-based systems

3-7, C-1, D-1

Save

command l-19, 25,

2-1

Saving an

edited definition file 1-19, 21, 25

Screen editing 1-29

Screen editing

commands 1-32, 33

Screen

elements l-26

Screen formats 1-30

Screen names 1- 18

Searching

for a string

within

a screen

1-33, 35

Soft-Scope 2860 5-5

Software requirements

1-4

Special

editing commands

1-33

Start address of a system

3-8

Starting the

operating system in ROM C-21

Starting

the operating system

in ROM from the iSDM" monitor C- 15

Submit files 1-18,2-2,4,B-34,46,

C-8, D-10

Synchronous

initialization 5-2

System debugger

5-5

Index-6 ICU User's Guide

Testing

the system

5-1, 4

Unit information,

adding

B-10, 18

UPDEF

Utiliry

l-1,7,44

Upgrading

definition

files 1-43

Using

the ICU 1-3, 39

Version

numbers, files 1-12,44,46

When

to use the

ICU 1-2

Writing

Application

code

3- 1

INDEX

ICU

UsePs Guide Index-7

intel

EXTENDED

iRMX@II

PROGRAM

MtNG

TECHNTQU

REFERENCE

MANUAL

lnte Corporation

306 5 Bowers Aven

u e

5anta Clara, Californ a 95051

CopyrLght

I 1988, Intel

Corporat on,

A Rrghts Reserved

PREFACE

INTRODUCTION

This manual summarizes

techniques

that will be useful to you as you produce

applìcation system

based on the Extended iRMX II Operating

System. A typical

development process goes

through these

stages:

. Dividing the application

into

jobs

and

tasks

o Writing the code for tasks

r Writing

interrupt handlers

. Configuring

and starting up the

system

. Debugging

an application

Use this manual

as a reference guide when

developing your application system.

The

techniques

described here will

help you save time and

avoid

problems

during the

development process.

Information has been

added to this manual

to reilect changes in the use of external

declaration INCLUDE files. Use of individual

files, hints for efficiency, and tables of the

Nucleus,

Basic I/O System, Extended

l/O System, Human Interface,

Application Loader,

and Universal Development

Interface system

calls

with

their corresponding

external

declaration

file names appear in

Chapter 2.

READER

LEVEL

This manual assumes

that you are

familiar with the following:

o the

PL/M-286 programming

language

. PL/M-286 segmentation

models

. iRMX II jobs,

tasks, mailboxes, physical

files or named files, stream files, type

managers and composite

objects, system calls, and segments

. the

System Debugger

Programming Techniques l

PREf'ACE

. object

module

linking

o object libraries

. programming in the

iRMX II environment

using

PL/M-286

MANUAL OVERVIEW

This manual

is organized

in the lbllowing

manner:

Chapter 1 This chapter

provides information

on PL/M-286

segnentation

models.

Chapter

2 This

chapter describes

how to invoke iRMX II system calls

from

your source code.

Chapter 3 This

chapter describes how communication

occurs

between iRMX

jobs.

Chapter 4 This chapter

presents guidelines for stack

sizes.

Chapter 5 This chapter describes

how to convert iRMX I (IRMX 86)

applications to iRMX II applications. This

chapter also describes

how to improve the

performance of

your application.

Appendix A This appendir

lists and describes

sample iRMX II applications.

CONVENTIONS

The following conventions

are used throughout this manual:

. User input

appears in one of the following forms:

as bolded text irirh!n a screen

o The term

"iRMX II" refers

to the

Extended

iRMX II.3 Operating System.

r The term'iRMX I" refers to the iRMX I (iRMX 86) Operating System.

. All numbers, unless otherwise stated, are assumed to be decimal. Hexadecimal

numbers include the

"lI" radix character

(for

example,

0FFH).

tv Programming

Techniques

CONTENTS

CHAPTER

1PAGE

CHAPTER 2

USING

|RMXO II

SYSTEM CALLS PAGE

CHAPTER 3

COMMUNICATION

BETWEEN iRMX@

JOBS PAGE

CHAPTER

GUIDELINES

FOR STACK SIZES PAGE

Programming

Techniques

CONTENTS

CHAPTER

4 (continued) PAGE

APPENDIXA

EXAMPLE PROGRAMS PAGE

vl Programming Techniques

CONTENTS

APPENDIX

A (continued) PAGE

TABLES

TABLE

A-1

A-2

A-3

A-4

PAGE

iRMX@ II External Declaration

INCLUDE Files.....................

..........................2-5

Interface Libraries

and iRMXo II Layers................. ............2-11

Stack Requirements for Interrupts and System Ca11s.........-........-. ....-.-..-..-..-..-..4-4

Literal Files Helpful With Nucleus System CaIIs................................................A-5

Literal Files Helpful With

BIOS System Calls...............................................-....A-6

Literal Files Helpful With

EIOS System Calls....................................................A-6

Literal Files

Helpful

With

Human Interface System CaIÌs...............................A-6

Programming Techniques Ytl

CONTENTS

FIGURES

FIGURE

A-1

A-3

A-4

A-5

A-6

A-7

A-8

A-9

A-10

A-11

v|ll Pmgrarnming Techniques

CHAPTER

SELECTTNG

A PLIM-286

SEGMENTATION

If/IODEL

1.1 INTRODUCTION

Read this

chapter only if you will be programming iRMX II tasks using PL/M-286. You

should already be familiar

with the following concepts:

. The PL/M-286

programming

language

c PL/M-2t16

segmentation models

. iRMX II jobs,

tasks, and segments

When

you

invoke

the PLIM-286 compiler,

you

must specify

(either explicitly or by

default) the segmentation model

(SMALL,

COMPACT,

MEDIUM, or t-qRGE) that

your program will

use. The segmentation model

affects the amount

of memory required

to store

your

application's object

code and the perfbrmance of

the application.

With

operating

systems that run on lJ0[J6 processors

(or

til0286 and tì0386

processors n

real address

mode), choosing the appropriate segmentation

model is important for

reducing the amount of memory

that an application uses. Memory

use is important

because the 8086

processor

is limited

to I megabyte of memory address

space. The

operating system, on the other hand, uses

the 80286 and 80386 processors

in protected

virtual

address mode

(PVAM). ìn PVAM,

the processor can

access the full memory

address range that is

available. Thus, program size becomes less imporlant.

However, loading a segment register in PVAM takes longer than ìoading

other kinds of

instructions. If you

can minimize

the number of times the

processor must switch

segments,

application

performance will

improve. Because

the segmentation

model

determines how code and data are stored, choosing

the

proper

model

minimizes the

number of segment

switches, and increases

perlbrmance.

The following sections explain

which segmentation model

will attain the highest

performance,

while

still satisfying

system requirements.

Programming

Techniques l-l

SELECTING

A PL/M-286 SEGMENTATION

MODEL

1.2 WHAT ARE THE

SEGMENTATION

MODELS?

The four segrnentation

models supported by PL/M-286 are SMALL, COMPACT,

MEDIUM, and

[,ARGE. T\e PL/M-286 User's Guidc

for ikMX 286 Systems describes

each of these

models in detai.l. This

section

qives

a brief overview of each.

Code sections from all linked modules are

placed

in the same code

segment,

which

is addressed by CS. Data

and stack sections

are

placed in the same data segment, which

addressed

both

and SS.

Code sections from

all linked modules are olaced in the same code

segment,

which

is addressed by

CS.

Data

sections are

placed

into a

single data segnrent,

which

is addressed by DS. Likewise, stack

sections are placed

into a stack segment,

which

is addressed by SS.

The code section from each

compiled module is placed in its own

code segrnent, enabling the

total amount of code to be

more than

64K bytes. Data and stack

sections from all finked modules

are

placed

into a sing.le data segment, which

is addressed

by both DS

and SS.

During program

execution, the CS register

is updated whenever

PUBLIC or EXTERNAL procedure

is activated.

Code and data sections

from each compiled

module are placed

into

their own code and

data segments, enabling

the total amount of

code and data to be more

than 64K bytes.

Stack sections are

placed

into a sing.le stack segment, which

is addressed by SS.

In I-ARGE model,

code and data segments

are paired.

During

program

execution, both the

CS and DS are updated whenever

PUBLIC or EXTERNAL nrocedure

is activated.

SMALL

COMPACT

MEDIUM

TARGE

Specifying

the

ROM or RAM compiler controls

determines whether

the

constants

you

define in your prog'ams

are placed

in the code or data areas.

This

provides

additional

control on the size

of those segments.

1.3 RESTRICTIONS

The fewer

times

your application

must

load the segrnent

registers,

the better it performs.

To improve performance,

choose

the segmentation

model

that uses

the fewest segments

but still supports

the required

amount of

code or data.

This practice

means starting

with

the SMALL model and working

up to the TARGE

model,

using the first

model that can

handle the

amount of

code or data in your application.

However,

some models

place

restrictions

on iRMX II ooerations.

t-2 Pmgramming

Techniques

SELECTING A PLIM-286 SEGMENTATION

MODEL

1.3.1

Small

Model Restrictions

When you compile programs using the PL/M-286

SMALL control, all POINTER

values

are 16 bits long. This introduces some restrictions,

including

inability to address the

contents ofan iRMX II segment received from another

job. Because ofthese restrictions,

the only applications

that can use SMALL model are

those that invoke UDI system calls

only.

Applications

that invoke other iRMX II system calls cannot use the SMALL

seprnentation model.

1.3.2

Compact

Model Restrictions

You cannot compile exception handlers in the COMPACT model

and link them

with

other COMPACT prcrcedures,

because the operating

system always makes a far call to an

exception handler. To include exception handlers, compile

them using the l-A.RGE size

control.

1.3.3 Medium

Model Restrictions

When

using

PLIM-286 MEDIUM model, you lose the option

of having the Operating

System dynamically

allocate stacks

for

tasks that are created dynamically. Anticipate

each

task's stack requirements, and explicitly reserve memory for

each stack during

configuration.

1.3.4

Using

Large Model

There are no restrictions

with

the

PL/M-286 [-A.RGE model. If your application is too

large for the other models, or

you wish

to avoid restrictions,

use the I-ARGE

model.

1.4

CHOOSING

SEGMENTATION

MODEL

For best performance, use the following

guidelines

when choosing

a segmentation model:

. If your

code and data can each fit into a

64K-byte segment, use the COMPACT

model.

. If your

application is too large for COMPACT,

consider using COMPACT

subsystems. This

enables you to set up your application in

pieces (subsystems), each

which

adheres to the COM

PACT model. With COMPACT

subsystems, segment

registers are changed only

when you

call

procedures or access

variables that reside in

one

of the other subsystems. However, creating

COMPACT subsystems requires

technical knowledge than the

other alternatives and

it requires changes

to the

source code. Refer to the PL,/M-286

User's Guide

for |RMX 286Systems

for more

information.

Programming

Techniques l-3

SELECTING A PL/M-286 SEGMENTATTON

MODEL

. If you decide not to use COMPACT subsystems, MEDIUM offers the next

best

performance. MEDIUM, however, requires that all data

and stack fit into a

single

64K segment.

. If all else

fails,

use

l-ARGE

model. There are no size or iRMX II restrictions

with

I-ARGE, but

this

model results

in the largest number of segment register switches.

To determine

whether your

application can fit into the COMPACT model, try compiling

and binding it under the COMPACT model. If the application is too large for

COMPACT, BND286 will return an error message. At that point,

you

can decide

whether

to use MEDIUM, [-A,RGE,

or recode your application

for COMPACT

subsystems.

If your

application

will

be loaded into RAM,

you

may be able to use the ROM or RAM

controls to adjust segment sizes so that your application fits into the

COMPACT

MEDIUM models. These controls speciS where your program's

constants

will

reside.

For example, ifyour application's data is slightly larger than 64K

bytes, specifying

the

ROM control (which places

the constants in the code segment)

might alÌow the remaining

data to fit in a 64K segment.

This could make your code eligible for

the COMPACT or

MEDIUM models.

l-4 Programming Techniques

USING |RMX@ II CHAPTER 2

SYSTEM CALLS

2.1 INTRODUCTION

Read this chapter if you write programs

that use iRMX Il system calls. You should

already be familiar with the

foÌlowing concepts:

o System calls

. Object module linking

. Object libraries

. PL/M-286 segmentation

models

This chapter explains

how to include iRMX II system calls in

your programs,

and how

bind your code with

the necessary iRMX II libraries.

2.2 CODING

THE

SYSTEM CALLS

The first step in invoking

iRMX II system calls is

placing

source statements in your code.

The following sections

discuss how to place

system calls in your PL/M-286 and ASM286

source code.

2.2.1 Invoking

System Calls From PL/M-286

The iRMX II system call

reference manuals use the PL/M-286 syntax when listing the

iRMX II system calls. When writing

code, use the synt:rx listed in

the system call

reference

manuals.

2.2.2 lnvoking System

Calls

From Assembly Language

Programs communicate with the operating system calling inîerface

procedures

designed

for use with

programs

written in PL/M-286. To invoke system calls from assembly

language

programs,

the assembly language

programs

must obey the

procedure-calling

protocol used by PL/M-286. For example, ifyour ASM286 program uses the

SEND$MESSAGE system call, then

you

must call the rq$send$message

interface

procedure

from

your

assembly language code.

Pmgramming Techniques 2-l

USING iRMX@ II SYSTEM

CALLS

FROM I-ANGUAGES

The technique for calling

PL/M-286 procedures

from assembly language is

described in

the ASM28ó Macro Assembler

Operating Instructions

for \RMX 28ó Sysfems. This section

presents an overview of the technique.

In general, to call a PL/M-286 procedure, first push all the parameters onto the stack and

then call

the procedure. Push the parameters in the order they

are listed in the system

call reference

manuals; that is, starting with the leftmost

parameter.

Long

pointers

(complete

addresses

consisting of a selector and an offset) should be

pushed as two

words:

the selector first, then the offset.

The CALL instruction also

places the return address ofyour calling

procedure

onto the

stack.

This enables

control to return to your program after the system call completes.

Some system calls return

values.

In assembly language, the returned

values

are available

in registers,

as follows:

Type Register

BYTE AL

WORD AX

DWORD DX:AX

INTEGER AX

POINTER ES:BX

SELECTOR AX

When writing assembly language

routines that call PLIM-286 interface

procedures, you

must adhere to a segmentation model (COMPACT,

MEDIUM, or I,ARGE)

because

conventions for making

calls depend on the segmentation model.

Ifyour application

written entirely in assembly

language,

you

can arbitrariìy select an

interface

library

(COMPACT

or l-ARGE)

based on

whether

your application

makes near

or far calls. Size and performance

advantages can be gained

by using the COMPACT

interface procedures,

because their procedure

calls are all NEAR. The IARGE interface,

which

has procedures

that require FAR procedure

calls, is advantageous only ifyour

application code is larger than 64K b1tes.

However, if some

of your

application

code is written in PL/M-286, your assembly

language

code should use the same

interface

procedures

as those

used by

your

PL/M-286

code.

7-) Pmgramming

Techniques

USING

iRMX@

II SYSTEM

CALLS

FROM

LANCUAGES

The following

example shows

how to call iRMX II system calls from

assembly

language.

The examole

assumes that

the COMPACT seqmentation

model

is used.

DATA

segnent RW FUBLIC

seg_tok Dl1l ?

excèp Dl.l ?

DAÎA ENDS

coDE segnent ER PUBLIC

extrn rqc

reate s ègment : near

ny_prog PROC near

; Gec addressability to parameters

push bp

uìov bp, sp

;

; Save caller's DS

and obtain local DS

push ds

mov

ds, daÈa

Typical ASM

statemenEs

; seg_tok - rq$ create

segrnenc

(400H, @excep);

;

push 400H

push ds

push offset excep

call rqcreatesegment

uÌov seg_tok, ax

Pmgramming

Techniques t_1

USING iRMX@

II SYSTEM CALLS

I.'ROM I-ANGUAGES

; IF except o E$OK THEN

GOTO

cmp excep, 0

Typical ASM staLenents

rny_prog ENDP

CODE ENDS

END

error;

2.2.3

lnvoking

System

Calls From

Programs written

in c can

easily

directly access

iRMX II system

calls

by defining them

alien procedures.

For example,

the

following Iines

define

the CREATE$SEGMENT

and

DELETE$SEGMENT

system

calls

as alien procedures.

alien unslgnèd short rqcreatesegment (

)

alien rqdele tesegrnent

(

)

Ifyou invoke

system

calls from

you

must pass parameters

ofthe same

type expected

the system

cal.ls.

The

c compiler

does

no tlpe

checking

of arien

procedurei.

Raiher, it

assumes

the parameter

t)?es

are those

that are

used

in the actual

call.

oarticular. 32.

bit

constants

should

be explicitly

marked

by using

the

L suffix.

2.3 INCLUDING

EXTERNAL

DECLARATION

FILES

When

you

call

procedure

that

is not

defined

in your

current program

mo<lule (a

separately

compiled portion

ofyour program),

you

must

declare

that procedure

to be

external.

Doing so

enables

the

binder to

satisù/

the

references

to thaiprocedure

when

links your

program

modules

together.

This enables

program

in one module

to call

procedure

in another

module.

Invoking

iRMX II system

calls

just

calling

any

pLlly',-zgí

procedure.

Because you

don't define

the system

calÌs

in your programs,

they

must

be external

procerJures.

Therefore,

you

must

include

external

declarations

for

each svstem

call

vou invoke.

2-4 Programming

Techniques

USINC

iRMX@ II SYSTEM CALLS

FROM

IANGUAGES

Intel has made

it easy for

you

to place external declarations for

the system calls in

your

programs. Supplied on the iRMX II release diskettes are INCLUDE files,

which

reside

permanently

in one location and

provide

the PL/M-286 external

procedure

declarations

for all iRMX II and UDI system calls. An INCLUDE file eliminates

duplication of

statements in

your

source

code modules. The

declarations are

written

once,

placed in an

INCLUDE file, and then used in lieu of repeating the

actual declaration in each

module.

For example, to use the INCLUDE file NUCLUS.EXT,

place the following

statement at

the beginning ofyour PL/M-286 source code. This

statement declares all the Nucleus

system calls to be external.

TNcLUDE

(,,/Rr0(2

8 6,/ r NC/NLlC LUS

EXT

)

Table 2-1 lists

the external declaration INCLUDE files

supplied

with

the

operating

system. After installation ofthe operating

system, these files are

available in the

/RMX286/INC directory.

Table 2-I. iRMXo

ll External Declaralion

INCLUDE Files

INCLUOE Fil€ Languag€ D€scription

RMXPAS.EXT

RMXFTN,EXT

RMXPLM.EXT

NUCLUS,EXT

BIOS.EXT

EIOS.EXT

LOADER.EXI

HI.EXT

UDI.EXf

PASCAL-286

FORIRAN-286

PLlM-285

PLlM-286

PL/M-286

PLlM-286

PLlM-2e6

External

declarations for all system

calls.

Refer to the

'Using

the PASCAL INCLUDE

File'

section for more information.

External d€clarations

for all system calls

that

return a valu€. R€l€r to the 'Using

the FORTRAN

INCLUDE File' s€cîion

for mor€ information.

Ext€rnal declarations

for all iRMX ll system

ca s.

External declarations

for Nucleus system

cafls.

External declarations

for Basic l/O

System

calls.

External declaratìons

for Extend€d

l/O System

calls.

External declarations

for Application

Loader

system calls.

Ext€rnal

declarations

for Human Interface

system calls.

External

declarations

lor

UDI

system calls.

Pmgramming Techniques t-<

USING iRMX@ II SYSTEM CALLS T-ROM I-ANGUAGDS

Because each INCLUDE file contains external declaratíons for many

system calls

(either

all iRMX II system calls or

all system calls in a

particular

subsystem), including

particular

file

will probably

result in external declarations for

several system calls

your

program does not invoke. Although having extra external declarations

poses

problems

for the compilers and causes no error conditions,

you can improve

compilation

speed by

copyingjust the external declarations

your program

needs into

a separate

INCLUDE file

and specifying

that file in the INCLUDE statement.

2.3.1 Using the PASCAL-286 Include File

When

using PASCAL-286 to write an application, you must include

the RMXPAS.EXT

INCLUDE file

with your

PASCAL-28ó source program. To do this, enter this statement

your

source program:

lNCLUDE

(

/RMX2

86lrNC/RMXPAS

EXT

)

This statement inserts

the contents of RMXPAS.EXT into your

PASCAL-286 program.

This file contains external declarations

for all the iRMX II system

calls. However, it uses

names that are slightly different

from the system call names shown

in the reference

manuals. Because PASCAL

does not allow dollar signs ($)

procedure

names, the

system

calls are declared

without

the

characters. To make the

names recognizable, the

INCLUDE file

mixes uppercase and lowercase

letters in the names.

You can use this

convention

your

programs also.

Because of data-type

checking that the PASCAL-286

compiler performs,

the INCLUDE

file

may require editing

before

your

program will

compile correctly.

Four Nucleus and

two

EIOS system calls

are affected:

Nucleus

System Calls EIOS System Calls

RQCreateJob

RQECreateJob

RQCreateTask

RQSignalException

RQCreatelOJob

RQECreatelOJob

These

six system calls

enable you to specifo

an absolute value

(0)

or a POINTER

(such

@stacktop)

as the STACK R parameter.

No single PASCAL-28ó

data type

can be used

to declare

both types of values

RMXPAS.EXT

contains

a declaration for speci$ing pointers.

This declaration enables

you to speciff

a stack

location by supplying

pointer

to the stack.

You

may

want

to use

the

vaìue

0, which

indicates that the

operating system

is to

provide

the appìication's

stack location,

for the STACKPTR

paramerer.

2-6 Pmgramming

Techniques

USING iRMX@ II SYSTEM CALLS

FROM I,ANGUAGES

To let the operating system

provide rhe stack,

edit RMXPAS.EXT as shown in the

following paragraph and

use comment

notation around the form of the declaration that is

no longer

needed. The following example

changes the declaration of the STACKPTR

parameter

in the Nucleus

call RQ$CREATE$TASK but the form applies to all five

system

calls that may need editing. Note that only

one STACKPTR declaration can be

"active."

Change

to read

T'IJNCTlON RQCREATETASK(

VAR

{VAR

PRIORITY

STARTADDRESS

DATASEG

STACKPTR

STACKS IZE

TASKFIACS

EXCEPTR

BYTE

;

BYTES;

WORD

;

BYTES

/STACKADDR/;

)

LONGINT;

ITORD

;

WORD

;

BYTES

) ;

VAR

Note

that

you

can change any or all five declarations,

depending

on the

requirements of

your ovr'n PASCAL-286 program.

2.3.2

Using

the FORTRAN-286

Include File

When

you use FORTRAN-286

write

an application,

you

must include the

RMXF|N.EXT INCLUDE file

with

your FORTRAN-28ó source

programs.

To do this,

place

the following statement in your source code:

$INCLUDE

(

/RMx2

86lINCIRMXFTN.

EXT)

FIJNCTION RQCREATETASK(

VAR

PRIORITY

STARTADDRESS

DATASEG

STACKPTR

{STACKPTR

STACKS IZE

TASKFI.AC

EXCEPTR

BYTE

;

BYTES

;

WORD

;

BYTES

/STACKADDR/;

LONGINT

;

WORD

;

I,IORD

;

BYTES

) ;

VAR

Programming Techniques 'r

-7

USING

iRMX@

II SYSTEM

CALLS

FROM

I.A,NGUAGES

This statement

inserts the

contents of RMXFIN.EXT into

your

FORTRAN-286

program.

Only

those system calls

that return

values need to be declared,

so not

all system

calls

are contained in the

file RMXFTN.EXT.

When

invoking

iRMX II system calls from FORTRAN'28ó programs, remember

the

following techniques:

e Use the %VAL pseudo

function

when

passing any

parameter

that is

not a

pointer.

FORTRAN

passes parameters by reference;

the TcVAL

pseudo function

forces the

parameter to be

passed by

value. When passing parameters, match

the tJpe

of the

formal

parameter. That is,

variables

WORD or BYTE

types should be

passed as

words

the stack; DWORDs

should be passed as two

words. You must do

this to

assign

parameters to a

variable

and then

pass the

variable

using 7oVAI. This method

is mandatory for expressions

(even built-ins such as INT2), because expressions

cannot be

passed using

7oVAL.

o Because FORTRAN

does not recognize unsigned entities,

you may have difficulty

referring to byte

values greater than or equal to 128,

word values greater than or equal

to 32768, and double

word

values

greater than or equal

to2**37. For example,

the

GET$PRIORITY system call returns an unsigned

byte

value

that indicates

the

priority. To deal

with

this number in FORTRAN,

either check the

value

a negative

number, or assign the

value

to a

word

and mask the

high byte to zero. These examples

show how

to deal

with

byte and

word values.

Dealing

with

bvte

values

greater than or equal to 128

integer*2 task_tok, status, pri _\.rord

í nl-éoèr*l nÌ"1

pr i*Rqce tPr ior i ty (

lval (

task-tok) ,

status )

.or,rràra the stgned byre to an unsigned word

prl_word - pri .

and.

/l0ff

2-8 Progranming Techniques

USING |RMX@ II SYSTEM CALLS

FROM T.ANGUAGES

Dealing

with word values

greater than or equal to 327ó8

lnteger*2 se8_tok, scatus, size

integèr*4 s ize_dlrord

slze=RqGetSize

(lval (

seg_tok), stacus)

converE the sígned word to an unsigned dr.rord

slze_dword - slze. and.

/l0ffff

Programming Techniques 2.9

USING

iRMX@ II SYSTEM

CALLS

FROM IANGUAGES

FORTRAN

strings are not iRMX lI strings and

are not useful for any

iRMX II

system calls. A FORTRAN

string should be

converted into an array,

with the first

byte set to the length of the string. The

following example illustrates

this technique.

SUBROUTINE Rru'(STR

(

FILE-NAME,

FI LE-ARRAY)

CHAMCTER*(*) FILE-NAME

INTEGER*I FILE_ARRAY(*)

TNTECER*2

LN,I

UI:LEN

(FILE-NAME)

C move string to array

FILE_ARMY(1)-LN

D0 100

r-1, LN

FILE-ARMY( I+1 ):ICHAR(

FILE-NAME

(

I : I ) )

100 CONTlN'IJE

C suppress trailing blanks, fiLl leading length byte

D0 200, I-1 ,LN

rF (CHAR(FILE_ARRAY(LN+2-r)).NE.''

) THEN

FI LE_ARRAY

( I )

-LN+1.I

RETURN

ENDIF

200 coNTlN'ItE

END

character*40 f i 1e-naure

integer*1 file_array(41), co(5)

call rmxs tr (

' : co :

' ,

)

file'name-, ,/r

nx286

/Llb/ sotstce/ a.x,

call rrnxstr(file_name, file_array)

end

2-lo Programming Techniques

USING

iRMX@ II SYSTEM CALLS

FROM

LANGUAGES

2.4 BINDING YOUR CODE TO

INTERFACE LIBRARIES

After you have

written your programs and inserted INCLUDE statements

for the

necessary

system calls, you must compile the code

and bind it to the

appropriate iRMX II

interface library.

Interface lìbraries,

supplied with the iRMX II product, provide a

standard and simple

interface to the

system calls. The interface libraries

contain

procedures that correspond

to iRMX II system calls. These procedures have

the same names

and use the same

parameters as the system calls.

To invoke a system call,

simply declare

the system calls

external

procedures

(as

described in the

previous section)

and call the corresponding

interface

procedure

just as you

would

a PL/M-286 procedure.

The interface

procedure

performs

complicated operations to invoke

the actual

system call. For example,

iRMX I interface

procedures use soffware interrupts to invoke system

calls. Their iRMX

II counterparts make calls to call

gates when accessing

system cal.ls.

After compiling

the

program

code,

you must satisfy the

external references

to the system

calls by using

BND286,

which

binds the

compiled code to the

appropriate

interface

libraries. There

are several interface libraries

from

which

choose.

Which interface

library must be bound

to your program depends on

the system calls

and the segmentation

model used.

-îable

2-2lists the interface

libraries.

As Table 2-2

shows, for each segmentation

model, except

SMALL, there is

one interface

library for UDI and one interface library for all the other layers.

The SMALL model is

supported only for UDI. Ifyour code includes only UDI system calls

(or if it uses the

I/O

support provided by

the language), bind your program only

to the appropriate

UDI

library. Ifyour code

doesn't invoke UDI system calls, or

you don't

plan to include the

language's I/O support,

bind the code

just

to the appropriate

RMX;oo< library.

If your

code invokes both

UDI and other iRMX II system

calls, bind the code

to both of the

libraries for the segmentation model

you

chose. In this last

instance,

when you specify the

BND286 command

to bind

your

code, the

UDI interface library

must

precede the

RMXrco< library in the list of modules

to be bound.

Table 2-2. Interface

Libraries and

iRMX@

II Layers

SMALL COMPACT LARGE OR

MEDIUM

All lay€rs

€xcspt

UOI

UDI UDIIFS.LIB

RMXIFC.LIB

UDIIFC.LIE

RMXIFL.LIB

UDIIFL.LIE

Pmgramming Techniques 2-tl

USING iRMXO II SYSTEM CALLS FROM I.ANGUAGES

2.5 BIND

SEOUENCE

The previous

section described which

interface libraries you should

bind to your

program's

object code. This section discusses

the entire BND286

command that should

be used to bind a program

in preparation

for execution under the Operating

System.

The following example shows

the bind sequence

for a PL/M-286 program

that uses the

COMPACT segmentation

model. The program

consists of three object

modules,

MODA.OBJ, MODB.OBJ,

and MODC.OBJ. The

program

invokes

UDI and other

iRMX II system calls.

After binding the resulting

executable

module

will be

placed

in a

file called

FINAI-SYS. It is assumed

that FINAISYS will be invoked

from the

Human

Interface; that

is, by tlping its name

at the Human

Interface prompt.

BND286 &

MODA.OBJ,

MoDB.O&],

!{oDC. OBJ, &

LANG:

PLM286.LIB, &

/Nrx286 /LfBnDr r Fc

. LrB, &

/î,to/.286 /LLB/P$LXIFC.

LrB &

OBJECT(FINÀLSYS) &

SEGSTZE(STACK(+L750))

RCoNFIGURE(DYNAMTCMEM(5000H,

oFFFTH)

)

In this

BND286 statement,

the three

object files (MODA.OBJ,

MODB.OBJ,

and

MODC.OBJ)

are

bound together with

three

lbraries: PLM286.LIB,

UDIIFC.LIB and

RMXIFC.LIB. The library

called PLM286.LIB

is the standard

pLM-286

library

distributed with the

compiler. It satisfies

compiler-generated

externals,

such

as those

that

occur when you

call built-in

functions

(DWORD arithmetic

is one

example).

PLM286.LIB

should

always be the

first library that you

bind to your pLM-286 object

code.

The

second

and third libraries

(UDIIFC.LIB

and RMXIFC.LIB)

are the

iRMX II

interface

lìbraries used with the COMPACT segmentation

model. These interface

libraries

satisry the

external

references generated

when

your programs

invoke

UDI and

iRMX II system

calls. UDIIFC.LIB

should always

precede

RMXIFC.LIB

in the bin<l

sequence.

The OBJECT

control specifies

the

name of the executable

file to be generated

BND286. In this case, the

file is

called FINAI-SYS.

The SEGSIZE(srACK(+

1750)) control

specifies

that an additional

1750 decimal

byres

stack

beyond

that required

by the program

alone

should

be reserved

for this application.

These extra bytes

are

required

for invoking

system calls. Refer

to Chapter

7 for

guidelines

on selecting

stack

sizes.

2-12 Pmgramming

Techniques

USING

iRMXO

II SYSTEM

CALLS

FROM

I.ANGUAGES

The RCONFIGURE(DYNAMICMEM(5000H,

0FFFFH)) control

directs BND286

produce a single+ask loadable

(STL) module, to assign

a minimum of5000H

bytes of

dynamic memory to the

module, and to limit the amount of memory

it can borrow

from

its parent to OFFFFH byes. All iRMX II tasks

to be loaded by the Application

Loader

must be STL modules

(and programs invoked at the Human

Interface level

are ìoaded by

the Application

Loader). Therefore,

your BND286

command should

always include

the

RCONFIGURE control.

Programming

Techniques 2-13

CHAPTER 3

COMMUNICATION

BETWEEN

|RMX@ il JOBS

3.1 INTRODUCTION

Read this

chapter

if you want

pass

information from one iRMX II job

to another. You

should already be familiar with the following concepts:

. iRMX Il jobs,

including the

root

job

and object directories

. iRMX II tasks

. iRMX II segments

. iRMX Il mailboxes

. iRMX II physical

files or named files

. iRMX II stream files

o iRMX II qpe managers and

composite objects

In multiprogramming systems, where each of several applìcations is implemented as a

distinct

iRMX II job,

information must occasionally pass from one

job

to another. This

chapter describes several

techniques you can use to accomplish this.

The techniques are divided

into two

groups:

passing data between

jobs,

and passing iRMX

II obiects.

NOTE

Many of the techniques in this chapter involve sending tokens or pointers

to other

jobs.

If the sending

job

deleted, these entities become invalid.

If the receiving

job

uses the entities later, the results are unpredictable

(usually

general protection

error). It is the programmer's responsibility

to avoid these situations.

Progremming

Techniques 3-l

COMMUNICATION

BETWEEN iRMX@ II

JOBS

3.2 PASSING DATA BETWEEN JOBS

Data can be sent from one

job to another in several ways:

1. You can use the SEND$DATA and RECEIVE$DATA system

calls

to exchange the

information. SEND$DATA and RECEIVE$DATA use a mailbox to exchange up

to 128 bytes of information. To use this method, the task that creates the mailbox

must

catalog

it in the root object directory, so that the other task can access it. Thrs

procedure

is described later in this chapter.

The advantages of this technique

are

o Because this technique requires only the Nucleus, you can use it in systems that

not use other iRMX II layers.

. Althou€ù the Operating system copies the information

from one

place

another, it copies the information very quickly.

o It is the quickest

method of

passing

small amounts

of data.

. It can be used to exchange

larger amounts of data by

passing

the

pointer

that

data as data itself in the SEND$DATA system call. The receiving

job can then

use the pointer

to refer to the

relevant data. This method of exchanging

data rs

faster than

using SEND$MESSAGE because it does

not require the overhead

of creating a segment.

The disadvantages

of this technique

are

. Only 128 bytes

of information can be

exchanged

with the SEND$DATA and

RECEM$DATA system calls.

2. You

can create

an iRMX II segment

and

place

the information

in the segment.

Then,

using one of the techniques discussed

below for passing

objects between

jobs,

you

can deliver

the segment.

The advantages

of this technique

are

. Because this

technique requires

only the Nucleus, you

can use it in systems that

not use other

iRMX II layers.

. The Operating

system does

not copy the

information from

one

place

to another.

The disadvantages

of this technique

are

o The segrnent

occupies memory

until it is deleted,

either explicitly (by

means of

the DELETE$SEGMENT

system call),

or implicitly (when

the

job that created

the

segment is deleted).

Until the

segment is deleted,

a substantial

amount of

memory

is unavailable

for use elsewhere

in the system.

. The application

code may have

to copy the information

into the

segment or

from it.

t-2 Programrning

Techniques

COMMUNICATION

BETWEEN iRMX@ II JOBS

3. You can use an iRMX II stream

file.

The advantages

of this technique are

. You can

use I/O System calls to pass

information directly between tasks,

without slowing

down the transfer

by temporarily

placing

the data on a

secondary storage

device.

o This technique

can easily be changed to Technique

4 (below).

The

disadvantages

of this technique

are

r You must configure

one or both I/O systems into

your application system.

. There is a 4K byte

limit on the amount of data you can pass via a stream

file.

o Writing data to and reading

data from a stream file is much slower than any of

the

methods.

As a last resort, you

can use the Basic I/O System, the Extended I/O System, or the

Universal

Development Interface to write the information onto a mass

storage

device, from which the

job needing the information can read it.

The advantages of this

technique are

. Many

jobs

can

read the information.

. This technique can easily

be changed to Technique 3

(above).

The disadvantages

of this technique are

. You must incorporate one or

both I/O systems

(and possibly

UDI) into

your

application system,

e Device I/O is slower than reading

and

writing to a stream file, making this the

slowest of the

four methods.

3.3 PASSING

OBJECTS

BETWEEN

JOBS

Jobs can also communicate with

each other by sending objects across

job

boundaries. You

can use

any of several techniques

to accomplish this. In the following discussions

you

will

see how to pass objects

by using object directories,

mailboxes,

and parameter objects.

Although you

can

pass

any object from onejob

to another, there is a restriction

pertaining

to connection

objects.

When

a file connection created

in one

job (Job

A) is

passed to a

second

job (Job

B), Job

B cannot successfully use the object to perform I/O. Instead, Job

B must create another connection to the same

file. It does this by invoking

the Basic I/O

System's

A$ATTACH$FILE system call, using the connection obtained from Job A as the

prefix

parameter. No subpath parameter needs to be specified. A$ATTACH$FILE

returns

a new connection to the same file,

which

Job B can use to

perform

I/O. This

restriction about connections is discussed in the Extended |RMX II Basic I/O System User's

Guide and in the |RMX II Extended I/O Svstem

User's

Guide

Programming

Techniques 3-3

COMMUNICATION BETWEEN iRMX@ II JOBS

3.3.1

Passing

Objects

Through Object

Directories

Consider

hypothetical

system in

which tasks in separate

jobs

must communicate

with

each other. Task B in Job

B must not begin, or resume running, until Task A in Job A

grants permission.

One way to perform

this synchronization is

to use a semaphore. Task B can repeatedly

wait at the semaphore until it receives a unit, and Task

A can send a unit to the

semaphore

whenever

it wishes to grant permission for Task B to run. If Tasks

A and B

were within the same

job, this would be a straightforward use of a semaphore.

But the

two tasks are in different

jobs,

and this causes

some complications.

Specifically, how do Tasks A and B access the same

semaphore?

For instance,

Task A can

create the semaphore and access it, but how can Task A provide

Task B with a token

for

the semaphore? The solution is to use the object directory of the root

job.

the

following explanation, each of the two tasks must

perform

half of a

protocol. The

process of creating and

cataloging

the semaphore

is one half, and the

process of looking

up the semaphore is the other.

For this

protocol

to succeed, the programmers of the two tasks

must agree on

a name for

the semaphore,

and they must agree

which

task performs which half of the protocol. In

this example, the semaphore

is named PERMIT_SEM. And, because Task B must

wait

until Task A grants

permission, Task A will create

and catalog the semaphore, and Task B

will look it up.

Task A performs

the creating and

cataloging as follows:

1. Task A creates a semaphore with no

units by calling the CREATE$SEMAPHORE

system

call. This provides Task A with a token

for the semaphore.

2. Task A calls

the GET$TASK$TOKENS system call to

obtain a token for the root

job.

3. Task A calls the

CATALOG$OBJECT system call to place

a token for the

semaphore

in the object directory of the

root

job

under the name PERMIT_SEM.

4. Task

A continues processing, eventually

becomes ready to grant permission, and

sends a unit to PERMIT SEM.

3-4 Programm ing Techniques

COMMUNICATION BETWEEN iRMX@ II JOBS

Task B performs

the look-up protocol

follows:

1. Task B calls the

GET$TASK$TOKENS

system call

to obtain a token for the

root

job.

2. Task B calls the LOOKUP$OBJECT

system

call to obtain a token

fbr the object

named PERMIT_SEM.

If the name

has not

yet

been cataloged,

Task B

waits

until

It ls.

3. Task B calls the RECEIVE$UMTS

system

call to request a unit

from the

semaphore. If the

unit is not avaiìable,

Task A has not yet granted permission

and

Task B waits. When

a unit is

available, Task

A has

granted permission

and Task B

becomes ready.

You should be aware

of several aspects

of this technique:

o In the example, the

object directory technique was

used to

pass

a semaphore. You

can use the same technique

pass

any type of iRMX II object.

. The semaphore

was

passed via

the object directory

of the root

job. The root

job's

object directory

is unique because

it is the only object directory to which alljobs in the

system

can

gain

access. This accessibility

allows onejob to "broadcast"

object to

anyjob that knows the

name under

which

the

object is cataloged.

. The object directory

of the root

job

must be

large enough to accommodate the names

all the objects

passed

in this

manner. If it is not, it will become full and

the

Operating system wi.ll

return an exception

code

when

attempts are made to catalog

additional

objects.

. Ifyou use this technique to pass

many objects,

you

could have

problems

ensuring

unique names.

To avoid this, use an

object directory other than the root object

directory for different

sets ofjobs. For example, have

one

the

jobs

catalog its token

the root

job's

object directory

under a previously set name.

Any other

jobs

can then

look

up the token of the

cataloged

job

in the root

job's

directory, and

use its object

directory

rather than that

of the root

job.

e In the example, the object-passing protocol

was

divided into two halves: the create-

and-catalog

half and the look-up

half. The

protocol works

correctly regardless of

which

half runs first.

Programming

Techniques J-f,

COMMUNICATION BETWEEN iRMX@ II JOBS

3.3.2

Passing Objects

Through

Mailboxes

You can also send objects from onejob to another

by using a mailbox. This is a two-step

process; the two

jobs

using the

mailbox must first use

the object directory

technique to

obtain

mutual access to the mailbox,

and then use

the mailbox to pass

additional

objects.

There

are two ways to transmit information

via a mailbox. If the mailbox is set up to

transfer data, the tasks can use

SEND$DATA and RECEIVE$DATA to send and

receive

128-byte data. With these calls,

tasks can transfer strings,

arrays, and even tokens for

objects, as

long as the information

is 128 bytes or less.

If the mailbox is

set up to transfer objects, the

tasks can use SEND$MESSAGE

and

RECEIVE$MESSAGE

to send and receive iRMX II objects. With these calls,

only the

object tokens are sent and received.

Whenever rwo

jobs

send data

via

mailboxes, the sending and

receiving task must

perform

handshaking to ensure that they

are finished using the segment containing the data.

If the

segment is deleted and the

receiving task attempts to access the now nonexistent segment,

a general protection error occurs.

3.3.3 Passing Parameter Objects

One of the

parameters

of the CREATE$JOB system call is a

parameter

object. This

parameter

allows a task in the

parent

job

pass

an object to the newly created

job. Once

the tasks

in the new

job

begin running,

they

can obtain

a token

for the

parameter object

by calling GET$TASK$TOKENS. This technique is illustrated in the

following

example.

Suppose that Task I in Job I is responsible for spawning a new

job (Job

2). Suppose also

that Task 1 maintains an array needed by Job 2. Task I can

pass

the array to Job 2 by

putting the array into

an iRMX II segment and

designating the segment as the

parameter

object in the CREATE$JOB system call. Then the tasks of Job 2 can calÌ the

GET$TASK$TOKENS system call to obtain a token for the segment.

ln the example, the parameter object is a segment.

However,

you

can use this technique

to pass any

kind of iRMX II object.

3.3.4 Restrictions

As mentioned earlier, there is a restriction concerning the passing

of connection objects

between

jobs.

When a

file connection created in onejob is

passed

to a second

job,

the

second

job

cannot use

the object to

perform

I/O. Instead, the second

job

must create

another connection to the same

file. This restriction is discussed in the Extended |RMX II

Basic

I/O Svstem User's Guide and in the r'RMX Extended I/O Svstem

User's Guide.

3-6 Programming Techniques

COMMUNICATION BETWEEN

iRMX@ II JOBS

3.3.5 Comparison

of Object-Passing

Techniques

Consider

these

guidelines

when

deciding

how to pass

an object berween

jobs:

. Ifyou are

passing

only one object

from a parentjob

to a child

job,

use the

parameter

object when

the parent

creates the

child.

. Ifyou are

passing

only

one object

but not from parent

to child, use the object

directory

technique. It is simpler

than

using a mailbox.

. If two

jobs

frequently pass

objects between

each other, the mailbox

technique is the

fastest

and easiest

method.

. Ifyou need to pass

more than one object

at a time, use any ofthe following

techníques:

- If the tokens fit in a 128-byte array,

create a mailbox and use

SEND$DATA and

RECEIVE$DATA

to transfer

the array.

-- Assign an order to the

objects and send

them one by one to a mailbox

(using

either SEND$DATA

or SEND$MESSAGE) where

the receiving

job

can

pick

them up in order.

-- Give each

object a name

and use an object

directory.

- Write a simple

type manager

that

packs

and unpacks a set

of objects. Then pass

the set of objects

as one composite

object.

Programming Techn

iques J- /

GUIDELINES CHAPTER 4

FOR

STACK SIZES

4.1 INTRODUCTION

This chapter

is for three kinds

of readers:

. readers who vr'rite tasks

that create

iRMX II jobs

or tasks

. readers who write

interrupt

handlers

o readers who write

tasks to be

loaded by the Application Loader or tasks

to be invoked

by the Human Interface

You should

already be familiar with

the iRMX II System Debugger, and you

should know

which

system calls are provided

by the various

layers of the Operating System. You also

should

know the difference

between maskable and nonmaskable interrupts.

This chapter

will

help you

compute the amount of

stack

you

must specify for a system call

that creates

job

or task. Ifyou are writing

an interrupt handler, this

chapter tells

you

about stack

size limitations that you

must adhere to. If you are writing

a task to be loaded

by the Application Loader

or invoked by the

Human Interface, this chapter tells you how

much stack to reserve during

the binding

process.

4.2 STACK SIZE LIMITATION

FOR INTERRUPT

HANDLERS

Many Operating system tasks are

subject to two kinds

of interrupts: maskable and

nonmaskable. When

these interrupts

occur, the associated

interrupt handlers use the

stack ofthe interrupted

task. Consequently, you

must know how

much ofyour task's stack

to reserve for these interrupt handlers.

The

operating system assumes

that all interrupt handlers require no more

than 128

(decinal) bytes of stack, even

if a task is interrupted by both a maskable and a

nonmaskable

interrupt. Ifyou fail to adhere to this limitation when writing an interrupt

handler, you risk stack

overflow in your

system.

Programming Techniques 4-l

GUIDELTNES FOR STACK SIZES

To stay

within the 128

(decimal) byte limitation, restrict

the number of local

variables that

the interrupt handler

stores on the

stack. For interrupt handlers

serving maskable

interrupts,

you can use as

many as 20

(decimal)

byes

of stack for local

variables. For

handlers

serving nonmaskable

interrupts, use

no more than 10

(decimal) bytes. The

balance

of the 128 bytes is

consumed by the SIGNAI$INTERRUPT system call and by

storing

the registers on

the stack.

For more information

about interrupt

handlers. refer to the Ertended

|RMX II Nucleus

User's Guide.

4.3 STACK GUIDELINES

FOR CREATING

TASKS AND JOBS

When

you

create

a task by invoking a system call,

you must specify the size of the

task's

stack. And,

since every

new

job

has an initial task created

simultaneously

with

thejob,

you must also designate a stack size

when you create a

job.

Be careful

when specifing a task's stack size. Specifying

a stack size that is too small,

could

cause the task to overflow its stack. If the stack overflows, the hardware

will detect

the error and cause the Nucleus to invoke an exception handler,

which could delete the

offending task or activate the iSDM monitor.

Specifing a stack size that is too large

wastes

memory. Ideally, you should specify a stack size that is only slightly larger

(500-

1000 bytes) than v/hat is actually required.

This chapter illustrates two techniques for estimating a task's stack size: arithmetic

and

empirical. For best results, start

with

the arithmetic technique and then use the empirical

technique to tune

your

original estimate.

If your

programs are recursive, do not rely solely on either of these techniques. Stack

usage in recursive

routines

varies

because of run-time

events, and should be computed

carefully.

To minimize problems, pad the results ofyour computations by 500 to 1000 bytes to allow

for situations that you might not have experienced in your tests.

4.4 STACK GUIDELINES

FOR TASKS TO BE LOADED

INVOKED

Ifyou are creating a task to be loaded by the Application Loader or invoked by the

Human Interface,

you

must specify the size of the task's stack during the bind process.

The

following

techniques

will

help

you

estimate stack size requirements.

4-2 Prograrnming

Techniques

GUIDELINES FOR

STACK SIZES

4.5

ARITHMETIC TECHNIQUE

This technique slightly

overestimates

a task's stack size.

After you use this technique to

obtain

an estimate, use the

empirical technique

described later in this chapter

to refine

the estimate.

The arithmetic technique

is based on these factors,

which

affect a task's

stack:

. Interrupts

o iRMX II system calls

r Requirements

of the task's code (for

example, the stack used to pass parameters

procedures or to hold local variables

in reentrant procedures)

Estimate the size of a

task's stack by adding

the amount of memory required to

accommodate these factors.

The following sections

explain how to compute these

values.

4.5.1

Stack Requirements

for Interrupts

When

an interrupt occurs while a task

is running, the interrupt handler

uses the task's

stack

while

it services

the interrupt. Consequently, you must

ensure that a task's stack is

large

enough to accommodate the

needs of rwo interrupt handlers: one for

maskable

interrupts and one for nonmaskable interrupts. Refer to the

earlier section

"Stack

Size

Limitation for Interrupt Handlers" for more

information.

4.5.2 Stack Requirements

for System

Calls

When a task invokes an

iRMX II system call, the processing

associated

with the call uses

some of the task's stack.

The amount of stack

required depends on

which

system calls you

use.

Table 4-1 shows how

many bytes of stack a task requires to support the system calls of

each layer. Included in these figures

are the 128 bytes required by the interrupt

handlers.

To find out how much

stack

you

must allocate

for system calls, determine which layers of

the operating system your

task uses. Scan Table 4-

1 to find which

of those layers requires

the most stack.

By allocating

enough stack

to satisfy the requirements of the

most

demanding layer,

you

can satisfy the

requirements of all system calls used by

your

task.

Progranming Techniques 4-3

GUIDELINES

FOR

STACK SIZES

Table 4-1.

Stack

Requirements for Interrupts and System Calls

Layer BYes

(Decimal)

UDI

Human lnterface

Application Loader

Enended l/O System

Basic l/O System

Nucl€us

1750

1500

550

350

2s0

4.5.3

Computing Stack

Size

To compute

stack size, add the following numbers:

. The number of bytes

required for interrupts and system calls, according to the most

demanding

layer

you

intend to use.

. The

amount

of stack required by the

task's code. This figure can

be determined by

looking at the

information about the STACK

segment in the .MPl map

file

that

BND286 produces when

it binds

your

application code.

This stack usage is the result

of calling local procedures

and using the stack for local variables when

your code is

reentrant.

This sum

is a conservative, but reasonable,

estimate of a task's

stack requirements. For

more accuracy, use

the sum as a starting point for the empirical

fine tuning described

below.

4.6 EMPIRICAL

TECHNIQUE

This technique starts with

an overly

large stack and uses the

iSDM Monitor to determine

how much

of the stack

unused.

Once you have

found out how much

stack is unused,

you

can modify your task-creation

and

job-creation

system calls to

create smaller stacks.

To use this

technique, change your program

code

to break to the iSDM

monitor at the

beginning

and at the end of the program.

When

coding in PL/M-286, use the

CAUSE$INTERRUm(3)

statement

to break

to the monitor (INT3 in assembly

language).

Ifyour application

is loaded by the

Human Interface

(that

is, invoked

as a

command),

use the DEBUG

command to gain

access to the monitor,

instead of adding

extra instructions

to your code.

4-4 Programming Techniques

GUIDELINES

FOR

STACK SIZES

When

the iSDM monitor first receives control, fill the unused

portion of the stack

with a

value

that would

not normally appear

there. For example, use the monitor's S command

to fill the remaining

stack

with a

value

of OAAH.

Continue

running the program. When

the iSDM monitor receives control at the end of

the program,

examine the stack and

see how much of it still contains the value

you

filled in

earlier. That portion was

unused throughout

the entire execution of the program.

Use this technique

to determine stack usage,

but do not assume that the

value

you obtain

is an exact number. The

value you

determine

usually

won't

be exact because a typical run

of the program probably will not take the

deepest

path (using

the most stack) through the

program. Also, a tlpical run might not encounter interrupts on the deepest paths through

the program.

Programming Techniques 4-5

CONVERTING |RMX@

AND IMPROVING

CHAPTER 5

IAPPLICATIONS

PERFORMANCE

5.1

INTRODUCTION

When

moving an iRMX I application to the iRMX II Operating System,

your

fist

concern is usually making the application work. After you realize that the upv/ard

compatibility provided by

the iRMX II Operating

System makes the change easy,

you will

want

to get

optimum

performance

from the 80286 and 80386

processors.

This

chapter

helps

you

do that, by

providing

instructions that

will

enable

you to design applications

with

optimum performance.

5.2 EFFECTS OF SEGMENTATION

Segmentation is

one

of the most important

performance areas in which the iRMX I and

iRMX II Operating Systems differ. When using the 8086 processor, and the

80286/38ó

processors

in real-address mode, changing a segment register is as fast as changing any

other register, making it one of the fastest operations to perform. However,

with the

80286 and 80386 processors in protected virtual address mode, changing a

segment

in the global or local descriptor

tables (GDT or

LDTI. Therefore. it is a slower oneration.

5.2.1

Causes

of Program

Slowdown

When

the processor is in protected virtual address mode (as it is

when

the operating

system

runs), it is

possible

to spend unnecessary time on segment

because of the way PLIM-286 works. The default

model of segrnentation under

which

PL/M-286 compiles

your

code is I-ARGE. Under the LARGE model, the following items

apply:

. Every

procedure

has its own code segment

and its own data segment.

Programming Techniques 5-l

COI{I'ERTINC iRMX@ I APPLICATIONS AND IMPROVING PERFORMANCE

. Every reference

to a nonlocal variable causes the processor to set up the ES register

to access the

variable's

segnent, an operation requiring 17 clock cycles.

. Every procedure

call

to an external procedure or to a public internal procedure is a

long call,

which

changes the CS register and costs 26 clock cycles

(as

compared to 7

rycles

for a short call and 13

rycles

for a long call in real-address mode). The long call

is followed by a MOV to DS to establsh a new data segment. This costs an additional

17 clock cycles (as compared to 2 cycles in real-address mode).

The net result of this additional overhead

a significant slowdown when

compared to the

same instruction

running in real-address mode. The overall

slowdown of the application

depends of course on how often such

instructions are used.

5.2.2 Avoiding

Slowdown

To help avoid the slowdown

caused by changing a segment

"PL/M-286

Extended

Segmentation" chapter

in the PL/M-286 manual. In addition,

use the

COMPACT model of

PL/M-286

when

possible.

Use the MEDIUM model when you

cannot use

COMPACT, and use COMPACT subsystems when you

need more speed than

MEDIUM can give you. Resulting code

will have

fewer segment register changes

and

will

run faster.

A side benefit of this technique

is that it requires

fewer objects (the operating

system

has an

upper limit of 8000 objects).

In addition, you

can reduce slowdown by

using the OPTIMIZE(3) compiler

control

when

compiling

code. T\e PL/M-286 User's Guíde

describes the requiremenrs

for including this

control.

Use the OPTIMIZE(3)

control cautiously.

If you aren't

sure whether your code

meets the

requirements

for OPTIMIZE(3), use

OPTIMIZE(2)

instead.

s.3 PLIM-286

BASED

VARTABLES

Accessing

a PLIM-286 varíable

that is

BASED on a POINTER or a SELECTOR requires

that the ES register

be loaded

first. It is therefore

a slower operation

in protected

mode

(relative

real mode).

To avoid making

numerous

references to members

of a BASED

structure

or array, you

might want

to try the

following approach:

. Declare a

non-BASED copy

ofthe structure

or array.

o Use

MOVIV to copy from the original

BASED structure ro the

non-BASED

copy.

. Continue

accessing

only the copy.

To see

if this technique

helps,

place

SCODE

and

$NOCODE

controls

around the

areas of

code in which potential

slowdown occurs.

This causes

the compiier

to generate

assembly

language

listings of these areas. With the listings, you

can determine

how

often segment

registers

are loaded

and

whether

this

optimization

technique

is necessary.

<-t Programming

Techniques

CONVERTING

iRMX@ I APPLICATIONS

AND IMPROVING PERFORMANCE

5.4 OPTIMIZING

NUCLEUS PERFORMANCE

After you increase

your application's speed, try to optimize

the use of Nucleus system

calls. To do this,

you

must understand that under the operating

system,

fast Nucleus

system calls

get

faster and slow

system calls

get

slower,

when

compared

to the iRMX I

Nucleus

running on a real-mode

80286

processor. Therefore,

use the

fast system calls

(such as sending and receiving

messages) as

much as

possible, and use the

slower system

calls

(creating and deleting)

as little as

possible.

One

way to avoid creating

and deleting objects

is by reusing

segments. Instead

of creating

a segment each time

you need one and deleting

it each time

you finish, keep

the segment

for later use. If the segment size

is appropriate,

you

can

use it again

without incurring

the

overhead of creating

a new segment.

s.s

oPTrMrzrNG

SEQUENTIAL

l/O

Ifyour programs

use primarily sequential

I/O (as opposed

to random

I/O) you

can

increase performance

when using the Ext€nded

I/O System,

by assigning larger

buffers

than

you

used under the iRMX I Operating System.

5.6 MAILBOX

TUNING

When

creating

a mailbox,

you

can specif the number

of messages

that can be

waiting in

the mailbox's high-performance

queue. When

this

queue

overflows,

the

operating system

creates an additional

segment

to contain 100 more

messages.

This overflow

queue is

slower

than the high-performance

queue

only for the initial overflow,

because

at that time

the operating

system must create a new

segment to serve

as the overflow

queue (recall

that creating a segment is a

relatively slow operation).

After the

overflow

queue

created, that queue

isjust as fast as the high-performance

queue.

The overflow

queue is

not deleted

until the entire mailbox is

empty (both queues).

Because

ofthe mechanism

used to create and delete

overflow

queues,

when you create a

mailbox give it a

queue large enough to handle

all the messages

you

expect to be

waiting

at the

queue. However, if an overflow

is possible, you

might

want

prevent the

queue

from

emptying, so

that the operating system

won't delete

the overflow

queue and then

forced to create

it again

when another overflow

oocurs.

5.7 RECYCLING

BUFFERS

Because creating

and deleting segments

are slow operations,

applications

that

use many

buffers

can benefit

from reusing buffers

from a previously

created Buffer Pool instead

creatine buffers

and deleting them

as needed.

Programming Techniques 5-3

COIIVERTING iRMX@ I APPLICATIONS AND IMPROVING PERFORJVIANCE

You can recycle buffers by creating a Buffer

Pool

with a sufficient number of buffers

during

the application's initialization. When

you

create the Buffer Pool,

you

have

complete control (within

limits) over the number and size ofthe buffers available.

When a buffer is needed a task can invoke the REQUEST$BUFFER

system call to

receive the token of one

of the

buffers from the Buffer Pool. This is

faster than creating a

segment. When

the buffer is not needed

any more, the task can invoke

RELEASE$BUFFER to return the buffer

to the Buffer Pool (this is faster than deleting

segment).

5.8 CONSERVING LIMITED RESOURCES

With the iRMX I Operating

System,

programmers

must

often

pay

special attention

to the

amount of memory

in the system.

Because the 8086

processor

can access only one

megabyte of memory,

memory is usually

the scarcest resource

in the system.

Under the

iRMX II Operating

System, programmers

must still pay attention

to the

amount of memory in the system.

But, memory

is no longer a scarce

resource, because

the 80286

and 80386 processors

can each

access up to their full address range of memory

locations.

Instead,

the most limited

resource is the number

of entries in the global

descriptor table, which

serve as tokens

for iRMX II objects.

In an iRMX I environment, programs

often veri! memory problems

by examining

the

condition

code returned

by each system

call and looking

for E$MEM conditions.

In an

iRMX II environment,

programs should

check for both

E$MEM and

E$SLOT conditions.

The E$SLOT

code is returned

if there aren't

enoush GDT slots

to comnlete the

requested

system

call.

Build your iRMX II systems with

as many

GDT slots

possible.

For

systems

with

over

2MB of physical

memory,

allocating

full-size GDT slots

(8K slots that

consume 128K bytes

memory) seems a

reasonable cost

for the

problems

that the extra

GDT slots can

eliminate.

5-4 Pmgramming

Techniques

4.1 INTRODUCTION

This appendix contains complete programming

examples

that use iRMX II system calls.

You can

compile,

bind, and run these programs

from the Human Interface

yourself,

you

can use them

purely

as examples,

to see hovr' to perform certain operaîions under the

operating system

You can also use the EXAMPLE 1 files as a starting

point in developing

your application

code. Using different

parts

of these files saves you

from initially having to create the

source module, adding

include statements, re-writing

code

that attaches

the console, etc.

4.2 EXAMPLE 1

SYSTEM PROGRAMMING

CONCEPTS

Example 1 demonstrates

some iRMX programming

concepts by

printing prompts

to the

console screen

and accepting input from the user. To accomplish this, the

program

uses

two tasks: the main program

code the a second task called TASK2. The main

program

code

is the

initial task and creates the second task

TASK2.

The function of the main program

code is the following:

. set up the programming

environment by creating objects, the second task, etc.

o prompt the user for and capture

keyboard input

. pass

the captured input to TASK2

. exit

with an error after

receiving three user-supplied keystrokes.

The function of TASK2 is to receive user-supplied

keystrokes

from the main program

code

and

process

them. The

processing

consists of printing the received keystroke to the

screen once every second.

Because thejob uses two tasks, each task can perform its function separately from the

other task. Communication and data passing

between the

main program code and

TASK2 is handled

using

some basic iRMX programming

techniques.

Programming Techniques A-l

EXAMPLE PROGRAMS

The following sections show you where to locate

the actual code in the iRMX file

structure, explain basic iRMX programming

concepts used in the example, show how to

build the program, and

show how to run it.

A.2.1 Program

Source Code

The

program

source

code and supporting files can

be found in the Intel-supplied iRMX

file structure. The complete pathname

for the source code files and

related files is the

following:

/ rmx28 6

/ deno

/p 1m/ intro

Before attempting to understand

this example,

you

should produce

hard copies of the

source code

files or have easy access to view

them from a console screen.

Getting

and Setting

Terminal

Attributes

Creating

Tasks

Cataloging

Objects

A.2.2

Concepts

This example illustrates

nine common iRMX programming

concepts.

The following list

briefly describes

each of these

concepts:

In-Line Exception Processing The processing

of all errors resulting

from iRMX System

Calls in your

application

code rather

than using the

default

exception handler, which

deletes

tasks that get

errors.

Using separate

files that contain

PL/M-

286 data structure

definitions and

literal

definitions needed

to make

system calls.

Providing separate

literal files, such as

these, relieves you

from repeating data

structure

and literal definitions

throughout modules.

Using

iRMX System

Calls to

get

the

current terminal

attrihutes.

After getting

and

altering the attributes, you

can use

another iRMX System Call

to set them.

Using

an iRMX System

Call to create

additional

tasks from

an existing task.

Describing

to the system

where key

objects the

job

uses reside.

Tasks can

easily share cataloged

objects.

Using Literal Files

A-2 Prograrnming

Techniques

Using Response Pointers During

Inter-Task Communication

Using

Buffer Pools

Performing Screen Input/Output

Performing Simultaneous

Input/Output

EXAMPLE

PROGRAMS

Instructing serving tasks

where

respond with

information

that signals the

completion of a requesting task.

Response Pointers allow serving tasks to

keep track of which

requesting tasks they

are responding to.

Creating areas of memory for a

job

that

tasks can use as a common memory

resource. Once a buffer pool and its

buffers have been created, a[ì

the system

has

to do

order to use the memory is to

request and release buffers.

Reading and

writing

data to the

physical

terminal screen.

Tasks

performing I/O operations

independent of one another. For

example, one task may wait for terminal

input

whiìe

another

task processes data

and

writes

it to the terminal.

4.2.2.1 In-Line Exception Processing

Inline exception

processing provides

a way

for

your

application

to handle errors

generated

from system

calls. The flexibility of the iRMX Operating System allows

you

determine how to process exceptions: processing them in-line or using the default

exception

handler. This example demonstrates a method that lets you provide your own

exception processing. In order

for

you

provide your

own exeeptiÒn

processing, you

must do

two things: cause the system to pass control to your exception handler routine

instead of built-in exception handler

routines, and create

your

own

exception

handler

routine.

To get the operating system to pass

control to

your

routine instead

of a

built-in

routine

involves resetting the

value

of the current task's

exception

mode and coding your tasks to

call

your

exception handler routine.

This example uses a

procedure

called SET$EXCEF |ION in the file EXCEPT.P28 to

reset the exception mode to a

value

ofzero. A value

ofzero telìs the operating

system to

never pass control to built-in exception

handler routines.

lf you examine the beginning of

both

the main

program code

and TASK2,

you will see that the

very

first executable

statement is a call to the SET$EXCEPTION

orocedure

as follows:

Prograrnming Techniques A-3

EXAMPLE PROGRAMS

CALL se !$except lon( N0$EXCEPTIONS

) ;

This call passes a zero value parameter

(NO$EXCEPTIONS supplied

from a literal file)

to the

procedure. When

SET$EXCEPTION

executes, it calls

GET$EXCEPTION$HANDLER,

which returns exception handler information to

the

data structure addressed by except$info. The

procedure

then replaces

the exception

mode

with

zero usins the followins

statement:

except$

lnfo .

mode

= except$mode;

The

procedure then

calls SEfiEXCEPTION$HANDLER

to reset the exception handler

information with the

altered

data addressed by except$info.

supplying

a zero

value for

mode in the data structure that describes exception information, you tell the system to

never pass control to the built-in exception handler routine (refer to the Extended |RMX II

Nuclew Systems Calls Manual for detailed information on these system calls)

Now that you have got

the operating system not to call built-in exception handler routines,

you

must code your tasks to either check for individual expected errors

or to call

your own

exception handler routine. This example uses a procedure called

ERROR$CHECK in

the file EXCEPT.P28 as the exception handler

routine. Notice that in the source code for

the main program

code and TASK2, a call to ERROR$CHECK

follows every system call.

The following code illustrates

an example:

CALL

rq$s$open (co$conn, LTRITE$ONLY,

0, @status).

CALL etror$check(510,status) ;

nail$box - rq$lookup

obj

ec t (

CALLER,

G(3,

'MBX'), INFINITE$I.IAIT,

tatus ) ;

CALL

error$check(520,status) ;

pool$tkn: rq$ lookup$ obj ec t (

CALLER,

@(6,'BUFFER'), INFINITE$I4ÌAIT,

Gstatus);

CALL error$check(530,status) ;

The above code

is from TASK2. Each time a system

call is matle, a subsequent call is

made to

ERROR$CHECK passing it a line number and a word containing

the

status

from

the

system

call. The routine ERROR$CHECK

tests the value of status and

returns to the

calling task if it is zero (no

error occurred). lf the value of status is not

zero

(an error

occurred), then

ERROR$CHECK builds an error

message,

prints

it to the

screen,

and exits the

job.

A-4 Programming Techniques

EXAMPLE PROGRAMS

NOTE

The line numbers passed as the first parameter in calls to

ERROR$CHECK

have no implicit meaning. These numbers are simply

arbitrary numbers that can be associated

with a system

call. This

technique, allows

you

to easily find a system call

that generates an error.

4.2.2.2 Use of Literal Files

Within the iRMX directory structure,

you will find intelsupplied

literal files. These files

are located in the directory

/RMX286/INC and have a file extension

of .LIT. Literal files

provide

many

data structure definitions used by iRMX System Calls

and some extremely

useful lìteral definitions for PL/M-286 code. Including

the appropriate literal files in your

program

modules

saves you the trouble of having to repeatedly enter

the data structure

definitions manually in

your

source code and keeps

your code independent

of changes to

these structures between iRMX releases. Because

the names used in literal definitions

are descriptive,

your

code becomes easier to understand.

It is

good programming

practice

get

in the habit of using Intel-supplied literal

files.

This example uses include statements to include

various literal files in every

source code

file. The following

PL/M-286 statements are from the main

program code in the

file

DEMO.P28.

These statements show how to include six

literal files.

lnc lude

(/rrnx286linc/e rror. I it )

include (

r/rrnx2

86/inc/eornrnon.

11t )

incLude (/rmx2 86l1nclns texh . l ic )

lnclude

(/rmx286lt

ncltscrn. lit)

$include

(/rmx286linc/iaiors. lit)

$include (/rnx286 / inc / Io. IiL)

Tables A-1 through A-4 show

which

Intel-supplied

literal files are

useful for

which

types

system calls-

Table

A-t Literal Files Helpful Wilh Nucleus Syslem

Calls

Nucleus System Call Literal File

CREAfE$JO8 NSfEXH.LIT

GET$EXCEPTION$HANDLER NSTEXH.LIT

GET$IASK$TOKENS NGTTOK.LIT

GET$TYPE NGfTYP.LIT

SETSEXCEPTIONSHANDLER NSTEXH.LIT

Programming

Techniques A-5

Table A-2 Literal Files Helpful With BIOS System Calls

BIOS Syst€m Call Literal Fil€

A$GETSCONNECTION$STAf US IAGTCS.LII

to.Lrr

A$GET$FILE$STAfUS IAGTFS.LIT

IFLTYP.LIT

to.LtT

A$OPEN ro.LtT

A$PHYSICAL$ATTACH$DEVICE to.LrT

A$SEEK to.LrT

A$SPECIAL TSCRN.LIT

EXAMPLE

PROGRAMS

Table A-3 Literal Files Helpful With EIOS System Calls

EIOS

Syst€m Call Lit€ral Fil€

CREATE$IO$JOB NSTEXH.LIT

IEXIOJ.LIT

E$CREATESIOSJOB NSIEXH.TIT

EXIT$IO9JOB IEXIOJ.LIT

GET$LOGICAL$DEVICE$SIATUS to.LtT

LOGICAL$ATTACHSDEVI

CE to.LtT

S$GET$CONNECTION$STATUS ISGTCS.LIT

ro.L|l

S$GET$FILE$STATUS ISGTFS.LIT

IFLryP.LIT

to.LtT

S$OPEN ro.Lrf

S$SEEK to.LtT

S$SPECIAL ISIORS,LIT

TSCRN.LIT

Table A-4 Literal Files Helpful With Human Interface

System Calls

Human Intertace

System Call Lrteral File

C$GEI$OUTPUT$CONNECTION HGTOCN.LIT

C$GET$OUTPUT$PATHNAME HGTOCN.LIT

A-6 Programrning Techniques

EXAMPLE

PROGRAMS

Aside from the literal files shown in Tables A-1 through A-4, two

other important literal

files exist: COMMON.LIT and IAIORS.LIT. COMMON.LIT contains many literal

declarations commonly used in PL/M-286

programming.

You should include this file in

all

your

PL/M-286

programs.

IAIORS.LIT contains the structure for the I/O Result

Segment (IORS) returned in most BIOS System Calls. You should include this file in all

your

PL/M-286

programs that

make BIOS System Calls.

4.2.2.3 Gening and Setting

Terminal Atlributes

Many new users have difficulty understanding how to set the desired attributes for a

terminal. Before

you

set the terminal attributes,

you

must first

get

the current

attributes

by invoking the A$SPECIAL

(BIOS)

System Call or the S$SPECIAL

(EIOS) System Call

with

the spec$func

parameter

set to f$get$mode. The main

program code illustrates both

these calls. The only

visible

difference between the two calls is the

structure of the I/O

Return Segment used.

Refer to the main

progtam

code in the iile DEMO.P28.

To set terminal attributes,

this

code first sets

the current terminal attributes bv callins A$SPECIAL as follows:

CALL rq$a$special (ci$conn, SPECIAL$GET$TERM$DATA,

€cern$atts,

read$mbx,

Gstatus);

In this

call,

the literal SPECIAL$GET$TERM$DATA specifies that

are

getting

current terminal attributes. The

pointer

@term$atts

tells what data structure to

place the

attribute data into. The token read$mbx indicates the mailbox to

which

the IORS

arrives.

The code then

waits

indefinitely until the I/O Result Segment arrives. The

following

statement

illustrates

how the code waits:

lors$tkn - rq$receive$nessage (read$mbx, INFINITE$WAIT, NIL,

Gstatus

) ;

The main code then checks to make sure that terminal data

did in fact arrive by checking

the status ofthe I/O Result Segrnent. A zero indicates that the I/O operation was

successful.

Because

A$SPECIAL

and not S$SPECIAL was used to

get

the

terminal information,

must specifically delete the I/O Result Segment.

It is okay to delete the I/O Result

Segment at this point because the current

tcrminal data now resides in the

data structure

term$atts. Deleting the I/O Result

Segment frees that memory

for other uses.

Programm

ing Techn iques A-7

EXAMPLE PROGRAMS

The main

program code next modifies

two terminal attributes

to cause no line

editing and

no echoing

of keystrokes to the

screen, The code modifies

these

attributes using the

followins code:

terD$atts . connec

tion$ flags - ( (

tern$atts. connect ion$ flags

(Nor C$MASK$LINE$EDÌT)

) oR 1)

csMAsK$ECHO;

AND

This long assignment statement

effectively uses AND and OR logic to alter the

least-significant three bits of the 16-bit

connection$flags element

of the term$atts data

structure. The literals C$MASK$LINE$EDIT

and C$MASK$ECHO

are equal to 3 and

4, respectively. Refer to the Extended |RMX II BIOS System Call Manual for detatled

information about A$SPECIAL

and the data structure term$atts.

The use of the Iiterals, C$MASK$LINE$EDIT

and C$MASKI$ECHO,

defined in the

literal file TSCRN.LIT, facilitate

the setting of the attributes by sparing

you

from having

to type in the correct 16-bit binary sequences. It also makes

your program much easier to

understand, especially at a future date

when

you are trying to remember exactly

which

attributes you were trying to set when you wrote the program.

The main

program

code uses

the S$SPECIAL system call as shown below to

write

the

modified terminal attributes back to the file

ci$conn (the physical terminal connection).

CALL rq$s$special (ci$conn, S PEcIAL$s ET$TERM$ DATA,

eterxo$atts, NIL,

Gsratus ) ;

Notice that with the S$SPECIAL call, it is not necessary to specifically

delete the I/O

Result Segment. The operating system handles the task synchronization

(the

RQ$RECEIVE$MESSAGE)

and the IORS deletion for

you.

In summary, to change terminal attributes, you must first get them using

A$SPECIAL or

S$SPECIAL, alter them, and then set them again

using

either A$SPECIAL

S$SPECIAL.

If you

use A$SPECIAL, you must delete the IORS resulting from the I/O

operation. Ifyou use S$SPECIAL, the operating system takes care of IORS

deletion

for

you.

NOTE

Although, this example uses both versions

the special

call

(A$SPECLA.L

and S$SPECIAL), no reason exists that you could not use one version

alone.

A-8 Pnrgramming

Techniques

EXAMPLE

PROGRAMS

4.2.2.4 Crealing Tasks

When writing an application, you

will normally find that it takes several tasks to

accomplish thejob. Normally, you

code separate tasks in

separate files (modules) to ease

the maintenance of the tasks. Then, from the main

program, you

use iRMX System Calls

to create task objects for the individual modules the applìcation requires.

In this example, only two tasks exist: the main program code (in the file DEMO.P28) an<J

TASK2 (in the file TASK2.P28). Thus, in the main program code, TASK2 is created and

given

priority

lower than that of the creating task

(the

main

program

code).

Regardless

of the number of tasks

your particular

job

may have, the

principles

for task creation

remain the same.

The following code shows how the

main

program code creates and assigns a priority to

TASK2:

task - rq$create$task ( (rq$get$priority (

0ALLER,

ta tus

) - l),

@task2,

selector$of(NIL), NIL, 1024,

0, Gs

catus

) ;

CALL error$check(270, status ) ;

Imbedded in the CREATE$TASK System Call is

the

GET$PRIORITY

System Call. The

GET$PRIORITY System Call

gives the

new

task a priority one level lower than that of

the task creating it (the

higher

the numeric value the lower the

priority).

It is also

possible to assign an absolute priority if you so desire.

The data segment

parameter of the CREATE$TASK call is set to SELECTOR$OF(NIL),

which

indicates

that the task sets up its own data segment.

The stack pointer

parameter

is set to NIL, which indicates automatic stack

allocation.

Automatic

stack allocation means that the NUCLEUS dynamically creates the

stack for

the new task. The stack size of the new task has been set to 1024

bytes

(the

parameter),

which

is a fairly arbitrary number. If a task

will

be making

NUCLEUS

System

Calls,

the stack size should be at least 300 bytes. If you

assign

a stack size which is

too small, the operating system informs you

with

a General Protection

fault during the

task's execution.

Finally,

the task

flags

parameter has been set to zero,

which

designates

that the new task

has no floating-point

instructions.

For

detailed information on the system calls described

in this section, refer to

the

Extended LRMX II Nucleus System

Calls Reference Marutal.

Pmgrammlng

Techniques A-9

EXAMPLE PROGRAMS

A.2.2.5 Cataloging Objects

It is

possible

to catalog the key objects of a

job. By cataloging objects,

you

allow other

tasks the ability to look up the objects they need for processing

at run time. Also,

you grve

modules a higher degree of independence

from

other

modules. Another useful

reason to

catalog the key objects is to provide you with a helpful debugging tool. Ifyou are using

Soft-Scope 286 or the System Debugger to debug your programs, the advantage of having

your

objects cataloged is that

you

have a way to correlate TOKEN values with the names

you have assigned

in your program. The VIEW DIRECTORY command displays all

cataloged objects and their respective character strings.

A-10 Programming

Techniques

EXAMPLE PROGRAMS

This example catalogs several objects. The

following statements from the main

program

code in the file DEMO.P28

show how to use iRMX System Calls

to catalog the objects

described as MBX,

SEMAPHORE, BUFFER, and TASK2.

CALL rq$catalog9obj ect (CALLER,

uall$box, €(3,'l'fBX'), @status);

CALL error$check(220, status ) ;

senaphore - rq$create

s emaphore

(0, 3, FIFo$QUEUING,

@staLus);

CALL error$check (

2 30

s catus ) ;

CALL rq$caÈalog$obj ect (CALLER, sernaphore, @(9,

'SEMAPHORE'

) ,

Gstatus);

CALL error$check( 240, sratus);

pool$tkn' create$buf$pool(18,

18,0,SIZE(buffer),Gstatus)

CALL error$check(250,scacus) ;

CALL rq$caralog$obj ec t (CALLER,

pool$rkn, G(6,',BUFFER'),

estaÈus);

CALL error$check(260, status) ;

/* By including Èhe llne $compac

t (

expo rts task2)

ln che subsys.lnc file r,re

have forced cask2 tó be

large nodel and it therefore creates its o\.n daLa

segnent. lt also prèvènts us frón gettlng a warning

when we use @task2 as the Polnter to the starllng

address for the new task.

task - rq$create$task ( (

rq$get$priori ty (CALLER,Gstatus)

- 1),

@task2,

selector$of(NIL), NIL, 1024, 0,

@status ) ;

CALL

error$check(270, status) ;

CALL rq$catalog$

obj ec t (CALLER,

task, Q(5,'TASK2'), Gstatus);

CALL

error$check(280, status) ;

In each

of the above four

calls to CATALOG$OBJECT,

the first parameter

indicates

whose

job object directory

the object

will be cataloged

under. The token

CALLER

indicates

to use the calling

job's

(main program code)

object directory.

The second

parameter tells

which object is going

to be

cataloged. The third parameter gives the

object a name to

be cataloged under. And,

the fourth

parameter

pointer

that

points

to the condition

code

generated

by the

system call.

For more detailed

information about

the system call CATALOG$OBJECI, refer to the

Extended

LRMX II Nucleus System

Calls Reference

Maruul.

Programming

Techniques A-l r

EXAMPLE PROGRAMS

A.2.2.6 Using a Response Pointer During

lnter-Task

Communication

When you

design

application,

tasks need to communicate with one another. For

example, a serving

task

may

need to inform a requesting task that a process is done, or

that it has

received some information. Many times, more than one task needs to

communicate with the same task. For example,

perhaps

a requesting task sends

information to several serving tasks, and then needs to be notified

when

each of

the

serving tasks are done processing data. iRMX System Calls allow you to SEND and

RECEIVE data between tasks and keep track of inter-task communication.

The main program code in the file DEMO.P28 demonstrates how a task sends an object

to another task (TASK2). The following code from the main program code shows the

iRMX Svstem

Call SEND$MESSAGE:

D0 t - 1 to 3;

buff$tkn - rq$request$buffer(pool$tkn,sÍze(buffer),Gstatus) ;

CAII, error$check (

2 90

status) ;

buf fer - wri.te$read(@message$2,

SIZE

(message$2

), INFINITESÍ./AIT,

@status);

CALL error$check( 300, starus) I

/* A semaphore is belng passed as

thè exchange to lrhich the response should be sent,

CAII rq$send$nessage

(rnall$box, buff$tkn, semaphore,

@status) ;

CALL error$check (

310

stacus) ;

END :

/* now waiÈ for thlee responses so thaÈ we know che other task

has processed thè data.

unlÈs - rq$rece ive$uni ts (sernaphore,

3, INFINITE$WAIT,

@srarus);

CALL error$check(320,status) ;

bytes$writ * rq$s$wrlte$nove (co$conn, @message$3,

size(rnessage$3),

Gsratus) ;

CALL error$check(330,status) ;

In the above

code, the main program loops three

times. Each

time through the loop, the

main program

code sends

TASK2 the object buff$tkn. In this example, the

object sent is a

user-supplied

keystroke obtained through

the system call WRITE$READ

just

prior to the

SEND$MESSAGE

call. After sending the keystroke,

the main program

code returns to

the top

of the loop and calls WRITE$READ

wait

for another keysrroke.

A-12 Programming Techniques

EXAMPLE

PROGRAMS

Every time TASK2 receives

an object sent from the

main

program

code, it responds

sending a unit to the object SEMAPHORE. TASK2 knows exactly

where to send the unit

because when the main

progam code issued the SEND$MESSAGE

call, it passed

the

token for SEMAPHORE to the mailbox. Thus,

when

TASK2 does

the

RECEIVE$MESSAGE call, the token for SEMAPHORE can be kept in TASK2's

version

of the

variable

SEMAPHORE (SEMAPHORE is not a global

variable). This technique

makes use ofthe response and response$ptr

parameters

for the

SEND$MESSAGE and

RECEM$MESSAGE calls, respectively. By speciling where

TASK2 is to respond, the

main

program code ensures that TASK2 responds to the

correct task. In applications

where

than two tasks exist, this request/response technique

is critical.

Pmgramming Techniques A-13

EXAMPLE PROGRAMS

TASK2 demonstrates how a task receives

objects and can send units to a semaphore,

thus

ensuring inter-task communication.

The following

code is from the

procedure

TASK2

the file TASK2.P28:

Using the

RECEIVE$MESSAGE

call, TASK2 waits at the previously

created and

cataloged

mailbox to receive

the object token buff$tkn

from the main program

code. The

second parameter

(INFINITE$WAIT) indicates for TASK2 to wait forever until the

object

arrives. The third parameter

(@semaphore)

is the response$ptr parameter.

This

parameter

telÌs

the operating system where

to put the

response token passed

in from the

SEND$MESSAGE

call.

After receiving the

object, TASK2 processes

it. The processing

consists

of printing out a

message to the console

that processing

is beginning, performing

some housecleaning on

the buffer pool

(refer

to Section A.2.2.7 for information

on buffer pools),

and updating

the unit count

for SEMAPHORE.

buff2$tkn - rq$recefve$message

(nail$box, INFINITE$WAIT,

@senaphore, Gstatus ) ;

r.rrlce$nbx

* rq$creace$nailbox (FIFO9QUEUING,

@status)

;

D0 FOREVER

IF status - E$OK THEN

DO; CALL rq$a$wríte (co$conn, @nessage,

size(nessage),

vrlte$mbx, Gstatus);

CALL errorgcheck(540,status) ;

actual - rq$walt$io (co$conn, wríte$mbx, INFINITE$WAIT,

tatus ) ;

CALL

error$check( 550,status)

;

IF buff$tkn o selec tor$of (NIL) THEN

DO; CALL rq$release$buf fer (poo1$

tkn, buf f

$tkn, @s

tatus ) ;

CAII error$check (

560

s tatus ) ;

END

;

buff$rkn - buff2$tkn,

CALL rqgsend$units (senaphore, l, @status);

CALL error$check(590,status) ;

END

;

ELSE

IF status o E$TIl,tE THEN

CALL error$check(600, status) ;

A.l4 Pmgramming Techniques

EXAMPLE PROGRAMS

Updating the

unit count for SEMAPHORE is accomplished

through

the system call

SEND$UMTS. In this

call, TASK2 sends one unit to the object

pointed

to by the local

variable semaphore. Recall

that the local variable semaphore

contains the token

for the

object SEMAPHORE created in the main program code. After updating the

unit count,

TASK2 begins to print the keystroke repeatedly

to the screen,

waiting for another

object

to be received

from the main

program code.

When

the main

program code sends the third and final keystroke

to TASK2, it examines

the number

of units in the object

SEMAPHORE. The

followirg statement

performs

this:

unlts - rq$rece ive$uni te (

semaphore

INFINITE$WAIT

, gsÈatus);

The call to RECEIVE$UNITS waits infinitely until three

units have

arrived at the object

SEMAPHORE. When TASK2 has sent

over the third unit usins SEND$UMTS, the

main

program code conlinues

processing.

In this example,

the

processing is immediate ancl simple.

The inter-task

communication

technique

shown here

would

very valuable in complex

processing such as

when one set

of data sent to a second

task takes longer to

process than a second

set.

In summary,

the system calls SEND$MESSAGE,

RECEM$MESSAGE,

SEND$UMTS,

and RECEIVE$UNITS

can be used

to pass data and

provide needed

synchronization

between tasks. In applications

where more than

two tasks exist,

you can

use the response

parameter of SEND$MESSAGE

and the response$ptr

parameter of

RECEIVE$MESSAGE

to ensure

that tasks respond to

correct requesting

tasks.

A.2.2.7 Using

Buffer

Pools

Buffer Pools

provide your

system

with an available shared

resource

of fixedlength

segments

of memory that can

be used, as needed,

by any task in

your

job

without having

to repeatedly

create or delete

memory segments.

These buffers

can be used

within a task,

passed

between

tasks, and returned to the Buffer

Pool

when processing is

complete,

so as

to be available for

the next task that needs

the memory. Because

the allocation

memory is a

very slow process relative to other system

calls, it is

good programming

practice to create

your Buffer Pools at the beginning

ofyourjob. Once the Buffer

Pool is

created, it is

simply a matter of requesting

and releasing buffers

within

the

Buffer Pool to

make use

of the memory.

Both the main

program code and TASK2

make use of Buffer

Pools. The

main

program

code initially

creates the

the Buffer Pool and requests

buffers.

TASK2 releases

buffers

back to the Buffer

Pool. The relationship

illustrated between

the main

program code

and

TASK2

is one of a

supplier task and a consumer

task. The

main program

code is

requesting the

buffers

(supplying) from the Buffer Pool,

while TASK2

is releasing

(consuming) buffers back

to the Buffer Pool.

Programming

Techniques A-r5

EXAMPLE PROGRAMS

First,

let's

look at the code that creates the Buffer Pool. The main program code uses the

following code to make a call to the

procedure

CREATE$BUF$POOL:

pool$tkn - creaÈe$buf$pool

(

18, 18, 0, SIZE(buf fer), @status)

;

CALL ètror$check (

250, status ) ;

CALL rq$catalog$obJect (CALLER,

pool$tkn, €(6,'BUFFER'), @status) ;

CALL error$check( 260, status) ;

This call

passes parameters

that define the

buffer

pool. The token pool$tkn is used to

reference or identif the Buffer Pool. The

next two

parameters (18

and 18) indicate the

maximum number

of buffers in the pool and the

initial number of buffers. The

parameter

"SlZE(buffer)"

returns

the

value

of one. Thus, the size of each buffer created

will by only

one byte long. Finalìy,

"@status',

is the token that points

to the

word containing the status

the

call.

Notice that after the

main

program

code calls CREATE$BUF$POOL,

it makes a system

call

to CATALOG$OBJECT to catalog the newly

created Buffer Pool.

The

Buffer Pool is actually

created in CREATE$BUF$POOL

in the file CRBPOOL.P28.

The following code shows

how the Buffer Pool

is created using iRMX System Calls:

A-16 Pmgramming Techniques

EXAMPLE PROGRAMS

create$buf$pool : PR0C EDURE

(nax_bufs , init_nun_bufs, attrs, sizè,

sÈatus_ptr) TOKEN PUBLIC

;

DECIARE ,/* Paraneters *,/

nax_bufs I.IORD, /* naxlnun mlnbe r of buffers ln

buffer Pool */

init_num_bufs WORD, /* inÍtlal nurnbe r of buffers in

pÓol */

attrs !IoRD, /* buffer pool creation

attÍibutès */

slze woRD, /* síze of buffers in buffer

PooL */

status_pÈr POINTER

i /* exceptlon pointer */

DECIARE /* Local Pararìeters */

scatus BASED status Dtr l,loRD

buf_poo1

buf_tok

ToKEN, /* buffer pool cornplete

wlth buffers */

ToKEN, /* buffer token *,/

llORD; /* locaL lndex */

DECLARE l* L|terals */

BFTAGS LITERALLY '0108'; /* single buffer, don't

release */

buf_pool - rq$ create$buffer$pool (nax_bufs

, attrs, status-Ptr);

CALL

error$check( 10, status ) ;

D0 1- I to lnit_mln_bufs;

buf_tok : rq$creaÈe$segment(size, staÈus_ptr) ;

CALL error$check(20, status ) ;

IF status o E$oK THEN

RETURN sel-ector$of

(NIL) ;

CALL rq$re leas e$buffer (buf_pool , buf_tok, BFIAGS, status-ptr);

CALL error$check( 30, s tatus ) ;

IF status o E$oK THEN

RETURN selector$of (NlL) ;

END

;

RETURN

buf_poo1 ;

END create$buf$pool;

END crbpool;

Programming

Techniques a-17

EXAMPLE PROGRAMS

In order for the

procedure CREATE$BUF$POOL to create the Buffer Pool,

several

sysrem calls are used. First, a call to cREATE$BUFFER$POOL

is made. This call

creates a Buffer Pool in which 18 buffers are allowed and no data chaining between

the

buffers can occur. Next, the routine loops 18 times

(one

for each buffer allowed in the

Buffer Pool). Each time through the loop,

system calls are made to

CREATE$SEGMENT and RELEASE$BUFFER. Each time these calls are made, a

one-bye memory segment is created and released for use to the Buffer Pool. When

the

loop finishes, 18 individual one-bye buffers reside in the Buffer Pool ready for use by any

task.

In order to use buffers from the Buffer Pool, the main program code and TASK2 must

request and release buffers. Recall that when the main program code was involved in its

loop

send user-supplied keystrokes to TASK2, that the object being sent was a buffer.

Let's look at that code again to see how it requests a buffer from the Buffer Pool and

waits

for data to arrive in it.

DO f - 1 to 3;

buff$tkn * rq$ reques

t$buffer (pool

tkn, slze(buffer) ,@status) ;

CALL error9check (

290

stacus) ;

buffer - wrlte$read (@rnessage$2,

SIZE(message$2),

INFINITE$I.IAIT

, Gs

tatus ) ;

CALL

error$check(300,status) ;

/* A semaphore ls belng passed as

Èhe exchange co which the response should be senÈ.

CALL

rq$ s end$rne s sage (rnail$box, buff$tkn, semaphore,

Gstatus);

6ALL error$check (

310

status) ;

END :

The

first statement in the

loop makes a system call

to REQUEST$BUFFER to return

token

for the buffer. The program

then

waits

indefinitely

for the user to enter a keystroke

using the WRITE$READ system

call. When a key is pressed,

the character goes

into

buffer, which

is a variable

BASED on buff$tkn. Thus, the character

is captured in the first

available buffer from the Buffer Pool. The main

program

code

can now proceed to send it

to TASK2 throush the

mailbox MBX.

A-18 Programming Techniques

EXAMPLE PROGRAMS

After TASK2 receives the buffer,

it releases the buffer so

it is not sitting idle. The code

below

shows how TASK2 releases

buffers from the

Buffer Pool:

DO; CALL rq$a$write (co$conn, Gmessage,

size(xnessage), lrritegmbx,

tatus ) ;

CALL error$check(540,stetus) ;

acEual - rq$walt$io (co$conn, wrÍte$nbx, IN!'INITE$WAIT,

@srarus

) ;

CALL error$check( 550

status ) ;

IF buff$tkn o sè lec rÒr$of

(

NIL) THEN

DO; CALL rq$release$buf

f er

(poo1$

rkn, buf

$rkn,

rarus

) ;

CALL

error$ check

(

560

status) ;

END

;

buff$rkn - buff2 $

tkn ,

CALL rq$send$units (senaphore, 1, Gstatus);

CALL error$check( 590, status ) ;

END

;

At this point, TASK2

has already received the

buffer at the mailbox. The loop above is

performed

every time the

main program code sends over

a keystroke. The first time

through the

loop, the

variable

bufflitkn is

equal to selector$of(Ml-),

which

is zero. Thus,

TASK2 skips around the

code that releases the buffer

back to the Buffer Pool. The

reason this code is skipped

is because the character

needed is still in the the buffer and

TASK2

must

get

it. The statement "buff$tkn

= buff2$tkn" captures the

data from the

buffer

into another area of memory

local to this task.

TASK2 is now free to later release

the buffer since it is really

no longer of any use.

TASK2 continues

processing

the

keystroke until another

keystroke is received.

The

second and third times through

the loop, TASK2 releases the buffer used during the

trip through the loop by calling

RELEASE$BUFFER. The code releases the

buffer before capturing

the currently received keystroke.

The

parameter

buff$tkn

contains the token that indicates which

buffer to release

(the

same buffer

requested

the main

program

code for the previous

loop

pass).

After releasing the buffer, buff$tkn

can then be set

equal to buff2$tkn, the token

of the buffer containing newly arrived

keystroke.

In summary, it is the responsibility

of the calling task to create and set up Buffer Pools

used between tasks that share data. Once the

Buffer

Pool has been established. the

calling task must request a buffer, get

data into it, and

pass

the buffer

the serving

task.

After receiving the buffer, the

serving task must secure the data

and release the buffer

back to the Buffer Pool for

possible

use bv other tasks.

Pmgramming Techniques A-19

EXAMPLE PROGRAMS

For detailed

information

on the system

calls used

with Buffer Pools, refer

lo the Extended

\RMX II Nucletu Syuem

Calls Reference

Marunl.

A.2.2.8 Methods

ol Screen

Input/Output

During an application

that involves

keyboards

and terminal

screens,

you

will probably

find

it necessary

to be able to read

and

write information

to and from the console

screen.

This

example

shows two of three

methods

that

you can use to perform this type

of I/O.

A very simple type

of I/O is

demonstrated

through

a Human Interface

System

Call. Thrs

call is

shown in the file DEMO.P28

in the

procedure CLEAR$SCREEN. The following

code shows

the

orocedure:

clear$screen: PRocEDURE;

DECISRE i IIORD

cr$lf$str(*) BYTE DATA

(2,cR,LF);

DOi-1ro25;

CALL rq$c$send$eo$response

(NIL, 0, @cr$lf$str, Gstatus);

END

;

END

clear$screen;

In the above

procedure, the

call to C$SEND$EO$RESPONSE

is used to

clear the screen.

This

procedure

calls

C$SEND$EO$RESPONSE

25 times.

Each time the call

is made, the

system sends a

carriage return and line

feed to the terminal.

The parameter ML

indicates that

no response is expected

back from the user.

Thus, the screen is

cleared.

This method of I/O is simple and

quick. Using this call,

you

can also

cause

your program

wait

and receive

a response from the terminal.

To receive a response,

provide

appropriate

values for the first two call

parameters.

Refer to the Extended

|RMX Human Inteface Svstem

Calls Manual for more information

on this

system call.

A-20 Programming

Techniques

EXAMPLE PROGRAMS

The second and third

methods of terminal

I/O involve

using BIOS System Calls.

Borh

methods

also require that you

establish

connections that can be

used to

write

to and

read

from

the terminal.

The following statements

from the

main

program

code in the

file

DEMO.P28

show how

to establish

these connections:

The above code

creates a new physical

file and its connection

ibr terminal output :CO:

and

creates a connection

to the existing

terminal input file

:Cl:. After creating the

connections,

the

program

then opens the :CO:

file as

WRITE$ONLY

and

the:CI: file as

READ$ONLY. Now,

whenever

the application needs ro perform

terminal output, it

writes

co$conn. And,

whenever

the applìcation wants

to read from the terminal, it

reads

from ci$conn.

A second method of

I/O that this example

shows is demonstrated

using the following

code

from the

procedure

WRITE$READ

in the file DEMO.P28:

CALL

rq$a$wriEe (co$conn, msg$ptr, rnsg$size, wrire$nbx, Gstatus);

CALL

error$check(2000,status) ;

ac tual-rq$wai t$

io (co$conn, write$rnbx, INFINITE$WAIT,

@sratus);

CALL error$check(2010, s tatus ) ;

The

above code

writes

message to the terminal. The call

to A$WRITE sends the

message addressed by msg$ptr

to the screen. After the I/O is

performed,

the system

returns

an I/O Result Segment (IORS)

to the mailbox write$mbx. The

IORS contains

information

about the

I/O call. Next, a call to WAIT$lO is made.

This call

returns

the actual number

of bytes

written

in the previous

A$WRITE call. Notice that the

time specified to wait

for

WAIT$IO

return data is indefinite. Thus,

when

data does

arrive, the

procedure

knows

that the I/O operation has completed. The call WAIT$IO

also performs one other convenient

operation for the

programmer

it recycles the IORS

for

A$READ, A$WRITE, and A$SEEK

calls and deletes the IORS for all other BIOS

calls.

The user

does

not have to specifically perform the deletion.

co$conn-rq$s

$create$

fi le (@(4,':C0:'),

CALL error$check( 100

status ) ;

c i

$conn-rq$

$aÈtachg

fi.le (G(4,':CI:'),

CALL èrror$check(110, status ) ;

CALL

rq$s$open (co$conn, WRITE$ONLY,

CALL error$check( 120

status);

CALL rq$s$open (ci$conn, READ$ONLY,

CALL error$chèck

(

130

status) ;

tatus ) ;

Gstatus ) ;

Programming

Techniques A-21

EXAMPLE PROGRAMS

A third method

of I/O (not demonstrated

in this

example) that

can be used

very similar

to the second example

above.

This method

also involves

using read and

write system calls

to the

previously defined

files :CO:

and :CI:. With this method,

however,

no subsequent

call is made

to WAIT$IO. Because

no call is made

to WAIT$IO, the

programmer must

wait at the mailbox

designated

for the

IORS, extract

information from the mailbox

about

the I/O operation,

and then

delete the IORS.

For more information

about

the calls

used to perform

terminal I/O, refer

fo the Extended

.RMX II EIOS System

Calk Manual aÍd rhe Extended

|RMX II BIOS System Calls

Marutal.

A.2.2.9 Simultaneous

Input/Output

The final concept

that thís

example demonstrates

is simultaneous

Input/Output.

That is,

one

task can be

performing or waiting

for input while another

task is

processing or

performing

output.

Once the initial

job

environment

is established, the function

ofthe main

program code is

to collect

three keystrokes

from the user. As shown before, the main program code

accomplishes

this function using the

following

program loop:

D0 l - 1 to 3;

buf f

ckn - rq$request$buf

fer (pool$tkn, size (buffer), QsLatus ) ;

CALL error$check (

290

status) ;

buffer - write$read (Gmessage$2,

SIZE(nessage92),

INFINITE$I^IAIT,

tatus ) ;

CALL error$check (

300

status) ;

/* A senaphore is being passed as

the exchange to whlch the response should be sent.

CALL rq$send$message

(nai1$box, buff$tkn, senaphore, €stetus);

CALL

error$check

(

310, status);

END

;

As shown above, the main

program code waits for the keystroke. If the user does

not

enter one, the

program continues to

wait virtually

forever. Each time a keystroke

provided, the program "wakes up" and processes it by sending it off to TASK2. After

sending the

keystroke, the program resumes waiting for another keystroke.

A-22 Pmgramming

Techniques

EXAMPLE PROGRA,MS

When

TASK2 receives the keystroke, it performs some processing such as releasing

the

buffer the data arrived in and completing its half of some inter-task

communication.

After this initial processing,

TASK2

writes

the received keystroke

to the terminal at the

rate of one character

per second. TASK2 continues

to write keystrokes until it receives

another one. The following code shows how TASK2 indefinitely

prints

the current

keystroke and

waits for the next one:

CALL rq$a$write (eo$conn, build$ptr(buff$ckn,0), 1, write$mbx,

@status

) ;

CALL error$check

(

610

status) ;

actual - rq$wait$lo (co$conn, wrlte$rnbx, INFINITE$I,JAIT,

@status) i

CALL error$check( 6 20

status) ;

buff2$tkn - rq$rece ive

$ne

s sage (nail$box, 100, @senaphore,

tatus ) ;

In the above code, the first four lines aocomplish

writing the contents ofthe buffer from

the Buffer Pool out to the screen.

The last system call to RECEIVE$MESSAGE

waits for

one

second at the mailbox mail$box for the arrival

of the next buffer (the next

keystroke).

If one second elapses, control loops

up and eventually returns to the first four statements

that again output the keystroke

to the screen. If the next buffer

arrives at the mailbox

before the second

elapses,

TASK2

begins

processing

the new

keystroke at the

top of the

infinite loop.

As can be seen from the timing of the I/O from the two tasks, the main

program code is

clearly waiting for, receiving, and

processing keystrokes at the same time

that TASK2 is

writing

the

previous keystroke to the terminal and

waiting to receive the next

one. Thus,

input from the terminal and output to the terminal

can be occurring

in two separate

tasks

independent of one another.

A.2.3

Compiling and

Binding the

Code

Along with the source code files are t$r'o files you can use to compile and bind the job.

The file COMPILE.CSD compiles the source code into object modules. The file

DEMO.CSD binds the job into an executable

program named EXAMPLE.

Programming

Technlques L-23

EXAMPLE PROGRAMS

To compile the

example, enter

the Human Interface

command SUPER

and supply

the

appropriate

password.

Running

under SUPER

gives

you

all the needed

file access

rights

to run

the example. Next, enter

the following command from

the directory

that contains

the example's files:

This command executes

the submit file COMPILE.CSD.

This file initiates the

compilation

of all the

jobs

source code files. After compilation,

you should have one

object file for each

source code file in the

job.

bind the example, enter the following

command:

This

command executes the submit file DEMO.CSD. This

file binds the example and

places

the executable

program

in the file EXAMPLE in the current default directory.

NOTE

Ifyou wish to generate the example as another user, create new directory,

copy the example's files to the new directory, move to that directory,

submit COMPILE.CSD, and submit DEMO.CSD. Generating the

example from another directory allows

you

to alter source code,

while

keeping the

original

version

intact.

4.2.4 Running the

Example

You should now have a file called EXAMPLE that

you

can execute. To run the example,

tvDe its name as follows:

A-24 Pmgramming

Techniques

EXAMPLE PROGRAMS

After typing the filename, the example

prompts you with the following message:

At this

point,

the example

is executing code in the PROMPT$AND$WAIT

procedure in

the file DEMO.P28. The example is

counting down from 60,

waiting for you to

press a

key to start things

going. The string

<lm>

in the

previous screen is the decrementing

count. To continue,

press

a key. After

pressing any key, the example

clears the screen

and

prompts you

with

the following message:

Please hit a key which will be forlrarded to task2 for processing.

Let's assume

you enter the letter X for

the first

"counted"

keystroke.

The example reads

the X from the

terminal and passes it on to TASK2. TASK2

"wakes up" and

prints out the

following message

to the screen:

TASK2

PROCESSING

Please hit a key which will be forwarded to cask2 for processing

'..

The X characters that TASK2

prints

the screen continue to

appear at the rate

ofone

per second. The character

will repeat indefinitely

until you

enter

another keystroke.

Also, notice

that the

prompt

to enter another keystroke

is buried

in the middle of

TASK2's

processing message and the string of letters

that it displays.

A close examination

of the main program code and TASK2

show the synchronization

used to time

the output

of these tasks. The tasks use a

semaDhore to achieve task

communication.

1RMX

II PLIH Exanple, V3.0

Welcorne

to the PL/,! Demo

Program!

At the prompt you will be given 60 seeonds to hit any key.

If yÒu do not hlt a key thè demo

vlll continue anway.

You nay hlt an "E" if you wish to exiÈ Èhe prograu.

You now have (xx) seconds left to hic a key.

Pmgramming

Techniques A,-25

EXAMPLE PROGRAMS

Entering the next two keystrokes

conclude the example. The following

output assumes

you

enter the

characters

Y and Z:

TASK2 PROCESSING

Please hlt a key which wlll be forwarded to task2 for processlng

....

îASK2 PROCESSINC Z

Thls concludes the PL/M Demo Program.

This vould be a good time to exanine the program code to see hov

these features work.

l.le wiII no',r exit by generacíng an error.

INTERNAL ERROR AT il 340 STATUS

: QQ23: E$SUPPORT

After

you

enter the final keystroke, the main program

code recognizes that

you

have

entered

three characters. This fact signals

the code to end the

program.

Notice that the

main program code

ends the

program

before TASK2 can begin printing

the third

character to

the

console

screen.

4.3 EXAMPLE 2

TASK

COMMUNICATION

The second

example is a simple one

that shows one method that two

tasks can use to

communicate with

each other.

The example is written

in PLIM-286 and can be invoked

by the operator

from the

Human Interface level.

A.3.1

Program

Source Code

Figures

A-1, A-2, and A-3

list the source code of

this example. This

example includes

three tasks:

an initialization

task

(called

INIT) that creates

the other two tasks and a

mailbox, and two

tasks

(called

ALPHONSE and GASTON)

that exchange messages via

mailboxes.

The next few paragraphs

discuss how

these tasks operate.

The example runs when

invoked at the

Human Interface

level from the keyboard.

The

task called

IMT runs first, creating

a mailbox that

it catalogs in the root directory

under

the

name

"master.'

It creates the tasks

GASTON and ALPHONSE.

and then susDends

itself.

A,-26 Pmgramming

Techniques

EXAMPLE PROGRAMS

When

GASTON receives control, it gets the token

for the mailbox

created

by INIT (by

looking up the name

"master"

in the root

job's

object directory). It then creates a segment

(in which

it will place

a message)

and a response mailbox

(to which

ALPHONSE will send

a reply). Next it goes into a loop in which

it places

a message in the segment (after

displaying it on the screen), sends

the segment to the master mailbox, and waits at the

response mailbox for a reply.

When

ALPHONSE receives control, it too gets the token for the mailbox created

by IMT

(again,

by looking up the name in the

root

job's

object directory). It then

goes

into a loop

in which

it waits

at the mailbox for a message, checks to see if the token it received is a

segment, and if it is, places its own

message in the segrnent

(after displaying it on the

screen),

and sends the segrnent to the response

mailbox.

By using

the two mailboxes, the tasks ALPHONSE and GASTON are synchronized.

GASTON sends a message to the first mailbox and waits

the second

one

before

continuing.

ALPHONSE

waits

at the first mailbox. When it receives a

message,

it sends

reply to the second mailbox and waits

at the first for another message. This

cycle

continues for 15 messages.

After sending its fifteenth message,

GASTON drops

out of the loop. lnstead of sending a

segment

to the master mailbox, GASTON tJisplays a final message to the screen and sends

the token for a task

(the

token for the INIT task)

to the mailbox.

When

ALPHONSE

receives this token and finds it is not a sesment, ALPHONSE drops out of its loop and

deletes itself.

finish the processing, GASTON causes the INIT task to resume processing

(remember, the INIT task suspended

itself earlier).

When

INIT takes over, it deletes

both offspring tasks and issues an EXIT$IO$JOB system call to return control to the

Human Interface level.

In this example, each of the three tasks are

contained in separate

files. The procedures

for compiÌing

and linking assume that source files are called INIT.P28

(shown

in Figure

A-1), ALPHONSE.P2S

(shown

in Figure A-2), and GASTON.P28

(shown

in Figure A-3).

a-27

Pmgramming Techniques

EXAMPLE PROGRAMS

$compact

$debug

init: DO;

DECIARE token

DECIARE

fi fo

DECIARE

E$OK

DECIARE

self

DECIARE task$priority

DECIARE call lng$task

LITERALLY

BYTE

;

TOKEN

;

TOKEN

;

TOKEN

;

WORD

;

TOKEN

;

TOKEN

;

TOKEN

;

POINTER;

WORD EXTERNAL;

POINTER;

I,IORD

;

WORD

;

,SELECTOR'

;

,0,;

/* An error has occurred

/* Exi t

Figurc A-1. Example PLIM-286 Application

(INIT)

DECTARE

ca l l ing$ tasks $j ob

DECIARE nastersrnbox

DECIARE status

DECIARE init$Èask$token

DECI-ARE gas Èon$ task$ token

DECIARE alphonse$

task$ token

DECIARE alphonse$

s tart$add

DECIARE

gas ton$ start$add

DECI^ARE gaston$ds

DECIARE

alphonse$ds

DECIARE stack$po inter

DECLARE s tack$s 1z e

DECIARE task$flags

gASTON: PROCEDURE

EXTERNAL;

end gaston;

alphonse: PRoCEDURE EXTERNAL;

Y U drPrrur'5c,

inc lude

(/rrnx286/inc/nuclus. ext)

i nclude

(/rux286

/ inc

/ eios. ext)

exit:PROCEDURE PUBLIC;

lF status o E$OK THEN

CAUSE$INTERRUPT(3);

END

;

A-28 Pmgramming Techniques

EXAMPLE PROGRAMS

calling$tasks$j ob : S ELECToR$oF

(

NIL) i ,/* Directory in which to x/

/* catalog obj */.

calling$task : SELECT0R$0F(NIL); /* Task whose

priority will */

,/* be Sotten *

gas

ton9 s tart9 add - @gaston; /* SeC up start addresses */

,/* for tasks *

alphonse$ s tart$ add - @alphonse;

stack$pointer : NIL; ,/* Values for creating tasks *,/

SEaCKìSIZe - lt4H;

task$flags - 0;

initgtask$coken - RQ$GET$TASK$TOKENS

( /* Cet token for init task */

self,

tatus ) ;

IF status o E$OK THEN /* An erroî has occurred */

CALL exit;

CALL RQ$ CATALOC$OBJ ECT ( /* Catalog task token in */

callingStasks$job. /* direclory of calling */

init$task$token, ,/* task's job */

@(4,'init'),

tatus ) ;

IF scaÈus

o E$oK THEN /* An error has occurred */

CALL exit;

master$mbox - RQ$ CREATE$MAILBoX

( /* Create mailbox tasks use */

fifo, ,/* to pass messages. */

@status

) ;

lF status o E9OK

THEN /* An error has occurred */

CALL exit;

CALL RQ$ CATALOG$OBJ ECT ( /* Catalog mailbox in */

calling$tasks$job, /* direcxory of callÍng */

masCer$mbox, /* task's job */

G(6,'master'),

@status ) ;

IF status o E$oK THEN /* An error has occurred */

CALL exit;

task$priority - RQ$GET$PRIORITY

( ,/* Cet prioríty of calling */

calling$task, /* task */

tatus ) ;

IF status o E$OK THEN /* An error has occurred */

CALL exit:

Figure A-1. Example PL/M-286 Application (INIT)

(continued)

Pmgramming Techniques A-29

EXAMPLE PROGRAMS

task$priority - task9Priority + 1; j:

alphonse$ task$ token : RQ$CREATE$TASK

(

task$prlorlÈy,

alphonse$ s tart$add ,

SELECTOR$0F

(@alphonse$ds

stack$pointer,

stack$s1ze,

task$fl-ags,

Gstacus

) ;

IF status o E$OK THEN /*

CALL exit;

gas ton$ task$ token - RQ$CREATE$TASK( /*

task$priority,

gas ton$ s tart$add ,

SELECToR$oF(Ggas ton$ds

stack$pointer,

stack$slze,

task$f1ags,

Gstatus);

IF status o E$oK îHEN

CALL exit;

CALL RQ$SUSPENDgTASK

(

calllng$task,

@status);

IF status o E90K THEN

CALL exlt;

CALL RQ$EXIT$IO$JOB

(

NIL,

Gstatus);

IF status o E$OK THEN

CALL exit;

LoOP: GoTO LOOP;

/* An error has occurred */

Pick lower

new tasks prioricy for */

,/* Suspend self and let

,/* other tasks run

^^.i'rra.l * /

An error has

Create tasks

END

;

,/* An error has occurred */

,/* An error has nnnrrrrarl * /

If we got here, we're

in trouble

lnit

Figure A-1.

Example PLIM-286 Apprication

(INIT)

(continued)

A-30 Pmgramming Techniques

EXAMPLE PROGRAMS

$conpacc

$debug

alphonse: D0;

DECIARE

DECIARE LF

DECIARE token

DECIARE

vait$forever

DECIARE

FOREVER

DECIARE self

DECIARE E$OK

DEoIARE cal l lng$ tasks $j ob

DECIARE

rnas ter$nbox

DECIARE

respons

$rnbox

DECIARE status

DECIARE type$code

DECIARE t ime$

l imi t

DECIARE

count

DECIARE

alphonse$ds

DECIARE

seg$token

DECIARE seg$

s iz e

DECI-ARE

di sp lay$rnes

s age

(

* )

CR,LF, 'After you, Gaston',

LITEMLLY

LITERALLY

LITEMLLY

LITERALLY

TOKEN

;

TOKEN

;

TOKEN

;

WORD;

WORD

;

ifORD

;

I.IORD

WORD

PUBLIC;

TOKEN

;

WORD

;

BYTE

CR, LF);

'13';

'10';

,SELECTOR';

oF['Fr ' .

LTHILE 1

' ;

s ELECTOR$oF

(Nr

L) ',

;

DECI^A,RE message BASED seg$token STRUCTURE

(

count

rext(25)

exit: PRoCEDURE

EXTERNAL;

end exlt;

include (

/rmx286/inc/nuclus .

ext)

$include (/rrnx286

/ Lncl\i .

exx)

alphonse: PROCEDURE

PUBLIC;

tlme$lirnlt - 25;

seg$size

- 32;

cal1lng$ tasks

ob - SELECTOR$OF(NIL);

rnas te r$nbox:RQ$LooKUP$OBJECT

(

cal l ing$ casks

ob,

G(6,

'rnaster'

) ,

wait$forever,

Gstatus);

Figure

A-2. Example PL/M-2Eó

Application

(ALPHONSE)

DATA (

BYÎE ,

BYTE)

;

/* Delay factor for message */

/* display */

/* size of nessage segnent */

/* Directory in which to */

/* look up obj */

/* Look up nessage rnailbox */

Progranming Techniques A-3r

EXAMPLE PROGRAMS

IF status o E$OR THEN /* An error has occurred */

CALL exit;

DO FOREVER;

seg$token - RQ$RECEIVE$MESSAGE

( /* Receive Gaston's response */

nrcrarqmh^Y

walt$forever,

@response$rnbox ,

Qstacus

) ;

IF status O E$oK THEN ,/* An error has occurred */

CALL

exlt;

tyPe$code

: RQSGET$TYPE( /* See what kind of object */

seg$token, /* íL is */

tatus ) ;

IF status o E$OK THEN /* An error has occurred */

CALL exit;

IF type$code o 6 THEN ,/* If not a segnent, stop x/

DO;CALL

RQ$SUSPEND$TASK

(

se 1f

@starus);

IF stacus o E$OK THEN /* An error has occurred */

CALL exit;

END

;

nessage

. count : size(display$rnessage);

CALL MOVB

(Gdi

sp lay$me

s sage

, Gnessage.

rexr , size (displaygmessage)

) ;

CALL

RQ$C$ S END$CO$RES

PONS E ( /x Send

nessage to screen */

NIL,

Gmessage.

count

tatus ) ;

IF status O E$OK THEN /* An error has occurred */

CALL exit;

CALL RQSSLEEP

( /* Wait awhile ro give user */

tine$linit, ,/* time to see the nessage */

Gstatus ) ;

Figure

A-2. Example PL/M-2E6

Application

(ALPHONSE)

(continued)

A-32 Programrnin

Techniques

EXAMPLE PROGRAMS

IF status o E$OK THEN /* An error has occurred */

CALL exit;

CALL RQ$SEND$MESSAGE

( /* Send nessage to response */

response$mbox

, /* ma ilbox *

seg$token,

SELECT0R$0F(NrL),

Qstatus);

IF scatus o E$oK THEN /* An error has occurred */

CALL exlt;

END; /* FOREVER

END; ,/* Alphonse */

END

;

Figure

A-2. Example PL/M-286 Application

(ALPHONSE)

(continued)

$conpact

$debug

gaston: D0;

DECI^ARE

DECIARE LF

DECIARE toKen

DECIARE fi fo

DECI-ARE self

DECIARE

lrait$forever

DECIARE E$OK

DECL{RE

parent$task

LITEMLLY

LITERALLY

LITEMLLY

LlTERALLY

LITEMLLY

LITERALLY

TOKEN

;

TOKEN

;

WORD

;

WORD

;

WORD

;

WORD

;

WORD PUBLIC;

,10,;

,SELECTOR';

'0'

SELECTOR$OF

(

NIL) ' ;

,OFFFFH'

;

,0,;

DATA (

DECIARE

cal l ing$ tasks $j ob TOKEN:

DECI-ARE naster$nbox TOKEN;

DECIARE re sponse

$rnbox

DECIARE

s tatus

DECTARE

tirne$linit

DECLARE

counc

DECIARE final$count

DECI-ARE gas

ton$ ds

DECIARE

seg$token ToKEN;

DECIARE

seg$size tioRD;

DECIARE ma in$rnes sage

(*) BYTE

CR,LF,

'After you, Alphonse',

CR, LF);

Figure A-3. Example

PL/M-2E6 Application

(GASTON)

Programming Techniques A-33

EXAMPLE PROGRAMS

DECI-ARE

flnal$rnes sage

(

* ) BYîE DATA

(

CR,LF, 'If you inslst, Alphonse', CR, LF);

DECIARE nessage BASED seg$token STRUCTURE

(

count BYTE,

text(27) BYTE);

exlt PROCEDURE

EXTERNAL;

end exlt;

include (

/rmx2 8 6/inc/nuc lus .

ext )

include (/rrnx286

/ ír,c

/hi .

ext)

gaston PROCEDURE

PUBLIC;

count - 0; /* lniCialize count */

flnalScount - 15: ,/* Set number

of loops */

tlrne$linit : 25; /* DeLay

factor for display */

/* to screen */

seg$size : 32; /* Size of rnessage

segnent */

calllng$tasks$job : SELECTOR$OF

(

NI L) i ,/* Directory in which to */

/x ì-ook up obj */

naster$nbox - RQ$LOOKUP$OBJ ECT ( /* Look up message rnailbox */

cal l ing$ tasks

ob,

@(6,'rnaster'),

wait$forever,

tacus

) ;

IF status O E$OK THEN /* An error has occurred */

CALL

exÍr;

response$rnbox

: RQ$CREATE$MAILBoX

( /* Create response mailbox */

fifo,

@status ) ;

IF status O E$OK THEN /* An error has occurred */

CALL

exít;

seg$coken

- RQ$ CREATE$ S

EGMENT

( /* create lnessage segnenr */

seg$size,

@status);

IF status O E$oK

THEN /* An error has occurred */

CALL

exit;

Figure A-3. Example PL/M-286 Application (GASTON)

(continued)

A-34 Programm

ing Techniques

EXAMPLE PROGRAMS

DO l,v'}tl

LE count < f inal$count;

message.

counL

- s i ze

(ma

i n$message

)

;

CALL

MoVB

(@ma

in$me

s sage

, @message.

text, SIZE(nain$message)

) ;

CALL RQ$ C$ S END$CO$RES

PONS E ( /* Send message

to screen */

NIL,

/)*^^^^^^ ^^..-*

Yxrr

s s dÉE . LvurrL,

tatus ) ;

IF scatus O E$oK THEN /* An error has occurred */

CALL exit;

CALL RQSSLEEP

( /* tlait awhile to give user */

tineglinit, /* time to see the message */

tatus ) ;

IF status O E$OK

THEN /* An error has occurred */

CALL exit;

CALL RQ$SEND$MESSAGE

( /* Send message to rnaílbox */

naster$mbox,

seg$token,

response$mbox,

@status ) ;

IF status o E$OK THEN /* An error has occurred */

CALL exit;

seg9token : RQ$RECEM$MESSACE

( /* Receive response from */

response$nbox , /* Alphonse */

wait$forever,

NIL,

tatus ) ;

IF status O E$OK

THEN /* An error has occurred */

CALL exit;

count - count+1 ;

END

; /* l,IHtLE x

rnessage

. count : size(final$message);

CALL MOVB(Gfinal$message,@message.

text,SlZE(finaI$message) ) ;

CALL RQ$ C$ S END$CO$RES

PONS

E ( /* Send final message to */

NlL, /* screen */

@message

count ,

Gstatus ) ;

Figure A-3. Example PL/M-286

Application

(cASTON)

(continued)

A-35

Programmin g

Techniques

EXAMPLE PROGRAMS

IF status o ESOK

THEN ,/* An error has occurred */

CALL

exit;

CALL RQSSEND$MESSAGE

( /* send token for rnailbox to */

rnaster$mbox, ,/* mailbox. This wiJ-l stop */

rnaster$rnbox, /* other task. */

sFI Fcrnp qnF

/ N-t T.)

Gstatus);

IF status o E$OK THEN ,/* An error has occurred */

CALL

exit;

parent$task - RQ$ LOOKUP$OBJ

ECT ( /* Look uP token for calling */

' calling$tasks$job, /* task */

@(4,'init'),

vait$forever,

€status ) ;

rF status o E$oK THEN /* An error has occurred */

CALL

exit;

CALL RQ$RESUME$TASK( ,/* Resurne calling task for */

parent$task, /* cleanuP */

Qstatus

) ;

rF status o E$oK

THEN /* An error has occurred */

CALL exit;

CALL RQ$SUSPEND$TASK

( /* Suspend

self just in case */

self,

Gstatus);

IF stacus o E$oK

THEN ,/* An error has occurred */

CALL

exit;

END; /* Gaston */

END

;

Figure A-3. Example

PL/M-286 Application

(GASTON)

(continued)

A.3.2 lnclude

Files

shown in Figures A-l through A-3, each of

the tasks contains

$INCLUDE

statements

to include

the external declarations

of the

iRMX II system calls.

INIT.P28 uses

both

Nucleus

and Extended I/O System calls, so

it includes

the external files

for both those

layers. ALPHONSE.P28

and GASTON.P2S

use Nucleus and

Human Interface

system

calls, so they include

the external files for those two layers.

A-36 Programming

Techniques

EXAMPLE PROGRAMS

Each task

contains its own

set of include

files because

each is a separately

compiled

module.

If the tasks were

all

contained in

the same program

module, only one set

$INCLUDE

statements would

be needed.

4.3.3

Compiling

and Binding

the

Code

The following

command

is used to compile

the three

files of PL/M-286

source statements:

The PLM286

commands do

not include

controls for

selecting the model of segmentation

(SMALL,

COMPACT,

MEDIUM, or I-ARGE)

because the

$COMPACT

control

was

already

included in the source

files.

The compiler

produces

three files

of object code.

Because the PLM2tl6

command did not

speci! names

for the

object code files,

the files are given

the names INIT.OBJ,

ALPHONSE.OBJ,

and

GASTON.OBJ

by default.

After compiling,

the object files

must be bound

together and bound with

the iRMX ll

interface

libraries. The BND286

statement

used to do this is

as follows:

ln this BND286 statement,

the three

object lìles

(INIT.OBJ,

GASTON.OBJ,

and

ALPHONSE.OBJ)

are

bound together with

two libraries:

PLM286.LIB and

RMXIFC.LIB. PLM286.LIB

is the standard

PLIM-286library distributed with

the

compiler. RMXIFC.LIB

the COMPACT version

of rhe iRMX II interface library.

The OBJECT

control specifies

the name of the

executable file generated

by BND286. In

this case, the

file is called SAMPLE.

The

SEGSIZE(STACK( +

1500)) control specifies

that 1500 bytes of stack should

reseryed

in addition to the amount

required by the program.

As listed in Chapter 4, this

amount

represents the amount

required by iRMX II applications that include the Human

Interface.

The RCONFIGURE(DYNAMICMEM(5000H))

control directs BND286 to

produce

STL (single-task

loadable) module and

îo assign a minimum of 5000H bytes of dynamic

memory to the module.

Pmgramming

Techniques A-37

EXAMPLE PROCRAMS

A.3.4

Running

the ExamPle

The BND286

command

produces

an executable

file called

SAMPLE. To run the example,

the Human Interface

prompt type

the name

of the file.

A.4 EXAMPLE 3

CONTROL.C

HANDLER

This

section shows an

example

of a CONTROL-C

handler.

It is

written in PL/M-286

and

uses UDI calls

exclusively.

lt can be invoked

from

the Human Interface

level.

A.4.1 Source

Code

Figure A-4

contains the

source code

for the CONTROL-C

example

(a file called

ECHO.P28).

The main

program echoes

to the screen

any line entered

at the terminal.

However,

before starting

this infinite

loop, the

program installs

a CONTROL-C

handler

and opens

a connection

to the terminal.

The CONTROL-C

handler

procedure called

CC$TRAP) is invoked

when the operator enters

a CONTROL-C

at the keyboard.

resets the CONTROL-C

handler.

issues

a message to

the terminal, and exits

to the

Human Interface.

A-38 Prograrnming

Techniques

EXAMPLE PROGRAMS

$large DEBUG

Pt.l(79) RoM

ECHO DO;

TNcLUDE

(

/RMX2

8 6/rNC/RMXPLM.

EXr

)

DECI.ARE

NUL LITERALLY 'SELECTOR$OF(NIL)

' ,

JOB$ABORTED LITERALLY

CR LITEMLLY ' ODH'

LF LITERI.LLY 'OAH'

READ$WRITE LITERALLY '3' ,

TRUE LITEMLLY 'OFFH'

FALSE LITEMLLY 'O' ;

DECI-ARE

CONSOLE TOKEN,

ACTUAL WORD,

STATUS WORD,

IO$BUFFER( 256 ) BYTE;

DEClARE

INIT$MSG( * ) BYTE DATA

(

CR, LF, ' DNTER

DATA FROM KEYBOARD'

CR, LF) ,

CONTROL$CSMSG(

* ) BYTE DATA

(

CR, LF

GONNA GO BYE BYE

NOW"CR,LF);

CC$TRAP: PROCEDURE PUBLIC;

DECIARE

STATUS 'WORD;

Let the Oneral-or know

thaL we are finished.

CALL DQ$hT.ITE

(

CONSOLE,

@coNTROL$C$MSG,

srzE(coNrRoL$c$Msc),

GSTATUS ) ;

Return control back to the CLI

CALL

DQ$EXIT( JOBABORTED

);

END CC$TRAP;

Figure

A-4. CONTROLC Handler Example

Pmgramming Techniques A-39

EXAMPLE

PROGRAMS

Main line code is required so the APplication Loader gets an

initialization record. We vill open a connection to the terninal

and seÈ a CONTROL-C

handler in place before installing the interrupt

handler. lf a CONTROL-C

is entered frorn the keyboard the CONTROL-C

handler, CC$TRAP,

will reset the interruPt and then call DQ$EXIT

Install the CoNTRoL-C

handler

CALL DQ$TRAP$CC

(

GCC$TRAP,

@STATUS

) ;

Create an open connection to the console. :CI: and :CO:

will

autonatically be cataloged in our job's object directory as Part

of the loading process.

coNsoLE - DQ$ATTACH

(

G(4,':CO:'),

@STATUS

) ;

CALL DQ$OPEN

(

c0Ns0LE,

READ$I.IRITE,

€STATUS

) ;

r-.t^-* Fl-^

CALL DQ$WRITE

(

CONSOLE,

GINITMSG,

SIZE(INIT$MSG),

GSTATUS

) ;

Ii},IILE TRUE;

tr'ntpr forewpr loon echo lines entered at the console.

Read a line frorn the keyboard.

ACTUAL : DQ$READ

(

CONSOLE,

@IO$BUFFER,

SIZE

(

IO$BUFFER)

@STATUS ) ;

Figure A-4. CONTROLC

Handler Example

lcontinued)

A-40 Programming

Techniques

EXAMPLE PROGRAMS

Echo it back to the crt.

CALL DQL'RITE

(

coNsoLE,

@IO$BUFFER,

ACTUAL,

GSTATUS ) ;

END

; /* I,IHI LE I */

END

ECHO;

Figure

A-4. CONTROLC Handler

Example

(continued)

4.4.2

Compiling

and Binding

the

Code

The following

command is used

to compile the code

for this example:

The

PLM286 command

doesn't

include controls for

selecting the model of segmentation

(SMALL,

COMPACT,

MEDIUM, or LARGE) because the

$LARGE

control

was

already included

in the source

files. The ROM

control is also included,

place

the

constants in the data segment.

The compiler places

the

generated

object code

into the file ECHO.OBJ.

After compiling, the

object file must

be bound with

the appropriate iRMX II interface

libraries.

The BND286

statement used

to do this

is as follows:

4.4.3 Running the

Example

The BND286 command produces

an executable

file called ECHO. To run the

application,

simply type the

name of the file at the Human Interface prompt. To invoke

the CONTROL-C

handler and stop

the

progam,

hold down the CONTROL key and type

Programming

Techniques A-41

EXAMPLE PROGRAMS

A.5 HARDWARE

REQUIREMENTS

FOR

REMAINING

EXAMPLES

Sections

A.6 and A.7

show examples

of interrupt

handlers.

Both of these

examples

require hardware

that might

not be available

on all iRMX II systems.

This hardware

includes

an iSBX

350 parallel MULTIMODULE board and

an iCS 920

digital signal

termination

panel. The examples

were developed

using the

iSBX 350 module

mounted

an iSBC

286/ 10A

processor board.

Before running

the examples in

sections A.6

and A.7, you should

configure

the hardware

as follows:

iSBX

350 configuration

. Add

jumper

E5-86,

placing

+5V on Jl pin 50

. Remove

jumper

El-E2 and addjumper

E2-83. This

configures Port A for input.

o Remove

jumper

E13-El4

and add

jumper

El3-E'18.

This configures

the Port A

interrupt

to MlNTR0.

o Install

the iSBC 901 terminator

packs in sockets XU3,

XU5, and XU6.

o Install the 7438

buffer in socket XU4.

iCS 920 configuration

o Connect

jumper

E2-83, enabling the

+5V from

the iSBX 350 to

power the iCS 90

board.

o For

wirewrap matrices J1 through J24, install

jumper

1-2, enabling the LED

indicators. Also install

jumper

3-4

wire

the iSBX signals to the

plus connectors on

the terminal strip. Finally, install

jumper

5-6 to place the

ground

the connectors on

the terminal strip.

Cable configuration

o Connect the iSBX 350

board to the iCS 920 board

with a 50-pin ribbon cable

(3M

33ó5-50 or equivalent).

When fabricating the ribbon, note

that the iCS 920 connector

J25 is

wired the opposite of the iSBX 350

pins.

o Connect the cable to the iSBX 350 board

using a connector equivalent

to one of the

following:

3415-0000

AMP 88083-1

ANSLEY

6Oq.5OI5

SAE SD6750 Series

L-42 Programming

Techniques

EXAMPLE PROGRAMS

. Connect the cable to the iCS 920 board

using a connector equivalent

to one of the

following:

3M 3425-7050

ANSLEY 609.5001M

Switches

. Pull-up resistors are provided to +5V on both the iCS

920 and iSBX

350

boards.

Single-pole, single-throw switches will be

adequate for data inputs 0 through 7. The

interrupt switch should

be a momentary-contact switch.

o Switches 0 through 7 should be wired to terminals A0 through A7 respectively. The

momentary-contact switch should be wired to terminal C4.

NOTE

Because timed interrupt waits

are available

with the Operating System,

testing can proceed without

the interrupt circuit in

place.

iSBC

286/ l0A configuration

. Install the iSBX 350 module in the J5 connector of the iSBC

28ól10A board.

4.6 EXAMPLE 4..INTERRUPT TASK

This example shows an interrupt task that

works with

the

hardware described in the

section. In this example, the interrupt task echoes

the Port

A switches

to the

Port B lights whenever the interrupt switch

togg.led.

This example is invoked from the Human Interface level.

For the example to

work,

the

user must have a marimum task priority of 126 or higher (numerically lower). The

example also includes a CONTROL-C handler, enabling

you to cancel the program and

return to the Human Interface level bv enterins a CONTROL-C.

4.6.1

Source Code

Figure A-5 contains the source code for the interrupt

task example (a file called

INTRTSK.P2S). The program consists of an interrupt

handler, a CONTROL-C

handler,

and

a main

program.

The interrupt handler

(SBXj50$IN1$HNDLR) receives control

whenever the interrupt

switch is toggled. It informs the interrupt task

(the

main

program) of the interrupt

issuing the SIGNAT$INTERRUPT

system call. It performs no other operations.

Progryamming Techniques A-43

EXAMPLE PROGRAMS

The CONTROL-C handler

(CC$TRAP)

is invoked

whenever the

operator enters

CONTROL-C at the keyboard.

When this happens, the routine

invokes the

RESET$INTERRUPT

system call to reset

the CONTROL-C handler and

then exits

the Human Interface

level by invoking

the DQ$EXIT system call.

The main program issues a DQ$TRAP$CC

system call to set up the

CONTROL-C

handler. Then it creates

a connection to the terminal

and initializes the iSBX 350

interface.

When this is complete, it issues

the SET$INTERRUFI system call

to install

the interrupt handler. Finally,

it enters a loop

where

it performs a WAIfiINTERRUPT

to wait for the interrupt signal

from the interrupt handler. When

it receives

notification

the

interrupt,

it reads the status of the switches and

sets the lights accordingly.

Then it

waits for the next interruDt.

$Iarge DEBUG Pt.I(79) ROM

SBX350_MOD:

DO;

WARNING:

In order to run this 1ab from the Hurnan Interface the user must

have the abillÈy to create tasks with a priority of 126. If you

are using dynamic logon terminals the process involves creating

a user with a rnax

priority of 126

or 'less. lf you are usÍng a

static logon terninal, you rnay have to reconfigure your systen.

TNcLUDE

(

/R-r,fX2

8 6/rNC/RMXPi,r'f . EXT

)

DECIARE

NUL LITEMLLY 'SELECTOR$OF(NIL)'

Use MINTRO from an iSBX 350 installed on J5

SBX3

INTR$LEVEL LITERALLY '075H"

JOB$ABORTED LITERALLY '4' ,

CR LITERALLY '

ODH'

LF LITERALLY 'OAH'

READ$WRITE LITERALLY '3' ,

Figure A-5. Internrpt Task Example

A-44 Pmgrarnming

Techniques

EXAMPLE PROGRAMS

SBX3509P0RT$A LTTERALLY ',OAoH',

SBX35O$PoRT$B LTTERALLY ',OA2H',

SBX350$P0RT$C LTTEMLLY ',OA4H',

S BX3 5

O$CONTROL$ PORT LITERALLY 'OA6H"

Set Port A for strobed input and Port B for Mode

0 output

s Bx3 5 0$ rNIT$MODE LTTERALLY ',10111000B',

ENABLE$PORT$A$

INTERRUPT LITEMLLY ' OOOO1OO1B'

;

DECI-ARE

(

CONSOLE ) TOKEN,

(

STATUS ) WORD;

DECIARE

SBXINITMSC

(*) BYTE DATA (

CR,LF,'THE

INTERRUPT TASK IS NOW INITIALIZED',CR,LF),

CONTROL$C$MSG

(*) BYTE DATA (

CR,LF,'CONNA

GO BYE BYE NOIJ"CR,LF);

CC$TRAP: PROCEDURE

PUBLIC;

DECI.ARE

STATUS WORD;

fìlaer rha iht-èrr,'nl-

CALL

RQ9RESET$

INTERRUPT

(

sBx3 50

INTR$LEVEL,

GSTATUS

);

Let the Operator know that r,re are finished.

CALL DQ$\,'RITE

(

c0NsoLE

GcoNîRoL$c$Msc,

sIZE(CONTROL$C$MSc),

@STATUS

) ;

Return concrol back to the CLI

CALL DQ$EXIT

(

JOBABORTED

);

END CC$TRAP

;

Figure A-5. Interrupt

Task Example

(continued)

A-45

Programming

Techniques

EXAMPLE PROGRAMS

SBX35O$INT$HNDLR: PROCEDURE INTERRUPT PUBLIC;

DECIARE STATUS WORD

;

l.pl. thp intcrrunt task do all of the work. The time for a

context slrítch should help in the debounce of the ínterrupc

sr^'i Èch .

CALL RQ$ S ICNAL$ INTERRUPT

( SBX3 50

INTR$LEVEL, @STATUS );

END SBX350$INT$HNDLR;

Maln llne code is require so the application loader gets an

initlallzatlon record.

We will open a connection to the terrninal and set a CONTROL-C

handler in place before installing the interrupt handler.

If a CONTROL-C

is entered from the keyboard, the CONTROL-C

handler, CC$TRAP, will reset the interrupt and then call DQ$EXIT

lns tal l- the CONTROL-C handler

CALL DQ$TRAP$CC

(

GCC$TRAP,

GSTATUS ) ;

Create an open connection to the console.

CONSOLE

- DQ$ATTACH

(

G(4,':co:'),

GSTATUS ) ;

CALL

DQ$OPEN

(

coNs0LE,

READ$L'RITE,

@STATUS ) ;

Figure A-5. Interrupt Task

Example

(continued)

A-46 Pmgramming Techniques

EXAMPLE PROGRAMS

Initialize the SBX3 50 interface.

Port A - Input

Port B - output

Port C - Output

Port A interrupt enabled

oUTPUT(SBX350SCoNTROL$PoRT)

: SBX350$rNrT$MoDE;

OUTPUT

(

SBX3 50

CONTROL$PORT

) : ENABLE$PORT$A$ INTERRUPT

;

-"--t Handler .Lrrc auee!!uP

CALL RQ$S ET$ INTERRUPT

(

sBX3 50$ TNTR$LEvEL,

GSBX3

s0$ TNT9HNDLR

NUL,

GSTATUS ) ;

lh€^rh Èha nnÀ r. r ^?

CALL DQ$I./RITE

(

coNs0LE,

GSBXINlTMSG,

srzE(sBX$rNrr$MsG),

GSTATUS

) ;

Enter forever loop waiting for interrupts.

DO WHILE 1;

CALL RQ$WAIT$INTERRUPT

(

sBX3 5 0$ rNTR$LEVEL

GSTATUS );

l,lait Lo debounce the inlerrupt swÍtch.

CALL RQ$SLEEP

(

GSTATUS

) ;

Crl the innìrl d.eta.

OUTPUT( SBX35O$PORT$B

) : NOT

(INPUT( SBX35O$PORT$A

));

END;

/* WHILE I */

END SBX35O_MOD;

Figure A-5. Interrupt Task Example

(continued)

Programming Techniques A-47

EXAMPLE PROGRAMS

A.6.2 Compiling and

Binding the

Code

The following command is used to compile the code for this

example:

The PLM286 command doesn't include controls for selecting the model of

segmentation

(SMALL, COMPACT, MEDIUM, or I-ARGE) because

the

$LARGE control was

already include<j in the source files. The ROM control is also included, to place the

constants in the data segment.

The compiler places the generated object code into the file INTRTSK.OBJ.

After compiling, the object file must be bound with the appropriate iRMX II interface

libraries. The

BND286

statement

used to do this is as follows:

A.6.3 Running

the Example

The BND286

command

produces

an executable

file called INTRTSK.

To run the

applications,

type the name of the

file at the Human Interface prompt.

To invoke the

CONTROL-C

handler and stop the program,

hold down the

CONTROL key and type C.

4.7 EXAMPLE

5..FIRST-LEVEL

JOB

This section

contains a larger, more

complicated example that

is typical of a real-world

application.

It is a multitasking,

data acquisition application

configure<J

as a firstJeveljob.

Each time

an interrupt

occurs from the iCS 920

board, the application

reads the iCS 920

switches via

the iSBX

350 board installed on the

iSBC 286110A board.

After a number of

interrupts,

the application

calculates the mean,

median, and mode of the

inputs and and

displays

this information at the terminal.

The application

also accepts input from the

terminal

to indicate how

many samples to take

before calculating the

results.

The application

is divided into two

jobs:

a firstJevel

job

that handles all the data

acquisition

and formats

messages for the terminal,

and a terminal

job

that handles all I/O

with

the terminal.

The terminal

job

is an offspring

of the firstlevel

job.

A-48 Programming Techniques

EXAMPLE PROGRAMS

Within the first-level

job are three tasks: an initialization task

(IMTTSK), an interrupt

task

(SBX350TSK),

and a

process

task

(PROCESSTSK).

The

initialization task creates

the other tasks in thejob and also creates the offspringjob.

The interrupt task

collects the

data

from the

iSBX350 board and passes it on to the

process task. The process task

receives instructions

from the I/O job and sends formatted information

to the I/O job.

The terminal

job also contains three

tasks: an initialization task

(TERMIMTTSK), a

terminal input

task

(TERMINTSK),

and a terminal output

task (TERMOUTTSK).

The

initialization task creates the other tasks in thejob and establishes a connection

to the

terminal. The terminal input task reads input from

the terminal. The terminal

output

task sends output to the terminal.

The tasks in this

application communicate

via mailboxes.

The interrupt task creates

and

catalogs a mailbox

called SBX35OMBX

where

it will receive data from the

process task. It

also looks up the name of

the process task's mailbox,

which it uses to send information

the

process task. Likewise, the

process

task creates

a mailbox called PROCIOMBX

and

looks up the

name of the interrupt task's mailbox.

In addition,

the process task looks up

the names of the mailboxes

created by the terminal input

and terminal output

tasks so

that it can

send data to and receive data from the terminal. These

mailboxes,

called

TERMINMBX and TERMOUTMBX are created by

the terminal input

and terminal

output tasks

when they start running.

A.7.1 Source Code

The source code

for this example is divided into five

separate files. INITTSK.P2S

contains the initialization

task for the first-level

job

(INITTSK). It is listed in Figure

A-6.

INITTSK performs the following operations:

. Creates

the interrupt task SBX35OTSK

o Creates the

process

task PROCESSTSK

. Creates the terminal

job

TERM.P28

contains all the tasks in the

terminal

job

(TERMINITTSK TERMINTSK

and TERMOUTTSK). It is listed in Figure A-7.

TERMINITTSK

performs the folìowing

operations:

o Creates a connection

to the terminal and catalogs

it as CONSOLE

o Creates

the terminal input and

output tasks

TERMINTSK

performs the following

operations:

. Looks up

the connection for CoNSOLE

. Creates

the mailbox for

terminal input

and catalogs it as TERMINMBX

Programming

Techniques A-49

EXAMPLE

PROGRAMS

. Starts an infinite loop in

which it

waits

at the TERMINMBX mailbox for an input

request, reads a line of input, and

sends

the

input data to the response

mailbox

specified

TERMOUTTSK performs the following operations:

. l,ooks up the

connection for CONSOLE

o Creates

the mailbox for terminal output and catalogs it as

TERMOUTMBX

. Starts an infinite loop

in which it waits at the TERMOUTMBX mailbox for an output

message, formats

the message and sends it to the console, and deletes

the message

S8X350.P28 contains the code for the interrupt task (SBX35OTSK) and the interrupt

handler

(SBX350INTHNDLR).

This file is listed in Figure A-8,

SBX350TSK

performs

the following operations:

o Creates and catalogs the mailbox SBX350MBX.

. Initializes the

iSBX 350

board.

r Sets the

SBX350INTHNDLR

procedure

as the interrupt handler associated with this

task.

. Looks

up the TERMOUTMBX mailbox and sends an initialization

message

there.

. Looks up the PROCIOMBX mailbox

and sends initialization data there.

. Begins an

infinite loop in

which

waits

at the SBX35OMBX

mai.lbox for a message

indicating the number of samples to

take. For each sample, it

waits

for an interrupt,

obtains

the sample from the iSBX 350 board,

stores the data in an array, and clears

the interrupt. When

it has obtained all the

samples, it sends the data to the

PROCIOMBX.

SBX35OINTHNDLR

simply invokes

the SIcNAIJINTERRUPT system

call. This

passes

control to the

SBX350TSK interrupt task, which

actualìy handles the interrupt.

PROCIO.P2S

contains the code

for the process task (PROCESSTSK).

This file is listed

in Figure

A-9.

PROCESSTSK performs

the following

operations:

. Looks up the

TERMINMBX, TERMOUTMBX,

and SBX35()MBX

mailboxes.

. Creates a mailbox

for communication with

SBX35OTSK and catalogs it as

PROCIOMBX. It waits

at the maiÌbox

to synchronize with

SBX350TSK.

. Sends

parameter

request

message to TERMOUTMBX,

sends an input request

message to TERMINMBX, waits

at the response

mailbox for the terminal input, and

verifies

the input

valid.

PROCESSTSK

continues to perform this step

until it

receives valid

input. Then it sends the valid

message to the SBX350MBX

mailbox.

A-50 Pnlgramming Techniques

EXAMPLE PROGRAMS

. Begins an infinite loop in which

the following operations are performed:

- Waits

at the PROCIOMBX for data from the interrupt task.

- Formats the data and sends

it to the TERMOUTMBX mailbox.

- If no input request is pending,

sends a message to the

TERMINMBX mailbox

requesting

input.

- Checks the

response mailbox without waiting

to see if the operator has responded

with an input request.

- If there is an input request, valìdates

it and passes it to the interrupt task via the

SBX350MBX mailbox.

Then deletes the segment containing the data.

UTIIS.P28 contains

utility procedures used by the various

tasks. The

procedures

include

STRLEN to return the

length of a null-terminated string, BTOA to take a byte value and

convert it to ASCII, ATOB to convert

an ASCII string to a byte

value,

CALC$MEAN to

calculate

the mean, CALC$MEDIAN to calculate the

median,

and CALC$MODE to

calculate the mode. This file

is listed in Fisure A-10.

Programmlng Techniques A-51

EXAMPLE PROGRAMS

$CoMPACT

DEBUG PW(79) ROM

STARTUP: DOi

$TNcLUDE

(

/RMX2

86lrNC/RrO(PLM. EXT)

DECIARE

NUL LITERALLY 'SELECTOR$OF(NIL) ' ,

NO$NPX LITERALLY 'O' ,

ALL$ERRORS LITERALLY '3' ,,

SBX35O TSK: PROCEDURE

EXTERNAL;

END SBX35O_TSK;

TERI,Í INIT TSK: PROCEDURE

EXTERNAL;

END TERX-TNIT-TSK;

PROCIO TSK: PROCEDURE EXTERNAL;

rnn ppÀarn rctz.

Setup public data variable so this can be configured in as

r fi rct l orrol i nh

DECI.A,RE DUMMY$DATA$VARI BLE BYTE PUBLIC;

INIT-TSK: PROCEDURE PUBLIC;

This task ls the initial task of our first level job. It

creates t\^ro other tasks: BX350TSK, which will become the

interrupt task handling digital input, and PRoCIOTSK, which

is responsible for processing the the input data and

providing formatted I/O for the operator. This task also

create a separate job for Lerminal I/O.

DECI.ARE

TERM$JOB$TOKEN TOKEN,

INIT$JOB$TOKEN TOKEN,

sBx3 5o$TASK$TOKEN roKEN,

PROC IO$TASK$TOKEN TOKEN,

STATUS I.'ORD,

DUMMY$EH$STRUC STRUCTURE (

EH$PTR POINTER,

EHSMODE BYTE);

CAUSEINTERRUPT(3);

Figure A-6. First-l-evel

Job

Initialization Task

(INITTSICP2S)

A-52 Pmgrarnming Techniques

EXAMPLE PROGRAMS

SeÈ up che exception handler structure. PLM 286 does not

allow NIL to be used within a DATA declaration. SetuD of

DUMMY$EH$STRUC

nust be done dynarnically. Nore: We còuld

have lied to PLM by declaring EH$PTR ai a DWORD.

DUMMY$ EH9STRUC

. EH$PTR

- NIL;

DUMI'îY$

EH$STRUC . EH$MODE

- ALLSERRORS;

CreaÈe the task which handles digital input from the SBX350.

Note: This wíll become an interruDt Èask.

sBx350$TASK$ToKEN

- RQ$CREArE$rASK(

139,

GSBX350 TSK.

ÈEr.ncroEgor(GDUMMygDATAgvARTBLE),

,/* Initialize rhe DS, as we are */

/* in CoMPACT

,/* Let rmx assign the stack */

NIL,

400H

NO$NPX,

@status );

,/* Stack Size

/* This Lask doesn't use the NPX

/* in COMPACT

/* Let rmx assÍgn the stack */

/* etrrlz (iza

/* This Lask doesn't use the NPX

Create the process control task that manipulates the digital data.

PROCIO$TASK$TOKEN

: RQSCREATE$TASK(

139,

appnaTrr Tcv

SELECTOR$OF(GDUMMY$DATA$VARIBLE),

/* Inítíalize the DS, as we are */

NfL,

400H

NO9NPX,

@status );

Create the terninal job to process console input. The

terminal init task will create an input task and an ourput

task. A job Ís noL actually required for this appl ication

but we are doing it to show

RQE$CREATESJoB.

INIT$JOB$TOKEN

: RQSCET$TASK$TOKENS(

t, ,/* cet thÍs j ob's token. x/

GSTATUS );

Figure A-6. First-I*vel Job Initialization Task (INITTSK.P28)

(continued)

Programming Techniques A--53

EXAMPLE PROGRAMS

TERM$JOB$TOKEN

- RQ$E$CREATE$JOB(

40H, /* We will be cataloging objects in this */

rNrrgJoBgroKEN,

l: i::"".Îl:'i5iTl ."u." ro the rerninar

job */

400H, ,/* Minirmrur

memory

pool */

oFFFFFH, ,/* Mernory

pools can contain up co 16 Megabyces. */

0100H, ,/* Max írnum

objects for this job */

3, /* TERMINITTSK

plus two ochers */

0, /* No lirnit on priority of tasks in this job */

GDUMMY$EH$

STRUC

, ,/* Use SDB as error handler */

0, ,/* Require paraneter checking as this job */

/* nakes BI0S calls. */

139, /* Initial task priority is 139 */

@TERM INIT TSK.

Àer-ncîon$oF(GDÙMMygDATA$vARtBLE),

,/* rnitialize rhe DS, as we are */

/* in COMPACT */

NIL, /* Let rrnx assign the stack */

400H, /* Stack Size */

NO$NPX, /* This task does not use the NPX */

@status );

Inicialization is conDlete. so delete this task

CALL RQSDELETE$TASK(

NUL

GSTATUS

);

END INIT-TSK;

END STARTUP;

Figure A-6. First-Level Job Initialization Task (INITTSICP2E)

(continuedl

A-54 Pmgramming Techniques

EXAMPLE PROGRAMS

cornpac t DEBUG

pw(79) ROM

TERM_MOD: DO;

$INcLUDE

(

/RMx2

8 6/rNc/RMXPLM. Exr

)

DECIARE

NUL LITEMLLY ' SELECTOR$OF

(

NIL) ' ,

CONNECTION$OBJ ECT$TYPE LITERALLY 'OlOlH' ,

PARAMETER$OBJ ECT$TYPE LITERALLY '02',

IIAIT$FOREVER LITEMLLY 'OFFFFH'

PHYS ICAL$

FILE$

DRIVER LITEMLLY '01',

READ$WRITE LITERALLY '3' ,

S}IARE$ALL LITEMLLY '3' ,

DRAU LITERALLY 'OOOO1I11B'

SUPER LITEMLLY 'O' ,

WORLD LITERALLY 'OFFFFH'

NO$NPX LITEMLLY '0"

TRUE LITEMLLY ' OFFH'

FALSE LITEMLLY 'O' ,

CR LITEMLLY 'OAII' ,

LF LITERALLY 'ODH'

;

STRLEN: PROCEDURE( STRPTR

) BYTE EXTERNAL;

DECIARE

STRPTR POINTER;

END STRLEN;

TERMIN TSK: PROCEDURE PUBLIC;

TERMINTSK receives nessages at TERMINMBX.

It performs a

read operation and returns a zero terminated string to the

response mailbox specified during the receive message.

DECIARE

PARA.I.IETER$OBJ ECT9TOKEN TOKEN

TERM$IN$MBX TOKEN,

TERM$OUT$MBX TOKEN,

CONSOLE$TOKEN TOKEN,

BUFFERT TOKEN,

USER$RSP$MBX TOKEN,

BIOS$RSP$MBX TOKEN,

BUFFER BASED BUFFERT

(128) BYTE,

ACTUAL WORD,

STATUS I.'ORD

;

Figure A-7. Terminal

Job

(TERM.P28)

Programning Techniques A-55

EXAMPLE PROGRAMS

Create the mailbox at which keyboard input requests will be received

TERMINMBX

- RQ$

CREATE9MAI

LBOX

(

@STATUS

);

Catalog the mailbox as "TERMIN"

in the parent job.

PAXA.I'Í

ETER$OBJ ECT$TOKEN

: RQ$GET$TASK$TOKENS

(

PARAMETER9OBJ

ECT$TYPE,

GSTAÎUS

);

CALL RQ$

CATALOG$OBJ ECT

(

PARAMETER$OBJECT$TOKEN,

TERM$IN9MBX,

@(6,',TERMrN',),

GSTATUS

);

Lookup the open connection for the keyboard

cONsoLE$ToKEN

: RQ$LOoKUP$OBJ

ECT

(

NUL,

G(7,',CoNsoLE',),

WAIT9FOREVER,

GSTATUS

);

Create the response

rnailbox to be used

with BIOS system calls,

BIOS$RSP$MBX

- RQ$

CREATE$MAI LBOX

(

@sTATUs

);

DO I*iILE TRUE;

Enter forever loop waiting for input requests.

It^i+ F^- ^- i^-.,

warL Lo! a rrrPLlc

requesf.

BUFFERT

- RQ$RECEIVE9MES SAGE

(

TERM$ IN9MBX

WAIT$FOREVER,

@usER$RSPMBX,

@sTATUs );

Figure A-7. Terminal

Job (TERM.P28)

lcontinued)

A-56 Pmgranrming Techniques

EXAMPLE PROGRAMS

Send a read request to the keyboard.

CALL RQ$A$REA-D

(

coNs0LE$ToKEN,

@BUFFER ,

SIZE(BUFFER),

Br0s$RsP$MBX,

GSTATUS );

Wait for a <CR> input fron the keyboard.

ACTUAL

- RQ$WAIT$ IO

(

coNsoLE9TOKEN,

Bros$RsP$MBX,

wAl rìruKÉvt K,

@STATUS

);

The terminal- driver will append a <LF> afrer the <CR>.

We don't want either of thern so zeÍo out the next to last

character.

IF ACTUAL >: 2 THEN

BUFFER(ACTUAL.2):O;

ELSE

BUFFER(O):O;

Send the zero terminated strÍng back to whomever

requested it.

CALL RQ$ S END$MES

SAGE

(

USER$RSPMBX,

BUFFERT

NUL,

GSTATUS );

END; /* DO I.IHILE

1 */

END TERUIN_TSK;

Figure

A-7. Terminal

Job

(TERM.P28)

(continued)

A-57

Programming

Techniques

EXAMPLE PROGRAMS

TERMOUT TSK: PROCEDURE

PUBLTC;

TERMOUTTSK expects to receive zero terninated strings at TERMOUTMBX.

Ic will then write these string ouc to the CoNSOLE.

DECIARE

PARAMETER$OBJ

ECT$TOKEN TOKEN,

TERM$OUT$MBX TOKEN,

CONSOLE$TOKEN TOKEN,

BUFFERT TOKEN,

USER$RSPgMBX TOKEN,

BIOS$RSP9MBX TOKEN,

BUFFER BASED BUFFERT

(1) BYTE,

ACTUAL WORD,

STATUS) WoRD;

Create the mailbox at whích console output rnessages wil-l be received,

TERMOUTMBX

- RQ$ CREATE$MAILBOX

(

GSTATUS

);

Catalog the maílbox as "TERMOUT"

in the parent job.

PARAMETER$OBJECT$TOKEN

: RQ$GET$TASK$TOKENS

(

PARAMETER$OBJECT$TYPE,

@sTATnS );

CALL RQ$CATALOG$oBJECT

(

PARAMETER$OBJ ECTSTOKEN,

TERM$OUT$MBX,

@(7,'TERMoUT',),

@srATUs );

Lookup the open connection for the console.

CoNSOLE$ToKEN

- RQ$LOoKUP$oBJ ECT

(

NUL

@(7,',coNsoLE'),

I'AIT9FOREVER,

GSTATUS );

Figure A-7. Terminal

Job (TERM.EZE)

(continued)

A-58 Programming Techniques

EXAMPLE PROGRAMS

Create the response nailbox Èo be used with BIOS system calls.

BIOS$RSP$MBX

- RQ$CREATE$MAILBOX(

GSTATUS

);

D0 trrHlLE TRUE;

Enter forever loop waiting for input requests.

Yr-|È f^-

warL ro! an ouLput nessage,

BUFFERT

. RQ$RECEIVE$MES SAGE

(

TERM$OUTSMBX,

LTAIT$FOREVER,

@usER$RSPr{8X,

GSTATUS

);

Write the nessage to the console

CALL RQSA$L'RITE

(

coNsoLE$ToKEN,

@BUTFER,

STRLEN(GBUFFER),

BrossRsP$M8x,

csrATUs

);

WaÍt for the nessage to be output

ACTTJAL

- RQ$WArT$rO

(

coNSoLE9TOKEN,

F.lnq(psp(MRY

i.tAlT9FoREVER,

GSTATUS ) i

Nolr deLece the segnent which we received ac TERMOUTMIX.

CALL RQ$DELETE$SEGMENT

(

BUFFERT

GSTATUS

);

END; /* DO IIHILE 1 */

END TERMOUT-TSK;

Figure A-7. Terminal

Job (TERM.P28)

(continucd)

Pmgramming

Techniques A-59

EXAMPLE PROGRAMS

TERM-INIT-TSK: PROCEDURE PUBLIC;

Thls task ls responsible for setting up the connections to

the console and creatíng the tasks TERMINTSK, and TERMOUTTSK.

DECI.ARE

MBX,

Bros9RsP$trBX ToKEN,

DIJI,ÍMY$MBX TOKEN

TERÌÍ$DEV$CON TOKEN,

TERM$FILE$CON TOKEN,

USERST TOKEN,

TERI'ÍIN$TASK$TOKEN TOKEN,

TERMOUT$TASK$TOKEN TOKEN,

IORST TOKEN,

IORS BASED IORST STRUCTURE (

STATUS WORD

STATUS,

ACTUAL ) LIORD,

BUFFER(

256 ) BYTE,

SICNON$MESSAGE

(*) BYTE DATA 'TERMINAL

ONLINE

READY FOR PROCESSING.',OAH,ODH

);

Create the response rnailbox to be used with BIOS systen cal1s,

BIOS$RSP$MBX

- RQ$CREATE$MAILBOX(

@srArus );

Create a device connection the terninal-.

CALL RQ$APHYS I CAL$ATTACH$DEVICE

(

€(2,

',r0,

) ,

PHYS

I CAL$FILE$DRIVER

Bros$RsP$MBX,

@STATUS );

Figure

A-7. Terminal

Job (TERM.P28)

(continued)

A-60 Programming Techniques

EXAMPLE PROGRAMS

Wait for the device connection token to be returned be the BIOS.

TERM$DEV$CON

: RQ$RECEIVE$MES

SAGE

(

Br0s$RsP$MBX,

WAIT$FOREVER,

GDUMMY$MBX ,

GSTATUS

Create a file connection on the terminal device.

CALL RQ$A$CREATE$

FI LE

(

NUL,

TERM$DEV9CON,

G(0),

DRAU

Bros$RsP$MBX,

GSTATUS );

wait for the device connectíon token to be returned be the BI0S.

TERM$FILE$CON

- RQ$RECEIVE$MES SACE

(

BIOS9RSP$MBX,

WAIT$FOREVER,

GDUMMY$MBX

GSTATUS

);

onan ihF t-erminrl File for both read and l,rrite.

CALL RQ$ASOPEN

(

TERM$FILE9CON,

READSL'RITE,

S}IARE$ALL,

BrossRsP$MBX,

GSTATUS

);

Figure

A-7. Terminal

Job (TERM.P2E)

lcontinued)

/* lJser token ignored for physical fi1es. */

/* Subpath pointer ignored for physical fi1es. */

/* Cranularity irrelevant. We are not on a */

,/* Randorn

Access device. */

/* Size irrelevant. lle are not on a Random */

./* Aî^òcc Àaf i îa * /

Programming

Techniques A-61

EXAMPLE PROGRAMS

i.talt for the I/O result segnent to be returned by the 81OS.

roRsr - RQ$RECETVE$IÍES

SAGE

(

Bros9RsP9MBX,

wAtT$FOREVER,

ANIIMMV<MP.Y

GSTATUS );

Catalog the connection token for the open

"coNsoLE".

CALL RQ$CATAI,OG$OBJ ECT

(

NUL,

TERIr$FILE9CON,

G(7,

,CONSOLE'

) ,

GSTATUS );

Create the task that will handle keyboard

TERMIN$TASK$TOKEN

- RQ$CREATE$TASK(

file in the local job as

inpuc .

11q

GTERMIN-TSK,

SELECTOR$oF

(@STATUS

) ,

NIL,

400H

N0$NPX,

Gstatus );

Create the task which will process console output.

TERMOUT$TASK$TOKEN

. RQ9CREATE$TASK(

139,

GTERMOUT-TSK,

sELECîOR$0F(QSTATUS),

NIL,

400H,

No$NPX,

Gstatus );

Delete thyself as nothing more to do.

CALL

RQ$DELETE$TASK(

NUL,

GSTATUS

);

Figure A-7. Terminal

Job (TERM.P28)

(continued)

/* Initialize the

/* Let rnx ass ign

/* <fAîV 9iza */

/* This task does

/* Tniii.l izo r}:.a

/* Let rrnx as s ign

/* ql-r^L 9iza */

/* this task does

DS as we are in COMPACT

the stack *,/

not use the NPX */

DS as we are in COMPACT

the stack */

not use the NPX

A-62 Pmgramming Techniques

EXAMPLE PROGRAMS

IFSTATUSOOTHEN

CAUSEINTERRUPT(

3 );

END TERM_INIT_TSK;

END TERM-MOD;

Figure A-7. Terminal

Job

(TERM.HZ8)

(cnntinued)

$COMPACT

DEBUG

PI,J(79) ROM

SBx350_MoD: D0;

TNCLUDE

(

/RMx2

8 6/rNC/RMXPLM

EXr

)

DECIARE

NUL LITERALLY 'SELECTOR$OF(NIL)'

Use MINTRO from an isBX 350 installed on J5

sbx35o

INTRSLEVEL LITERALLY ,075H, ,

WAIT$FOREVER LITEMLLY 'OFFFFH',

NO$LIAITING LITERALLY 'O' ,

ONESSECOND LITERALLY ' OIOO'

CR LITERALLY ' ODH'

LF LITEMLLY 'OAH'

SBX35OSPORT$A LITEMLLY 'OAOH'

sBx35OsPoRTsB LTTERALLY '0A2H"

SBX35O$PORT$C LITEMLLY 'OA4H"

S BX3 5 OSCONTROLS PORT LITERALLY 'OA6H',

Set Port A for strobed input and Port B for Mode 0 output

SBX3 5 O$ INIT$MODE LITERALLY '1O111OOOB'

ENABLE$PORT$A$ INTERRUPT LITERALLY 'OOOO1OO1B'

;

Figure

A-8. Interrupt Handler

and

Task (SB)350.P28)

Programming

Techniques A-63

EXAMPLE PROGRAMS

SBX3 5O$ INT$HNDLR: PROCEDURE INTERRUPT PUBLIC;

DECIARE STATUS WORD

;

Let the interrupt task do all of the work. The tirne for a

context swlcch should help in the debounce of the interrupt s!,/itch.

CALL RQ$ S IGNAL$ INTERRUPT

( SBX3 50$ INTR$LEVEL,

GSTATUS );

END SBX3 5OS INT$HNDLR:

SX350 TSK: PROCEDURE PUBLIC;

DECIARE

SBX35OMBX TOKEN,

PROCIOMBX TOKEN,

RSPMBX TOKEN,

STATUS WORD,

INPUT$VALUES

(128) BYTE,

ACTUAL BYTE,

NIJMBER$OF$

SAMPLES BYTE,

SBX$INIT$DATA BYTE,

INDEX BYTE;

DECIARE

SBXINITMSC(*) BYTE DATA

(

CR,LF,'THE

INTERRUPT TASK

IS NOI' INITIALIZED

' ,

CR, LF, O

) :

InÍtlallze the SBX350 i nterface

Port A - Input

Port B - Output

Port C - Outpuc

Port A interrupt enabled

oUTPUT

(

SBX3

5O$CONTROL$

poRT

) - SBX3 50$ rNrT$MoDE;

OUTPUT

(

SBX3 5O$CONTROL$

PORT

) - ENABLE$PORT$A$

INTERRUPT

;

sBx35o$MBX

- RQ$CREATE$MAr LBox (

60H

@STATUS ); /* Set up for passing data not RMX objects */

Figurr A-E. Interrupt Handler

and Task (SBX350.P2E)

(continued)

A-M Programming Techniques

EXAMPLE PROGRAMS

CALL RQ$CATAT,OG$OBJ

ECT

(

NUL,

sBx350$MBX,

G(9, '

SBX35O|.ÍBX')

GSTAÎUS );

Install che Interrupt Handler.

CALL RQ$ SET$ INTERRUPÎ

(

sBx3 50$

INTR$LEVEL,

@s8x3

50$ TNTSHNDLR,

NUL,

@STATUS

) ;

PROCTOMBX

- RQ$LOoKTJP$OBJ ECT

(

NUL,

G(9,

'PRocroMBX',

) ,

WAIT$FOREVER,

@STAÎUS );

CALL RQ$SEND9DATA(

PROCIOMBX,

@SBXINITDATA,

GSTATUS );

ACTUAL

- RQ$RECEIVE$DATA

(

SBX35OMBX,

GNUI,IBER$OFSAMPLES ,

IiIAtT$FOREVER,

GSTATUS

);

DO I+IHI

LE 1

;

Enter forever loop waiting for interrupts.

D0 INDEX

- 0 T0 ( NUMBER$OF$SAMPLES

- I );

CALL RQ$I{AIT$

INTERRUPT

(

sBX3 50$ rNTR$LEVEL

GSTATUS );

Figure A-E, Interrupt Handler

and Task (SBX350.H!8)

(continued)

Prograrnming Techniques A-65

EXAMPLE PROGRAMS

WalÈ to debounce the interrupt sr,titch.

CALL RQ$SLEEP

(

GSTATUS

) ;

Cet the lnput data.

INPUT$VALUES

( rNDEX

) - NOT

(TNPUT(

SBX35O$PORT$A

));

oUTPUT( SBX350$P0RT$B

) - INPUT$VALUES

( rNDEX

);

END; /* DO INDEX

- O TO ( NUMBER$OF$SAMPLES

. 1) */

CALL RQ$SEND$DATA(

PROC I OMBX

@INPUT$VALUES,

NUr.fSER$OF$

SAT.ÍPLES,

@STATUS );

ACTUAL

- RQ9RECEIVE$DATA

(

SBX3 5OMBX,

@NUMBERSOFSAMPLES

N0$r{AITING,

GSTATUS );

END; /* l,lHILE I *,/

END

SBX35O-TSK;

END SBX35O-MOD;

Figure A-E. Interrupt Handler

and

Task (S8X350.P28)

(continued)

A-6ó Progranming Techniques

EXAMPLE PROGRAMS

$CoMPACT

DEBUG Pl,J(79)

RoM

PROCIO_MOD: Do;

9INcLUDE

(

/RMX2

8 6/rNc/RMxpLM.

EXT)

STRLEN: PROCEDURE( STRPTR

) BYTE EXTERNAL;

DECI.ARE STRPTR POINTER;

END

STRLEN;

BTOA: PROCEDURE( CHR, STR ) EXTERNAL;

DECIARE

CHR BYTE,

STR POINTER;

END BTOA;

ATOB: PROCEDURE( STR

,STSP ) BYTE EXTERNAL;

DECIARE

STR POINTER,

STSP POINTER;

END ATOB;

DECIARE

NUL LITERALLY

I'AIT$FOREVER LITEMLLY

'SELECToR$oF(NIL)'

'OFFFFH'

'0'

'0,'

,ODH'

OAH

OFFH

' ,

,0';

NO$WAITINC

E$OK

TRUE

FALSE

LITERALLY

LITEMLLY

LITERALLY

LITEMLLY

CALC$MEAN: PROCEDURE

( CoUNT, BUFFP

) BYTE EXTERNAL;

DECIARE

COUNT BYTE,

BUFFP POINTER;

END CALC$MEAN;

CALC$MEDIAN:

PROCEDURE(

CoUNT, BUFFP

) BYTE EXTERNAL;

DECIARE

COUNT BYTE,

BUFFP POINTER;

END CALC$MEDIAN;

Figure A-9. Process

Task

(PROCIO.P28)

Programming Techniques A-67

EXAMPLE PROGRAMS

CALC$MODE:

PROCEDURE(

COUNT,

BUFFP

) BYTE EXTERNAL;

DECI^ARE

COUNT BYTE,

BUFFP POINTER;

END

CALC$MODE;

PROCIO

TSK: PROCEDURE

PUBLIC;

DECIÀRE

TERMINMBX TOKEN,

ÎERMOUTMBX TOKEN,

SBX35o$MBX ToKEN,

PRoC$ro$MBX ToKEN,

PROCgIO$RSP$MBX TOKEN,

DUMMY$MBX TOKEN,

BUFFERT TOKEN,

STATUS T.TORD,

ACTUAL WORD,

NUMBER$OT$

SAMPLES BYTE,

rAST$SAMPLE BYTE,

MEAN BYTE,

MEDIAN BYTE,

MODE BYTE,

I'AITINC$ FOR$KEYBOARD BYîE,

VALID BYTE,

DATA$BUFFER

(IOOH) BYTE,

BUFFER BASED BUFFERT

(256) BYTE;

DECI^A,RE

INITMSG

(*) BYTE DATA(

CR,LF,' INPUT INITIALIZATION

COMPLETE

' ,CR,LF,O

MEAN$MSG

(*) BYTE DATA (

CR,LF,' THE MEAN INPUT

VALUE I,JAS '),

MEDIAN$MSC

(*) BYTE DATA (

CR,LF,'THE MEDIAN

INPUT VALUE WAS '),

MODE$MSG

(*) BYTE DATA (

CR,LF,'THE

MODE TNPUT VALUE IIAS '),

ENTRY$MSG

(*) BYTE DATA (

CR,LF,'PLEASE ENTER

A DECIMAL VALUE BETWEEN l AND

128 <CR>

SMPLE$MSG

(*) BYTE DATA (

CR,LF,'THE

NUMBER OF SAMPLES TAKEN

WAS ');

Figure A-9. Process Task

(PROCIO.P28)

lcontinued)

A-68 Programming

Techniques

EXAMPLE PROGRAMS

Lookup the mailboxes for terrninal l/0 and the SBX350 task.

TERM$IN$MBX

- RQ$LOOKUP$OBJ ECT

(

NUL,

@(6,'TERMTN'),

T.TAIT9FoREVER,

GSTATUS );

TERM$OUT$MBX

- RQ$LOOKUP$OBJ

ECT

(

NUL,

@(7,',TERMOUT',),

WAIT$FOREVER,

@sTArus );

sBX350$MBX

- RQ$LOOKUP$OBJ ECT

(

NUL

@(9,

sBX3soMBX'

) ,

WAIT$FOREVER,

GSTATUS );

Setup a rnailbox where the PPI task can send data for processing.

PROCIO$MBX

: RQ$CREATE$MAI LBOX

(

60H, /* set up for passing data not RMx objects */

GSTATUS );

Catalog the mailbox so the PPI task can find it.

CALL RQ$ CATALOG$OBJ ECT

(

NUL

PR0Ct0$MBX,

G(9,

PROCTOMBX'

) ,

GSTATUS

);

Wait for data fron PPI task iniÈialization before proceeding.

ACTUAL

_ RQ$RECEIVE$DATA

(

PROCIO$MBX,

GDATA$BUFFER,

WAIT9FOREVER,

GSTATUS );

Figure A-9. Process Task

(PROCIO.P28)

lcontinued)

Programming Techniques A-ó9

EXAMPLE PROGRAMS

Create a nailbox for use when requesting keyboard input

pRoclo$RsP$MBX

- RQ$CREATE$MATLBOX

(

0, /* set up for passing RMX

objects */

GSTATUS );

l.lalt for a response from the operator before proceeding.

VALID - FALSE;

DO I,IHILE NOT

VALID;

waiE for initialization data from the operator before proceeding.

send a rnessage requesting operator input

BUFFERT

. RQ$CREATEg S ECMENT

(

S I ZE

(

BUFFER

) ,

GSTATUS ) i

CALL MOVB

(

GENTRY$MSG ,

GBUFFER

SIZE( ENTRY$MSG

) );

CALL RQ$SEND$MESSAGE

(

TERM9OUT$MBX,

BUFFERT

NUL,

@sTArus

);

Now check for a response.

BUFFERT

- RQ9CREATE$ S EG},IENT

(

slzE(BUFFER),

@srArus );

BUFFER(O)

- 80H;

CALL

RQ$S END9MES SAGE

(

TERM$ IN$MBX,

BUFFERT

PRoC$r0$RSP$MBX,

GSTATUS

);

Rt lFFFp,r _ D^(D F.F r\rF$MES

SAG E (

PROC$ 10$RS

P$MBX

t{A.L I ì f Ut(ÉV EK ,

GDUMMY$MBX ,

@STATUS ) j

Figure A-9. Prccess

Task (PROCIO.P28)

lcontinued)

A-70 Programming Techniques

EXAMPLE PROGRAMS

Valldace che input parameter and cransforn it fron ASCII

NUMBER$OF$ SAMPLES

- ATOB

(

@BUFFER ,

€STATUS );

rF(STATUS-0)

AND (NWBER$OF$SAMPLES

>O )

AND ( NUMBER$OF$

SAMPLES

<:128 ) THEN

VALID - TRUE;

Delete the segment received at PROCIO$RSP$MBX.

CALL RQ$DELETE$ S EGMENT

(

BUFFERT

GSTATLS );

END; /* DO LIHILE NOT VALID */

LAST$SA.I,fPLE

- NUMBER$OFSMPLES

;

Now let the PPI task proceed

CALL RQ$SEND9DATA

(

sBX350$MBX,

GNUMBER$OF$SAMPLES,

@STATUS ) ;

Set a flag noting the no requests are pending for keyboard input.

I,IAITINC$

FOR$KEYBOARD

: FALSE;

DO I,IHILE 1;

Enter nain loop for processing digital I/O.

Wait for data .from PPI task.

ACTUAL

- RQ$RECE

VE$

DATA

(

PROCIo$MBX,

ANATA

(RIIFFFP

wAl r

lruKÉv È.K

GSTATUS

);

Figure

A-9. Process Task

(PROCIO.P28)

(continuedl

Programming Techniques A-71

EXAMPLE PROGRAMS

Now

fornat the data and send it to the terminal output task.

Inform the operacor of the number of sarnples taken.

BUFFERT

- RQ$CREATE$

S EGMENT

(

S I ZE

(

BUFFER

) ,

GSTATUS );

CALL MoVB

(

GSAMPLE9MSG,

GBUFFER ,

clTF/ qaMr)IFCMqcì\.

CALL BTOA

(

ACTUAL,

GBUFFER(

SIZE( SAMPLE$MSC)

) ) ;

CALL RQ$ SEND$MES SAGE

(

TERM$OUT9MBX,

BUFFERT

NUL,

GSTATUS

);

Calculate the nean input value send it to the operator

ds Pdr L sLrrrrÉ..

MEAN

: CALC

SMEAN

(

ACTUAL,

GDATA$BUFFER );

BUFFERT

- RQ$ CREATE$ SEGMENT

(

SIZE(BUFFER),

€STATUS );

CALL MOVB

(

€MEAN$MSG,

@BUFFER ,

srzE( MEAN$MSG

) ) ;

CALL BTOA( MEAN,

GBUFFER(

srzE( MEAN$MSG)

)

) ;

CALL RQ$ S END9MES

SAGE

(

TERM$OUT$MBX,

BUFFERT

NUL,

QSTATUS );

Figure A-9. Process Task

(PROCIO.P28)

(continued)

A-72 Prograrnming

Techniques

EXAMPLE

PROGRAMS

Calculate the median input value send it to the operator

,c nrrt af a zcro t érhin,tè.1 <trino

MEDIAN

- CALC$MEDIAN

(

ACTUAL

GDATA$BUFFER

);

BUFFERT

. RQ$CREATE$ S ECMENT

(

SIZE(BUFFER),

GSTATUS

);

CALL MOVB

(

GMEDIAN9MSG,

GBUFFER,

srzE( MEDTANSMSG

) ) ;

CALL BTOA

(

MEDIAN,

GBUFFER(

SIZE( MEDIAN$MSG)

) ) ;

CALL RQ$SEND$MESSAGE

(

TERM$OUT$MBX,

BUFFERT

NUL

GSTATUS

);

Calculate the rnode input value send it to the operator

d> Pd! L 5L' "'6..

MODE

- CALC$MoDE

(

ACTUAL,

@DATA$BUFFER );

BUFFERT

- RQ$

CREATE$ S EGMENT

(

srzE(BUFFER),

GSTATUS

);

cALL MOVB

(

GMODE$MSG,

GBUFFER

c r 7F r/ MnnF(MC/: r \ .

CALL BTOA(

MODE

@BUFFER(

SIZE(

MODE$MSG)

)

) ;

CALL RQ$SEND$MESSAGE

(

TERM$OUT$MBX,

BUFFERT

NUL,

@STATUS ):

Figure A-9. Process Task

(PROCIO,P28)

lcontinued)

Pmgramming Techniques A-73

EXAMPLE PROGRAMS

send a rnessage

requesting operator input

BUFFERT

- RQ$ CREATE$

S EGMENT

(

SIZE(BUFFER),

GSTATUS

);

CALL MOVB

(

@ENTRY$MSC,

@BUFFER

srzE

( ENTRY$MSG)

) ;

CALL RQ$ SEND$MES SAGE

(

TERM$OUT$MBX

BUFFERT

NUL,

@STATUS );

IF WAITING$

FOR$KEYBOARD

<> TRUE THEN DO;

lf no input request message

ís pending then send one,

BUFFERT

- RQ$CREATE$ S EGMENT

(

SIZE( BUFFER),

@srATUS ) ;

BUFFER(O)

- 80H;

CALL RQ$SEND$MESSAGE

(

TERM$IN9MBX,

BUFFERT

PROC$

IO9RS P$MBX

@STATUS ) ;

I'AITING$ FOR$KEYBOARD

: TRUE;

END

;

Check for a response from the operator before proceeding.

BUFFERT

- RQ$RECEIVE9MES

SACE

(

PRoC$ ro9RSP$MBX

NO9WAITINC,

GDUMMY$MBX

@STATUS );

IF STATUS

- O THEN DO;

Figure

A-9. Process Task

(PROCIO.P28)

lcontinued)

A-74 Programming Techniques

EXAMPLE PROGRAMS

Validate the input parameter and transform it fron ASCII.

NUUBER$OF9 SA]"TPLES

- ATOB (

GBUFFER,

@STATUS

);

rF (

NUMBER$oF$ SAMPLES >0 )

AND ( NI,I.fBER$OF$SAMPLES <:128 )

AND(STATUS-O)THENDO;

New sarnple size requested. Inform the interrupt task.

CALL

RQ$SEND$DATA

(

sBX350gMBX,

GNUMBER$OF$SAI'iPLES,

GSTATUS ) ;

IAST9SAMPLE

- NUMBER$OF$SMPLES

;

END

;

Delete the segment we received frorn the keyboard.

CALL RQ$DELETE$

SEGMENT

(

BUFFER$T,

@STATUS ) ;

Clear the fJ-ag showing that a keyboard input request is pending

I.IAITINC$ FOR$KEYBOARD

: FALSE;

END;

/* IF STATUS

: 0 */

END; /* DO h'IIILE 1 *,/

END PROCIO-TSK;

END

PROCIO-MOD;

Figure A-9, Process Task (PROCIO.P28)

(continued)

Prograrnming Techniques A-75

EXAMPLE PROGRAMS

$COMPACT

DEBUG PW(79)

ROM OPTIMIZE(O)

UTILIfi-MOD : DO;

TNcLUDE

(

/Rrfi 2

8 6/rNC/RMXPLM. EXT

)

DECIARE

NUL LITEMLLY 'SELECTOR9OF(NIL)'

WAIT$FOREVER LITERALLY ' OFFFFH'

TRUE LITEMLLY 'T' ,

FALSE LITEMLLY 'O' ,

MAX$STRINC LITERALLY '255' .,

STRLEN: PROCEDURE( STRPTR

) BYTE PUBLIC;

DECIARE

STRPTR POINTER,

STRINC BASED STRPTR(I) BYTE,

INDEX BYTE;

INDEX

- O;

Í,ÍHILE ( STRING(INDEX)

O O ) AND ( INDEX

< MAXSTRING

) ;

INDEX

. INDEX

+ 1;

END

;

IF STRING(INDEX)

: O THEN

RETURN

INDEX:

ELSE

RETURN

END STRLEN;

BTOA: PROCEDURE( CHR, STRINGSP

) PUBLIC;

DECI-ARE

STRING$P POINTER,

CHR BYÎE;

DECIARE (

QUOîr

ENT

REMAINDER,

COUNT

MORE$DATA,

INDEX) BYTE,

STRINC BASED

STRINC$P(80) BYTE,

DIGIT(8o) BYTE;

Figure A-10. Utility Procedures

(UTILS.P28)

L-76 Programming Techniques

EXAMPLE

PROGRAMS

INDEX,MORE9DATA

- O;

REI,IAINDER

- CHR

;

IF CHR

: O THEN DO;

DrcrT(0)

' '0';

DrGrT(l):0;

INDEX

: 1;

END

;

ELSE DO I.IHILE REMAINDER > O;

DIGIT( INDEX

) : ( REMAINDER MOD 10 ) +,0';

REMAINDER

- REMAINDER

. ( REMAINDER MOD 10 );

REI,ÍAINDER

- REÌ.fAINDER

/ 10;

INDEX

- INDEX

+ 1;

DIGIT(INDEX)-O;

END

;

This string must be reversed to have the most significant

.lioít- ^rri-nrrr- fir9l 31 the termínal.

COUNT

: O;

DO WHILE INDEX > O;

STRING( COUNT

) _ DIGIT( INDEX

. 1 );

COUNT

: COUNT

+ 1;

INDEX

: INDEX

- 1;

END

;

STRINC(COUNT):0;

END BTOA;

ATOB: PROCEDURE

( STR$P, STS$P

) BYTE PUBLIC;

This procedure ís total ly wrong!

DECIARE

STR$P POINTER,

STS$P POINTER,

CHARS BASED STR$P

(

1) BYTE,

STATUS BASED STS$P WORD,

VALUE BYTE,

INDEX BYTE,

I BYTE,

MULTIPLIER

) BYTE:

Figure A-10. Utility Procedures

(UTILS.P28)

(continued)

Program min

Techniques A-77

EXAMPLE PROGRAMS

INDEX,

VALUE

. O;

MULTIPLIER

- 1;

STATUS

. O;

DO r,rHrLE

( CHARS

( ÌNDEX ) >: '0',)

AND

( CHARS

( INDEX

) <: ',9' );

INDEX

- INDEX

+ 1;

END

;

IF INDEX

: O THEN DO;

STAÎUS

- OFFFFTI;

RETURN

END

;

I - INDEX

-1;

DOWHILEI<INDEX;

VALUE

- VALUE

+ (( C}IARS( I ) -'O' ) * MULTIPLIER);

MULTIPLIER

. MULTIPLIER

* 10;

END

;

RETURN VALUE;

END ATOB;

CALC$MEAN: PROCEDURE

( CoUNT, BUFFP

) BYTE PUBLIC;

DECIARE

COUNT BYTE,

BUFFP POINTER,

BUFF BASED BUFFP(1) BYTE,

INDEX BYTE,

TOTAL WORD;

TOTAL

- O;

DO INDEX

- 1 TO COUNT;

TOTAL

- TOTAL

+ BUFF( INDEX . 1 );

END

;

RETURN

( TOTAL / COUNT

)

END CALC$MEAN;

CALC$MEDIAN: PROCEDURE( CoUNT, BUFFP

) BYTE PUBLIC;

DECTARE

COUNT BYTE,

BUFFP POINTER,

BUFF BASED BUFFP(I) BYTE,

VALUES(1OOH) BYTE,

TOTAL BYTE,

INDEX BYTE;

Figure A-10. Utilify Procedures

(UTILS.P28)

(continuedl

A-7E Programming Techniques

EXAMPLE

PROGRAMS

CALL

SETB( 0, GVALUES,

SrZE( VALUES

) );

DO INDEX

. 1 TO COUNT;

VALUES(

BUFF( INDEX - 1 ) ) - VALUES( BUFF( INDEX - 1 ) ) + 1;

END

;

TOTAL

. O;

INDEX

- O;

DO r,rHILE TOTAL <- ( COUNr

/ 2

) ;

TOTAL

. TOTAL

+ VALUES

( INDEX );

INDEX

- INDEX

+ 1;

END

;

RETURN

INDEX .1;

END CALC$MEDIAN;

CALC$MODE:

PRoCEDURE( CoUNT, BUFFP

) BYTE PUBLIC:

DECIARE

COUNT BYTE,

BUFFP POINTER,

BUFF BASED BUFFP(T) BYTE,

VALUES(IOOH) BYrE,

(

MAX,

INDEX ) BYTE;

CALL SETB( 0, GVALUES,

SrZE( VALUES

));

DO INDEX

- 1 TO COUNT;

VALUES

( BUFF( INDEX - 1 )) : VALUES

( BUFF( INDEX - 1 )) + 1;

END

;

r{Ax

- 0;

DO INDEX

. O TO IAST(VALUES);

IF VALUES

( INDEX ) > VALUES( MAX

) THEN

MAX

: INDEX;

END

;

RETURN MAX;

END CALC$MODE;

END UTILITY_MOD;

Figure A-10. Utility Procedures

(UTILS.P28)

(continued)

Programming Techniques a-79

EXAMPLE PROGRAMS

A.7.2 Compiling and

Binding the Code

The

following commands are used

to compile the code for this example:

These

PLM286

commands do not include controls for selecting the model

segmentation (SMALL, COMPACT, MEDIUM, or l-ARGE) because

the

$COMPACT

control

was

already included in the source files. The ROM control is also included, to

place

the constants in the data

segment.

The compiler

places

the

generated object code into the files INITTSK.OBJ, SBX350.OBJ,

TERM.OBJ,

PROCIO.OBJ,

and UTI[-S.OBJ.

After compiling, the object fi-tes must be bound

with

the appropriate iRMX Il interface

libraries. Because the code

will

be configured into the system

with

the Interactive

Configuration Utility, the BND286 command required is different than the ones used for

the

examples. The BND286 command for this example must include the

NOLOAD and NOPUBLICS EXCEPT controls.

The NOLOAD control

is required because the SUBMIT file created by the ICU will

invoke BLD28ó to further

process

the resulting module. The NOPUBLICS EXCEFI

control is required to limit

the

public symbols

in the output module. The only

public

symbols

in the output module are the entry point

of the initial task and the dummy

variable

identifying the data segment of that task. If all public symbols were

allowed,

the

names of the

iRMX II interface

procedures would

conflict with

the names of the call

gates

used inside the operating system.

Even though the NOPUBLICS EXCEPT control

is required, including that control can

make

debugging somewhat of a chore because the

MAP286

utility will

not be able

generate

much

valuable

information. To correct that problem, you can use a three-step

bind

operation that

produces

one output file for use by MAP286 and another output file

that

will

be used as input to the ICU.

To implement this solution, first bind the object code with the

NOLOAD and DEBUG

controls and place the

result in a temporary fiìe. Then use the temporary file as input to

BND286 and include the

LOAD ontion.

This

will

cause the error

NO START ADDRESS FOUND IN OUTPUT MODULE

A-80 Programming Techniques

EXAMPLE PROGRAMS

This error can be ignored. The object module produced from this invocation of BND286

can be used as input to MAP286 to generate

a map of the first-level

job. Finally, run the

temporary

file through

BND286 again, specirying the NOLOAD and NOPUBLICS

EXCEPT controls. The output of this invocation will be combined during configuration

with the rest of the operating system.

The following commands perform

the operations

just mentioned. They create both a

usable map file and the object

module that

will be combined

with the

operating system.

A.7.3

Configuring

the First-Level

Job

To add the first-level

job to the operating system,

you must use the ICU and build a

configuration containing that

job. The easiest

way

to do this is to start with an existing

configuration file and modif it to include the new first-level

job. You

can use any

configuration file that includes the SDB, the Basic I/O System, and supports a

device with

the

name T0. This example assumes that you start

with

the configuration

file 28612.DEF

as supplied

with

the operating system.

Programmin

Techn

iques A-81

EXAMPLE PROGRAMS

When you

run the ICU, make

sure to examine the following

screens:

Memory for System

(MEMS)

screen.

Sub-systems (SUB) screen.

Device Drivers.

In many cases,

when you

add

a first-level

job

to the operating system,

you must

allocate more memory for the operating

system. In this instance,

you won't need

to allocate

more memory because

you

will be eliminating some of the layers

the operating system from your

configuration (only the Nucleus, SDB,

and BIOS are needed). In fact,

you'll

probably have more than enough memory

allocated for operating system code. If

you were

building an actual

production

system,

you

could find out exactly how

much

you

need by running the ICU twice.

The first time through, allocate a

generous amount of system

memory.

After you

run the SUBMIT file generated

by the ICU, examine the .MP2 file

produced by BLD286 and find out how

much memory

was

actually used. Then

back and modifo the MEMS screen

accordingly, and generate the system

again. For this example,

just

leave the

MEMS screen set to its default

value.

This example requires

just

the services

the Nucleus, System

Debugger, and Basic

I/O System. Therefore, speciff

NO for

the UDI (UDI =

NO) and YES for the

Basic

I/O System

(BIO=YES).

There are no changes

required to the

BIOS screens,

but only the 8274 driver is

required for this example. To remove the

other drivers,

invoke their driver screens

and enter the

value

to delete them

from the confiquration.

A-82 Programming Techniques

User Jobs

(USERI)

screen.

User Modules (USERM)

screen.

EXAMPLE PROGRAMS

Because you are adding a firstlevel

job,

you

must fill out the User Jobs screen to

describe that

job. The

fields

on this

screen are similar to îhe parameters in

the RQE$CREATE$JOB

system call.

Figure A- 1 I shows the filìed-out User

Jobs screen. Notice that the Task Start

Address

(TSA)

and Public

Variable

Name (VAR) fields are set to the public

names that remain in the first-level iob

after

running BND286

(DUMMYvARIBLE and lNlT_TsK).

On this screen,

you

must indicate the

paîhname

of the ohject module

containing

your

firstJeveljob.

This is the

file

produced

by BND286 earlier

IEXAMPLE.LNK).

After

you

make these modifications with

the lCU,

generate

a new system and run the

SUBMIT

file

produced

by the ICU. You

can invoke

your system by using the Bootstrap

Loader to load the operating

system file

produced

by the ICU's SUBMIT file.

(usERJ

)

( NAì'I)

(oDs)

(

Pr.rr

)

(

PMA)

(MoB

)

(l,fTK)

(MPR)

(EHs)

(

Er'{)

(Pv)

(TP)

(TSA)

(vAR)

(ssA)

(ssr)

(NPX)

EXAI'IPLE

OFFFH

OFFFFFH

OFFFFH

ALL

YES

139

INIT TSK

User Jobs

Job Name

[0-14 characters]

ObJecc directory Size [0-

3840

]

PooI Mininun [20H - OFFFFzu]

PooI Maxirm-un

[20H - OFFFFFH]

Maxlnum ObJecrs 11 - oFFFFHI

l,faxirnurn Tasks [1 - OFFFFH]

Maximum

Priority [0 - 255]

Excepcion Handler Entry Point [L-31 chars]

Exception Mode INever/Prog/Envi ronlAl L

]

Parameter Validatlon IYes/No ]

Task Priority [0-255]

Task Entry Polnt [1-31 chars]

Public Varlable Name

l0-31 charsl

Stack Segment Address ISS:SP]

Stack Size [0-OFFFFH] 0300H

Nurneríc Processor Extension Used f

Yes,/Nol

DUMUYDATAVARI

BLE

0000 :

0000H

Programmlng Techniques

Figure A-l l. User

Jobs

Screen

A-83

$SLEEP

A.32,35

A$GET$CONNECTION$STATUS A.6

A$GET$FILE$STATUS A.6

A$OPEN

A.ó,61

A$PHYSICALI$ATTACH$DEVICE A-6

A$READ A.21,57

A$SEEK

A.6,21

A$SPECI-AL

A'.6,7,8

A$WRITE A-21,23,59

Assembly

code

Parameter passing

2-3

Using

iRMXo system calls

2- 1

Based variables

5-2

Bind sequence

2-12, A-23,37, 41, 48, 8l

Binding code to interface

libraries 2- 1 1

BIOS.EXT 2.5

BND286

2-1t, 12, A-37,41,48, 81

Buffer Pools

Creating

5-3, A- 16

Overview

A-3

Passing buffers A- 15

Releasing buffers A-17,

Requesting buffers A-18

Using 5-3, A-15,

C code

Parameter passing

2-4

Using

iRMXo system calls 2-4

C$GET$OUTPUT$CONNECTION A-6

C$GET$OUTPUT$PATTINAME A-6

C$SEND$CO$RESPONSE A-32, 35

C$SEND$EO$RESPONSE A-20

CATALOG$OBJECT A-11, 16, 29, 56, 58, 62, 65, 69

Pmgramming Techniques Index-l

INDEX

Cataloging

objects A-2,

Coding iRMX@

system calls 2-l

Communication

A-3

Jobs 3-1

Tasks

A- 12, 22

Compact

segmentation model l-2

Compiler controls

RAM 1-2,4

ROM 1-2,4

Compiling code A-23,

37,41, 48, 80

Configuring ajob into the operating

system A-81

Constant locations 1-4

Control-C handler

A-38

Conventions iv

Converting

iRMX@ I applications 5-1

CREATE$BUFFER$POOL A. 17, 18

CREATE$IO$JOB A.6

CREATE$JOB

A-5

CREATE$MAILBOX A-14, 29, 34,

56,58, 59, 60, 64, 69,70

CREATE$SEGMENT

4.17, 18,34,

70, 72,73,74

CREATE$TASK

A-9,

11,30,53,

Creating tasks A-2, 9

Data

Acquisition

job A-48

Data

passing

between

jobs 3-2

SEND$DATA and

RECEIVE$DATA 3-6

Dynamic stack allocations

1-3

E$CREATE$IO$JOB A-6

E$CREATE$JOB A-54

EIOS.EXT 2-5

Example

Binding code A-23, 37,41, 48, 81

BND286 2-12

Buffer

Pools A-15

Cataloging objects A-10

Clearing the

screen

A-20

Compiling code A-23,37,41, 48, ll0

Index-2 Programming Techniques

Example (cont.)

Concepts A-1

Configuring

job into the operating

system

A-83

Control-C

handler

A-38

Data acquisition

A-48

Execution

of a

job A-24, 38, 41, 48

First-level

job A-48

FORTRAN-28ó

string conversion

2- 10

In-line exception processing

A-3

Include

files 2-5, 6, 7

Inter-task

communication A-12, 22, 26

Interrupt

handler A-43,49,

Job initialization A-52

Literal files A-5

Programming concepts

A-1

Programs A-1

Pushing parameters

onto

the stack

2-3

Response pointer

A-12

Screen I/O A-20, 35, 55

Simultaneous

IIO A-22

System calls from assembly source code 2-3

Task creation A-9

Terminal

attributes

A-7

Exception handlers 1-3, 5-4,

A-4

Execution

ofajob A-24, 38, 41, 48

EXIT$IO$JOB A-6,27,30

External procedures

't-2,2-4,

File connection restrictions

3-3, 6

FORTRAN-286

code

Include

file 2-7

Parameter passing

2-8

Restrictions 2-8

String conversion

example

2- 10

Strings 2-10

Using

iRMXo system calls 2-8

INDEX

Programming

Techniques Index-3

INDEX

General

protection

error 3-1,

GEfiEXCEPTION$HANDLER

A-4,

GET$LOGICATJDEVICE$STATUS

4.6

GET$PRIORITY

A-9, II, 29

GET$TASK$TOKENS

A.5, 29,

53, 56, 58

GET$TYPE

A-5,32

Getting

terminal

attributes

A-7

HI.EXT 2-5

I/O Result

Segnent

(IORS) A-21, 22,

Improving

performance (see optimization)

In-line

exception

processing A-2,

Include

files

BIOS.EXT 2-5

Description

2-5, A-36

EIOS.EXT

2-5

Example

of use 2-5, 6

Example use

of 2-7

FORTRAN-286

fiÌe 2-7

HI.EXT 2-5

LOADER.EXT 2.5

Location of 2-5

NUCLUS.EXT 2.5

PASCAL-286 file 2-6

RMXFTN.EXT 2-5,7,8

RMXPAS.EXT 2.5,6,7

RMXPLM.EXT 2.5

Types 2-5

UDI.EXT 2.5

Initialization A-52

Inter-task communication A-3,

12, 26

Interface libraries

BND286 restrictions 2-12

Choosing for use 2-11

Function 2- 11

RMXIFC.LIB 2.11, 12

UDIIFC.LIB 2-11, 12

Interrupt handlers

4-1,3, A-43, 49,

Interrupts 4-1

)-l

Index-4 Programming

Techniques

l-arge

applications

1-2, 3

Literal

files A-2,

LOADER.EXT

2-5

l,oading

the stack

2-3

LOGICAI]'ATTACH$DEVICE

A-ó

LOOKUP$OBJECI

A-4, 31,

34, 36,56,

58, 65, 69

Mailbox 3-6,A-27,49

Mailbox optimization 5-3

Manual overview

Maskable

interrupts 4-1

Medium segnentation

models

1-2

Multitasking

job A-48

Nonmaskable

interrupts

4-1

NUCLUS.EXT

2-5

Object catalogin g A-2,

Object

directory ofthe rootjob 3-5

Object passing

between

jobs 3-3

Optimization

Based variables

5-2

Compiler

controls 5-2

Mailboxes

5-3

Nucleus

5-3

Overflow queues,

mailboxes

5-3

Seglentation

model

5-2

Sequential I/O 5-3

Based variables

5- 2

Parameter passing

Assembly

code 2-3

Between

tasks 3-6

C code

2-4

FORTRAN-286

2.8

INDEX

Pmgramming

Techniques lndex-5

INDEX

PASCAL-286

code

Include

file 2-6

Restrictions

2-6

Stack

allocation 2-7

Passing

buffers between

tasks

A-15

Passing

data

passing bet'ween

jobs

BIOS 3-3

EIOS 3-3

Segments

3-2

SEND$DATA and RECEIVE$DATA 3-2

Stream

files 3-3

UDI 3.3

Passing

objects between

jobs

Guidelines

3-7

Mailboxes

3-6,

Object directories

3-4,

Overview 3-3

Parameters

3-6,7

Performance

1,-1,2-2,

6, 5-1.,2

PLIM-286

code

Based variables 5-2

Using iRMXo system calls 2-1

Processing exceptions

A-3

Program

conversion 5-1

Programming

examples A-1

Public

procedures l-2,2-2

RAM

compiler control

1-2, 4

Reader level iii,

1-1, 2-1, 3-1,

4-1

RECEM$MESSAGE

A-7, 8, 13,

14, 15,23,32,35,

56, 59, 61,62,70,74

RECEIVESUMTS

A.12. 15

RELEASE$BUFFER

A-14, 17,18,

Releasing buffers

A-17, 19

REQUEST$BUFFER

A.12,

18, 22

Requesting

buffers A-18

RESET$INTERRUFT

A.44.

Response

pointer

A-3, 12

Restrictions

BND286 2-12

Compact

segmentation model

1-3

Connection

objects 3-3, 6

FORTRAN-286

code 2-8

Index-6 Pmgramming

Techniques

Restrictions (cont.)

Ilrge segmentation

model 1-3

Medium segmentation

model 1-3

PASCAL-286 code 2-6

Passing data between

jobs 3-2, 3

Passing objects between

jobs 3-6

Small segmentation model 1-3

Stack size 4-2

RESUME$TASK

A-3ó

RMXF|N.EXT 2.5,7,8

RMXIFC.LIB 2.1I, 12

RMXPAS.EXT

2-5,6,7

RMXPLM.EXT 2.5

ROM compiler control 1-2, 4

Root

job object

directory 3-5

S$GET$CONNECTION$STATUS

A.-6

S$GET$FILE$STATUS A-6

S$OPEN A-4,6,21

S$SEEK A-6

S$SPECIAL A-6,7,8

Screen I/O A-3, 20,35, 55

Segnent registers 7-1, 5-1, 2

Segnentation model

Assembly language calling conventions 2-2

Choosing the size 1-3,2-2, 3

Compact 1-2,2-2,3

Default

5-1

Interface libraries 2- I I

l-arge 1-2, 2-2, 5-1

Medíum 1-2,2-2

Small 1-2

Semaphores

Cataloging 3-4

Creations 3-4

Getting units from 3-5, A- 15

Looking up 3-5

Use in synchronization 3-4

SEND$MESSAGE A-12, 13, 14, 15, 18, 22,33,35,36,

57,70,72,73,74

SEND$UNITS

A.14, 15, 19

SET$EXCEPTION$HANDLER A-4, 5

SET$INTERRUM A.44, 47, 65

Setting terminal

attributes A-7

INDEX

Pmgramming Techniques Index-7

INDEX

SIGNAI]$INTERRUPT A.43, 46, 50,

Simultaneous

I/O A-3, 22

SLEEP A-47,66

Small applications

1-2, 3

Small segrnentation

model 1-2

Stack

Allocation in PASCAL-286

code 2-7

Computing size using

the arithmetic technique

4-3, 4

Computing

size using the empirical

technique 4-4

Interrupt requirements

4-3

Overflow 4-1, 2

Recursive code 4-2

Size for created

tasks andjobs 4-2

Size

for loaded or invoked tasks 2-12,

4-2, A,-37

Size limitation for

interrupt handlers 4-1, 3

System call requirements 4-3,4

Stream file 3-3

SUSPEND$TASK A-30, 32, 36

Synchronization

Tasks in different

jobs 3-4

Using semaphores 3-4

Task creation A-2, 9

Terminal

attributes A-2, 7

Terminal I/O A-20, 35, 55

UDI system calls 2-

UDI.EXT 2-5

UDIIFC,LIB 2-11, 12

Using iRMX@

system

calls 2- 1

WAIT$INTERRUM A-44, 47, 65

WAIT$IO A-2r, 22, 23, s7, s9

Writing code 2-1

Index-8 Progr-amming

Techniques

INTERNATIONAL

SALES

OFFICES

IN'TE

L CORPORAIION .]APAN

3065 Bowers Avenue Intel

Japan K.K

Sanîa Clara,

California

95051 Flower-HillShin-machi

1-23.9,5hrnmachi

EELGIUM Setagaya-ku, Tokyo

Intel

Corporation

Rue

des Cottages

65 NETIIERLAND5

B-1180 Brussels tntel

Semiconductor

(Netherland

I V.)

Alexanderpoort

8u ild ing

DENMARK Marten Meesweg

Intel

Denmark A,/5 3068 Rotterdam

G lentevej

6î

-3rd

Floor

k-2400

Copenhagen NORWAY

lntel Norway

A"/5

ENG LAN

D P.O

Box

Intel

Corporation

K.)

tID Hvamveien

Prper's

Way N-20l3,

Skjetten

Swindon,

Wiltshire

5N3

1RJ

sPAIN

FtN

LAND Inrel

tberia

lntel Finland

OY Calle Zurbaran

28-lZeDA

Ruosilante

2 28010 Madrid

00390

Helsinki

SWEDEN

FRANCE Intel

sweden A.B.

Intel

Paris Dalvaegen

1 Rue Edison-BP

303 5-171

36 Sotna

78054

5t.-Quenti n-en-Yvel

i nes

Cedex

5WI-TZERLAN

ISRAE L Intel

Semiconductor A.G.

Intel

Semiconductors

LTD. Talackerstrasse

Atidim

Industrial Park 8125

Glatrbrugg

Neve sharet CH-8065

Zu rich

P.O Box 43202

el-Aviv 61430 WEsT

GERMANY

lntel

5em

icond

uctor G.

B. H.

ITALY Seidlestrasse

Intel

Corporatron S.P.A. D-8000 Munchen

Milandf

iori,

Palazzo

El4

20090 Assago

(Milano)

461847 001_Extended_i RMX_II.3_Volume_4_System_Utilities_and_Programming_Information_1988 001 Extended I RMX II.3 Volume 4 System Utilities And Programming Information 1988

461847-001_Extended_iRMX_II.3_Volume_4_System_Utilities_and_Programming_Information_1988 461847-001_Extended_iRMX_II.3_Volume_4_System_Utilities_and_Programming_Information_1988

Navigation menu

Versions of this User Manual:

Views

Navigation