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
| Download | |
| Open PDF In Browser | View PDF |
intef
E X T E N D Ei D
RMX@II.3
O P E R A T I NSGY S T E M
DOCUMENTATION
VOLUME
4
SYSTEM
U T I L I T I EASN D
P R O G R A M M I NI N
GF O R M A T I O N
O r d e r N u m b e r ; 4 6 1 8 4 70 0 1
ntel Corporation
3 0 65 B o w e r sA v e nue
5 a n t aC l a r aC
, alrfora
n 95051
C o p y r r g h t ì 9 8 8 , l n t e C o r p o r a t r o nA, l l R i g h t sR e s e r v e d
I n l D c a t i ( r n so u t s r d e t h e U n r t e d S t a t e s , o b t a i n r d d ì t r o n a l r r r p r e s , r l l n t e ì d o e u m c n l a l i o n b y
r , ) n t r L ( t i n gy o r r r l o c a l I n t e ì s a l e s , r f f i c e .I ' ì r ry o L r rc o n s c n r e n c eL, n t e f n a t i , ) n asl a l { r s , r f f i caed d r e s s r : s
a r e l o c a t e d d i r e c t l y b e i ì r r et h e r e a d e r r e p ì v t a r d i n r h e b a c k I l l h e m a n u a I
t h e i n l o r m a t i o n i n t b r s d o c u m I o t i s s r . t b i et rt , r . h a n q e { r t h ou t r ì , , rt ( r '
l n t e l ( ' , ) r f o r a l r l ) nr ì r r k o sd , ) w a r r a n t \ ' , r f r ì r ì vk r r l w r t h r f j l a r d l , r t h r s ù ì a t { . r ì a l .i n c l ( ì d i n g ,b L r l n r ) l
l i m r t e d 1 o ,t h e i n r p ì i o d| | r r r a r t ì o s ) l n r f r r h a . l r l ) r l L ! v a r r l f i t n e s sl ì r a p a r t i c u l a r p u r p o s € . I n l e l
(1,)rp,)rati,)n
r f s p i ) n s L b r l i l ri 'ì ) r r ì ! ì v f r f , r f s r h r l n ì r ì v r p p e a r r n l h i s d ( x L ì n r e n t .I n l € l
C o r p o r a t i o nm a k e s n , rr , r r r r r n i l n r e or tr )L r p d a t p) . t , r k e p p . L r r r e n lt h e I n { i ) r m a t i r ) nc o n t a r n o dì n t h r s
I n l e l ( o r p , J r a l i o na s s u n ì r s n , ì . { r s p r ì n s r b i l i t fyi ) r t h f u s e r i i r n v f i . r u i l r ! o r h € r t h a n c L r c u i l r y
r : m b r x ì i e di n l r n I n l e l l ) r , r l L r ( l \ , ) , r l . h e r . i r c u i t 0 t t l e n l l i . { ' r ì \ p s r r e i r r r p l i e d .
I n t e l s . ) l ì r r n . r p r ) d u . t s a r f L o p v r r r : h t c db v a n ( l r h a l l r c m a ì n t h e p r ) p e r t y , ) i l n t e l ( , ) r p o r r l r ) n .
t ' s e . d L r p l ì c a l i r r n , rrrl ì s c l , r s u r ei s s u b t e ( t t , ) r r s t r ì c t i , ) . \ i t a l P d r n I n t e l s , ; o f t s a r e l r c o n s p . , ' r n s
r l e i ì n e di n A S t ) R 7 1 0 , 19 r r ) r 9 r .
\ o p a r t , ) f t h r s d o ( . u n ì e n 1r n a r b e f , ) p r e d 0 r r e p r r x l u c e d r n a n y f o r m o r b v a n v r n e a n s , r r l h o u t p r r o r
{ r i l t f n c o n s e n tr ) l I n t e | ( ' , ) rp , ) f l r t i , ) n .
Ì h e f l l l o $ L n g a r e t r a d e m ? ì r k s, ) l I n t p l ( o r p o r î t i o Ì 1 a n d r t s a f f i ù a t e s a n d m a y b e u s c d o n l y L 0
r d e n l i l v I r ) t e lp r , ! l u f i s :
Ab,rve
,l.lìX
rPS(l
BII II( S
('OY Ypute r
(lRl'iDiî
rll I)l)K
rS I I ( '
r\lMX
rSllX
I ) r ì t aI ì p e h n e
lnsrle
LSI)U
,nr,,l
rSSII
T
rnrcllìOs
iSX 11
r
Intolevisrr)n
Lrbrarl \fenrLqer
f2lCFi
, n r e l i g e n tl d e n t , f i o r
tf('s
lCFl
, n t e l i s e n t i ' ] r r ) s r a n ì m i n q \fega(hassrs
rCÉlL
Inlollec
iCS
Inteìlink
rDtìl'
,OSP
IDIS
rPl)S
lìfnil's
rlìUX
\ft('tìo \f'\ r \ t RA lll]
\fUI,TIB(,S
\ILI,'TI(]HA\\EI,
\ f L ; t . lt \ f o t ) ( L u
O p e n \ LL
o\a !l
IllusA Ilubbìe
PIIoMPT
QL:EST
Quex
Rrpplenode
R\f x/80
RUPI
SI,II
LPI
VLS'('!:1.
ìl'Stì
K E . \ * l K , \ f S D O S , \ f L r l t L p l a n . r n d \ f i c r o s o l ì a r e t r a d e m a r k s , r l \ l i c r o s o f t C , - r r p o r a t L o n[.. \ l K r s a
t r r d e n ì a r k ' r i B e l l L r i b o r r t , r r r e s F l t h e r n c l r s a l r a ( l e n r r r k ' r t X e r | \ ( , ) r p o r a t i o n . C ( ' n r r , r n r r sì s a
L r a d e m a r k , r l ( l e n t r o n ' r s D a t r ( , ) m p u l e r ( ' , , r p o r a t L o n(. h a s s i s T r a k r s a l r a d e n Ì a r k , r l ( Ì e n e r a l
[ ) e v Ì c e sC o n r p a n v , I r ì f . \ ' A \ , r o d
VUS rrf tradenìxrks rf l)rqrtrl tqurpmenr Corporarion_
S n ì a r t m o d e m i 2 0 0 a n d l l a y e s a r e r r a d e m a r k s o f I l a \ ' f s \ l r c r o c o | n p u t ( ' rl , r o d u c r s ,I n c . I B M i s a
r f g r s t e r p d t r a d e ù r a r k , ) l l n l t ' r n a Ì i o n a l l l u s Ì n e s s \ f a c h r n e s . S o f t S { . 0 p er s a r e g t s t e r e d r r n r l e r n a r k o f
(li)ncurrent Scrences.
( ' , ) p y r i q h t ! l 9 l l l ì .l n t o l C , r r p o r r t i o n
VOLUMEPREFACE
MANUALS
IN THISVOLUME
This volume (Volume 1, Ertended iRMl{'@II Operating Syltent Lltilitit:s and prograntniry4
Infonnation) includesthe following manuals:
Exteruled IRMXP II Boorstap Loader ReferenceManual
Extended iRMÀo II SystentDebug4erReferenceManuol
Extended iRlll)o II Disk Verilication Lltilitl ReferenceManuul
Guide to tlu: Etcntletl IRM}@ II lrtteructive Configuration utiliq,
Ertended iRltl)@ II Prograrntning Technique.sReftrente Mrtttuttl
The Extended iRMA\o II Bootstrap Loader RefercnccManual tlescril.testhc use of the
Bootstrap Loader and how to modify the Bootstritp Loatler îiles.
The Ertenderl iRhl)@ II SystemDehugqerReferenceManualdescribesthe iRMX@ II
Operating System'sstatic debug-eer.All of thc SystemDebugger commancisare explained
and an exampledebug-uing
sessionis provided.
The Ertended iRMXo II Dkk Veificatbn lrility Rcferenu Munual rlescrihesthe Disk
v e r i l i c a t i o n U t i l i t y w h i c h i s u s e dt o e x a m i n ea n d r n o t l i f yt h c d a t l ì s t r u c t u r e so f i R M X o I I
n a m e da n d p h y s i c avl o l u m e s .
The Guide to the Efiended iRMXo II Interactive Conf.guration Utlltv'manual describes the
I n t e r a c t i v eC o n f i { u r a t i o nU t i l i t y c o m m a n d sa n d m e n u s ,a n d p r o v i d e sa n e x a m p l es y s t e m
configuration.
The Extended iL\lÀl@ II Progrurnnting TechniquesReference!úanuul provides programnring
t e c h n i q u e sa n d e x a m o l e s .
iRMX@II SystemUtilitiesand Prograrnming
lnformationVolume
Itl
VOLUME PREFACE
VOLUMECONTENTS
Manualsare listedin the order theyappearin the volumes.For a synopsisof eachmanual,
refer to fhe Introductiortto the Ertended|RMX\ II OperatingSystem.
VOLUME 1. Erk:nriediRMXo II Introduction,It$tallation,and OperatingInstructions
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 SystemUser Guide.s
Extended iRltlXÒ II Nucleus U.ser'sGuide
Extended iRMXo II Ba.sicI/O SystentUser'sGuide
Guide
Extended |RIVX@I I E.rtendedI/O SystentU.ser'.s
Extended iRM)P ll Hurnctn Interface User'sGuide
Extended iRMXo II Applicatbn Loader User'sGuitle
Erteruled iRl'ltX@ll UniversalDevelopment Intefaca U.ser'sCuide
Device Div'cr.s Uscr's Gu' le
VOLUME
3: Ertended iRMXo II Sy*em Calk
Extended iRMXo II
Extended iRMÀ@II
Extended iRhl}.@ II
Ertended |RMX@ll
Extended iRMXa II
Ertended iRlllYù II
VOLUME
Nucleus SystentCalls Referente Manual
Basic I/O SystemCalls ReferenceManual
Ertended I/O System Calls Reference Manual
Applicatiort Loader SystentCalls ReferenceManual
Hurnrut Interface Sy-stent
Calls ReferenceManrutl
UDI Sl,sternCalls ReferenceMartual
4: Ertendad |RMX@II Operuting $,stem Utilities
Extended iRltlX@II Bootstrup Loadar ReferenceManual
Extended iRlt't)@II S1'stent
DebuggerRet'erencel4anual
Extended iRltl)'@ II Di.sk Verification Utility Ret'ere ce lllanual
Extended |RMXò II Progranuning TechniquesReferenceMrutual
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 ReferenceManual
lv
iRl\tX@ll SystemUtilitiesand ProgrammingInformationVolume
REV.
-001
REVISIONIIISTORY
f)riginnll**ur
DATE
0l/88
intel
E X T E N D Ei D
RMX@II
B O O T S T R ALP
OADER
R E F E R E NM
CAEN U A L
l n t e lC o r p o r a t r o n
3 0 65 B o w e r sA v e nue
S a n t aC l a r aC
, a l i f o r na 9 5 0 5 1
C o p y r i g h t I 9 8 8 , I n t e lC o r p o r a t r o A
n ,i l R g h t sR e s e r v e d
PREFACE
INTRODUCTION
The BootstrapLoaderenablesyou to generatea systemîhat canbootloadfrom Intelsuppliedor customdevices.A hootablesystemgainscontrolimmediatelyafterpower-up
or systemreset. This manualprovidesinformationthat enablesyou to configureyour
systemto boot from specificdevices,to includeyour own customdevicedriversaspart ol
the system,and to placeyour generatedsysteminto PROM devices.
READERLEVEL
The manualassumes
thatyou arefamiliarwith the iRMX ìl Operating
Systemandan
editorwith whichyou canedit sourcecodefiÌes. lt may alsobe helpfulif you are familiar
with the following:
o
SUBMITfiles.
.
ASM86 sourcecoclefiles.
MANUALOVERVIEW
This manualis organizedastbllows:
ChapterI
This chapterprovidesan overviewof the BootstrapLoaderoperations.
Chapter2
This chapterprovidesan operator'sviewpointof usingthe Bootstrap
Loader.
Chapter3
This chapterdescribes
how to configurethe first stageof the Bootstralr
Loader.
Chapter4
This chapterdescribes
how ro configurethe third srageof the
Bootstrap
Loader.
Chapter5
This chapterdescribes
how to write customfirst-stagedrivers.
Chapter6
This chapterclescribes
how to write customthird-stagedrivers.
Bootstrap[,0ader
llt
PREFACE
Chapter7
error handlingprocedures.
This chapterdescribes
AppendirA
how to includeautomaticboot device
This appendirdescribes
your
systcm.
it
ion
into
rccogn
AppendixB
This appendixdescribes
how to load the BootstrapLoaderand the
monitorinto PROM devices.
CONVENTIONS
are usedthroughoutthis manual:
The followingconventions
o
whenshownin keyboard
InformationappearingasUPPERCASEcharacters
examplesmustbe enteredor codedexactlyasshown.You may,however,mix lower
whenenteringthe text.
and uppercase
characters
.
within anglebrackets( < > ) whenshownin
Fieldsappearingaslowercase
characters
variableinformation.You mustenteran appropriate
keyboard
examples
indicate
valueor symbollbr variablefields.
.
User input appearsin one of the followingforms:
as bolded
tv
text
nithln
a screen
.
The term"iRMX If'refersto the Extended
iRMX ll.3 Operating
System.
.
The term'iRMX I'refersto the iRMX I (iRMX 86)Operating
System.
.
All numbers,
unless
otherwise
stated,areassumed
to be decimal.Hexadecimal
numbersincludethe "H" radixcharacter
(for example,
OFFH ).
Bootstrapl,oadcr
CONTENTS
CHAPTER1
OVERVIEW
OF BOOTSTRAP
LOADEROPERATIONS
PAGE
CHAPTER2
USINGTHEBOOTSTRAP
LOADER
PAGE
CHAPTER3
CONFIGURING
THEFIRSTSTAGE
PAGE
Bootstrap [,oader
CONTENTS
CHAPTER3 (continued)
PAGE
CHAPTER4
THETHIRDSTAGE
CONFIGURING
PAGE
vl
BrntstrapInader
CONTENTS
CHAPTER4 (continued)
PAGE
CHAPTER5
WRITINGA CUSTOMFIRST.STAGE
DBIVER
PAGE
5.1Introduction
..............................5-1
5.2 DeviceInitializeProcedure...........
.......................5-2
5.3 DeviceReadProcedure....
.............................
5-3
5.4 Supplying
Configuration
Information
to the First-Stage
Driver...............................5-4
5.4.1Hard-Cocìing
the Configuration
Information
.......................5-4
5.4.2Providing
a Configuration
Fiìe......................
..........................5-5
5.5 Usingthe MULTIBUS@
Il TransportProtocol
.............................5-8
5.5.1Message
Passing
ControllerInitialization..
...........................5-9
5.5.2Message
Tlpes..................
..........,..............5-10
5.5.3Request/
Response
Transaction
ModeI.........
.......................
5-10
5.5.4Sendand Receive
Transaction
Models
................................
5-l5
5.5.5Message
Broadcasting......
.........................
5-20
5 . 5 . 6T r a n s m i s s i M
o no d e s . . . . . . . . . . .
......................5-22
5.5.7Interconnect
Space
.......5-22
5.5.8DriverCodeConsiderat
ions......................
.............................
5-30
5.6 Changing
BSl.A86or BS1M82.,486
to Includethe NewFirst-Stage
Driver........
5-33
-5.7Generating
a NewFirstStageContaining
theCustomDeviceDriver..................
5-34
CHAPTER6
WRITINGA CUSTOMTHIRD-STAGE
ORIVER
PAGE
6.1 Introduction
..................,...........6-1
tr.2 Whata Third-Stage
DeviceDriverMustContain.....
........,...........6-1
6.3 DeviceInitialization
Procedure...........
................
6-3
6.4 DeviceReadProcedure
..........6-4
6.5 Protected
ModeConsiderations
....................
...................................6-ó
6.(rSupplying
Configuration
lnformationto theThird-Stage
Driver..............
...............6-1
ó.7 UsingMULTIBUS@
II TransportProtocol
..............
......................6-8
6.8 Changing
BS3.A86
to Includethe NewThird-Stage
Driver............................-..........6-8
fi.9 Generating
a NewThirdStageContaining
the CustomDriver.................
...............6-9
BootstrapLoader
vtl
CONTENTS
CHAPTEB7
PAGE
ERRORHANDLING
7.1Introduction
..............................7-1
-l
7.2 Analyzing
...............l
Bootstrap
LoaderFailures.
-1
7.2.1ActionsTakenby theBootstrap
.....................7
LoaderAfter an 8rror...,..........
-2
7.2.2 AnalyzingBrrorsWith DisplayedError Messages
.
.............7
7.2.3 Analyzing
ErrorsWithoutDisplayed
Error Messages.......................................7-5
-7
7.2.4lnitialization
Errors..............
........................7
APPENDIX
A
PAGE
AUTOMATICBOOT DEVICERECOGNITION
4.1 Introduction...........................
...............................A-1
A.2 How AutomaticBootDevìceRecognition
Works...........
............
A-1
A.3 How to IncludeAutomaticBootDeviceRecognition.......
.........
A-2
A.4 How to Exclude
AutomaticBootDeviceRecosnition
.............................................
A-5
APPENDIX
B
PAGE
PROMMING
THEBOOTSTRAP
LOADER
ANDTHEISDM"MONITOR
B.l Introduction
.............................B-1
8.2 Incorporating
theiSDM"Monitor..............
....................................8-l
vltt
Brxrtstrapl{)ader
CONTENTS
TABLES
TABLE
PAGE
l-1 Intel-Supplied
Bootstrap
LoaderDrivers.
......................................
1-8
2-1 Supplied
Third StageFiles.....................
..............2-7
3-l Procedure
Namesfor Intel-Supplied
FirstStageDrivers...............,........................
3-25
3-2 5.25-lnchDiskettesSupportedby iSBC@
20tland MSC-specificDrivers.............
3-26
3-3 8-InchDiskettes
Supported
by iSBC@
208and MSC-Specific
Drivers..................3-2ó
4-l Namesfor Intel-Supplied
Third StageDrivers................
..............4-7
4-2 MemoryLocations
Usedby the Bootstrap
Loader...................................................4lfi
7-I Postmortem
-6
Analysis
of Bootstrap
LoaderFailure..
....................7
FIGURES
FIGURE
B(x)tstrap Lr|ader
PAGE
LX
CHAPTER1
OVERVIEW
OF BOOTSTRAP
LOADEROPERATIONS
1.1 INTRODUCTION
The BootstrapLoaderis a programthat is not part of anyparticularOperatingSystem.
storage
Rather,it is a programthat loadsan applicationsysteminto RAM from secondary
so that it canbeginrunning.This processis calledbootstraploadìngor booting. Booting
canoccurwhenthe systemis turnedon, whenthe systemis reset,or underoperator
controlwhenthe monitoris active.
into PROM
The BootstrapLoadereliminatesthe needto placecompleteapplications
program--into
devices.Instead,you canplacethe BootstrapLoader--irrelativelysmall
PROM devicesand storeyour applicationsystemon a massstoragedevice.The Bootslrap
Loadercanthenbe usedto load the applicationprograminto RAM.
of threestages.
The BootstrapLoaderconsists
The first stageresidesin PROM devices.It determinesthe nameof the file to load,loads
controlto that part. Intel System300Series
part of the secondstage,and passes
are deliveredwith the first stageof the BootstrapLoaderand the iSDM
Microcomputers
monitor alreadyplacedin PROM devices.Intel ModulesDevelopmentPlatformsare
deliveredsimilarlyexceptwith the D-MON386monitor. If you are huildingyour own
you canusethe informationin this manualto configurea first stageand
computersystems,
placeit into PROM devices.
The secondstageresideson track0 of everyiRMX-formattcdnrmed volume. That is,
wheneveryou usethe HumanInterlàceFORMAT commandto format a volume,the
secondstageis copiedto that volume. Wheninvoked,the secondstagefinishesloading
itselfinto memoryand thenloadsa file from the samevolumeand passescontrolto it.
The contentsof thisload file dependon the kind of systemyou are loading.If you are
loadingan iRMX I system,the file loadedby the secondstagecontainsthe application
systemitself. Ifyou are loadingan iRMX II system,the file loadedby the secondstage
containsthe third stageof the BootstrapLoader,whichfinishesthe loadingprocess.
BootstrapLoader
l-l
OVERVIEWOF BOOTSTRAPLOADEROPERATIONS
for loadingiRMX ll applications,
becausetheseapplications
Thc third stageis necessary
requirethe 80286processorto be runningin protectedmodeand becausetheyusethe
OMF-2tì6objectmoduleformat. The OMF-28fiformat is differentfrom the OMF-86
format and thereforecannotbe handledb1'thesecondstage.The third stageplacesthe
processorin protectedmode,loadsthe iRMX II applicationsystem,and transferscontrol
to that applicationsystem.The third stageresidesin a namedfile on the samevolumeas
the secondstage.Your BootstrapLoaderpackagecontainsa configuredthird stagethat
canloadapplications
from selected
devices.The instructions
in thismanualcanhelpyou
configureyour own third stageto add supportfor otherdcriees.
The bootstraploadingprocesscannotbe completedwithouta devicedriver. The device
driver is a smallprogramthat providcsthe interfacebetweenthe BootstrapLoaderand a
hardwaredevice(or a controllerfor the device).Whenyou configurethe Bootstrap
Loader(a taskthat is independent
of operatingsystemconfiguration),
you specifothe
devicedriversthat the BootstrapLoaderrcquires.Duringthe courseof configuration,
thesedevicedrivers(whichare usuallydistinctfrom the drìversneedetJ
by the application
system)
are linkedto the Bootstrap
Loaderautomatically.
1.2THESTAGESOFTHEBOOTSTRAP
LOADER
T h e B o o t s t r a pL o a d e r h a s a n u m b e ro f s t a q e st h a t c o n t r o lt h e l o a c l i n go f t h e a p p l i c a t i o r .
s y s t e m .i R M X I a p p l i c a t i o n sl o a d u ' i t h a t w o - s t a g ep r o c e s s .i R M X I I a p p l i c a t i o n su s e
t h e s et w o s t a g e sb u t a l s or e q u i r ea t h i r d s t a g e .
1.2.1 FirstStage
The Bootstrap Loader's first stageconsistsof two parts. One part is the code for the first
stage,and the other part is a set of minimal devicedrivers used by the first and second
stagesto initialize and read from the devicethat containsthe systemto be booted.
The Bootstrap Loader packagecontainsdevicedrivers 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 stagemust be in one of two places. The natural
place fbr the first stageis in PROM devices,either as a standaloneproduct or combined
w i t h a m o n i t o r . f n t e l S y s t e m3 1 0 a n d 3 8 0 S e r i e sM i c r o c o m p u t e r sa r e d e l i v e r e dw i t h t h e
Bootstrap Loatler's first stage,the iSDM monitor, anrJthe SystemConficlenceTest (SCT)
in the PROM devices. Intel System320 SeriesMicrocomputers are deliveredwith the
Bootstrap Loader's first stage,the iSDM monitor, the D-MON3tì(r monitor, and the SCT in
t h e P R O M d e v i c e s .I n t e l M o c i u l e sD e v e l o p m e n P
t l a t f o r m sa r e d e l i v c r e dw i t h t h e
B o o t s t r a pL o a c l c r ' sf i r s t s t a g e ,t h e D - M O N 3 8 6 m o n i t o r ,a n d t h e S C T i n t h e P R O M
devices.
t-2
Brxrtstrap [-oader
OVERVIEWOF BOOTSTRAPLOADEROPERATIONS
l f y o u h a v ea s y s t e mt h a t i n c l u d e st h e i S D M m o n i t o r a n d y o u a r e a c l d i n gy o u r o w n d e v i c e
driver to the Bootstrap Loader's first stage,you might find it useful to load the first stage
into the target system'sRAM using a developmentsystemiSDM kracìerand activatethc
f i r s t s t a g eu n d e r i S D M c o n t r o lf r o m t h e d e v e l o p m e nst y s t c m .A f t e r a c t i v a t i n gt h e f i r s t
s t a g e y, o u c o u l d t h e n d e b u gd r i v e r c o d e . I f y o u r s y s t e mi n c l u d e st h e D - M O N 3 8 ( rm o n i t o r ,
however,you must perform all driver debuggingfrom the target system. You cannot
download the first stagefrom a developmentsysteminto the target systemand then use DM O N 3 8 ó t o i n i t i a t ep r o g r a me x e c u t i o n .W h e n d e b u g g i n gu n d e r t h e s el a t t e r c i r c u m s t a n c e s ,
y o u m a y w i s h t o e i t h e r d e b u gw i t h i n t h e P R O M d e v i c e so r p e r h a p su s e a w o r k i n g
B o o t s t r a pL o a d e r t o b o o t l o a dt h e B o o t s t r a pL o a d e rt h a t c o n t a i n st h e n e w d r i v e r .
W h e n t h e f i r s t s t a g eb e g i n sr u n n i n g ,i t f i r s t i d e n t i f i e st h e b o o t s t r a pd e v i c ea n d t h e n a m e o f
t h e f i l e t o b o o t , e i t h e r b y a c c e p t i n gt h a t i n f o r m a t i o nf r o m a c o m m a n dl i n e e n t e r e cul t t h e
m o n i t o r o r b y u s i n gd e f a u l tc h a r a c t e r i s t i cess t a b l i s h c w
d h c n t h e f i r s t s t a g ew a s c o n f i g u r e t ì .
T h e B o o t s t r a pL o a d e r n e x tc a l l si t s i n t e r n a ld e v i c ed r i v e r f o r t h e c l e v i c ew, h i c h i n i t i a l i z e s
the device and reatis the first portion of the secondsttìgeinto memory. (The secondstage
alwaysresideson track 0 and block 0 of the named volume, so it can be accessedeasily by
t h e f i r s t s t a g e . )A f t e r c a l l i n gt h e i n t e r n a ld e v i c ed r i v e r ,t h e î i r s t s t a g ep a s s e sc o n t r o lt o t h e
secondstage.
Becausethe first stageworks on both lt0tl6/ lllfi- ancl802t16/31.ì(r-basccl
computers,it
o p e r a t e si n r e a l a d d r e s sm o d e w h e n r u n n i n gi n a n t l 0 2 t l 6 / 3 8 6 - b a s esdy s t c m .T h i s m e a n s
that any devicedrivers you write for the first stagemust also opcrate in real addressmode.
1.2.2 SecondStage
Unlike the first stage,the secondstageof the Bootstrap Loadcr is not configurable. Its slze
i s a l w a y st h e s a m e( l e s st h a n f ì K b y t e s ) ,a n d i t d o e sn o t d e p e n do n t h e a p p l i c a t i o ni n a n y
w a y . T h e c o t ì ef o r t h e s e c o n ds t a g er e s i d e so n a l l v o l u r n e sf o r r r a t t c dw i t h t h e i R M X I o r
i R M X I I H u m a n l n t e r f a c eF O R M A T c o m m a n d s .T h e r c f ì r r e t, h e s e c o n ds t a g ci s a l w a y s
availablefor loading applicationsresidingon random accesstlevices.
W h e n t h e s e c o n ds t a g er e c e i v e sc o n t r o l ,i t f i n i s h e sl o a d i n gi t s c l f i n t o m e m o r y a n d t h e n
loads the file determined by the first stage. When loading the file, it usesthe same device
driver used by the first stage. In iRMX I systems,the load file is the application systcm
i t s e l f . I n i R M X I I s y s t e m st,h i s f i l e i s t h e t h i r t l s t a g eo f t h e B o o t s t r a pL o a d e r .
Bmtstrap LOader
l-3
OVERVIEWOF BOOTSTRAPLOADER OPERATIONS
NOTE
II.3 OperatingSystemfrom a
You cannotbootstrapload the iRMX IL 1, 11.2,
volumethat wasformattedusingthe iRMX 1.6or I.7 (iRMX 86 Release6 or 7)
FORMAT command.However,you canmakethe volumebootablewithout
reformattingthe entirevolumeand losingthe datastoredon it. To be ableto
from the samevolume,
boot both the iRMX I and iRMX II OperatingSystems
invokethe iRMX II.3 FORMAT commandand specifythe BOOTSTRAP
control. With BOOTSTRAPspecified,FORMAT just replacesthe second
stageon track0 of the volumewhile leavingthe remainingdatauntouched.
When the FORMAT commandfinishes,you canbootstrapload both the iRMX
from the samevolume.
I and iRMX II OperatingSystems
1.2.3ThirdStage
The third stageof the BootstrapLoaderis usedfor loadingiRMX Il-basedapplications
into memory.The third stageresidesin a namedfile on the bootstrapdevice.Both the
third stageand the applicationsystemto be loadedmustresidein the samedirectoryon
the volume.
third stage.
There are two typesof third stages:a genericthird stageand a device-specific
The type neededfor your systemdependson the sizeof the applicationsystemyou intend
to load.
1 .2.3.1 Generic Third Stage
from any
The genericthird stageis so namedbecauseit canload applicationsystems
devicethat the first stagerecognizes.This stagecontainsno devicedriverof its own.
Instead,it usesthe samedevicedriverusedby the first and secondstages.This meansthat
you won't needto write a separatedevicedriverto work in protectedmode,but it also
meansthat the genericthird stagerunsin real addressmode. In real addressmode,
addressability
is restrictedto the first (lowest)megabyteof memory.Therefore,the
genericthird stagecanloadonly thoseapplicationsystems
that are smallerthan 840K
bytes.The remainingspaceis usedby the BootstrapLoader,the monitor and the SCT. To
load largerapplications,
you mustusea device-specific
third stage.
When the genericthird stagereceivescontrol,it usesthe devicedriversuppliedin the first
stageto load the applicationsystem.Then it switchesthe processorinto protectedvirtual
addressmodeand passes
controlto the application.
l-4
Bo()tstraplrader
OYERYIEWOF BOOTSTRAPLOADEROPERATIONS
1.2.3.2Devicespecilic
ThirdStage
The device-specific
third stageswitchesthe processorto protectedvirtualaddressmode
beforeloadingthe applicationsystem.This enablesthis stageto load into memory
addresses
higherthan one megabyte.However,becausethis stageswitchesthe processor
into protectedmode,it cannotusethe first stage'sdevicedrivers(whichoperateonly in
real mode). Instead,it mustcontainits own devicedriver,operatingin protectedmode,to
controlthe devicefrom whichthe applicationsystemis loaded.
The device-specific
third stagesuppliedin your BootstrapLoaderpackagesupportsthe
following devices:
.
iSBC21SG/iSBX2l8A winchesterand diskettecontrollercombinationor the
iSBC214controller
.
iSBC264bubblememorycontroller
.
controller
iSBC 186/224Amulti-peripheral
o
Systems
SCSI(SmallComputerSystemslnterface)anooo<:pm<>"
message
at the terminal,issuesits prompt(a singleperiodfor real-modeiRMX I
andwaitsfor a command
iRMX II systems),
fwo
systems, periodsfor protected-mode
from the terminal.At this point the operatorcaninvokeanyof the iSDM monitor
commandsthat are appropriatefor real or protectedmode. (To continuerunningthe
loadedprogram,enterG .)
tellsyou that
of the Debugswitchis that the monitor'sinterruptmessage
One advantage
you
not
fails,
might
you
are
booting
If
a
system
process
was
successful.
the loacling
whether
the
or
otherwisebe ableto tell whetherthe bootstrapload itselfwasunsuccessful,
and then failed during initialization. The presenceor absenceof
systemloadedsuccessfully
whenyou usethe Debugoptionclarifieswhetherthe loadingwas
the interruptmessage
successful.
Bootstrapl-oader
, -'l
LOADER
USINGTHE BOOTSTRAP
Becausethe Debugoptionleavesyou in the monitor,you canalter the contentsof specific
memorylocationsandperformother monitoractions(suchas, inval-id interface type
ERROR
E R R O R- i n v a l i d
Daraneter
cornbination
3.2.4 "/"CPUMacro
The %CPU macroidentifiesthe typeof CPU that performsthe bootstraploading
operation.You mustincludethis macroin the BS1.A86or BSlM82..486file once(and
only once).
The syntaxof the CPU macrors
%CPU(cpu_type)
where:
cpu_type
The typeof CPU performingthe bootstrapoperation.Valid typesare:
Typ"
Description
8086
8088
8018ó
801llti
80286
80386
8[ì86processor(iRMX I only)
8088processor(iRMX I only)
(iRMX I only)
8018óprocessor
lì0ltllìprocessor(iRMX I only)
80286processor
(iRMX I andiRMX II)
80386processor(iRMX I and iRMX II)
llOnly)
3.2.5 "/"BMPSMacro(MULTIBUS@
passingsystemusedduringbootstraploading.
The %BMPSmacroconfiguresthe message
(MPC),
Coprocessor
This macroidentifiesthe baseaddressof the MessagePassing
addressdistancebetweenMPC ports,and informationthat defineshow directmemory
access(DMA) transfersoccur. If you havea MULTIBUS II systemthat bootloadsfrom a
devicewhosedriverusesMULTIBUS II transportprotocol(i.e.the 186/224Adriver),you
mustusethis macro. lf you havea MULTIBUS I s)'stemor a systemthat bootloadsfrom a
devicewhosedriverdoesnot useMULTIBUS II transportprotocol,you mustnot usethis
macro.
Bootstraplnader
3-ll
CONFIGURINGTHE FIRST STAGE
The syntaxof the %BMPSmacrols
port$sep,duty$rycle,
dma$in,dma$out,
dma$base$addr,
%BMPS(mpc$base$addr,
dma$trans,
data$width)
where:
mpc$base$addr
The baseI/O port addressof the MPC. Referto the
appropriatesingleboardcomputeruser'sguidefor this
address.
port$sep
The numberof addresses
separatingindividualMPC
ports. For example,if the mpc$base$addr
is 0000Hand
the nextthreeI/O port addresses
are 0004H,0008H,
and 000CH,respectively,
the port$sepis 4H. Referto
the appropriatesingleboardcomputeruser'sguidefor
the l/O port addressmap.
duty$rycle
The MPC duty cyclefor the localbus. (The rate at
whichdatapacketsare generated.)For informationon
how to calculatea dutycyclesuitablefor the localbus,
refer to the MPC User'sManual. For duty cyclessuitable
for Intel singleboardcomputers,refer to the appropriate
singleboardcomputeruser'sguide.
dma$base$addr
The baseI/O port addressfor the AdvancedDirect
MemoryAccess(ADMA) controller.Referto the
appropriatesingleboardcomputeruser'sguidefor this
address.
dma$in
The channelusedto receive(input) DMA message
passingtransfers.Referto the appropriatesingleboard
computeruser'sguidefor this channelnumber.
dma$out
The channelusedto send(output)DMA message
passing.Referto the appropriatesingleboardcomputer
user'sguidefor thìschannelnumber.
dma$trans
The l/O port addressusedfor DMA datatransfers.
Reier to the appropriatesingleboardcomputeruser's
guidefor this address.
data$width
The datawidth in bits of the localbus. This valuemust
be eitherl6 or 32 ldecimall.If thewidthis setto 32 bits
on a 386/116-or 386/120-based
board,flyby(onecycle)
DMA modeis enabled.
The %BMPSmacrocan qenerateerrorsif the localbuswidth is not l6 or 32 bitswide.
3-t2
Bmtstrap l-oader
CONFIGURINGTHE FIRST STAGE
3.2.6 %IAPX186 lNlT Macro(!RMXI MULTIBUS@
| Systems
Only)
T\e o/oIAPX_186_INIT
macrospecifies
the initialchip selectand modevaluesfor 8018ó
and 80188CPUs. Includethis macroonly for systems
that usethe 80186or 80188
processorand do not includea monitor in PROM devices.In systemsthat includethe
iSDM monitor,the monitorbecomesactivebeforethe BootstrapLoader,and the monitor
mustinitializethe CPU. An iSDM configurationmacrois availablefor this purpose.See
the iSDM SystemDebugMonitor Reference
Manual for more information.
The syntaxof the iAPX_186_INITmacrois
ToiAPX_186_INIT(rmx,
umcs,lmcs,mmcs,mpcs,pacs)
where:
rmx
The initial modeof the 80186Programmable
InterruptController
(PIC). Acceptablevaluesare as follows:
Value
Description
v
The 8018óPIC is initializedin iRMX compatibility
mode.
n
The 80186PIC is initializedin defaultmode.
umcs
Initial valuefor the upper-memory
chip-select
controlregister.
lmcs
Initial valuefor the lower-memory
chip-select
controlregister
mmcs
Initial valuefor the midrange-memory
chip-select
controlregister.
mpcs
Initial valuefor the memory-peripheral
chip-select
controlregister.
pacs
Initial valuefor the peripheral-address
chip-select
controlregister.
In all parametersexceptthe first one (rmx),NONE is alsoan acceptable
value,implying
that no initializationvalueshouldbe placedin the corresponding
register.For information
on the chip-select
controlregisters,
and the valuesto placein them,seethe datasheetsfor
the 80186and 8018t1
processors.
All the defaultparametervaluesfor this macro(in the Intel-supplied
BSl.Alt6file shownin
Figure3-1)areappropriate
to initialize
the CPUson the iSBC186/03(A),
iSBC186/51
and iSBC 188/48/56 boards.
The iRMX I OperatingSystemdoesnot allowyou to movethe 80186relocationregisterto
I/O addresses
other than 0FF00H,its defaultregister.
Bootstrapl-oader
3-13
CONFIGURINGTHE FIRST STAGE
%MANUAL,
3.2.7%CONSOLE,
and %AUTOMacros
The CONSOLE,MANUAL, andAUTO macrosspecifyhow the first stageidentifiesthe
file that the secondstagewill load (eitherthe loadfile or the third stage)and the deviceon
whichthe file is found.
o/oMANUAL,and %AUTO macrosis
The syntaxof the a/oCONSOLE,
TaCONSOLE
TaMANUAL
ToAUîO
Thereare no parametersassociated
with anyof thesemacros.
Dependingon the actionyou want the BootstrapLoaderto take,you can includenone,
any,or all of thesemacros,and the combinationyou choosedefinesthe set of actions
taken. Becausethe ToMANUAL macroautomatically
includesboth the %CONSOLEand
%AUTO macros,five functionally-distinct
combinations
are possible.Eachof these
combinations
requiresthat the devicelist at the end of the BS1.A86or BS1MB2.A86file
be setup in a certainway. For more informationon the devicelist,seethe discussion
of
the ToDEYICE macro later in this chapter. The following paragraphslist the possible
macrocombinations,
the devicerequirements,
and the actionsthat the BootstrapLoader
takeswheneachcombinationis invoked.
(Requiresthat the devicelist definedwith ToDEVICEmacroshave
No
o/oCONSOLE, only one entry.)
%MANUAL.
or TaAU'fO
macro
3-14
o
The BootstrapLoadertriesonceto load from the activedevice.
.
The BootstrapLoadertriesonceto loadthe file with the default
pathname(the oneyou definewith the %DEFAULTFILE macro).
Bo0tstraplrader
CONFIGURINGTHE FIRST STAGE
ToCONSOLE (Requires
thatthedevicelisthaveonlyoneentry.)
oruy
.
The BootstranLoadertriesonceto load from the devicein the device
list.
r
The BootstrapLoaderissuesan asterisk(*) promptat the console
terminalandwaitsfor an operatorto cnter the pathnameof the file to
load. It triesonceto load the file the operatorspecifies.
-- If the operatorentersa pathname,the BootstrapLoaderloads
the file with that pathname.
-- If the operatorentersa CARRIAGE RETURN only,the lile
with the defaultpathnameis loaded.
(Requiresa devicelist with at leastone entry.)
%MANUAI
only
.
The BootstrapLoaderissuesan asterisk(*) promptfor a pathnameat
theconsole
terminal.
.
The BootstrapLoaderchoosesa devicedependingon the operator's
response.
-- lf a devicenameis entered,the BootstrapLoaderloadsfrom
that device.It triesto load until the devicebecomesreadyor
until no more triesare allowed(as limitedby the optional
%RETRIESmacro).
-- If only CARRLq.GERETURN is entered,the BootstrapLoader
throughthe list of devices
looksfor a readydeviceby searching
(in the orderthe ToDEVICEmacrosarelistedin the BSl.,486
or BSI MB2.A86file). The searchcontinuesuntil a readydevice
is foundor until no more triesare allowed(aslimitedby the
optional%RETRIESmacro). If the BootstrapLoaderfindsa
readydevice,it loadsfrom that device.
.
The BootstrapLoaderchoosesa file dependingon the operator's
response.
-- If a pathnameis entered,it triesonceto load the file with that
pathname.
-- If no file nameis entered,it triesonceto loadthe file with the
defaultpathname.
Bmtstrap [-oader
3-15
CONFIGURINGTHE FIRSTSTAGE
(Requiresa devicelist with at leastone entry.)
%AUTO
.
The BootstrapLoaderlooksfor a readydeviceby searching
throughthe
list of devices(in the orderthe %DEVICE macrosare listedin the
BSl.A86or BSlM82.A86file). The searchcontinuesuntil a ready
deviceis foundor until no more triesare allowedlas limitedbv the
optional% RETRIESmacro).
.
If the BootstrapLoaderfindsa readydevice,it triesonceto load the
file with the defaultfile name.
o/oAUTO,
ToMANUAL,
and
o/aCONSOLE
(Requiresa clevicelist with at leastone entry.)
.
The BootstrapLoaderissuesan asterisk(*) prompt for a pathnameat
theconsole.
.
with a pathnamethat containsno devicename,
If the operatorresponds
the BootstrapLoaderlooksfor a readydeviceby searching
throughthe
list of devices(in the order the %DEVICE macrosare listedin the
BSl.A86or BSlMB2.A86file). The searchcontinues
untila ready
deviceis foundor until no more triesare allowedlas limitedbv the
optionalToRETRIES
macro).
.
lf the BootstrapLoaderfindsa readydeviceor the operatorresponds
with a pathnamecontaininga devicename,the BootstrapLoadertries
.,"':..
l;:::l;il:l:'::',:"?
::::T:::
;:T;':.,,^",
lathname.
-- If only CARRIAGE RETURN is entered,it triesto load the file
with the defaultpathname.
Wheneverthe BootstrapLoader'sasteriskpromptappears,the operatorcan includea
DebugSwitchalongwith a deviceand/or filenamespecification.The DebugSwitchis
clescribed
in Chapter2.
3.2.8 o/"LO
ADFILE Macro
The %LOADFILE macrocausesthe BootstrapLoaderto displaythe pathnameof the file
itloads. If you areloa is an lnvalid
Serial Channel type
port delta for the Baud Rate Timer
Invalid
8253/4 Baud Rate Counter is not 0, 1or
2
Counter 2 is the only valid
80130 Baud Rate Counter
80186 counter counter,type
is not a valid
Baud Rate Counter
is an invalid
Baud Rate Tirner cype
Counter 0 is the only valid
82530 Baud Rate Counter
825J0 channel must be specified
as A or B only
Max Baud Rate Count must be sreater
than 1
Bootstrap lnader
3-23
CONFIGURING
THE FIRSTSTAGE
3.2.14%DEVICE
Macro
The VoDEYICEmacrodefinesa deviceunit from whichyour appÌicationsystemcanbe
bootstraploaded.If the BS1.A86or BS1MB2.A86
file containsmultipleToDEYICE
macros,their order in the file is the order in whichthe first stagesearches
for a ready
deviceunit.
All,ToDEYICEmacrosthat selectdeviceunitson the samecontrollermustbe listed
consecutively
in BS1.A86or BSlMB2.A86,or assembly
errorswill occur. Recallthat
multiple%DEVICE macrosmaybe includedonly if the VoAUTOor ToMANUAL macro
is included(otherwise,
an error occursduringthe assembly
of BS1.,486or 8S1MB2.A86.1.
The syntaxof the ToDEVICEmacrois
ToDEVICE(name, unit, device$init,device$read,unit info)
where:
name
The physicalnameof the device,not enclosedin quotesor between
colons.This is the namethat you wouldenterto specirythis device
wheninvokingthe BootstrapLoaderfrom the keyboard.(However,
wheninvokingthe BootstrapLoader,you would surroundthis name
with colons.)
After the BootsîrapLoaderloadsfrom a device,it passesthe physical
nameof îhe device,aslistedhere,to the load file. To enablethe
OperatingSystem's
AutomaticBoot DeviceRecognitioncapability(see
AppendixA) to function,this physicalnamemustmatcha device-unir
namefor the deviceasspecifiedduringthe confìguration
of the
OperatingSystem. Refer to the InterúctiveConfigurationUtílity
Reference
Manualfor more informationaboutconfiguringthe
OperatingSystem.
3-24
unrt
The numberof this unit on this device.Unit numberingis the sameas
that usedfor devicesby the BasicI/O System.Referto theDevice
Diver User'sGuideîor more informationaboutunit numbering.
device$init
The nameof the deviceinitializationprocedurethar is part of the first
stagedevicedriverfor this device-unit.Beforeattemptingto readfrom
the device-unit,
the BootstrapLoadercallsthis proce<.lure
to perform
initializationfunctions.If the device-unithasan Intel-supplied
device
driver,specifythe nameof the deviceinitializationprocedureaslisted
in Table3-1. Ifyou supplyyour own driver(writtenas describedin
Chapter5), enterthe nameof the initializationprocedure.
Bootstraplr}ader
CONFIGURINGTIIE FIRST SI'ACE
device$read The nameof the devicereadprocedurethat is part of the first stage
devicedriverlbr this device-unit.To readfrom this device-unit.
the
first and secondstagesof the BootstrapLoadercall this procedure.lf
your BootstrapLoaderusesa genericthird stage,it too usesthis device
readprocedureto readliom the deviceunit. If the device-unithasan
Intel-supplied
devicedriver,specifythe nameof the deviceread
procedureaslistedin Table3-1. If you supplyyour own driver (written
asdescribedin Chapter5), enterthe nameof the deviceread
procedure.
unit info
An ASM8ólabelthat marksthe locationof an arrayof BYTEs
containingspecificdevice-unitinformationrequiredby the massstorage
devicedefinedby this invocationof the ToDEVICEmacro.
This parameteris currentlyusedonly by the SCSIdevicedriver. Ifyou
includeit for anyotherdevice,the BootstrapLoaderwill fail to load
your applicationfrom that device.Referto the "FirstStageDevice
of the
Driver Files"sectionof this chapter,underthe clescriptions
ToSCSIand 9iSASl UNIT INF'Omacrosfor informationabouthow
anclwhento specifythis unTtinformationand for examplesof its use.
for IntelTabÌe3-l liststhe namesof the deviceinitializationand devicereadprocedures
suppliedfirst stagedevicedrivers.
Table 3-1. I'rocedure Names for Intel-Supplied l'irst StageDrivers
Dsvice Drivor
Devicelnilialize
Procedure
DeviceRead
Procedure
iSBC208 SpecifìcDriver
iSBC208 GeneralDriver *
|SBCMSCSpecificDr ver.
iSBCMSC GeneralDriver
SCSIDriver
iSBX218ADriver
iSBC224ADriver
iSBC251 Driver
iSBC254 Driver
iSBC264 Driver
deviceinit20S
deviceinit20Bgen
deviceinitmsc
deviceinitmscgen
deviceinitscsi
deviceinil2lSA
deviceini1224A
deviceinit25l
deviceinlt254
deviceinlt264
deviceread20S
deviceread20Sgen
devicereadmsc
devicereadmscgen
devicereadscsi
deviceread2'18A
deviceread224A
deviceread25l
deviceread254
deviceread264
as wellas the iSBX218A
The MSC driverssupportthe iSBC214,iSBC215G,|SBC220 controllers,
to supportthe iSBC
controllermountedon the iSBC215Gboard. The driversmustbe reconfigured
220 controller.
for the iSBC208and MSC devices.
Table3-1listshoth specificand generalprocedures
Configurations
of the BootstrapLoaderthat usethe generalversionof eitherdriverwill be
larser.
Bootstrapl-oader
3-25
CONFIGURINGTHE FIRST STAGE
One differencebetweenthe two versionsof thesedevicedriversis that the generalversions
from anyof the standardtypesof diskettesasdefinedin
will bootstrapload applications
only from
the InstallationSystems.The specificversionswill bootstrapload applications
specifictypesof disketteslistedin Tables3-2and 3-3. Thesetablesapplyto the specific
versionsof both the iSBC208and MSC devicedrivers.
Drivers
Table3-2. 525-InchDiskettesSupportedby iSBC208and MSC-Specilìc
Seclor Size
Density
256
256
Singl€
Double
NOTE:
Seclors Der Track
I
The diskettescan be formattedwith either48 tracks p€r inch or 96 tracks per inch, and
can b€ eithersingle-or doubl€-sided.
Table3-3. 8-lnchDiskettesSupportedby iSBC20Eand MsC-SpecificDrivers
Sector Size
Density
128
2s6
Singl€
Double
NOTE:
Seclorso€r Treck
26
26
lhe diskettesmay be eithersingle-or double-sided.
The Intel-supplied
BSl.A86and BS1M82.A8óconfigurationfilesinclude%DEVICE
macrosfor all of the supporteddevices,and includemultipleinstances
of someof the
macrosto indicatemultipleunitson the samedevice.It doesn'thurt to includesupportfor
all of thesedevices,evenif your applicationsystemwon't containall of them. And if you
add a new devicelater,you'll be ableto boot from the devicewithoutgeneratingnewboot
PROM devices.However,you canreducethe sizeofyour BootstrapLoaderby excluding
supportfor devicesthat you neverintendto use. Release3.2of the iSDM monitor
providesspacefrom 0FE400Hto OFFFTFHfor useby the BootstrapLoader. This
requiresyou chooseonly the devicesyou needwhenyou reconfigurethe BootstrapLoader
so it will fit into the spaceallocatedby the iSDM monitor. If the BootstrapLoaderdoes
not fit into the spaceallocatedby the monitor,you mustlocateit belowthe monitor.
To excludea devicedriverfrom the BootstrapLoader,two stepsmustbe performed.First,
excludeall the ToDEYICEmacrosin BS1.A86or BS1M82.A86that applyto deviceunits
on that controller.To do this,edit BS1.A86or BS1MB2.A86and replacethe percentsign
(7o)in îr u 5 L d É Y ,
&
&
&
&
&
&
Change the previous l i n e t o ' s t a r t ( f i r s t s t a g e _ 1 8 6 ) '
iAPX_186_INIT rnacro i s i n v o k e d i n t h e c o n f i g u r a t i o n
if the
fí1e.
s e g si z e ( b o o t ( 1 8 0 0 H) )
Figure3-4. First StageConfigurationFile BSI.CSD
(continued)
Bootstraplrader
3-43
THE FIRSTSTAGE
CONFIGURING
m a pp r i n c ( : f l : 1 2 . m p 2 )
;bootstrap
&
R e m o v eL h e ' ; '
f r o r u t h e l i n e ' : b o o t s t r a p ' w h e ng e n e r a t i n g a
a s t a n d a l o n e B o o t s t r a p L o a d è r í n P R O Mf o r a 8 0 2 8 6 - b a s e d C P U b o a r d .
Do not rernove the ' ;' if uhe BooEstrap Loader ls beÍng generated
f o r a n 8 0 3 8 6 - b a s e d C P Ub o a r d .
Bootstrap Loader fÍrst
stage generation conplete.
Figure 3-4. First StageConfigurationFile BSI.CSD
(continued)
the BSl.CSDSubmitFile
3.5.1 Moditying
To generateyour own versionof the BootstrapLoaderfirst stage,thereare several
changes
you might needto make.
First,ifyou haveexcludedanydevicedriversfrom the BootstrapLoader(by excluding
TaDEYICEmacrosfrom the BSl.A86or BS'lMB2.A86file), you won'tìvantto link the
codefor thosedriversinto the the first stage.To preventthe linkingof a devicedriver,edit
the LINKSócommandin the BSI.CSDfile andplacean ampersand(&) in front of anyfile
namethat corresponds
to a driveryou want to exclude.Figure3-5 is an examplethat
showsa portionof the BSl.CSDfile after excludingthe iSBC208,iSBX 218A,iSBX 251,
iSBC254and SCSIdevicedrivers.
3-44
Bmtstrap l-oader
CONFIGURJNGTHE FIRST STAGE
1ink86
&
f1 :12.obj,
&
f l : b s e r r . o b J,
&
&
f1 :bcico.obj,
& ; for s tandalone s e r i a l
&
f 1 :b 2 0 8. o b j ,
&
f1 :bnsc . obj ,
&
& f l : b 2 1 8 a. o b J ,
&
& fl :b25l.obj,
&
& f l : b 2 5 4. o b j ,
&
fl : b264.obj ,
&
f7:b224a . obj
&
&
f 1 : b s c s i .o b j ,
&
fl :bs1.1ib
&
t o f l : l 2 . l n k p r i n t ( : f l : 2 2 .u r p l ) &
&nopublics except (f irststage,
&
&
firststage_l86,
&
&
&
&
channel support
Renove the '&' from the beginning of the previous line if
iAPX_186_INITrnacro is invoked in rhe configurarion file.
Èhe
Figure3-5. Excludingthe iSBC251and iSBC254Drivers
NOTE
If you excludea dcvicedriver,do NOT includeany %DEVICE macrosfor it in
the BSl.A86or BSI lt{82.A86configurationfile or errorsfrom LINK86 will
occur.
Also, if you are not usingan iRMX I or iRMX II systemto configurethe Bootstrap
Loader,you mustcommentout the commandattachingthe directorywherethe Bootstrap
Loaderfilesresideasthe logicalname:F1:. Changethe line:
ATTACHFILE
$ AS :Fl :
to
;ATTACHFILE $ AS :F1 :
Bootstrap l,oader
3-45
CONFIGURING THE FIRST STAGE
3.5.2 Invokingthe BSl.CSDSubmitFile
invokethe
After you havemodifiedthe BSl.CSDfile to correspondto your configuration,
absolute
and
assiglt
them
together,
the BootstrapLoaderfiles,link
submitfile to assemble
addresses.
The formatfor invokinsthe submitfile is asfollows:
ATTACHFILE
/RMX286/BOOT
SUBMIT
B S l ( f i r s t - s t a g e _ a d d r e s s ,s e c o n d - s t a g e - a d d r e s sI i.r s t - s t a g e - f i 1 e )
where:
3-46
first_stage_address
The startingaddressof the first stageof the Bootstràp
Loader. This canbe a RAM addressifyou intendto run
the BootstrapLoaderfrom RAM, or it canbe a PROM
devicesaddressif you intendto placethe Bootstrap
Loaderinto PROM devices.The addressyou specif
shouldbe a full 20-bitaddress.Do not usethe
base:offset
form to indicatethe address.The iSDM
Release3.2monitorallocatesthe addressrangefrom
0FE400Hto 0FFFTFHto the BootstrapLoader. Ifyour
configurationof the BootstrapLoaderwill not fit in this
space,locateit at a loweraddressthan FF8000H.
second_stage_address
The addressin RAM wherethe secondstageof the
BootstrapLoaderwill be loaded.The dataareafor the
first and secondstagesis alsolocatedhere. The sizeof
this secondstageareaconsistsof lessthan 8K contiguous
bytes.The defaultaddressfor the secondstageis
0B8000H.This addresshasbeenchosento be
compatiblewith the defaultaddressof the third stage
whichis 0BC000H.
first_stage_file
The first-stage
configurationfile to use. lfyour systemis
a MULTIBUS I system,setthis parameterequalto the
the
string'bs1'.Settingthisparameter
to 'bs1'causes
locatedBootstrap
Loaderfile to be named'bs1'.Ifyour
systemis a MULTIBUS II system,set this parameter
to
equalto thestring'bslmb2'.
Settingthisparameter
'bs1mb2'causes
the locatedBootstrapLoaderfile to be
named'bs1mb2'.
B(x)tstrapl-oader
CONFIGURINGTHE FIRSTSTAGE
To invokethe BSl.cSD SUBMIT file with the defaultaddresses
for combiningwith the
iSDM monitor,typeone of the two setsof commandsbelow:
3.6 MEMORYLOCATIONS
OF THEFIRSTANDSECONDSTAGES
when you invokethe BSl.csD file,you assignmemorylocationsto the first and secon rd r r d L ru rr \ rr./
lend
Figure4-3. Intel-SuppliedBG3"{8óFile
4.3.1 o/"BMPS
Macro(MULT|BUS@
il Onty)
The ToBMPSmacroconfiguresthe message
passingsystemusedduringbootstraploading.
This macroidentifiesthe baseaddressof the MessagePassingCoprocessor
(MPC),
addressdistancebetweenMPC ports,and informationthat defineshow directmemory
access(DMA) transfersoccur.
The syntaxof the ToBMPSmacrols
%BMPS (mpc$base$addr,
port$sep,duty$cycle,
dma$base$addr,
dma$in,dma$out,
dmagtrans,
datagwidth)
where:
mpc$base$addr
The baseI/O port addressof the MPC. Referto the
appropriatesingleboardcomputeruser'sguidefor this
address.
port$sep
The numberof addresses
separating
individualMPC
ports. For example,if the mpc$base$addr
is 0000Hand
the nextthreel/O port addresses
are 0004H,0008H,
and 000CH,respectively,
the port$sepis 4H. Referto
the appropriatesingleboardcomputeruser'sguidefbr
the I/O port addressmap.
Bootstrap[.oader
,l-5
CONFIGURINGTHE THIRD STAGE
duty$cycle
The MPC duty cyclefor the localbus. (The rate at
whichdatapacketsare generated.)For informationon
how to calculatea dutycyclesuitablefor the localbus,
refer to the MPC User'sManual. For duty cycles
suitablefor Intel singieboardcomputers,refer to the
appropriatesingleboardcomputeruser'sguide.
dma$base$addr
The baseI/O port addressfor the AdvancedDirect
MemoryAccess(ADMA) controller.Referto the
boardcomputeruser'sguidefor this
appropriatesing.le
address.
dma$in
The channelusedto receive(input) DMA message
passingtransfers.Referto the appropriatesingleboard
computeruser'sguidefor this channelnumber.
dma$out
The channelusedto send(output)DMA message
passingtransfers.Referto the appropriatesingleboard
computeruser'sguidefor this channelnumber.
dma$trans
The I/O port addressusedfor DMA datatransfers.
Referto ihe approprint.singleboardcomputeruser's
guidefor this address.
data$width
The datawidth in bits of the localbus. This valuemust
be eìtherl6 or 32 (decimal).If thewidthis setto 32 bits
board,flyby(onecycle)
on a 386/116-or 386/120-basetJ
modeis enabled.
The ToBMPSmacrocangenerateerrorsif the localbuswidth is not l6 or 32 bitswide.
Macro(853.A86and BS3M82.A86
4.3.2 %OEVICE
Only)
T\e /oDEYICE macroappliesonly to the device-specific
third stage(BS3.A86and
a devicewith a particularthird stagedevicedriver. The
BS3MB2.A86files). It associates
syntajK
of the ToDEYICE macro is as follows:
ta.unit_info )
device$read,
device$da
ToDEYICE(unit, name,device$init,
where:
4-6
unit
The unit numberof this device.Unit numberingshouldbe the sameas
that usedin the BS1.A86or BS1MB2.A86file describedin Chapter3
name
The nameof the device.You shouldalwaysspecifuthe samenamethat
you usedfor the devicein the BSl.A86or BSlMB2.A86file.
Bootstrap LOader
CONFIGURJNGTHE THIRD STAGE
device$init
Publicnameoî the third stagedevicedriver,sinitializationprocedure.
Table4-1liststhe namesusedfor lntel-supplied
devicedrivers.lfyou
supplyyour own driver(writtenasdescribedin Chapter6), enterthe
nameof its initializationprocedure.
device$read Publicnameofthe third stagedevicedriver'sreadprocedure.Table4-1
liststhe namesusedfor Intel-supplied
devicedrivers.If you supplyyour
own driver (writtenasdescribedin Chapter6), enterthe nameof its
readprocedure.
device$data Publicnameof a labelthat marksthe first byteof the datasegmentused
by the third stagedevicedriver. Table4-l liststhe namesusedfor Intelsupplieddevicedrivers.Ifyou supplyyour own driver(writtenas
describedin Chapter6), you mustcreatesucha labeland enterits name
here.
unit info
An ASM86labelthat marksthe locationof an arrayof ByTEs
containingspecificdevice-unitinformationrequiredhy the masssrorage
devicedefinedby this invocationof the %DEVICE macro.
Table4-1 liststhe namesof the deviceinitializationprocedures,
devicereadprocedures,
and datasegments
for Intel-supplied
third stagedevicedrivers.
Table4-1. Namesfor Intel-SuppliedThird StageDrivers
DevicoDriver
OeviceInhislize
Procedur€
DevicaRead
Proc6dure
MSCDriver
iSBC264Driver
iSBC186/224A
Driver
SCSIDriver
deviceiniîmscgen
deviceinit264
device init 2244
deviceinltscsi
d€vicereadmscgen
deviceread264
deYicelead 2244
devicereadscsi
Dsta 569ment
data msc
aaazu
data bs drivers
oala scsl
4.3.3 "/"SASl_UNIT_INFO
Macro(BSCSl.A86
Fite)
The SCSIdevicedriverprovidesan interfaceto massstoragedevicesthrougheitherSASI
or SCSIcontrollers.ìf usingdevicescontrolledby a SASIcontroller,you mustspecifoa
sequence
of initializationbytesfor the controller.This informationis not requiredby SCSI
controllers.The initializationsequence
identifiesthe typeof iìeviceyou haveassigned
to
the particularunit of the SASIcontrolìer.The sequence
will be clifferentdependingon the
manufacturerand modelof the harddiskor flexiblediskettedrive.and the manufacturer
and modelof the SASIcontrollerboarditsell
BootstrapLoader
1-7
CONFIGURINGTHE THIRD STAGE
requiredby your deviceson
This macroenablesyou to definethe initializationsequences
(in
the SASIbus. For eachinstanceof the ToDEVICEmacro the 851.A86or
BS1MB2.A86file) that definesa deviceon the SASIbus,you mustalsoincludethe
file) to definethat device'sinitialization
ToSASI_UMT_INFOmacro(in the %BSCSI.A86
sequence.The labelspecifiedfor the unit info field of the %DEVICE macromustmatch
%SASI_UNIT-INFOfield.
the labelfield of the corresponding
of the %SASI-UNIT-INFO macrois not used
The informationsuppliedby an occurrence
by deviceson the SCSIbus. Therefore in the BS1.A86or BSIMB2.A86 file, VoDEYICE
macrosfor devicescontrolledby the SCSIbusshouldneverspecif a valuefor the unit info
readprocedures
parameter.Note that thereis only one pair of deviceinitialization/device
is
SCSI
or
SASI.
whether
the
controller
of
for the SCSIdriver regardless
The %SASI_UNIT_INFOmacrocanbe includedonly in the SCSI/SASIdriver
confisurationfile. BSCSÌ.A86.The macrohasthe form
init_count,init_data)
%SASI-UNIT
_INFO( label,init_command,
where:
4-8
label
A validASM86labelnamematchingthe one you
specifiedin the unit info field of the ToDEVICEmacro
or BSlM82.,486).
for yourdevice(in thefile BS1.,{86
init_command
A WORD that is the initializationcommandfor your
particularSASIcontroller.
init_count
the numberof initializationBYTEs
A BYTE specifying
your
controller
requires.
that
SASI
init data
The arrayof BYTEs of initializationdatarequiredby
your SASIcontroller.The lengthof this arraymustbe
equalto thevaluein the init countparameter.
BootstrapInader
CONFIGURINGTHE THIRD STAGE
The defaultinvocations
of this macroin BSCSLA86are
j . S B C7 8 6 / 0 3 A S C S I H o s t
;
lbscsi( 0C8H
, C C HO
, C E,H0 , 0 , 1 , 0 , O F F C O H , 2 , 0 )
, O C A HO
;
iSBc 286/700 SCSI Hosc
b s c s i ( 0 C 8 H ,0 c A H ,0 C C H 0
, C E H ,0 , 0 , 2 , 0 ,
0 2 0 0 H ,2 , l ,
0D1H)
Xebec 51420 SASI controller
and a Teac model F558. 5 L/4-ínch
;
flexible di skette drive.
;
Xs a si _ u n i t _ f n f o ( s a s i _ x 1 4 2 0 m f ,1 l h , 1 0 , 0 , 2 8 h , 2 , 9 0 h , 3 , 0 f h , 5 0 h , 0 f h , 0 1 4 h , 0 )
i
X e b e c 5 1 4 1 0 S A S I c o n È r o l l e r a n d a Q u a n t u mr o o d e l Q 5 4 0 , 5 L / 4 - l n c h
;
l,linchester dÍsk drive.
;
Z s a s i _ u n i t _ i n f o ( s a s i _ x 1 4 1 0 bO
, ch, 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/"lNTlMacro
The ToINTl macrocausesthe third stageto executean INT 1 (soliwareinterrupt)
instructionwhcnevera bootstraploadingerror occurs.This enablesyou to passcontrolto
a user-writtenprogramif loadingfails. However,to passcontrolto anotherprogram,you
mustplacethe addressof that programin position1 of the interruptvectortable. This
macrois supportedby only the D-MON3Sómonitor. The iSDM monitordoesnor support
thismacro.
The svntaxof the %lNTl maerois
a/olNTI
Thereare no parametersassociated
with this macro.
Exactlyone of the %lNTl, %lNT3, and %HALT macrosmustbe included,or an error will
occurwhen BS3.Alì6,BS3MB2.A[ìó,
or BG3.A8óare assembled.
BootstrapLoader
4-9
CONFIGURINGTHE THIRD STAGE
4.3.5 %lNT3Macro
The %INT3 macrocausesthe third stageto executean INT 3 (sofrwareinterrupt)
instructionwhenevera bootstraploadingerror occurs.Ifyou are usingthe iSDM monitor,
controlto the monitor. Otherwise,the INT 3 instructionhas
the INT 3 instructionpasses
no effectunlessyou haveplacedthe addressof your custominterrupthandlerin position3
of the interruptvectortable.
The syntaxof the aolNT3 macrois
7aINT3
with this macro.
Thereare no parametersassociated
Exactlyone of the %lNT1, %lNT3, and TaHALTmacrosmustbe included,or an error will
or BG3.A86are assembled.
occurwhen8S3.A86,BS3MB2.A86,
4.3.6 %HALTMaero
'Íhe
ToHAIJTmacrocausesthe third stageto executea halt instructionwhenevera
bootstraploadingerror occurs.The syntaxof the VoÍIALT macrois asfollows:
ToHAlT
with this macro.
There are no parametersassociated
Exactlyone of the ToINTl, %INT3,and ToHALTmacrosmustbe included,or an error will
occurwhenBS3.A86,B53MB2.A86,or BG3.A86are assembled.
4.3.7 a/oCPUBOARD Macro
The ToCPU BOARD macrospecifiesthe typeof processorboardin your system.The
third stageneedsthis informationso that it canproperlyinitializethe boardwhen
switchinginto protectedvirtualaddressmode. The syntaxof the %CPU BOARD macro
is as follows:
TaCPU_BOARD(type)
4-10
BootstrapLoader
CONFIGURINGTHE THIRD STAGE
where:
type
The tlpe of processor
boardin your system.The followingare the valid
values:
Value
Processor
Board
286/12
286/|Z
286112
2861100A
386/20
386/100
iSBC286/10board
iSBC2861104
board
iSBC28ól12board
iSBC2861100.4
board
iSBC386/2Xboardor iSBC386/3XBoard
iSBC386/116
boardor iSBC386/120
Board
4.3.8 %INSTALLATION
Macro(8G3.A86Only)
The TaINSTALI-ATIONmacrospecifies
whetherthe genericthird stagewill enterthe
monitorafter loadingthe applicationsystemor not. The syntaxof the %INSTALLATION
macrols:
ToINSTALI-ATION (monitor_entry)
where:
monltor_entry
The typeof actionthe BootstrapLoaderis to take upon
loadingthe applicationsystem.If monitorentry is 'n' the
systemis loadedand then executedwith no monitor
entryinbetween.If it is'y', the monitor is enteredafter
the systemis loaded.You mustrypein the monitorGO
commandto continue.
'y' for the monitor_entryparameter,
Whenthe monitoris entered,asa resultof specifying
the BootstrapLoaderprintsthe followingmessage
to the terminal:
Insert
the
Start-uD
Svsten
Cornmands Dlskette
and tvDe
"G"
NOTE
If your systemhas the D-MON386 monitor rather than the iSDM monitor, type
''GO< RETURN>".
BootstrapLoader
4-t I
THE THIRD STAGE
CONFIGUR-ING
This macrois usedto generatethe genericthird stageusedto boot the OperatingSystem
from diskettes.The %INSTALTATION macroallowsone diskette,whichcontainsonly
the OperatingSystemboot file and the third stageto be usetlto load the systemfrom
disketteinto memory. In enteringthe monitor,it allowsa seconddiskette,whichcontains
to be usedasthe systemdevicewhenthe systemis
the necessary
systemcommands,
initialized.
4.3.9%ENDMacro
and BG3.A86
The ToENDmacrois requiredat the end of the 853.A86,BS3MB2.A8ó,
is
as
follows:
files. The syntaxof this macro
ToEND
with the ToENDmacro.
Thereare no parametersassociated
4.3.10 User-Supplied
Drivers
If you want to usethe device-specific
third stageto loadyour systemfrom a deviceother
than one for whichIntel suppliesa third-stage
driver,you mustwrite your own device
driverproceduresthat the third stagewill call. Chapterfr describes
how to do this. In
to the BootstrapLoader:
addition,performthe followingactionsto add the procedures
Speci! the namesof the deviceinitializationprocedure,the devicereadprocedure,
and the driver'sdatasegmentin a ToDEYICEmacroin the 853..4[ì6file.
If thereare configurable
parametersassociated
with your device(suchasbase
addresses
or wakeupports),you mightwant to createyour own configurationmacro
and includeit in a specialconfigurationfile,just like the Intel devicesdo. Chapter5
describes
how to setup a macro. You will probablyusethe sameconfigurationfile for
both the first- and third-stagedrivers.
Assembleyour deviceinitializationprocedure,your devicereadprocedure,and your
configurationfile (ifyou haveone),and link the resultingobjectcodeto the rest of the
BootstraDLoaderobiectfilesand libraries.
4-12
Bfi)tstrap hader
CONFIGURINGTHE THIRD STAGE
4.4 GENERATING
THETHIRDSTAGE
TwoSUBMITfiles(BS3.cSD
andBG3.csD)areusedto generate
thetwotypesof third
stages.B53.cSDperforms
theassembly,
linkage,
andlocationofthe device-specific
third
stage.BG3.GSD
performs
thesameoperations
for thegenericthirdstage.Figures
4-4and
4-5showtheIntel-supplied
B53.CSD
andBG3.CSD
files.
attachfile
$ as :fl:
;
rnp1286: f 1 : Í 0 . a 8 6 $ o b j e c t ( % 0 . r n p 1 )
asn86 f l : f 0 . r n p l
a s n 8 6 f 1 : b m s c .a 8 6
asrn86 f 1 : b 2 l 8 a . a 8 6
a s m 8 6 fL:b264 . a86
asn86 f 1 :b s c s i . a 8 6
asm86 fI:b224a . a86
;
link86
&
f1 20.obj ,
&
f1 :bs3.lib,
&
f 1 : b r n s c. o b j ,
&
f l : b 2 1 8 a .o b j ,
&
f l : b 2 6 4. o b j
&
& f1 :bscsi.obj,
&
& fl:b224a.obj
&
co fl:10.lnk print(:f1 :Z0.mp1)notype nolines nosynbols
;
1 o c 8 6 : f l : Z 0. l n k
a d d r e s s e s( c l a s s e s ( c o d e( 1 1 ) ) )
o r d e r ( c l a s s e s ( c o d e ,d a t a ) )
noinitcode purge
staft (bs 3)
m a p p r i n t ( : f 1 : % 0 .n p 2 )
&
&
&
&
&
T h e T h i r d S t a g e , l o c a r e d a r a d d r e s s1 1 , i s i n t h e f i l e
10
Figure4-4. Device-Specific
Third StageSUAMIT File (B53.CSD)
BootstrapInader
,:t-13
THE THIRI) STAGE
CONFIGURING
atfacnîlIè
I
as
: f r:
;
a s m 8 6 : F l : b g 3. a 8 6
;
link86
:f1:bg3.obJ,
.!i-.uBJ.r!u
to
nolisr
&
&
ù
: fl :bg3.1nk notype nolines nosyurbols
&
&
&
&
L\urJ./
&
Pu!óc
:Fl:20.11nap print(:fl :ifO.mp2)
1oc86
: fl :bg3. lnk
a d d r e s s e s( c l a s s e s ( c o d e( Z l ) ) )
o r d e r ( c l a s s e s ( c o d e ,d a t a ) )
nolnitcode
èLd!
to
The Generic
in the file
Third Stage is
Z0 .11-
located
at
address
Z2 and is
Figure4-5. GenericThird StageSUBMIT File (BG3.CSD)
4.4.1 Modifyingthe SubmitFiles
your own versionof the third stage,you shouldmodifythe appropriate
Beforegenerating
submitfile to matchyour intendedconfiguration.
If you are usingthe device-specific
third stageand you haveexcludedanydevicedrivers
o/oDEYICE
from it (by excluding
macrosfrom the 853.A86or BS3MB2.A86file),you
won't want to link the codefor thosedriversinto the the third stage.To preventthe
linkingof a devicedriver,edit the LINK86 commandin the BS3.CSDfile and placean
ampersand(&) in front of anyfile namethat corresponds
to a driveryou want to exclude.
If you are not usingan iRMX I or iRMX II systemto configurethe third stage,you must
commentout the line wherethe directorycontainingthe BootstrapLoaderfilesis attached
as :fl: beforeinvokingthe othercommandsin the BS3.CSDor BG3.CSDfile. Changethe
line:
ATTACHFILE $ AS :Fl :
to
:ATTACHFII-ES AS :F1 :
4-14
Burtstrap [-oader
C O N F I G U R I NT
GI I E T H I R DS T A G E
4.4.2 Invokingthe SubmitFile
After you havemodifiedeitherthe BS3.CSDor BG3.CSDfile to correspondto your
configuration,
invokethe appropriateSUBMIT file to assemble
the third stagefiles,link
them together,and assignabsoluteaddresses.
The formatfor invokingeitherSUBMIT file
is as follows:
Device-soecificthird stage
SUBMIT B53 (filename,third_stage_addr)
Genericthird stage
SUBMIT BG3 (filename,extension,
third_stage_addr)
where:
filename
The nameof the file in whichto storethe senerated
rhirdstage.Also,the nameof the third-stage
configuration
file you are using(BS3.A8ófor
MULTTBUSI systemsand BS3MB2.A86for
MULTIBUS II systems).The genericthird stage
appendsthe nextparameter(extension)to the lìÌename.
extenslon
The extensionthe genericthird stageis to have. This
doesnot applyto the devicespecilìcthird stage.Normal
genericthird stagesusuallyhavethe extension'GEN'.
Genericthird stagesusedlbr OperatingSystem
installationshouldusethe extension'INS'.
third_stage_addr
The addressin RAM wherethe third stagewill be
loaded.The addressyou specifyshouldbe a full 20-bit
address.Do not usethe base:offset
form to indicatethe
address.
If you haveno specialrequirements
for loadingthe third
stage,speci$a valueof 0BC000Hfor this parameter.
Bootstraphader
4-r5
CONFIGURINGTHE THIRD STAGE
OFTHETHREESTAGES
4.5 MEMORYLOCATIONS
Whenyou configurethe first and third stagesof the BootstrapLoader,you canassignthe
you
at whichthe threestageswill be located.Beforesettingtheseaddresses,
addresses
in the BootstrapLoader.
mustunderstandhow defaultmemoryis assigned
Table4-2liststhe defaultmemorylocationsusedby the BootstrapLoader- It alsonames
the SUBMIT filesyou caninvoketo changethe memoryassignments.
Table4-2. MemoryLocationsUsedbv the BootstrapLoader
Deacription
1stStage
Code
D€fauh
Applicatìon
Dependent*
for iSDMR3.0
0FE40OH
Marimum
Size'
Configuration
File
14KBytes
BSl,CSD
2nd Stage
Code, I st/2nd
Data and Stack
088000H
8K Bytes
BSl.CSD
3rd Stage
(specifìc)
Cod€,Data
and Stack
0Bc000H
16KBltes
BS3.CSD
3rd Stage
(gen€ric)
Code
0Bc000H
8K Byîes
BG3,CSD
ThirdStage
(generic)
Data and Stack
0880@H
BSl,CSD
* Maximumsiz€is a functionol the sizeof the devicedriversincludedin the Bootsfap Load€r,
versionof the Bootstrap
The BootstrapLoaderReleaseDiskettecontainsa standalone
Loader,in the file namedBS1,whichselectsall the supportedlntel devicedrivers.The
map file, BS1.MP2,is suppliedto showthe layoutof the segments
in BS1. The first stageis
locatedat 0C0000Hand the secondstaseis locatedat 0B8000H.All defaultthird stases
are locatedat 0BC000H.
1-16
BootstrapIîader
CHAPTER
5
WRITING
A CUSTOM
FIRST.STAGE
DRIVER
5.1 INTRODUCTION
You canconfigurethe BootstrapLoaderto run with manykindsof devices.If you plan to
useone of the devicesfor whichIntel suppliesa devicedriver,you canskipthis chapter.
If you want to usethe BootstrapLoaderwith a deviceother than thosesupportedby Intel,
you mustwrite your own first-stage
devicedriver. (lf you want to load iRMX II
applications
pastthe first megabyteof addressspace,you mustalsowrite a customthirdstagedriver. Chapter6 describes
how to write thirtJ-stage
drivers.)This chapterprovides
you with guidelinesfor writinga customfirst-stage
driver.
You mustincludetwo proceduresin everyfirst-stage
devicedriver:a deviceinitialize
procedureand a devicereadprocedure.The deviceinitializeproceduremustinitializethe
bootstrapdevice.The devicereadproceduremustload informationfrom the deviceinto
RAM.
The restof this chapterrefersto the two procedures
as DEVICE$INIT and
DEVICE$READ. However,you cangivethemany namesyou want,providedno other
first-stagedriverprocedureusesthe chosennames.To checkthe namesof the Intelsuppliedfirst-stage
procedures,
useLI886 to Iist the modulesin the objectlibrary
/RMX286/BooT/BS1.I-lB or /RMX86/BooT/BS 1.LIB.
You mustwrite both procedures
in an t1086
language(eitherPL/M-ll6 or ASM86) and
conformto the I-ARGE modelof segmentation
of the PL/M-86 programminglanguage.
This meansthat you mustdeclarethe two procedures
as FAR (not NEAR) an 01),pushthe
valueonto the stack,and call the BSERRORprocedure.For example,
resultingworcl
the
device
code
is 0B3H,pushB301Honto the stack,and call BSERROR. If no
if
devicecodeexists.use00.
aocomplish
this in PL/M-86:
Addingthe followingstatements
EXTERNAL,
DECI.AREBSERROR
D E C I ^ A . RI O
E - E R R O RL I T E R A L L Y ' O B 3 O 1 H '
CALL BSERROR(ÌO_ERROR)
;
language,
note that BSERROR
lf you call the BSERRORprocedurefrom assembly
that is,declareBSERRORas
followsthe PL/M-86 TARGE modelof segmentation;
extrn
BSERROR:far
NOTE
In adclitionto the abovetwo steps,the proceduremustfollow MULTIBUS II
if the
transportprotocoland belongto the BSl-DriversCOMPACT sub-system
driverfunctionsin a MULTIBUS II environment.Referto Section5.5for
moreinformation
on theselwo requircments.
INFORMATION
TO THE
5.4 SUPPLYING
CONFIGURATION
FIRST.STAGE
DRIVER
Any customdevicedriveryou write needssomeconfigurationinformationaboutthe devrce
it supports,suchas the addressof the devicewakeupport. (To determinewhat devicespecificinformationyour driverneeds,consultthe hardwarereferencemanualfor the
device.)You canprovidethis informationto the customdevicedriverone of two ways:
.
Placethe information
directlyintothe driver(hard-coding)
.
Createa configurationfile similarto thoseprovidedwith the Intel-supplied
drivers.
5.4.1 Hard-Coding
the Configuration
lnformation
One wayto supplyconfigurationinformationto a customdevicedriver is to placeit
directlyinto the code. This methodworks,but if anyof the configurationinformation
changes,
or if you want to supporta similardevicethat hasa slightlydifferent
configuration,
you mustchangethe ciriverancìreassemble
it. Fortunately,first-stagedevrce
driversare usuallysmallenoughso that the amountof time requiredto reassemble
them is
negligible.
5-4
Brxtlstraplrtader
WRITING A CUSTOMFIRST-STAGEDRIVER
Figure5-t illustrateshow to placethe configurationinformationdirectlyinto the code.
This figureliststhe "Constants
and Data"sectionthat couldbe usedto supplythe MSC
first-stagedriverwith device-specific
configurationinformation.
Constants and Data
data_bsmsc
segnent
; Static
wakeup_newdrivl
dw
100H
;MSC wakeup address
device_newdrlvl
db
0
drtab_ne\,Jdrivl
db
db
db
db
db
d\r
256
2
0
9
L024
5
Data
;number of cylinders
;nuruber of fixed heads
;nurnber of rernovable heads
;numberof sectors
:device granularicy
;nurnberof alternaÈe cylinders
Figure 5-1. Hard-CodedConfìgurationInformation
5.4.2 Providinga Configuration
File
The secondwayto supplyconfigurationinlbrmationis to declareall device-specifìc
parametersasvariablesthat are externalto your devicedriver. A separatesmallmodule
candeclaretheseparametersaspublicvariablesin . You canincorporatethis second
moduleinto the BootstrapLoaderby placingassembly
and link commandsin the firststageSUBMIT file BS1.CSD.To usethis approach,followthe stepsbelow:
Bootstrapl-oader
5-5
WRITING A CUSTOMFIRST-STAGEDRTVER
1.
parameters
asexternal
thedevice-specific
In thecodefor thedevicedriver,declare
variables.
For example,
thefollowing
codecouldbeusedinsteadof thehard-coding
shownin Fisure5-l.
narne bpmsc
C
o
n
fl g u r a t i o n i n f o r m a t i o n :
;
extrn
r^rakeup_newdrivl w o r d
;l,Iakeup port
extrn
extrn
device_ne\rdrivl
drÈab newdrivl
;Devlce nurnber
;Device Table
byce
byte
Createan INCLUDE file containinga macrodefinition.The macrodefinitionmust
declarethe device-specific
parameters
aspublicvariables(matchingthe external
where
declarations
from the previousstep). This file shouldbe namedas"roo<.inc"
nooo<.a86).
To the list of modulesto be linked
(immediatelybelowthe LINK86 invocation),add the nameof the objectmodule
createdwhenyour file (no<.a86)
is assembled.
In both the ASMIJ6invocationand the
LINK86 invocation,prefacethe filenamewith the logicalname:Fl: (suchas
:f1:nc<.a86).
Unlessyou havereasonto do otherwise,usethe sameASM86 and
LINK86 optionsshownfor otherfilesassembled
and linkedby BSI.CSD.
Figure5-2showsmodifications
to BSl.CSDthat add supportfor the driver
configurationfilesjust created.Arrows ar the left of the figureshowthe linesthat were
added. Noticethat only the configurationfile is beingassembled
eachtime BSl.CSDis
invoked,not the entiredriver. BSl.CSDassumes
the useof the configurationfile
BS1.A86and that you haveassembled
your driverand addedthe resultingobject
moduleinto the libraryBSl.LIB.
Bootstrapl.oader
f,-/
WRITING A CUSTOMFIRST-STAGEDRIVER
;
; a s r n 8 6: f 1 : b s 1 . a 8 6
r n a c r o ( 9 0 )o b j e c c ( : f 1 - : b s 1 . o b J )
Prínr ( : fl:bs1 . lst)
a s r n 8 6: f l : b 2 6 4 . a 8 6 n a c r o ( 5 0 ) o b j e c t ( : f 1 : b 2 6 4 . o b )j p r i n t ( : f 1 : b 2 6 4 . 1 s t )
a s n 8 6 : f 1 : b s c s l . a 8 6 m a c r o ( 5 0 )o b j e c t ( : f l : b s c s t . o b J ) 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È
;
&
&
&
&;standaÌonè serlal channèl support
l lnKób
'f1
&
'hcprr
nhì
:f1:bcico.obj,
fl
hcnci
nhi
f l : b 2 6 4 . o b J,
fl : nrdrvlnac . obj ,
rl:Ds_t.llD
to
&
&
&
:f1 :bs1.lnk prlnt(: fl:bs1.npl) &
Figure5-2. ModifiedBSI.CSDFile
5.5 USINGTHEMULTIBUS@
IITRANSPORT
PROTOCOL
If the driveryou are creatingfunctionswithin a MULTIBUS I environment,
you neednot
readthis section.Skipto Section5.6.
If the driveryou are creatingfunctionswithin a MULTIBUS II environment,
you must
write the drivercodeto usethe MULTIBUS II message
transportprotocol.To helpyou
accomplish
this task,Intel providesa small,single-thread
communication
systemthat
enablesBootstrapLoaderdriversto communicate
with devicecontrollerswithin a
MULTIBUS II environment.This communication
systemis calledthe BootstrapLoader
CommunicationSystem.
The followingparagraphs
providean overviewof the BootstrapLoaderCommunication
System,whichusesconceptssimilarto the NucleusCommunication
System.Shouldyou
desirea more completedescriptionof thesecommunication
systemconcepts,
refer to the
Extended|RMX II NucleusUser'sGuiriein Volume 2 of the iRMX ll documentationset.
5-E
Bootstrap[.oader
WRITING A CUSTOMFIRST-STAGEDR-IVER
The BootstrapLoaderCommunication
Systemcanbe thoughtof as a subsetof the Nucleus
CommunicationSystem.It fully conformsto the MULTIBUS II transportprotocol
suitablefor a limitedbootloadingenvironment.Unlike the NucleusCommunication
System,the BootstrapLoaderCommunication
systemis designedto handlebootstrap
loadingonly. Consequently,
the systemis synchronous
in nature. In otherwords,
proceduresexecuteto completionone afterthe other;no multitaskingor needto handle
asynchronous
eventsexists,
MULTIBUS II transportprotocolfunctionssupportedby the BootstrapLoader
Communication
Systemincludecontroland datamessage
tlpes,a subsetof the
request/response
transactionmodel,sendand receivetransactionmodels,message
broadcasting,and accessto deviceinterconnectspace.
To supportthesefunctions,lntel suppliesa setof systemutilitiesgroupedtogetherin a
BootstrapLoaderMessagePassing
SystemModule. As a programmer,you haveaccessto
theseutilitiesthroughsystemcallsyou placein your drivercode. The remainderof this
sectionexplainsthe supportedfunctionsin the BootstrapLoaderCommunications
System
and showsyou how to useeachof the utilities.
5.5.1 MessagePassingControllerInitialization
Beforeany BootstrapLoaderCommunication
Systemcallscanbe made,you must
initializecertainpartsof the hardwarein preparationfor message
passing.You
accomplish
this initializationthroughthe BS$MPS$INITutility. You mustmakethiscall
from your driver'sinitializationprocedurebeforemakinganyother BootstrapLoader
Communicationutility calls.The followingutility descriptionpresentsBS$MPS$INIT:
CALL BS$MPS$INIT
INPUT PARAMETERS
This utility hasno input parameters.
OUTPUT PARAMETERS
This utility hasno outputparameters.
DESCRIPTION
The BS$MPS$INITutility provideshardwareinitializationfor the MessagePassing
Controller(MPC) and the AdvancedDirect MemoryAccess(ADMA) devices.You must
performa call to this utility beforeattemptinganyother BootstrapLoaderCommunication
Svstemutilitv calls.
Bootstrap Loader
5-9
WRITING A CUSTOM FIRST-STAGEDRI!'ER
CONDITION CODES
This utility hasno conditioncodes.
5.5.2MessageTypes
control
Systemsupportstwo typesof messages:
The BootstrapLoaderCommunication
messages
and datamessages.
occurbetweenthe
Controlmessages
consistof only a controlportion. Thesemessages
senderand receiverrequiring no explicitbuffer resourceallocation. The reasonfor no
hasno datapart. The maximumlengthof a
a controlmessage
bufferallocationis because
existsbetweencontrol
is 20 bytes.Also,a one-to-onecorrespondence
controlmessage
are control
(all unsolicitedmessages
messages
and MULTIBUS II unsolicitedmessages
messages).
consistof both a l6-bytecontrolportionand a variablelengthdataportion.
Data messages
do requireexplicitbufferallocationbetweenthe senderand receiver.The
Thesemessages
containsa variable
this typeof message
reasonbufferallocationis requiredis because
amountofdata. The maximumlengthof the dataportionis 64K-l bytes.
Transaction
Model
5.5.3Request/Response
Systemsupportsa subsetof the re<1uest/response
The BootstrapLoaderCommunication
Svstemuses.This subsethasthe
transactionmodelthat the NucleusCommunication
folìowingcharacteristics:
o
Systemfunctionswithin a bootloading
Becausethe BootstrapLoaderCommunication
originateonly from the hostCPU board. The specific
environment,requestmessages
to requestson a one-to-onebasis.
devicecontrollersthen matchresponses
.
requests.
No supportexistsfor multipleoutstanding
.
of response
messages
into specificapplicationbuffers
Fragmentation
and transmission
is completelytransparentto the user,the
canoccur. Becausethis fragmentation
asa singleresponse
to a singlerequest.
fragmentedresponse
is considered
o
Systemreceivesmessages
in the order in which
The BootstrapLoaderCommunication
they are sent.
Communicationbetweenthe CPU hostboardexecutingthe driverand lhe bootabledevice
controllerusesthe basictransmission
modelof sendand receive.The driversendsa
back. When the driver
requestto the devicecontrollerand thenreceivesa response
the
ID is generatedthat logicallyassociates
initiatesthe message,
an internaltransaction
thus
requestwith the response.This ID remainsvalid until the devicecontrollerresponds,
completingthe transaction.
5-10
Bootstrap l-oader
WRITING A CUSTOMFIRST-STAGEDRIVER
For messages
that requiredataaspart of the response,
the drivercan initiatethe allocation
of an rsvpdatamessage
bufferin whichto receivethe responsedata. The datacanthen
arriveeitherwholeor fragmented.Regardless
of fragmentation,
the hostCPU boardviews
the responsemessage
asone message.
If the requestmessage
requiresno dataas a
response,
the responsemustbe a controlmessage.
The utility the BootstrapLoaderCommunication
Systemusesto supportthe
request/response
transaction
modelis BS$SEND$RSVP.
The followingutilirydescription
presentsBS$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
A DWORD of the form host$id:port$id
identif ing the
remotedestination.
control$ptr
A POINTER to a controlmessage.If data$adr= NULL
= 0, then the controlmessage
(0) or data$length
is 20
byteslong. Otherwise,the controlmessage
is 16bytes
long.
data$adr
A DWORD containingthe absoluteaddressof a data
message.If data$adris NULL (0), then a control
message
is sent. Otherwise,data$adrpointsto a
contiguous
buffer.
data$length
A WORD definingthe lengthof the datamessage.If
length
data$length
is equalto zero,the controlmessage
is assumedto be 20 bytes.
rsrp$control$p
A POINTER to the receivedcontrolmessage.If
= 0, then
= NULL (0) or rsrp$data$length
rsvp$data$adr
the controlmessage
is 20 byteslong. Otherwise,the
controlmessage
is 16byteslong.
rsrp$data$adr
A DWORD containingthe absoluteaddressof a data
message
bufferfor the return responsethat is expected.
is
If rsrp$data$adr
is NULL (0), then a controlmessage
points
to
expectedasa reply. Otherwise,rsw$data$adr
arrives.
bufferin whichthe datamessage
a contiguous
BootstrapLoader
5-ll
WRITINC A CUSTOMFIRST.STAGEDRI!'ER
rslp$data$length
A WORD definingthe lengthof the rsrp databuffer.
flags
WORD reservedfor future use. Aithough this
parameteris ignored,you mustsupplya "0"valueasa
placeholder.
OUTPUT PARAMETER
exception$ptr
A POINTER to a WORD to whichthe Operating
Systemreturnsthe exceptioncodegeneratedby this
Systemcall.
BootstrapLoaderCommunication
DESCRIPTION
from a port to a remotesocketwith an
The BS$SEND$RSVP
utility sendsa message
explicit requestfor a return response.This call is synchronouswith respectto both the
requestand the response.
5-12
Bootstrapl-oader
WRITING A CUSTOM FIRST.STAGEDRIVER
EXAMPLE
This exampleillustratesthe fundamentals
of the request/response
transactionmodel
betweenthe hostCPU boardand bootabledevicecontrollerboard. This examoleis
written in PL/M-Sócodeand is intendedto be genericin nature.
//************************************************************
*
îhis exanple sends a 20,byte control nessage to the
*
bootable device controller board located ln slot 1
*
a t p o r t 5 0 0 o f t h e M U L T I B U SI I s y s t e n .
This nessage
*
sollcits
data from the device as DarÈ of the
*
ra
0
THEN CALL BSERROR;
.
.
(Typical code to execuLe
lor successful status. )
E N DC O D E ;
sAÌ,fPLE_BS
I SEND9RSVP
;
5-r4
Bootstrap [-{)ader
WRITINCA CUSTOMFIRST-STAGE
I)RtVER
CONDITION CODES
E$OK
0000H
No exceptional
conditions.
BS$E$BUFFER$SIZE
0082H
The rsvpbufferpostedis too
small.
BS$E$TRANSMISSION
00ElI{
An error occurretlwhile
transmitting
a MULTIBUS II
message.
5.5.4 Sendand ReceiveTransaction
Models
In additionto the request/response
transaction
model,the Bootstrap
Lolder
CommunicationSystemsupportsscndand receivetransactionmodels.Normally,
communication
betweena driverand a devicein a bootloadingenvironmentusesthe
request/response
or sendmodels.However,ifyour hostCPU boardcancapitalizeon a
receivetransactionmodelinitiatedliom the driver,the utility is available.
You can makecallsto the sendand receiveutilities,respectively
whenyou neetlthe driver
to simplysenda message
with no requestfor a response,
or whenyou needthe driverto
wait lbr spontaneous
communication
from a specificdevicecontroller.
The two utilitiesavailableto you that supportthe sendand receivetransactionmodelsare
BS$SENDand BS$RECEIVE.The followingutility descriptions
presentBS$SENDand
BS$RECEIVE:
CALL BS$SEND
(socket,control$ptr,data$adr,data$length,
flags,exceptiongptr)
INPUT PARAMETERS
socket
A DWORD of the form hostgid:portgid
identifyingthe
remotedestination.
control$ptr
A POIN'IER to a controlmessage.lf datagadr= NULL
= 0, then the controlmessage
(0) or data$length
is 20
byteslong. Otherwise,the controlmessage
is l6 bytes
long.
data$adr
B{ntstrap l-oader
A D W O R D c o n t a i n i n gt h e a b s o l u t ea d d r e s so f a d a t a
m e s s a g e I. f d a t a $ a d ri s N U L L ( 0 ) , t h e n a c o n t r o l
messageis sent. Otherwise,data$adr points to a
contiguousbuffer.
5-t-s
WRITING A CUSTOM FIRST-STAGE DRIVER
data$length
A WORD definingthe lengthof the datamessage.If
length
data$length
is equalto zero,the controlmessage
is assumedto be 20 bltes.
flags
WORD reservedfor futureuse. Althoughthis
you mustsupplya "0"valueasa
panrmetcris ignored,
placeholder.
OUTPUT PARAMETER
exception$ptr
A POINTER to a WORD in whichthe Bootstrap
Loaderreturnsthe exceptioncodegeneratedby this
Systemcall.
BootstrapLoaderCommunication
DESCRIP'TION
to a MULTIBUS II board
The BS$SENDutility sendseithera contrttlor a datamessage
parameter
socket.
identifiedby the
EXAMPLE
of message
passingfrom the hostCPU boardto
This exampleillustratesthe fundamentals
the bootabledevicecontrollerboard. This exampleis written in PL/M-Só codeand is
intendedto be qenericin nature.
/**********************************:t*******:******************
*
*
*
This exaurple sends a data nessagè to the bootable
controller board located in slot 1 at port 500 of
t h e M U L T I B U SI I s y s t e r n .
The control portion of the message sent is located
i.n the 16-byte data array p$control$rnsg (Peripheral
C o n m a n dM e s s a g e ) . T h e d a t a p o r t i o n o f t h e n e s s a g e
sent is located in the 100-bvÈe data arrav
send$data.
*
*
*
*
*
Note that the progranmer is responsible for
p $ c o n t r o l $ m s g a n d t h e a r e a c o n t a i n i n g t h e d a"t .a" . r . i r r g
p o r t i o n o f t h e r n e s s a g ea r e i n i t i a l i z e d
lrith correct
i
*
*
************************************************************/
5-ló
Bfi)tstrap l-oader
WRITING A CUSTOMFIRST-STAGEDRIVER
SAIPLE_BS$SEND
D:0 ;
DECI,AREs ocke t
DECIAREsocket$o s truc ture
( h o s E $i d
Porr$ id
pgcontrol gmsg ( l6 )
DECI^ARE
D E C I A R Es e n d $ d a t a ( 1 0 0 )
DECIAREdata$adr
DECIAREdata$ len8th
DECIAREfl ags
D E C I A R Ee x c e p t i o n
DECTAREsIoC
LITEMLLY
DECI-AREport
I-ITERALLY
DECIAREnul-l
LITEMLLY
DECIARElength
LITERALLY
C O D E :D O ;
socket$o.host$ld:
s o c k e t $ o. p o r t $ i d :
data$lengrh
fl ags
DWORD
;
WORD
,
W O R D )A T ( @ s o c k e t ) ;
BYTE;
BYTE;
DWORD
;
WORD
;
WORD
;
WORD
;
,lH'
;
,1F4H'
;
'0H';
, 64H,
1
slot;
pórt;
length;
null;
( G s e n d $ d a r a( 0 ) ) ;
data$adr : coNvERT A D D R E S S
.
.
.
(Typical
code to define
the 16-byte p$control$msg btock
holding the control
message. )
.
.
.
(Typi-caÌ code to define
the 100-byce message
p o r Ci o n . )
CALL BS9 SEND
( s o c k e t , @ p $ c o n c r o l $ m s g ( 0 ) ,d a t a g a d r ,
d a t a $ L e n g th , f [ a g s , @ e x c e p t i o n ) ;
IF exception <> 0
THEN CALL BSERROR;
.
.
(Typical code to execute
for success.ful sLaLus. )
END CODE;
SMPLE_BS$SEND;
Bootstrapl,oader
5-17
WRITING A CUSTOMFIRST-STAGEDRIVER
CONDITION CODES
E$OK
0000H
BS$E$TRANSMISSION O O E I H
CALL BS$RECEIVE
conditions.
No exceptional
An error occurredwhile
transmittinga MULTIBUS II
message.
(socket,control$ptr,data$adr,data$length,
exception$ptr)
INPUT PARAMETERS
socket
i d e n t i $ i n gt h e
A DWORD of the form host$id:port$id
remote sender.
control$ptr
A POINTER to the area in memory that receivesthe
control message.
data$adr
A D V / O R D c o n t a i n i n gt h e a b s o l u t ea d d r e s so f a d : r t a
messrìgereceived. If data$adr is NULL (0), then the
host CPU board expectsa control message.Otherwise,
data$adrpoints to a contiguousbuffer that receivesthe
data portion of the message.
data$length
A WO RD defining the length of the data message
received.
OUTPUTPARAMETERS
exception$ptr
A POINTER to a WORD to whichthe Operating
Systemreturnsthe exceptioncodegeneratedby this
BootstrapLoaderCommunication
Systemcall.
DESCRIPTION
The utility BS$RECEI\E,enablesa hostCPU boardto receivea message
from a specific
devicecontroller.The utilitiescall identifiesthe MBII slot to wait on, the tlpe of message,
and addresses
for the controlportionand,if necessary,
the dataportionof the message.
To receivedatamessages,
you mustprovidea buffercontainingadequatespacein whichto
capturethe data. Ifyou do not supplya largeenoughbuffer,the receivingCPU host
rejectsthe message.Also,your applicationmustmakea call to BS$RECEIVEbeforethe
actualmessage
is sent. No facilityfor queuingasynchronously
receivedmessages
exist.
5-18
BootstrapLOader
WRITING A CUSTOMFIRST-STAGEDRIVER
EXAMPLE
This exampleillustratesthe fundamentals
of message
passingfrom the hootabledevice
controllerboardto the hostCPU board. This exampleis written in PL/M-86 codeand is
intendedto be senericin nature.
/************************************************************
*
This example illustrates
h o w a h o s t C P Ub o a r d
*
receives a data message from the bootable
*
controller board located in slot 1 at port 500 of
*
t h e M U L T I B U SI I s y s t e m .
*
*
*
*
*
The controf portion of the message rèceivèd is
located in the 16-byte array p$sCatus$msg
( P e r i p h e r a l S t a r u s M e s s a g e ). T h e d a t a p o r t i o n o f
the nessage received is located in the 1024-byte
data array sent$data.
***********************************************************)t
*
*
*
*
*
*
*
*
*
/
S A H P L EB S S R E C E I V ED: O :
DECIAREs o c k et
DECI*AREs o c k e t $ o s t r u c t u r e
(host$id
porr$id
DECI.AREp $ s t a t u s $ m s g( 1 6)
DECIARE d a t a $ a d r
DECIARE d a t a $ l e n g t h
DECl-ARE f l a g s
DECIARE e x c e p t i o n
DECIARE s e n r $d a r a ( 1 0 2 4 )
DECLARESlot
LITERALLY
DECIARE POTI
LITEMLLY
DECISRE length
LITEMLLY
DECIAREn u 1 1
Ll TEMLLY
DWORD
;
WORD
,
I . J O R DA) T ( G s Ò c k e t ) ;
BYTE;
DWORD
;
WORD
;
IIORD;
WORD
;
BYTE;
'lH';
,1F4H'
;
, 400H'
;
,OH';
C O D E :D O ;
s o c k e t $ o .h o s t $ i d : s l o t ;
cnnl.ot(n
^^rt-(
i À :
port;
- lenglh;
dara$length
: null;
fÌags
@Ss e n t $ d a r a ( 0 )) ;
d a r a $ a d r : C o N V E R T _ A D D R E( S
C A L L B S$ R E C E I V E
( s o c k e t , @ p $ s t a t u s $ n s g ( 0 ), d a t a $ a d r ,
^ vC, l ^r -, ^' .6rt u. ld^L+ d
",
BootstrapLoader
I I dés
, \:cÀuFp
L I u'r/
,
5-r9
WRITINC A CUSTOMFIRST.STAGEDRIVER
] F exception <> 0
THEN CALL BSERROR;
(Typical
code to execute
for successful status. )
E N DC O D E ;
IVE ;
SAMPLE_BS
$RECE
CONDITION CODES
E$OK
0000H
conditìons.
No exceptional
BS$E$BUFFER$SIZE
0082H
The receiveclatabufferpostedis
too small.
BS$E$TRANSMISSION 00ElH
while
An erroroccurred
transmittinga MULTIBUS II
message.
5.5.5 MessageBroadcasting
to go out at the sametime to all boards
enablesonecontrolmessage
Messagebroadcasting
(busagents)in the MULTIBUS ll system.Recallthat the identificationschemefor boards
whichhavethe host$id:port$id
form. Host$idindicatesthe board
employssockets,
port
within the board. During message
port$id
indicates
the
unique
I/O
involvedand
arrives
broadcasting,
the host$idportionof the socketis uninterpreted.Thus,the message
at everyboardhavinga port identifieciby port$id.
Systemusesthe bs$broadcast
utility to support
The BootstrapLoaderCommunication
broadcasting.
The followingutility descriptionpresentsbs$broadcast:
message
CALL BS$BROADCAST
(socket,control$ptr,exception$ptr)
INPUT PARAMETERS
5-20
socket
identifyingthe
A DWORD of the form host$id:port$id
The
host$id
component
is ignored.
remotedestination.
control$ptr
A POINTER to the controlmessage
sent.
Bootstraphader
WRITING A CUSTOMFIRST.STAGEDRIYER
OUTPUT PARAMETER
exception$ptr
A POINTER to a WORD to whichthe Operating
Systemreturnsthe exceptioncodegeneratedby this
BootstrapLoaderCommunicationSystemcall.
DESCR]PTION
The bs$broadcast
utilirytransmitsa singlecontrolmessage
to the MULTIBUS ll boards
havinga port whoseID matchesthe port$idportionof the parametersocket.This
message
goesout on all MULTIBUS Il buses(iPSBparallelsystembusand/or iSSBserial
systembus)connectedto the broadcastìng
CPU hostboard.
EXAMPLE
This exampleillustratesthe fundrrmentals
of broadcasting
controlmessages
over a
MULTIBUS II system.This exampleis written in PL/M-tì(rcodeand is inten 0
THEN CALL BSERROR;
.
.
(Typical code to execute
for successfuÌ status . )
E N DC O D E ;
END SAMPLE-BS
9BROADCAST
;
CONDITIONCODES
E$OK
000011
No exceptionalconditions.
BSSESTRANSMISSION
00ElH
An error occurredwhile
transmittinga MULTIBUS II
message.
Modes
5.5.6 Transmission
waitsfor
Data message
transmissions
are synchronous
in that the senderof the message
the receiverof the message
to rcturn a transmission
statusvalue. This valueindicates
whetheror not the receiversuccessfully
acquiredthe message.Controlmessages,
however,
are not synchronous
in this manner.Thereis no indicationto the senderthat a control
message
hasbeenreceived.Also,relatedto eachtlT)eof message
transmission
is a
transactionID value. The communication
systemusesthisvalueinternallyto match
requestswith responses
and to indicatewhetherthe message
is an rsrp message
or a
sentis not an rsvpmessage,
nonrsvpmessage.lf the message
the associated
transactionID
valueis zero. If the message
sentis an rsvpmessage,
the associated
transactionID valueis
a nonzerovaluematchedto both the recìuest
and the resoonse.
5.5.7Interconnect
Space
The BootstrapLoaderCommunication
Systemsupportsaccessto boardinterconnect
space.This accessenablesthe driverto determinecriticaldevicestatusinformation.The
BootstrapLoaderCommunication
Systemprovidesinterconnect
spaceaccessthroughtwo
systemutilities: BS$GET$INTERCONNECT
and BS$SET$INTERCONNECT.
When
you usethesecallswithin your drivercode,you mustverify the valuereador written from
or to the interconnect
spaceis u'hatyou expect.The BootstrapLoadercodedoesnot know
what "correct"valuesshouldbe
<-) )
Bfi)tstrap Loader
WRITING A CUSTOMFIRST.STAGEDRIVER
The followingutility descriptionpresentsBS$GEfiINTERCONNECT:
value = BS$GET$INTERCONNECT (slot$number,reg$number,
exception$ptr)
INPUT PARAMETERS
slot$number
A BYTE that specifiesthe MBII slotwhoseinterconnect
spaceis to be read. You mustspecirythisvalueas
lbllows:
Value
Meaning
0-19
20-23
24-29
30
3l
specifiesiPSBslotnumbers0-19
illegalvalues
specifiesiLBX slot numbers0-5
illegal
specifiesthe iPSBslot ofthe CPU
that the callingsoftwareis
executingon, regardless
of the
actualiPSBslot numberof the
CPU
illegalvalues
32-255
reg$number
A WORD identifoingthe interconnect
registerto be
read. This valuemustbe in the rangeof 0000Hto
0l FFH (the interconnect
spacedefinition).
OUTPUTPARAMETERS
value
A BYTE containingthe contentsof the interconnect
registerread.
exception$ptr
A POINTER to a WORD in whichthe Bootstrap
Luaderreturnsthe exceptioncodegeneratedby this
BootstrapLoaderCommunication
Systemcall.
DESCRIFIION
The utility BS$GET$INTERCONNECT
readsthe contentsof the interconnect
register
specifiedby reg$number
from the boardspecifiedby slot$number
and returnsthe contents
in the parametervalue.
Bootstrap Loader
5-23
WRITING A CUSTOMFIRST-STAGEDRIVER
EXAMPLE
spaceregisters.The
of readinginterconnect
This exampleillustratesthe fundamentals
exampleis written in PL/M-86 codeand is intendedto be genericin 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.
************************************************************
*
*
*
*
*
*
/
: DO;
SA.I,fPLE_BS$GET$INTERCONNECT
DECIAREslot$nurnber
DECI-ARErecord$offset
D E C I A R Eu n i t $ d e f $ r e c
D E C I A R - rEe c $ l e n g t h $ r e g $ o f f
gen$staÈus$reg$off
DECTARE
DECLARErecord$found
D E C I À R Ee o E $ r e c
DECI,AREstacus
D E C T A R vEa l u e
DECI-AREslot
LITERALLY
DECIAREudr
LITERALLY
DECIAREgsro
LITERALLY
DECIAREeotrec
LITERALLY
DECI,ARErlro
LITERALLY
DECLAREro
LITERALLY
C O D E :D 0 ;
slot$nurnber
unit$def$rec
gen$statusSreg$off eot$rec
r e c $ l e n g t h $ r e g $ of f :
BYTE;
IíORD;
BYTE;
BYTE;
BYTE;
BYTE;
BYTE;
woRD;
BYTE;
'3H'
;
'0FEH'
'OAH'
;
'0FFH'
'01H'
;
'020H'
slot;
udr;
gsro;
eotrec;
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
BoolstrapLOader
DR]VER
WRITINGA CUSTOMFIRST.STACE
/***********************************************************
* 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 *
*
If so, bypass the D0 IiHILE loop and get
read from.
*
lf noc,
right to reading the specifíc regiscer.
record, *
and the record is not the EOT (End Of Tenplate)
*
execute the DO hTllLE loop to get at thè next rècórd.
***************rk*******:&************************************/
D0 WHILE (record$found o unit$def$rec)
(record$found <> eot$rec) ;
AND
/************************************************************
* Position record$offset to read lhe next sequential
* record.
INTERCONNECT
T h i s í s d o n e b y c a l l l n g B S9 C E T $
*
to read the aurrent record length, adding 2 (for the
* tl^iobytes used for the record type and record length
* registers), and finally adding the current
* recordSoffset value. Note that record$offset +
* r e c $ l e n g t h $ r e g $ of f y i e l d s t h e i n t e r c o n n e c t r e g i s t e r
* that holds the current record length.
*
*
*
*
:r
*
*
*
**********************)t*************************************/
record$offset - record$offset
B S$ GE T $1 N Î E R C O N N E C T
(slot$nurnber,
record$offset +
r e c $ 1 en g t h $ r e g $ of f ,
G st a t u s ) ;
+ 2 +
/***********************************************************
* Read the next record-type regi,ster into the variable
* record$found.
*
*
************************************************:t**********/
Bootstrap L0ader
< - ?q
WRITINCA CUSTOMFIRST-STACE
I)RIVER
r e c o r d $ f o u n d = B S$ c E T $I N T E R C O N N E C T
(slotSnunber,
recordSoffset,
Gstacus);
END;
/******************************************************:P*****
* Ca11 BS$GET$INTERCONNECT
to read the general status
* register.
The exact register location is deterurined by
* a d d i n g t h e r è g i s t e r o f f s e t v a l u è g e n $s t a t u s $ r e g $ of f t o
* record$offset
************************************************************
*
*
*
*
/
( slot$nurnber,
value - BS$GET$INTERCONNECT
record$offset + gen$status$reg$off ,
Gstatus).
ENDCODE:
END SA}fPLE-BS$GET$INTERCONNECT
;
CONDITION CODES
E$OK
0000H
No exceptionalconditions.
The followingutility descriptionpresenrsBS$SEfiINTERCONNECT:
CALL = BS$SET$INTERCONNECT (value,slot$number,reg$number,
exception$ptr)
s-26
BootstrapLoader
WRITING A CUSTOMFIRST-STAGEDRIVER
INPUT PARAMETERS
value A BYTE containingthe valueto be writteninto the interconnectregister.
slot$number
A BYTE specirying
the MBll slotwhoseinterconnect
spaceis to be written. You mustspecifythisvalueas
follows:
Value
Meaning
0-19
20-23
24-29
30
3t
specifiesiPSBslot numbers0-19
illegalvalues
specifiesiLBX slot numbers0-5
illegal
specifiesthe iPSBslot of the CPU
that the callingsoftwareis
of the
executingon, regardless
actualiPSBslot numberof the
CPU
illegalvalues
32-255
reg$number
A WORD identifuingthe interconnect
registerto be
written. This valuemustbe in the rangeof 0000Hto
spacedefinition).
0lFFH (the interconnect
OUTPUTPARAMETERS
exception$ptr
A POINTER to a WORD in whichthe Bootstrap
Loaderreturnsthe exceptioncodegeneratedby this
BootstrapLoaderCommunication
Systemcall.
DESCRIPTION
The utility BS$SET$INTERCONNECT
writesthe interconnect
registerspecifiedby
reg$numberon the boardspecifiedby slot$number
with the contentsin the parameter
value.
BootstrapLoader
5-27
WRITING A CUSTOMFIRST.STAGEDRIVER
EXAMPLE
spaceregisters.The
of writinginterconnect
This exampleillustratesthe fundamentals
exampleis written in PL/M-86 codeand is intendedto be genericin nature.
/************************************************************
*
the conÈroller
initÍalization
This exarnple writes
*
record
systen bus control
register
of the parallel
*
within
space found on the board in
the interconnect
*
Note that this code does no
slot nunber three.
*
to
checkinp of scatus after each call
*
*
*
. Thè
BS$GET$
INTERCoNNECîand BS$s ET$INTERCONNECT
prograumer rnust ensure values returned and writcen
correct.
* This exarnple uses the sane record - s earching scheme
* shown ln the exanple for BS$GET$INTERCONNECT.
************************************************************,/
*
*
*
*
*
are
*
*
SAI{PLE_BS
: D0;
$ SET$INTERCONNECT
BYTE;
DECI^ARE
slot$nurnber
\'ORD;
DECLAREstatus
WORD;
DECLARE
record$offset
BYTE;
D E C I - A RpEs b $ c t r l $ r e c
DECLARErec $ length$ re g$off
BYTE;
DECIAREcontr$ init$ reg$off
BYTE;
DECI-ARErecord$found
BYTE;
DECIAREeot$rec
BYîE;
D E C I A R Eh o s t $ m e s s $i d
BYTE;
' 3H'
DECIAREsloÈ
LITEMLLY
;
DECI,AREpsbcr
LITERALLY '6H' ;
DECLARE
ciro
LITERALLY 'DH';
DECLAREeotrec
LITERALLY 'OFFH'
' 01H'
DECIARErlro
LITEMLLY
;
DECIAREhnid
LITERALLY 'AH';
DECIAREro
LITERALLY '020H'
C o D E :D Q ;
slot$number
psb$ctrl$rec
contr$init$reg$off
eot$rec
-r ^c^LCY
lr -c -" ^ó fr h C - ^ .' Cc^t F
1 .F? u .
"v
host$mess$id
5-28
:
:
-
slot;
psbcr;
ciro;
eoLrec;
-
rlyò.
- hnid;
B(ntstrap [,0ader
WRITING A CUSTOM FIRST-STAGEDRIVER
/***********************************************************
* 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.
***********************************************************
*
*
*
/
r e c o r d $ f o u n d - B S$ c E T $I N T E R C O N N E C T
(s1ot$nurnber,
record$offset,
Gstatus);
/************************************************************
* Deterrnine if chís first
record is the record we wanc to *
* write.
*
I f s o , b y p a s s t h e D 0 l + r H l L El o o p a n d p r o c e e d
*
'rrítins the sne.ific
repísrcr
If n.lt end the record *
*
is not the EOT (End Of Template) record, executè the DO *
*
)t
I.IHILE loop to get at the next record.
************************************************************/
DO WHILE (record$found o psb$ctr1$rec) AND
(record$found O eot$rec) ;
/************************************************************
* Position record9offset to read the next sequential
* record.
T h i s i s d o n e b y c a l l i n g B S $ G E TI $
NTERCONNECT
* 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 +
B S9 G E T $
INTERCONNECT
( s l o r $ n u m b e r,
record$offset +
recglengthgreggoff ,
@status);
Bootstrapl,oader
5-29
WRITING A CUSTOMFIRST.STAGEDRIVER
/***********************************************************
* Read the nexÈ record-type register into the variable
* record$found.
***********************************************************/
record$found
*
*
- BS$GET$INTERCONNECT
(slot$nurnber,
record$offset,
G sL at u s ) ;
END:
/******************************************************)k*****
* c a l l B s SS E T S
t oT w r i t e t h e c o n t r o l l e r
INTERCONNEC
* initialization
The exact register locatíon
register.
* is deternined by adding the register offset value
* c o n t r $ i n l t $ r e g $ of f t o r e c o r d $ o f f s è t .
************************************************************
*
*
*
*
/
I N T E R C O N N E( h
CoTs t $ m e s s $i d , s l o t $ n u m b e r ,
C A L L B S$ S E T $
r e c o r d $ o f f s e t + c o n t r $ i n i t $ r e g $ o f f , @ st a t u s ) ;
ENDCODE;
END SAMPLE-BS
$ SET$INTERCONNECT
;
CONDITION CODES
E$OK
0000H
No exceptional
conditions.
5.5.8DriverCodeConsiderations
Whenwritingthe first-stagedriver,you mustprovidetwo proceduresto the Bootstrap
Loader: a deviceinitializationprrredure and a devicereadprocedure.To be compatible
with the BootstrapLoader,theseprocedures
mustperformthe samestepsas the
initializationand readprocedures
listedin Sections5.2and 5.3.
An additionalrequirementfor drivercodeusedin a MULTIBUS II environmentstipulates
that codeusinganyof the utilitiesshownin Sections5.5.2through5.5.6belongto the
BootstrapLoaderDriversCOMPACT sub-system.
The reasonfor this requirementis
becauseall the utilitiesare arcessible
asNEAR calls.
5-30
Bfi)tstrap k)ader
WRITINGA CUSTOMFIRST.STAGE
DRIVER
The followingpartialcodeprovidesln exampleof how to ensureyour drivercodeis part of
the BootstrapLoaderDriver coMPACT sub-system.
In this example,the coclingis shown
usingtheASM86programming
Ianguage.
name
public
public
bs2pci
device_ini t_2 24A
d e v i c e_ r e a d _ Z 2 4 t t
bs l_dr ive rs_cgroup
bsl_dr ive rs_dgroup
assume cs:
assune ds:
group
group
bsl_dr ive rs_c group
bsÌ_dr ive rs_dgroup
bsl_dr ive rs_data
segment word
.
(Typical
b s l_dr ive rs_data
ends
bs l_dr ive r s_c ode
device inir
224A
segment byte
p roc
.
bs1 drivers
b s 1_dr ive rs*code
bsI drivers data
code
(Typical
pubÌ ic
'DATA'
c o d e)
pubLic
far
'CODE'
code)
ends
In the aboveexample,
bs2pciis the nameof the driverntodule.You cannameyourdriver
moduleanyuniquenameyou desire.
The two followingpublicstatements
declarethe deviccinitializationand deviceread
proceduresaspublic. Thesepublicstatements
enablethe BootstrapLoadercodeto access
themasFAR calls.Again,youcannanteyourdeviceinitialization
andreatlprocedures
anyuniquenameyou desire.
Next,the two groupstatements
cnsurethatthisdrivermoduleis groupedtogetherwith the
BootstrapLoaderutilitiesaspartof the sameCOMPACTsub-system.
You mustusctlìc
two groupnamesbsl_driverscgroupirnclbsl_cirivers_dgroup
anclthe two segmentnames
hsl clriverscodeand bsl drivers data.
F i n a Ì Ì y ,t h e t w o a s s u m es t a t e m e n t se s t a b l i s ht h e c o r r e c tv a l u e sf o r t h e c o d e s e q m e n tb a s e
a d d r e s sa n d t h e d a t a s e g m e n th a s ea d d r e s sc, s a n d d s .
tsootstrapl,Oader
5--tI
WRITING A CUSTONIFIRST-STAGEI)RIVER
The followingalgorithmis an examplethat illustratesboth a methodof usingthe Bootstrap
LoaderCommunicationSystemes a wayof verifuinga certainboardis presentin the
The exampleis written using
systemanrlof usingthe utility BS$GET$INTE,RCONNECT.
a pseudocodethat is not meantto representanyknownprogramminglanguage.
*BEGIN COMMENTS:
*
Paraneters
received
a r e B O A R D $ I Da n d I N S T A N C E .
*
*
BOARD$ID is the identificatlon
Òf fhe troard beins looked for.
*
*
*
*
INSTANCE Ís the instance of a particular
bus system.
This
troard on the parallel
parameter allows for multiple occurrences of
the MULTIBUS II systern
the sarne board within
*
Parameters
returned
are
value
iPSB$SLOT
*
*
*
iPsB$sLoT is
is found, or
not found.
the MULTIBUS II board slot when the board
the value OFFH when Lhe board is
*
Note that
*
cnoní fi.
*
concains the board identification
the variable
ínl"ar.nnnpr.l-
V E N D O R _ I Dp o í n t s
sna.p
rèpister
to
the
fhat
value.
*END COMMENTS:
**********************************-x***************
*BECIN CODE:
* D O u n t i l a l l M U L T I B U SI I b o a r d s l o t s o n t h e P S B a r e
*
sequentially examined. Use the variabÌe
*
i P S B $ S L O Ta s t h e l o o p i n g v a r i a b l e t o i n d i c a t e
*
the slor nunber for che board being examined.
*
*
5-32
: B S$ G E T I$N T E R C O N N E( C
i PTS B $ S L O T ,
VENDOR$ID
V E N D O RI D , S T A T U S )
Bù)tstrap [,oader
WRITINGA CUSTOMFIRST-STAGE
I)RIVER
*
rf
*
*
*
x
*
*
*
*
*
*
)t
*
*
*
*
*
*
*
*
n
*
*
*
t h e V E N D O R $ I Dr e t u r n e d i s n o n z e r o ,
a board exi-sts in the examined slot
then
Ìt
V E N D O R $ Ì Dr n a r c h es B o A R D g t D
then
lf
INSTANCEis the desired Ínstance of
BOARD$ ID
then
return lhe iPSBSSLOT looping index to
indicace the sl-oc number of BOARD$ID
else
else
else
If we have checked all board slots
then
Return the value OFFtt as the ipSB$SLOT
parameter indicating t-hedevice
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
THENEW
FIRST.STAGE
DRIVER
The first stageof the Bootstrap Loader obtains information about the devicesantl their
associateddevicedrivers from the Bootstrap Loader configuration file BS LA86 or
BS1MB2.A86. To support a custom devicedriver, you musr add to that file a TTDEVICE
macro for each unit on the devicethît your first-stagedevice driver supports. For
example,if tr.voflexihle diskette drives are attachedto the device,you must add two
ToDEYICE macros to the list (one for each clrive). Chapter 3 describesthe syntaxol thc
%DEVICE macro.
Brntstraphader
5-33
WRITING A CUSTOMFIRST-STAGEI)RIVER
As an example,Figure5-3showsa portionof the BSl.A86file that waschangedto add
to
driver (changes
%DEVICE macrosfor two unitssupportedby a customfirst-stage
physical
1,
and
their
numbers
0
and
BSlMB2.A86wouldoccursimilarly).The unitshave
The nameof the customdriverdeviceinitialization
namesare YZ\ andYZ1, respectively.
the
nameof the devicereadprocedureis
procedureis NEWDEVICEINIT, and
NEWDEVICEREAD. Arrows to the left of the fisureshowthe addedlines.
b s1
$include ( : f1 :bs1.inc)
fcpu(80286)
of the iAPX 188
;iSBC 188/48 initialization
(
y
0
f
c
3
8
h
n
o
n
e
i
A
P
X
_
1
8
6
_
I
N
I
T
,
, B O b b h, n o n e , 0 0 3 b h )
,
;
Zdevlce (b0 , Ò r l o r r i n a i n i t ? 5 ú
Zdevice (bao , Ò . . l o r r i n a i n i r ? 6 ú
- -> ldevlce(y20,
0, nesdevlceinit,
--> ldevlce (yzI, l, newdeviceinit,
Tend
deviceread254)
d e v i c e r e a d 26 4 )
newdevlceread)
newdeviceread)
Figure5-3. NftrdilìedBSl.Att6File
THE
A NEWFIRSTSTAGECONTAINING
5.7. GENERATING
DRIVER
CUSTOMDEVICE
Once you have written the custom clevicedriver and changedthe Bootstrap Loader
Configuration files, you must generateir new first stagethat includesthe custom device
driver. To do so, follow the stepsbelow. (These stepsilssumethat you use an iRMX II
systemto developyour cocle.)
l.
Compìle or assemblethe first-stagecleviceinitialization and device read procedures.
For example,the following command assemblesdeviceread and device initialize
nrocecluresthat iìre assumc(lto reside in the file NEWDEVICE l.Al'tfr.
- a s m 8 6n e w d r i v l . a 8 6 o b j e c t ( n e w d r l v l . o b j )
iRMX rr 8086/87/186 MACRO
A S S E M B L E RV,2 . 0
Copyright 1980, 1981, 1982, INTELCORP.
IOUND
ASSEMBLYCOMPLETED,
NO É]RRORS
5-34
Bo0tstrapl,{)ader
I)RIVER
WRITINCA CUSTOMFIRST-STAGE
2. Insertthe objectmodulesfor the devicereadand the deviceinitializeproceduresinto
the objectlibraryof the BootstrapLoader. This libraryis namedBS1.LIB and
normallyresidesin the directory/RMX2tlfr/BOOT or /RMX86/BOOT. The
followingcommands
addtheobjectmodules
generated
ìn Stepl.
. LIB86
i R M X I I 8 0 8 6 L I B R A R I A NV 2 . O
Copyrlght 1980 INTEL CORPOMTION
*add newdrivl .obj to /rnx286/boot/bs1.1ib
3. Attach the directorv containingthe Bootstrap Loader configuration files as the current
default directorv:
- a t t a c h f 1 1 e /tntx296 /boot
-tsF^^l
^.1
^c
/rnx286 /boor , o ! L d L L ' E u n J
è.
,V.
4 . G e n e r a t ea n e w f i r s t s t a g eb y i n v o k i n gt h e S U t s M I l ' f i l e n a m e d B S I . C S D . C h a p t e r2
d e s c r i b e st h e d e t a i l so f t h e i n v o c a t i o n .A s a n e r a m p l e ,t h e f o l l o w i n gc o m m a n da s s u m e s
t h a t y o u h a v ec h o s e n4 0 0 0 0 Ha s t h e m e m o r yl o c a t i o no f t h e f i r s t s t a g ea n t l 4 3 0 0 0 Ha s
the memory location of the seconclstage.
Thisstepassumes
thatyou havemadeappropriate
changes
to the BSI.CSDfile as
describedearlierin this chapter.
The BSl.CSDfile placesthe resulting
locatedBootstrap
Loaderin the file BSl.
One thingto rememberaboutthis procedureis that because
you addedyour devicedriver
to the objectlibraryof the BootstnìpLoader,the devicedriveris automatically
inclucledin
all futureversionsof the first stagecreatedbv BS1.CSD.
B0otstraplr'ader
5--t:
CHAPTER
6
WRITING
A CUSTOMTHIRD.STAGE
DRIVER
6.1 INTRODUCTION
Ifyou plan to usethe BootstrapLoatlerto loadiRMX ll applications
from a devicefor
whichno Intel-supplied
third-stage
driverexists,you can makeone of two choices
dependent
uponthe sizeofyour loadlile:
'I'he
. For loadfilessmal-ter
than i3.lt)Kbytcs.usethe genericthird stage.
genericthird
stageusesthe first-stage
delice ciriversyou havealreadysupplied.Sincethe loadlile
fits in the I megabyteaclclress
spacesupportedin real mode,and first-stage
device
driversare ableto placethe loadfile,no needfor you to createnewdevicedriversexists
for the third stage.
.
For loadfileslargerthan 840Kbytes,usethe device-specifìc
third stage.The devicespecificthird stageusesnewclevicedriversthat you mustsupply.Thesedevicedrivers
run in protectedvirtualaddressmodeenablingthe loadfileto be placedusingthe full
16megabyterangeof addresses.
This chapteroutlinesthe procedurelirr writinga thirtl-stage
tlriver neededlbr the devicespecificthir
-->
( :fl:bs3enf.
inc )
(0,w0, device ini tmscgen, devicereadnsc gen, data_msc)
Ídevice
( 1 , w 1 , d e v l c e i n i t m sc g e n , d e v i c e r e a d n s c g e n , d a t a _ r n s c)
fdevice
( 8 ,wfO , devic e ini rnsc gen, devic ereadnscgen, data_msc )
ldevice
ldevlce (9,wfl,deviceinitmscgen,devlcereadmscgen,data_nsc)
(0, ba0, deviceinit264,
ldevice
devi ceread264 , data_264)
yz0, newdevicelnlt,
Idevlce(0,
newdeviceread, data_newdev)
ldevice(1,
yzl, newdevicelnft,
nevdevlceread,
data neudev)
;
;int1
Zlnt 3
;halt
%cpu_board (286/12)
i
lend
Figure6-l. Changingthe tsS3.A8ó
File
6.9 GENERATING
A NEWTHIRDSTAGECONTAINING
THE
CUSTOMDRIVER
Once you have written the custom devicedriver and changedthe Bodstrap Loader
Configuration files, you must genenrtea device-specificthird stagethat includesthe
custom devicedriver. To do so, perform the following steps. (These stepsassumethat you
u s e a n i R M X s y s t e mt o d e v e l o py o u r c o d e . )
l.
Compiìe or assemblethe third-stagedevice initialization and device read procedures.
For example,the following command assemblesdevice read and device initialization
proceduresthat reside in the file NEWDRIV3.A86.
Bootstrap[íader
ó-9
WRITING A CUSTOMTHIRD-STAGET)RIVER
- asn86 newdrív3. a86 obj ect (nesdrlv3 .obj )
i R l D { r r 8 0 8 6 / 8 7 / L 8 6 M A C R 0A S S E M B L E RV,2 . 0
copyrighr 1980, r981, 1982, INTELCoRP.
ASSEMBLYCOMPLETED,
NO ERRORSFOUND
z.
Insertthe objectmodulesfor the devicereadand the devìceinitializeprocedures
into the BootstrapLoaderobjectlibrary. This libraryis namedBS3.LIBand
normallyresidesin the directory/RMX8ó/BOOT or /RMX286/BOOT. The
followingcommandsadd the objectmodulesgeneratedin Step l.
- L I B S6
iRMX II 8086 LIBMRIAN V2.O
Copyright 1980 INTEL CORPORATÍON
*add newdriv3. obj to /rnx2B6/boot/bs3.1ib
3.
A t t a c h t h e d i r e c t o r yc o n t a i n i n gt h e B o o t s t r a pL o a d e r c o n f i g u r a t i o nf i l e sa s t h e
c u r r e n td e f a u l td i r e c t o n .
- attachflle
/rnx286 /t>oot ,
A
/rnx286 /boot
.fl-,.}la;
Aq
q
Generatea newthird sta_qe
by invokingthe SUBMIT file namedBS3.CSD.Chapter
3 describes
the detailsof invokingBS3.CSD.As an example,the followingcommand
namesthe new third stage"NEW3STG,"and locatesit at memorylocation08C000H.
This stepassumes
that you havemacleanyappropriatechanges
to the BS3.CSDfile
that are requiredto supporttrnyconfigurationfilesyou might havedesigned.
6-10
B(x)tstrap k)ader
CHAPTER
7
ERROR
HANDLING
7.1 INTRODUCTION
If the bootstraploadingprocessis unsuccessful,
the Bootstrap[-oaderìnitiateserrorhandlingprocedures.
Notification
ol lailuresoccurring
duringthe loadingprocess
clepends
on the configuration
of the firstrrnrlthirristl,qes.
Thischupterdescribes
the Bootstralt
Loader'serrorhandlingfncilities.
7.2 ANALYZING
BOOTSTRAP
LOADERFAILURES
T h e B o o t s t r a pL o a d e r c a n d i s p | r l n t e s s : t g east t h e t e r m i n . l w h e n b o o t s t r i ì pl o a c ì i n gi s
u n s u c c e s s f uA
l .s d i s c u s s c d
i n C ì h a p t c lr. r h c . I . C O N S O L h , . ; T ' E X T . a n d _ c É L I Sm
T acros
i n t h e B S E R R . A E ( fI i l c d c t e r m i n c* h c t h c r o r n o t n ì c s s i ì g eisr r e r i i s p l l y e r w
J hencrrors
o c c u rd u r i n g t h e f i r s t a n d s e c o l r ds t l r - s t sh.o w d e t i r i l c dt h e n t e s s a g easr e , a n d u n d e r w h a t
c i r c u m s t a n c etsh e v a r e d i s p l a y e d .A s C ì h l p t e r- l e x p l a i n st.h e t h i r d s t l q e a u t o m a t i c l l l y
d e t e r m i n e si f a m o n i t o r i s p r e s c n t .: r n c il l s o . d i s p l a v sc r r o r m e s s a g eas t t h e t e r m i n a l
r e g a r d Ì e sos f t h e f i r s t s t a g ec o n i i g u n t t i o n .
The following sectionsdescribewhrrt h;rp;rcnsu hen a bocttstraploutlinq error occursancì
how to analyzethe errclr. Therc arc two situationsdescribed:error anulvsiswhen nlessu_lllcs
a r e d i s p l a y e da, n d e r r o r a n a l v s i sw h e n n o r n e s s a q casr e d i s p l a y c c l .
7.2.1 ActionsTakenby the BootstrapLoaderAfteran Error
A f t e r r e s p o n d i n gt o a n e r r o r h y p u s h i n ga w o r d o n t o t h e s t i r c ka n d o p t i o n a l l yd i s p l a y i n ga
m e s s a g et ,h e B o o t s t r a pL o a d c r c i t h c r t r i e s a g a i n ,p a s s c sc o n t r o lt o a m o n i t o r ,o r h a l t s . l f
t h e e r r o r ì s d e t e c t e di n t h e f i r s t o r s c c o n ds t l r q et,h e a c t i o nt a k e n d e p e n d so n w h e t h e rv o u r
B S E R R . A t ì 6f i l e c o n t a i n sa n f i A ( l A I N . . ; l N T l , . - ; l N ' f l , o r _ c i H A L Tm a c r o . I f r h e e r r c l
i s d e t e c t e dì n t h e t h i r d s t a g e ,r h e a c r i o nr : r k e nd e p e n d so n w h e t h e ry o u r B S 3 . A 8 óo r
B C 3 . A 8 óf i l e c o n t a i n sa n c l l N ' f I , c i l N ' l ' ] . o r c . , i H A L Tm a c r o .
The only diffèrcnce betweenthe clcvicc-spccilicand generic third stagcsis that the generie
t h i r d s t a g en e v e rg e n e r a t e st h e c r r o r c o d c " D c v i c cN o t S u p p o r t e d "( r c l e r t o e r r o r c o d eJ . l
l a t e r i n t h i s c h a p t e r ) ,b e c a u s ct h e q e n e r i ct h i r d s t a g es u p p o r t sa l l t h e d e v i c e ss u p p o r t e dl r y
t h e f i r s t s t a g e . I f y o u i n v o k et h e t s o o r s t r t rLpo a d e rw i t h a d e v i c en a m e t h a t i s n o t
s u p p o r t e db y t h e f i r s t s t a q e ,t h e g c n c r i ct h i r d s t a g ew i l l n e v e re v e ng e t Ì o a d e di n t o m e m o r y .
Brxrtstrapl-oader
7-l
ERRORHANDLING
7.2.2 AnalyzingErrorsWith DisplayedErrorMessages
ToTEXÎ, or a/oLISTmacro,then the
If your BSERR.A86file containsthe o/cCONSOLE,
at the terminalwhenevera failureoccursin
BootstrapLoaderdisplaysan error message
consistsof one or two parts. The first part,
the bootstraploadingprocess.The message
is a numericalerror code. The secondpart is a shortdescription
whichis alwaysdisplayed,
of the error. Althoughthe secondpart is alwaysdisplayedfor third stageerrors,it is
displayedfor first and secondstageerrorsonly if the T,ITEXTor ToLISTmacrois included.
'l'he
the stageof
first digit indicates,if possible,
Eachnumericalerror codehastwo digits.
the bootstraploadingprocessin whichthe error occurred.The seconddigit distinguishes
the typesof errorsthat canoccurin a particularstage.Thereare four possiblevaluesfor
the first disit.
First Digit
0
I
2
3
Stage
Can'ttell
First
Second
Th irtl
messages,
and their causesand meaningsare as
cìisplay
The error codes,their abbreviated
folìows.
Error Code:
Description:
0l
I/O error
loading
iìt someundetcrmined
time duringthebootstrap
An I/O erroroccurred
process.
macrois inclucled.
the Bootstrap
[.oaderplacesa codein the highIf the ToCONSOLE
word
orderbyteof the
it pushesonto the stack,so that you canfurtherdiagnosethe
problem. This byte identifiesthe drivcr lìrr the devicethat producedthe error, as
follows:
Code
Driver
08H
l5H
20tì
MSC (with or
without2l8A)
218Aon CPU board
1861224A
18H
25H
5lH
54H
()EOH
other(in rangeA0H-DFtl)
1 1
25r
254 or 264
SCSI
driverfor your custom
BrntstrapLrader
ERRORTIANI)LING
Note that this devicecodeis oven'rittenwhenthe descriptionis printerJif the o/r'l'EXT
or ToLISTmacrois included.
The lastentry in the list of devicec.des assumes
that you havewritten:r devicedriver
for your deviceand haveidentifiedthe driverby somec.de in the inclicated
range-othervaluesarereserved
for Inteldrivers.For information
abouthowto incorporirtc
thiscodeintothe driver,seeCihapter
5.
Error Code:
Description:
11
Devicenot readv.
'fhe
specificdevice designatet{for bootstrap loatJingis not reatly. This error occurs
o n l y w h e n y o u r B S E R R . A I J ífT
i l e d o e sn o t c o n t a i nt h e f T A U T O m a c r o . T h c r c f o r c .
e i t h e r t h e o p e r a t o rh a s s p e c i f i e da p a r t i c u l a rd e v i c eo r o n l y o n e d c v i c ei s i n t h c
B o o t s t r a pL o a d e r ' st l e v i c el i s t , : r n t lt h e d e v i c ei s n o t r e a r j v .
Error Code:
Description:
12
D e v i c ed o e sn o t e x i s t . ( l f B S E R R . A I J 6
c u n t u i n st h e T c L I S Tn r a c r o ,
t h e d i s p l a yt h e n s h o w st h e l i s t o f k n o w n d e v i c e s . )
T h e d e v i c en a m e e n t e r e da t t h c c o n s o l eh a s n o c n t r y i n t h e B o o t s t r a pL o a d e r ' sd e v i c c
l i s t . T h i s e r r o r o c c u r so n l y w h e n I ' o u r t ì S E R R . A 8 ( lri l e c o n t a i n st h c g I M A N U A L
m a c r o a n d y o u e n t e r a d e v i c en a m e ,b u t t h e d e v i c en a m ey o u e n t e r i s n o t k n o w n t o t h c
B o o t s t r a pL o a d e r . A f t e r d i s p l a y i n gr h e m e s s a g et ,h e B o o t s t r a pL o a d e r t l i s p Ì a y st h e
n a m e so f t h e c l e v i c e isn i t s t l c v i c el i s t .
Error Code:
Description:
13
No deviccrcudv.
Noneof the devices
in the l]ootstrupl,oader's
devicelistarereadv.Thiserroroccurs
onlywhenyour BSERR.A8(r
lile contains
the 9óAUTOor oZMANUALmacroandvou
do not entera devicenameat theconsole.
Error Code:
Description:
2l
File not founrl.
T h e B o o t s t r a pL o a d e rc o u l d n o t f i n d t h e i n d i c u t e rfli l e o n t h e d c s i g n l r t e d
bootstriì[l
d e v i c e . T h i s i s t h e d e f a u l tf i l e i f n o p : ì t h n a m ew a s e n t e r e da t t h e c o n s o l e. O t h e n l i s e ,i t
i s t h e f i l e w h o s ep a t h n a m er l a s e n t e r e d . I n i R M X I I s y s t em s , t h e B o o t s t r a pL o a c ì e r
couldnot find the third staqc.
Brntstraphader
ERROR HANI)LING
Error Code:
Description:
22
Badchecksum.
or the
While tryingto load the targetfile (the applicationsystemfor iRMX I systems,
a checksumerror.
the BootstrapLoaderencountered
third stagefor iRMX II systems),
value
with eachrecordis a checksum
Eachfile consistsof severalrecords.Associatetl
that specifiesthe numericalsum(ignoringoverflows)of the bytesin the record When
valuefor eachrecordand
the BootstrapLoaderloaclsa file, it computesa checksum
for any
value. If thereis a discrepancy
comparesthat valueto the recordedchecksum
recorclin the file, it usuallymcansthrttone or more bytesof the file havebeen
insteadof continuingthe
corrupted,so the BootstrapLoirderreturnsthis message
loadingprocess.
Error Code:
Description:
23
endof lile.
Premature
recordsat the end of the
The BootstrapLoaderdid not fintl the requiredencl-of-file
or the thirdstagefor iRMX ll
1i)riRMX I systems,
system
targetfile (theapplication
systems).
Error Code:
Description:
24
No startaddresstìrunclin inputfile.
loadedthc targetfile but wasunableto transler
The BootstrapLoadersuccesslully
initiirlCSitndIP valueswerenot present.
controlto the file,because
Error Code:
Description:
3l
File not found.
bootstrap
device.
The thirdstagewasunableto finrlthe turqetfile on thedesignated
of the wayyou invokeclthe BootstrapLoader,the targetfile is expectedto
Regardless
havea .286extension.
Error Code:
Description:
32
Badchecksu
m.
a checksum
errorwhiletryingto loadthe targetfile.
The thirdstageencountered
Error Cotle:
Description:
33
Premature
endof file.
whileattempting
to loadthe
end-of-file
earlierthanexpected
The thirdstagereached
targetfile.
7-4
Boolstrap hadcr
ERRORIIANI)LING
Error Code:
Description:
34
Devicenot supportetJ.
The specifietldeviceis not supportedby the device-specific
third stage.That is,there
is no %DEVICE macroinvocationfor this devicein the BS3.Auófile.
Error Code:
Description:
35
Invalitlfile t1,pe.
The targetfile is not an 8028óbootloadable
file (usuallyproducedby BLD2lt6).
7.2.3 AnalyzingErrorsWithoutDisplayedErrorMessages
In mostcases,
you candetermìnethe causeof a BootstrapLoaderfailureby obsening the
behaviorof the Bootstrap
Loaderwhcnit failsto loadthe application
successlully.
You
'l'able
canthentakestepsto correctthe frriìure.
4-1Ìistssomecommonbehaviors
and
possiblecausesfor failure. The tableiìssunles
that the BootstrapLoaderis setup to halt if
it detects:ìn error. BeforehaÌting.the BootstrapLoaderplacesthe error codeinto the CX
reglsler.
Another possiblecauseoî îailure.the eltèctsof whichare unpredictlble,is that the device
controllerblock(asdeterminedby the device'swake-upatldress)canbe corrupted.To
avoidthis kind of failure,ensurethiìt neitherthe BootstrapLoadernor the targetfiJe
overlansthe devicecontrollerblock1ìrrthe device.
BrxrtstrapInader
7-5
ERRORIIANDLING
Table7-t. PostmolemAnallsisof BootstrapInader Failure
Behaviorof Loader
PossibleCeuses
B o o t s t r a pÌ o a d i n gf ai l s ì n
the first stage.
The indicateddeviceis not readyor is not
knownlo thc B(ìoî\trapLoader
An I/O error occurredduringthe first stage
(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 EIOSTask's Priorities
131
l0-2551
( P M I ) E I O S P o o l M l n i m u mI O - O F F F F H I
0180H
( P M A ) E I O S P o o l M a x i r n u m[ 0 - 0 F F F F H ]
OFFFFFH
(CD) Configuration directory lL-45 charactersl
:SD:RMX286/C0NFIC
FigureA-1. EIOS ConfîgurationScreen(ABR)
A-2
Bootstrapl,0ad€r
AUTOMATICBOOT DEVICERECOGNITION
.
If you setABR to "yes,"the ICU displaysthe screenshownin FigureA-2. On this
screen,you mustspecirythe characteristics
of the systemdevicevia the DLN, DPN,
DFD, and DO prompts.For the DLN, DFD, and DO prompts,you mustnot supply
this informationlater in the "LogicalNames"screen.
With the DLN prompt,you canspecifothe logicalnamefor your systemdevice.If you
changethisvaluefrom the default(SD),you mustchangeall otherreferences
to the
:SD:logicalnameto the new nameyou speciff. The ExtendedI/O Systemcreatesthe
logicalnameyou speci! only if you setABR to "yes."
With the DPN prompt,you specifothe physicalnameof a devicethat you want to use
asyour systemdevicein casethe ExtendedI/O Systemcannotfind the name
RQBOOTED catalogued
in the root ohjectdirectory.This situationnormaÌlyoccurs
whenyou loadyour systemusinga meansotherthan the BootstrapLoader. For
example,if you transferthe OperatingSystemto your targetsystemvia the iSDM
monitor,there is no bootstrapcievice.In thiscase,the ExtendedI/O Systemusesthe
devicenamespecifiedin the DPN promptasthe systemdevrce.
With the DFD and D0 prompts,you setothercharacreristics
with the
associated
systemdevice.For mostcases,
the defaults
(DFD=NamedandDO=0000H)arethe
nreferredvalues.
(ABDR)
-- ->(DLN)
-- ->(DPN)
--->(DFD)
--->(DO)
Automatic Boot Device Recognitlon
D,rfault Systen Device Logfcal Nane Il-12 chars]
D,:fault Systen Devlce Physlcal Nane [1-12 chars]
D,:fault Systen Device Flle Driver \P/S/N/R)
D,rfault Syster0Devlce Osners ID [0-oFFFFH]
SD
rr0
Named
0000H
FigureA-2. ABI)R Screen(DLN, DPN, DFD, DO)
.
Duringconfigurationof the BasicI/O System,
you mustspecifydevice-unit
informationfor t re devicesyou wishto support.One of the promptson each"DeviceUnit lnformatior" screen(NAM) requiresyou to specifythe nameof the device-unit.
Another parameLer
(UN) requiresyou to specifythe unit number. (SeeFigureA-3 for
an exampleof thr:seprompts.)To enablethe ABDR lèatureto work correctly,you
mustassign
device-unit
nantesandunit numbers
thatmatchthe devicenamesandunit
numbersassignecl
duringBootstrapLoaclerconfiguration.
.
You assignthe Br)dstrapLoadcrdcvicenamesand unit numbersby includingor
motJifyingo/oDE\rICEmacrosin the first-stage
configurationfile (BSl.A8óor
BS1MB2.Atl6).With the lCU, you candefinedevice-unitnamesand unit numbers
other thanthosethat arevalid tìrr the BootstrapLoadcr. But eachBootstrapLoader
devicenamemusthavea corresponding
device-unitname,and the unit numbersmust
be the same.
BootstrapLoader
A-3
AUTOMATIC BOOT DEVICERECOGNITION
youmustformatyoursystem
deviceusingthe
BeforeyoucanusetheABDR feature,
Utilirt^
|RMXIl lnteractive
Configuratton
FORMAT command.The Guideto theExtended
devicefor usewiththecurrentrelease.
howto setupyoursystem
describes
(IMSC)Mass Storage Controller Device-Unit lnformation
( D E V ) D e v i c e N a m e[ 1 - 1 6 C h a r a c t e r s ]
--->(NAìl) Devlce-Unit Name [1-14 chars]
(PFD) Physical File Driver Required IYesrzNo]
( N F D ) N a m e dF i l e D r í v e r R e q u i r e d l Y e s / N o l
(SDD) Singlè or Double Density Disks ISingle/Double]
(SDS) Single or DoubIe Sided Disks ISingle/Double]
(EFI) 8 or 5 inch Disks l8l51
( S U F ) S t a n d a r d o r U n i f o r m F o r n a t l Sc a n d a r d / U n i f o r m l
(GRA) Cranularity
[ 0 - O F F F F ]H
( D S Z ) D e v i c e S i z e [ 0 - O F F F F F F F F] H
- -->(UN) Unlt Numberon this Devtce [O-OFFH]
( U I N ) U n i t I n f o N a r n el L - 1 6 C h a r s l
(RUT) Request Update Timeout l0-OFFFFHI
(NB) No. of Buffers Inonrarid : O/rand : 1-0FFFFH]
( C U P ) C o m r n oU
n p d a t e l T r u e / F a 1 se l
( M B ) M a x B u f f e r s [ 0 - O F F H]
YES
YES
DOUBLE
DOUBLE
8
STANDARD
0100H
07c500H
0000H
0096H
0008H
TRUE
OFFH
FigureA-3. Device-UnitInformationScreen(NAM and UN)
A-4
Burtstrap Loader
AUTOMATICBOOTDEVICERECOGNITIO\
4.4 HOWTOEXCLUDE
AUTOMATIC
BOOTDEVICE
RECOGNITION
To configurea systemthat doesnot includethe ABDR feature,setrhe ABR prompt in the
"EIOS"screento "no"(seeFigureA- 1). This disablesthe ABDR fèature.
Whenyou setABR to "no",the ICU will not displaythe ABDR screen.Therelbre,you
mustprovideinformationfor the DLN, DPN, DFD, and DO promptsas input to the
"LogicalNames"screen.FigureA-4 showsan exampleof this screenafter it hasbeenfilled
in to includea logicalnamefor the systemdevice.The underlinedinformationin Figurc
A-4 is the informationyou wouldsupplyif you set the ABR prompt in FigureA-l to "no"
andyou want the systemdeviceto be a flexiblediskettedrivecontrolledby an iSBC208
devicecontroller.
(LOCN)
Logical
[1]
[2]
[3]
--->[4]
Logical Narnes
Narne : Iog_narne,devlce_narne, fiÌe_driver,
owners-id
c
h
a
r
s
]
,
C
h
a
r
s
]
,
[1-12
[1-14
ÍP/S/N/R], [0-OFFFFH]
Logical Name : BB
0H
, BB
, PHYSICAL,
Logical
Name : STREAM
STREAI"f
STREAM
0H
,
,
,
Logical Name: LP
L
P
P
H
Y
S
I
C
A
L
,
0
H
,
,
Logical Nane = SD
0H
, AFO
, NAXED
,
Figure A-,1. Logical Names Screen
Bootstrap[-oader
A-5
APPENDIX
B
PROMMING
THEBOOTSTRAP
LOADER
ANDTHE|SDM"MONITOR
8.1 INTRODUCTION
chapter 2 statedthat one of the waysto preparethe BootstrapLoaderfor useis t'
combineit with one of the Intel monitorpackages
and burn the combinedcodeinto
PRoM. This appendirsuppÌiesintbrmationaboutcombiningthe BootstrapLoaderand
the |SDM monitor. The iSDM S;vern DebugMonitor lJser'sGuide alsocontains
informationaboutthis process.
8.2 INCORPORATING
THE|SDMMONITOR
This sectiongivesthe instructions
requiredto placethe first stageand the iSDM monitor
into nvo 27128EPROM devices.You canmodifythis exampleto suit your own purposes,
oryou canfollowit exactly.Referto the iPPSPROM PROGRAMMING SOF|WARE
USER'SGUIDE for detailedinlìrrmationaboutthe commands.The step-by-step
procedureis as follows:
1.
Enter the nameof the (version1.4or later)softwareusedwith the iUpp Universal
PROM Proerammer:
2.
Specifo
thatthe PROMsirrc2712R
EPROMdevices:
3.
Respondwith the number oî the ciesired
work file drive:
1
This saysthat drive :fl : * ill be useclfor creating temporary IPPS workfiles.
4.
lnitialize the file type to be loacled:
This saysthat the load file is an li0lló Object Module Format file (which the first
s t a g ea n d t h e i S D M m o n i t o r a r e ) .
Bff)tstrap k)ader
B-l
PROMMING THE BOOTSTRAPLOADI]RANI) TTIEiSD]\I' MONITOR
5.
bytesof the BSI (lirst stage)file are to go into
Specifythat the even-numbcred
hytesare to go into EPROM l. (The address
EPROM 0 and the odd-numbered
of the
FE400His an examplevaluewhichis compatiblewith mostconfigurations
the
highest
OFFF7FH,
iSDM R3.2monitor. The upperboundof the format rangeis
memorylocationthe BootstrapLoadercanusewhencombiningit with the iSDM
monitor. The upperboundalsoappliesto all previousversionsof the iSDM 86 or
Loadermemorymaps
iSDM 286monitors.Alwayscheckthe monitorandBootstrap
into the PROM devices.Also,be surethat the
beforeburningthe addresses
you usedo not collide.l'he numbers3, 2, and I matchIPPSpromptsfor
addresses
definingthe information.)
6.
bytes.Use the
Tell the softwareto progriìmonc EPROM with even-addressetl
the adilress
to use:
followingformulato determine
((addressof first stage)- (startaddressof EPROM ptk))12
=
a appears
whereyou mustentera carriage
return.Whenpressing
the
carriagereturn key,the text < CR > doesnot appeîr on the console.
Althoughall syntaxdiugramsshowuppercase
Ìerters(e.g.,VR), you canalsouse
lowercase
letters.
The manualrefersto the iRMX II Operating
Systemasthe opcrltingsyslem.
All numbersunlessotherwisestatedare assumedto be decimal.Hcxaclecimal
numbcrs
includethe "H" radixchlracter(for example,
OFFH).
Darker shadedtext appelrringovershadedtextwithin figuresor screendisplaysdoes
not actually
appearon the screen.The textwithinthe darkerbor supplies
information
that is helpfulin understancling
the figureor screendisplav.
lv
System Debugger
CONTENTS
CHAPTER1
iRMX@
II SYSTEMDEBUGGER
OVERVIEW
PAGE
CHAPTER2
SYSTEMDEBUGGER
COMMANDS
PAGE
SystemDebugger
CONTENTS
3
CHAPTER
PAGE
A
APPENDIX
COMMANDS
ISDM"MONITOR
PAGE
APPENDIX
B
D.MON386COMMANDS
PAGE
SAMPLE DEBUGSESSION
vl
SystemI)cbugger
CONTENTS
APPENDIX
B (continued)
PAGE
FIGURES
FIGURE
a 1
a a
1 À
z-)
SystemDebugger
vll
CONTENTS
PAGE
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
Ylll
. . . . . . ....... . 2 -l u
. . . . . . . . . . . ..... .-2. .- 2 0
. . . . . . . . , . . . . . :. -. :. z. . . . . .
........
.....2-24
of VO Output................
F-ormat
. ..2-28
.-.........
Formatof VR Output.................
...
.....2-32
..'.
..
Formatof VS Output................
...............2-37
.......
Formatof VT Output:Job Display.........,......
................2-39
Task........
Non-lnterrupt
V
Formatof f Output:
. . . . . ... . . . 2 - 3 9
F o r m ao
t f V T O u t p u t :I n t c r r u pTt a s k. . . . . . . . . . . . . . . .
--..........2-42
Formatof VT Output: Miìill)oxwith No Qucue..
-----..
................2-42
...
..
..
.......
with
Task
Queue
Formatof VT Output: Mailbox
.. .. .. .. . .......... ...2-43
Formatof VT Output: MailboxwithOhjcctQueue.......
. .. .. .. . . .. ....l-13
riith
\'lcssirte
Data
!f
irillxrr
Queue..
of
VT
Output:
Format
. . .. .. . .. . ..2-'11
...... .. ........
u'ithNo QucLre
Formatof VT Output:Senrrrlthttre
.. . . . .. . .. .. .. .. .. . 2-.l-5
* ith Tlsk Queuc...
Formatof VT Output:Sennphore
.......
. ....2-1-5
Formatof V'f Output: Regionu'ithNo Queue..
w i t hT a s kQ u e u e . . . . . . . . .-. -. .- . . . . . . . . ...... . . . . 2 ' 4 6
F o r m a ot f V T O u t p u t :R c q i o n
()trject..................
........ .2-17
nsion
Formatof VT Output: Exte
. . . .... . . . . . 2 - ' 1 6
F o r m a ot f V ' f O u t p u t :S c g m c n t . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.. .. . . .....2-11Ì
OtrjectOther Than8IOS.......
Formatof VT (lutpLrt:Compositc
. 2-'19
Formatof VT Output: fillOSLJscrOltjcctCompc1site.............................
a li l eC o n n c c t i o n . . . . . . . . . . . ........ .......2 - 1 9
F o r m a ot f V T O u t p u t :B I O SP h y s i c F
.. . .. .. ..,...2--51
Stream
File
C-Ìtnnection..................
Formatof VT Output: IìlOS
..... 2--5'1
...........................
NunretjfrileConnection
Formatof VT Output: 13lOS
F o r m ao
t f V T O u t p u t :I ì l O SR c n r o t [eì i l eC o n n e c t i t l n . . . . . . . . . . . . . . .......2. -. .5. 6. . . . . . .
r l r o l o c oPl o r t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 5 1
F o r m ao
t f V T O u t p u t :S i g n : P
'l'ransport
Port......................-.............2-5ft
Prtttctcol
Formatof VT Output: Diìtir
Plo r t. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 - 5 l J
F o r m ao
t f V T O u t p u t :D a t a l n t n s p o rPt r ( } t o c o
.................2-60
F o r m ao
t f V ' f O u t p u t :B u f l e rP o o l . . . . . . . . . . . . . . . . . . . .
................2-63
F o r m ao
t f V L JO u t p u.t. . . . . . . . . . . . . . .
(lnit)....................
................3'2
E x a m pefP L / M - 2 8 6A p p l i c l t i o n
................3-5
A p p l i c : r t r o( A
nl p h o n s e ) . . . . . . . . .
ExamplP
e L/M-286
(
C
l
a
s
t
o
n
)
.
.
.
.
.
.
.
.
.
.
.
.
.
......,,........3-7
P L . I M - 2 8A6p p l i c a t i o n
Example
....................... l - 12
MOVW in Gaston(ìrdc.....
F o r m ao
t f V J O u t p u.t. . . . . . . . . . . . . . .
i R M X @I l J o bT r e e . . . . . . . . . . . . .
System l)ebugger
CHAPTER1
IRMX@
II SYSTEMD E B U G G E R
OVERVIEW
1.1 INTRODUCING
THE|RMX@
II SYSTEM
DEBUGGER
Whenyou developapplication
svstems,
you needdebugging
capabilities
on your
development
system.In additionto the iSDM SystemDebugMonitoror the D-MoN3Err
Monitor,Intelprovides
rheiRMX II SystemDebugger
(SDB)îor debugging
your
iRMX I I-based
application
system.
NOTE
T h e r e m a i n d e ro f t h i s m a n u a lu s e st h c t e r m ' , m o n i t o r 't,o r e l e r t o b o t h t h e
i S D M S y s t e mD e b u g M o n i r o r a n d r h e D - M O N 3 l ì ( rM o n r r o r .
T h e S y s t e mD e b u g g e ri s a m e m o r y - r e s i d e netx t e n s i o no f t h e m o n i t o r ; t h e r e f o r c ,v o u m u s t
have the monitor if you have thc SystentDebuggerconfi{ured into your system. The
monitor provides code disassembly,executionbreakpoinrs,memory cJisplay,
and pro_qran.l
d o w n l o a dc a p a h i Ì i t i e sT
. h e S y s t e n D e b u q q e re x t e n d st h e m o n i t o r ' sd i s a s s e m b lfyu n i t i o n s
b y i n t e r p r e t i n gi R M X I I c a l l s ,d a t a s t r u c t u r c sa, n d s t a c k s .
M o n i t o r a n d S y s t e mD e b u g g e rc o n r m a n d sa r e e n t c r e c i n r c s p o n s et o t h e i s D M M o n i t o r ' s
protected-modp
e r o m p r ( . . ) o r r h e D - M O N l 8 ( r M o n i r o r ' sp r o m p t ( >
). Whenyou invoke
t h e m . n i t o r , b o t h t h e o p e r a t i n gs y s t c ma n d y . u r a p p l i c a t i . ns v s t e ma r e l i . z e n . A s v o u u s e
m o n l t o r c o m m a n d st o s e t l t r e a k p o i n t sw h i l e t h e a p p l i c a t i o nc o d e i s e x e c u t e dy, o u c a n
inspect systemobjects,changesystcmcall parametersand regisrers,and test chrrnees.
R e f e r t o A p p e n d i xA f o r m o r e i n f o r m a t i o no n i S D M M . n i t . r c o m m a n d sa n d A p p c n d i x B
tor D-MON3tì6Monitor cornmanos.
SystemDebugger
l-I
iRI\TX@II SYSTEI\Í I)EBTJGGEROVERVIEW
DEBUGGER
THESYSTEM
1.2 SUPPORTING
T o u s e t h e S y s t e mD e b u g g e ry, o u m u s t h a v eo n e o f t h e f o l l o w i n gh a r d w a r ec o n f i g u r a t i o n s
w i t h a l l t h e r e q u i r e ds u p p o r th a r d w a r e :
o
An Intel MicrocomPuter ctlnnectedto an 8021ì6-or 386-basedboard
.
A terminal connecteddirectly to lrn 802iì(r-or 386-bltscdlrortrtl
.
or 386-basedlxlard
An Intellec@Development Svstenìconnectedto an E1)21ì(r-
I n a d c l i t i o nt o t h e a b o v eh a r d w a r e v, o u m u s t h a v eb o t h o f t h e f o l l o w i n g :
o
T h e E , P R O Mp o r t i o n o 1 t h e i S D M S y s t e mD e b u g M o n i t o r o r t h e D - M O N 3 f ì 6 M o n i t o r
.
A t l e a s tt h e m i n i m a l c o n f i s u r a t i o no f t h e i R M X I I N u c l e u s
DEBUGGER
THESYSTEM
1.3 CONFIGURING
t h r o u g ht h e
Y o u c a n n o tu s e t h e S y s t e mD e b u q q e ru n t i l y t t t ti n c l u t l ei t i n v o u r s 1 ' s t e m
'fo
t
h
e
S
y
s
t
e
m
D
e
b
u
g
g
e r b, e g i nb y
i
n
c
l
u
d
e
I n t e r a c t i v eC o n f i g u r a t i o nU t i l i t i , ( I C L J ) .
i n v o k i n gt h e I C U . N e x t ,p r o v i d et h e f o l l o w i n gi n l b r m a t i o nt h e I ( ì t J r e q u i r e st o c o n f i g u r e
the SystemDebuggcr:
1 . I n t h e I C U ' s " S u b - S y s t e m s c" r e c n ,r e s p o n d" y e s "t o t h e S D B p r o m p t .
2 . I n t h e I C U ' s " S y s t e mD e b u q q e r s" c r e c n ,s e t t h e i n t e r r u p tl c v e lv o u w a n t t o u s e t o
i n v o k et h e m o n i t o r m a n u a l l y( b v p r e s s i n qa h a r d w a r ei n t e r r u p tb u t t o n ) .
T o u s e t h e N o n - M a s k a b l eI n t e r r u p t( N M I ) f o r d e b u g - q i ntgl e v i c ed r i v e r s ,s e et h e
Ertended |RMX II Hardn'are and Softv'are lrtstalloliott CLtitle.
F o r d e t a i l e di n f o r m a t i o no n c o n f i g u r i n tt h c S y s t e mD e h u g g c r c, o n s u l tt h e E x t e n f u d
iRlvIX II Interactive Confrguration l.ltilif Rtftrotcc ltlartuttl.
DEBUGGER
THESYSTEM
1.4 INVOKING
Y o u m u s t e n t e r t h e m o n i t o r t o u s e t h e S v s t e mD e b u [ q e r . Y o u c a n i n v o k et h e m o n i t o r i n
tnree ways:
l.
U s e a h a r d w a r es w i t c hp h y s i c a l l yc o n n e c t e dt o t h e i n t e r r u p tl c v e ly o u s p e c i f i e dd u r i n g
s v s t e m s, a v e st h e s y s t e m ' s
c o n f i g u r a t i o n .A c t i v a t i n gt h i s s u ' i t c hh a l t st h e r r p p l i c a t i o n
t
o
t
h
c
n
r
o
n
i
t
o
r
.
c o n t e n t s a, n t l p a s s e sc o n t r o l
2 . U s e t h e H u m a n l n t c r l ì r c cD E t s U G c o m m r t n d .D E B U C l o a t l sy ' o u rs p e c i f i e d
a p p l i c a t i o np r o g r i ì mi n t o m a i n m e m o r va n d t r i ì n s l c r sc o l ì t r o lt o t h e m o n i t o r .
l-2
System I)cbugger
iRMX@II SYSTE]\Í
DEBUGGERO!'ERVIElV
3. Usethe Bootstrap
LoaderDEtsLJG
switch.Whenyou specifyrhisswitch,the monitor
comesup afterthe systemis loucled
but befìtrethe systemstartsrunning.Thc CS:lP
pointsto the firstinstruction
of the application
system.At thispointthe systemhusnot
beeninitialized;
therefctre,
youcanrun onlymonitrtrcctmmands.
Usingthe MAP2IJ(I
output,youcanidentilywherevouwantto insertbreakpoints.
(For moreinfitlnlttion
on BIND, MAP, and OVL, sec theAI,X 286UtilitiesU.ser's
Guitlefttr |RMX l/.$urlnr.r).
Usethe breakaddress
parameter
in the monitor'sCO (G) commandto setbreakpoints
in the application
systcmcocle.Whenyouenter"G ", thc systemstartsanLiis
initialized.The monitoris invokedwhenthe CS:lPreaches
the breakpoints.
Iìor more
informationon bootingwith DE,BUG,consultrheExtended
|RMX II BootstntpLoudcr
Reference
Manual.
Whenyou invokethe monitor,the application
systemstopsrunningitndall systerlactivir\
freezes.The appropriate
promptitppears
(the".."for the iSDM Monitoror thc " > " for the
D-MON3tl6Monitor),anciyoucunbcqinenteringSystent
Debuggcr
and moniror
commands
to exirmine
system
objccts.
1.5 USINGTHESYSTEM
DEBUGGER
T h e S y s t e mD e b u g g e ru s c sn t o n i t o rJ l r o c e d u r ctso p a r s et h e c o m m a n dl i n o a n d t o o u t l t u t
l o t h e c o n s o l e t; h e r e f o r e y, o u r u n b o t h S y s t e mD e b u g g c ru n t l m o n i t o r c o m m : r n c lfsì - o r nt h e
monitor. The syntaxfor SystemDebugter commundsis a "V" or "v" followed bv another
l e t t e r ,a n o p t i o n a ls p a c e u
, n d u n o p t i o n i r lp a n ì m e t e r .
T h e t w e l v eS y s t e mD e b u e e e rc o m m i r n d s( d e s c r i b e di n C h a p t c r2 ) f a l l i n t o t h r e e c i r t e q o r i c s :
.
E i g h t c o m m a n d se x t e n dt h c n r o n i t o rm c m o r y d i s p l a yf u n c t i o n sb y d i s p l a y i n gi l ì M X l l
d a t a s t r u c t u r e sa n d o t ! c c t s .
.
T h r e e c o m m a n d se x t c n dt h c n t o n i t r t rd i s a s s c m b lfyu n c t i o n sb v r c c o g n i z i n ga n d
d i s p l a y i n gi R M X I I c a l s .
.
A h e l p c o m m a n dp r o v i d e sa s h o r td e s c r i p t i o no f a l l t h e c o n ì r n a n c l s .
A l l c o m m a n d sc i t h e r d i s p l a yi n l ì r r m a t i o na s h e x a d e c i m anl u m b e r so r t r y t o i n t c r l ) r e tt l ì e
i n f o r m a t i o n . I f t h e S y s t e mD e b u u c r c l ì n n o ti n t e r p r e tt h e i n f o r m a t i o n ,i t d ì s p l a y st h e
actual heradecimalvalue, followed by tu,o question marks.
i R M X I I p r o v i d e st w o f e a t u r e st h a t en a b l ev o u t o l e a v et h e m o n i t o r w i t h o u t r i j s c t t i n gy o u r
s y s t e m :w a r m - s t a r ta n d C l - l - r e s t a r t .T h e \ ì a r m - s t a r tl e a t u r er e i n i t i a l ì z e tsh e s y s t e n a
t nd
j
r e t u r n sc o n t r o lt o t h e H u m a n I n t c r f a c e .T h e C l - l - r e s t a r tf e a t u r ed e l e t e st h e c u r r e n t o t r
t h e n r e t u r n sc o n t r o lt o t h e f l o m m l r n t l[ - i n e I n t e r p r e t e r . R e f e r t o C h a p t e r2 f o r n t o r e
information on these tèatures.
SystemDebugger
l --l
iRMX@ II SYSTENI I)EBUGGER OVERVIEIV
TOYOURAPPLICATION
1.6 RETURNING
your applicationsystemwith the SystemDebugger,or if
Whenyou havefinisheddebugging
code,usethe monitor'sGO
you madeto the apPlication
youwantto testthechanges
of the application.
command(G) to resumeexecution
l-4
Systeml)ebugger
CHAPTER2
SYSTEMDEBUGGER
COMMANDS
2.1 INTRODUCTION
T h i s c h a p t e rc o n t a i n sd e t a i l e dd e s c r ì p t i o nos f t h e i R M X I I S y s t e mD e b u g g e rc o n t n l r n d s .
C o m m a n d sa p p e a ri n a l p h a b e t i c aol r c l c r ,w i t h t h e î i r s t r r c u r r e n c eo f e u c hc o m m a n d
a p p e a r i n gi n
a t t h e t o p o I t h e p a g e . A d i r e c t o r yo f t h e c o m m a n d s d, i v i c l e tiln t o
l u n c t i o n a lg r o u p s ,p r e c e d e st h e c o m m r n d d e s c r i p t i o n s .
T h i s e h a p t e ru s e st h e [ o l l o u i n - [\ . ( , n \ ( . n t i ( ì n \ :
.
" C S : l P "i s t h e C o d e S e g m c n t : l n s t r u icot n P o i n t e r - - T h cp o i n t c r t o t h e i n s t r u c t i o nt h l t
w o u l d b e e x e c u t e dn e x t i î t h c r r p p l i c a t i o sn v s t e n\ìr ' c r er u n n i n g . I f v o u s p e c i f v i r nI p
v a l u e( o n e f b u r - d i g i th e x i r c i e c i r r rnrul m b e r )b u t n o t i ì C S v l r l u e ,t h e S y s t e n ìD e b u q , q c r
u s e st h e c u r r e n tC S a s t h c d e l ì t u l tb a s e .
o
" S S : S Pi"s t h e S t a c kS e g m e n t : s l r r cPko i n t e r - - ' [ ' hpeo i n t e r t o t h e c u r r e n ts t a c kl o c a t i o n .
.
E n t e r i n gz e r o ( 0 ) a s a v a l u c l i r r a n o p t i o n a lp i r r i t n ì e t c irs t h e s a n r ea s o m i t t i n gt h e
p a r a m e t e r ;t h e d e f ì r u l tv a Ì u co 1t h c p i r r i r m e t e irs u s c d .
.
A l l t e r m i n a le x a m p l e sa s s u n l et h r ì tt h e i S D M S y s t e mD e b u q M o n i t o r i s b e i n qu s e c l .
T h u s ,e x a m p l ei n p u t l i n es s h o u ,r h e i S D l v lm o n i t o r p r o m p r ( . . ) .
2.2 CHECKINGVALIDITYOF TOKENS
M a n v S y s t e mD e b u g - { ecr o m m u n d su s c i R N I X I I t o k c n sî s p l r a m e t e r so r d i s p l a yt o k e n si r s
p a r t o f t h e c o m m a n do u t p u t . T h e i l L M X I I O p e r a t i n gS v s t e n m
t i r i n t a i n st o k en s i n r l o u b l v
Ì i n k e d l i s t s . W h e n y o u e n t e r u t o k e n i t s u p l r u l m e t e r t, h e S v s t e mD c b u g g e rc h c c k st h e
v a l i d i t yo f t h e t o k e n b y l o o k i n ga t t h e t ì r r u a r c ri n d b a c k w a r dl i n k s o f t h e t o k e n .
I f o n e o f t h e l i n k s i s b a d ,t h c S v s t e n rl ) e b u g g c rg e n e n ì t e sÍ ì n e r r o r m e s s a g ea l o n gw i t h t h e
s t a n d a r dc o m m a n do u t p u t . T h e t o k e n v o u e n t e r a s a p a r a n l e t c ra l w ; r y sa p p c a r sl t s t h e
c e n t e rv a l u e i n e a c hl i n e o f t h e t o k c n t l i s p l a l ' .T h e d i s p l a y sf o r f ì r r u , a r c al -n d b l c k u a l d - l i n k
erroÍs are as lbllows:
Forwardlink ERROR: .1I I l-->.lF.E5
. 1 l l I < - - . + t r l J ->54- -1 5 5
'IFFFF<--,ll-s5
tsackward
lìnk E,RROR:4lll-->110F'l
> 4 l5-5
4 I I I < --4E85--
4El.ì-5<--.1155
SystemDebugger
SystemDebuggerCommands
Arrows to the left indicatebackwardlinks; arrowsto the right indicateforward links. A
questionmark beforeor aftera valuesignifiesa forwardor backwardlink error,
respectively.
the tokeninvalid.A tokenmay also
Ifboth linksare bad,the SystemDebuggerconsiders
be invalid if it belongsto an objectin the deletionprocess,if an incorrecttoken is entered
as a parameterin a systemcall,or if a deletedor unusedtokenis enteredasa parameter.
When the token is invalid,the SystemDebuggerdisplaysthe followingmessage:
***
lNvALlD ToKEN ***
A link error indicatesthat iRMX II datastructureshavebeencorrupted.The most
commonreasonfor this problem is a task might haveaccidentallywritten over part of the
systemdatastructures.However,the iRMX II protectionmodefeatureprotectsagainst
Data structurecorruptioncan alsooccurif
suchoverwritingundernormalcircumstances.
you are usingthe Non-Maskable
Interrupt(NMI). The Nucleusmay havebeen
interruptedwhile it wassettingup the links. (The NMI is a hardwareinterrupt. For more
Manual or the 8038óHardware
information on the NMI, seethe 80286HardwareReference
Reference
Manual.)
2.3 PICTORIAL
REPRESENTATION
OF SYNTAX
consists
deviceto illustratecommandsyntax.The schematic
This chapterusesa schematic
ofwhat lookslike an aerialviewof a modelraiìroad,with syntacticelements(appearingin
circles)scatteredalongthe track. To constructa valid command,imaginethat a train
entersthe systemat the far left, travelsfrom left to right only (backingup is not allowed),
choosesone branchat eachfork, and finallydepartsat the far right. The command
generatedconsistsof the syntacticelementsit encounters
on its journey. The following
schematic
showstwo valid seouences:
AC and BC.
2-2
SystemDebugger
SystemDebuggerCommands
Theseschematics
do not showspacesaselements,
but you may includeone or more spaces
betweenthe commandand parameter.For example,eventhoughthe syntaxfor VR is as
follows:
sagmenl
token
The followingcommandis valicl:
The spacebetween"VR" and "xxxx"is optional.
2.4 LEAVING
THEMONITOR
Two features
enableyou to leavethe monitorwithoutresetting
yoursystem:wrrm-strrrt
andCLI-restart.
The warm-startfeatureis the processof startinga systcmwithoutreloadingit from
secondary
storage.Warm-startrcinitializesthe system,that is,it beginsexecutingthe
applicationsystemat the samepoint whcrethe BootstrapLoaderpasses
controlto the
system.
To warm-start
the system
from the iSDM monitor,enterthe followingcommand:
To warm-startthe systemfrom the D-MON3lì6monitor,enterthe followingcommancl:
If no systemcodeor datasegments
werecorrupted,the systemreiniîializes.If segment
corruptionhasoccurred,the applicationsystemwill not run; you mustrebootthe system.
If yoursystemcontains
a CommandLine Interpreter,
andrunningyourapplication
programcausesan exceptionthat brcaksto tht: monitor(for example,a General
Protectionexception),
enterthe followingcommlìndto CLI-restartthe systemfrom the
iSDM monitor:
SystemDebugger
2-3
SysternDebuggerCommands
Enter the following command to CLI-restart the systemfrom the D-MON3lì6 monittlr:
These commandscausesthe systemto attempt to delete the job tree of the running task. If
the running task is part of the application'sjob (not a subsystemtask running on behalf of
thejob) control returns to the Command Line Interpreter. Otherwise,you must reboot the
system.
2.5 COMMAND
DIRECTORY
Page
Command
DISPI-AYINGiRMX II DATA STRUCTURES
VB--Display
DUIB lnformation.
. ..
VD--Displaya Job's Object Directorv.
. 2- 1 2
VF--Display
Nunber of
.2-14
VJ - -Display
Job Hierarchy
. 2 -r 8
VK--Display
Ready and Sleeping Tasks..
.2-22
VO--Display
Objects
.2-24
V R -- D i s p l a y
1/O Request/Result
VT- -Display
iRMX II
Free Slots
in
a Job.
Segment
.2-21
.2-36
Object.
RECOGNIZINGAND DISPLAYINGiRMX II SYSTEMCALTS
VC--Display
Systern Call
..2-9
Information.
V S - - D i s p l a yS t a c k a n d S y s t e mC a l I I n f o r m a t i o n . . . . . . .
W- -Display
System Calls
in
a Task's
Stack. .
.2-62
OTHER COMMANDS
V H -- D i s p l a y
2-4
Help lnformation.
. ..
.2-16
SystemDebugger
The VB commanddisplaysthe DUIB informationfor the specifiedphysicaldevice.For
additional
information
aboutDevice-Unit
Information
Blocks(DUlBs),referto Chapter
of the ExtendediRMX II DeviceDivers User'sGuùIe.
PARAMETER
Physicaldevice
The nameof the physicaldevicefor whichyou want to viewthe
DUIB intbrmation
(e.g.,WMF0). Thisdevicemustbe partot
the svstcmconfisuration.
DESCRIPTION
The VB command displaysthe DLJIB information fbr the specifiedphysicaldevice. Figure
2 - 1 i l l u s t r a t e st h e o u t n u t f r o m t h e V B c o m m a n d .
Device name:
Func ts :
Dev$gran
D e v $s i z e
Uni t
Device$info$p
UpdateStimeout
Priority
Init$io
Queue$io
(phys ical
d e v i c e name>
xx
DUIB addre s s
XXXX ; XXXX
XXXX
MewAhlffar<
xx
XXXXXXXX
Device
Dev$unit
XX
XXXX : XXXX
XXXX
XXXX : XXXX
XXXX
N"m(h"f€arc
XXXX
XX
Fixe d$upda te
Fini sh$ io
C a n ce 1 $ i o
xx
xxxx
xxxx
Flags:
D e n si t y
Size
xx
File driver:
Physical
xxxx
: xxxx
: xxxx
XXXXXX
X
XXXX
Valid
Si d e s
Format
Named
Stream
XXXX : XXXX
XXXX : XXXX
xxxxxx
xxxxxxxx
xxxx
XXXXX
Figure2-1. Fr)rmaltrf VB Output.
SystemDebugger
7-1
VB--DISPLAYDUIB INFORMATION
The fields displayedin Figure 2- I are as lbllows:
2-6
Functs
A BYTE used to specifythe [/O function validity for this
devrce-unrt.
DUIB address
T h e s t a r t i n ga d d r e s si n m e m o r yo f t h e s p e c i f i e dD U I B .
Dev$gran
A wORD that specifiesthe devicegranularity, in bytes. This
parameter appliesto random accessdevices,and to some
common devices,such as tape drives. It specifiestht: minimum
numtrer of bytesof information that the device reads or writes in
o n c O P c iIl l i (ì n .
Max$buffers
The muxinrum number of buffers that the EIOS can allocatefìrr
a c o n n e c t i o nt o t h i s d e v i c e - u n iw
t h e n t h e c o n n e c t i o ni s o p e n e d
by a call to S$OPE,N.
Dev$size
The number of bytesof information that the device-unitcan
store.
Device
The number of the devicewith which this device-unitis
associated.
Unit
T h e n u m b e ro f t h i s d e v i c e - u n i tw, h i c h d i s t i n g u i s h etsh i s u n i t
f r o m o t h e r u n i t so f t h e d e v i c e ,
Dev$unit
T h e d e v i c e - u n int u m b e r ,w h i c h d i s t i n g u i s h etsh i s c l e v i c e - u n i t
f r o m o t h e r d e v i c e - u n i tisn t h e h a r d w a r es y s t e m .
Device$info$p
A P O I N T E R t o a s t r u c t u r et h î t c o n t a i n sa d d i t i o n a li n f o r m a t i o n
a h o u tt h e d e v i c e .T h e c o m m o n ,r a n d o m ,a n d t e r m i n a ld e v i c c
drivers recluirea Device lnformation Table in a specifictormat,
for each device.
Unit$info$p
A P O I N T E . Rt o a s t r u c t u r et h a t c o n t a i n sa d t l i t ì o n a il n f o r m a t i o n
about the unit. R:rnrlomaccess,common rlevice(such as tape
t J r i v e s )a, n c it e r m i n a lc l e v i c ed r i v e r sr e r l u i r et h i s U n i t
Inlbrmation Table in a specificlbrmat.
Update$timeout
T h e n u m t r e ro f s y s t e mt i m e u n i t st h a t t h e I / O S y s t e mm u s t w r i t
before writing l partial sector,after processinga wriîe request
for a disk device.
Num$buffers
The number of buffers of device-granula
rity size that the I/O
SystenìalÌocates.
Priority
The priority of the I/O Systemservicetask for the device.
Fixed$update
Indicateswhether the fixed update option was selectedfor this
device-unitwhen the application systemwas configured.
Init$io
T h e a d d r e s so f t h e I n i t i a l i z eI / O p r o c e d u r ea s s o c i a t c w
d ith this
unrt
Systen I)ebugger
vB--DISPL\Y DUIBIn*FORNIATI
ON
Finish$io
The addressof the FinishI/O procedureassociated
with this
unit.
Queue$io
The addressof the QueueI/O procedureassociatetl
with this
unit.
Cancel$io
The adciress
of the CancelI/O procedureassociated
with this
unlt.
Flags
Specifiesthe characteristics
of diskettedevices.
Valid
whetherthe Flagsfieldis "Valid"or "NotValid"for
Indicates
t his tleriee.
Density
The densityof the device.If the flagsfor this DUIB are invalicl,
this field is marked"N/A".
Sides
The numberof mediasidesthatthe devicecanwriteto. Ifthe
flagslor thìsDUIB areinvalid,thisfieldis marked"N/A".
'l'he
physicalsizeof the clevice(-5l/4-inch or S-inch).If the
flagsfor this DUIB are invalid,this lìeld is marked"N/A",
Size
Format
Indicates
whethertrack0 of a diskis to be formattedasa
STANDARD diskette( 12ttbytes/sector)
or asa UNTFORM
diskette(all sectorsformattedasspecified).This parameter
appliesonly to flexiblediskettes.Hard disksare alwrys
speciiied
asUNIFORM. lf the flagsfor thisDUIB are invalid,
thisfieldis marked"N/A".
Filedriver:
A WORD that indicates
the BIOSfile driverto whichthis
connection
is attached.
Named
Indicateswhetherthis deviceis configuredto usethe Namedfile
driver.
Physical
lndicateswhetherthis deviceis configuredto usethe Physical
file driver.
Stream
Indicates
whetherthisdeviceis configured
to usethe Streamfile
driver.
SystemDebugger
)-1
VB--DISPÍAYDUIB INFORMATION
ERRORMESSAGES
SyntaxError
An error wasmadewhenenteringthe command.The correct
syntaxis VB . Any other syntaxproducesthis
messaSe.
VB not supported
VB couldn'tfind the bytebucketDUIB entry in the BIOS code
segment.If no DUIB entryfor the bytebucketexists,VB ìs
unsupported.
If the BIOS hasnot beenconfiguredinto the system,or if the
BIOS codesegmenthasexecute-only
attributes,this error
message
is returned.
DUIB not found
2-8
VB returnsthis error message
undertheseconditions:
1.
The DUIB is not configuredinto the system.
2.
The DUIB entryfor the specifieddeviceis locatedbetbre
the b)'tebucketDUIB entry.
3.
The usermadean error while enteringthe physicaldevice
name.
SystemI)ebugger
The VC commandchecksto seeif a CALL instructionis an iRMX II systemcall. The VC
commandidentifiessystemcallsfor all iRMX II OperatingSystemlayers.
PARAMETER
polnrer
The addressof the CALL instructionto be checked.This
parametercantreanyvalid monitoraddress(two four-digit
hexadecimal
numbersseparated
hy a colon).
If you are usingthe iSDM monitorand you do not supplya
pointer(or you specifo0), this parameterdefaultsto the current
CS:lP. If you specifyan IP value(onefour-digithexadecimal
number)but not a CSvalue,the SystemDebuggerusesthe
currentCS asthe defaultbase.
lf you are usingthe D-MON38ómonitor andyou specilythe
addresswith an offsetvaluewith no basevalue,the parameter
defaults
to thecurrentCS:lPvalue.
DESCRIPTION
lf the CALL instruction
is an iRMX II system
call,the VC commanddisplays
information
aboutthe CALL instructionasshownin Fieure2-2.
gate /INNNN
(subsysten) system call
F i g u r e2 - 2 . F o r m a f o f V C O u l p u t
The fieldsin Figure2-2are aslbllows:
gate#NNNN
SystemDebugger
with the iRMX II systemcall at the
The gatenumberassociated
addressspecifiedin the command.
2-9
VC--DISPI,AY SYSTE]\Í CALL INFORMATION
(subsystem)
to the
The iRMX ll OperatingSystemlayercorresponding
systemcall.
systemcall
The nameof the iRMX II systemcall.
NOTE
The SystemDebugger usesthe gate number to determine whether the CALL
instruction representsa systemcall. Sincethe SystemDebugger does not
disassemblethe code, but rather examinesa byte value at a particular offset
from the CALL instruction,in rare casesa non-systemcall can be displayedas
an iRMX II systemcall. However, the SystemDebuggerdoes recognizeand
d i s p l a ya l l i R M X I I s y s t e mc a l l s .
ERROR MESSAGES
SyntaxError
An erftrrwasmadein entering the command.
Not a systemCALL
The parameterspecifiedpointsto a CALL instructior.
that is not an iRMX II system
call.
Not a CALL instruction
The CS:lPspecifieddoesnot point to any kìnd of call
instruction.
EXAMPLES
you disassembled
Suppose
the following
codeusingthe iSDM monitor'sDisplayMemory
(DX) command:
1 8 A 0 : 0 0 6 D5 0
1 8 A 0 : 0 0 6 8E S A D I E
1 8 A 0 : 0 0 7 1E 8 D D 0 3
1 8 A 0 : 0 0 7 48 8 0 0 0 0
1 8 A 0 : 0 0 7 75 0
18A0:0078 8D060600
1 8 A 0 : 0 0 7 C1 E
1 8 A 0 : 0 0 7 D5 0
1 8 A 0 : 0 0 7 EE 8 4 1 l E
1 8 A 0 : 0 0 8 1A 3 0 0 0 0
PUSH
CALL
CALL
MOV
PUSH
LEA
PUSH
PUSH
CALL
Mov
AX
A : lFlE
A : 0451
AX,O
A-\
A - \ , l n o R DP R T 0 0 6
DS
Ax
A - LEC2
w o R DP T R 0 0 0 0 H , A x
;$+7856
1$+992
;$+7748
If you usethe VC commandon theCALL instruction
at address1tìA0:0t)(rE
by entering
the followingcommand:
2-r0
SystenrI)ebugger
VC..DISPI.AYSYSTEMCALL INFORMATION
The SystemDebuggerdisplaysthe followinginlbrmation:
gate 110468
(Nucleus) set exception handlèr
Gatenumber0468corresponds
to an RQ$SET$EXCEPTION$HANDLER
systemcall,
whichis a Nucleuscall.
Now,supposeyou want to seeif the CALL instructionat 18A0:0071
is a systemcall. Enter
the followinscommand:
The SystemDebuggerresponds
with the following:
Not a systen
CALL
Finally, ifyou use the VC command on the instruction at l840:0074, the SystemDebugger
respondswith the following:
Not a CALL instruction
SystemDebugger
2-tl
The VD commanddisplaysa job's objectdirectory.
PARAMETER
The tokenfor thejob havingthe objectdìrectoryyou want
displayed.To obtainthejob token,usethe VJ command.
job token
DESCRIPTION
If you specifieda validjob token,the SystemDebuggerdisplaysthejob's objectdirectory,
asshownin Fisure2-3.
Directory
narnel
narne2
s\ze:
xxxx
Entries used:
tokenl
: ^ ^ l - LdJ^r
. . - { * i - !drLIiÈt
token2...tokeni
.
iok.r,i
namek
tokenk
namen
cokunat
Figure2-3. Formatof YD Output
Figure2-3showsthesefields:
2-12
Directorysize
The maximumnumberof entriesthisjob canhavein its object
directory.
Entries used
The numberof entriespresentlyin the directory.
SystemDebugger
VD..DISPLAY
A JOB'SOBJECTDIRECTORY
namel...namen
The namesunderwhichobjectsare catalogued.Thesenames
wereassìgned
at the time the objectswerecatalogued
wìth
RQ$CATALOG$OBJECI.
tokenl...tokenn
Tokensfor the catalogued
objects.
taskswaiting
Signifiesthat one or more taskshaveperformedan
RQ$LOOKUP$OBJECT
on an objectnot catalogued.The
tokensfollowingthis field identifythe tasksstillwaitingfor rhe
objectto be catalogued.
For more information on objectdirectories,seethe Extendtd\RMX I I NuclettslLser's
Guide.
ERRORMESSAGES
SyntaxError
No parameterwasspecifiedfor the command,or an
error wasmadein enteringthe command.
TOKEN is not a Joh
... IIWALID TOKFN ***
A valid tokenwasenteredthat is not ajob token.
The valueenteredfor the tokenis not a valid token(as
definedin "CheckingValidityof Tokens"earlierin this
cnapter).
EXAMPLE
Supposeyou want to look at the objectdirectoryofjob "2280".Enter the following
command:
The SystemDebuggerresponds
with
DirecÈory slze:
000A
S
2228
R?IOUSER
RQGLoBAL
2?OO
2280
Entries used:
0003
The symbols'$", 'R?IOUSER",and "RQGLOBAL" are the namesof objectsrhc sysrem
creates;their respective
tokensare 2228,2200,
and 2280.Thereare no waitingtasksor
invalidentries.
SystemDebugger
2-13
The VF commanddisplaysthe number of free Global DescriptorTable slotsavailableto
the user.
PARAMETERS
The VF commandhasno parameters.
DESCRIFIION
The VF commanddisplaysthe number of free Global DescriptorTable (GDT) slots
availableto the user,in the format shownin Figure2-4.
Number of free
slots
: xxxxxxxx
Figure 2-4. Format oflT
2-14
Output.
SystemDebugger
!T'..DISPI,AY NUMBER OF FREE SLOTS
ERRORMESSAGES
Syntax
Error
SystemDebugger
An errorwasmadein entering
thecommand.
2-15
the twelveSystemDebuggercommrrnds.
The VH commanddisplaysand brieflydescribes
PARAMETERS
This commandhasno parameters.
DESCRIPTION
alongwith their parameters
The VH commandlistsall of the SystemDebuggercommands,
and descriptions.
ERRORMESSAGE
SyntaxError
An error wasmadein enteringthe command.
EXAMPLE
If you enterthe followingcommand:
2-16
SystemDebugger
VH--DISPLAY
HEI.PINFORMAI]ON
The SystemDebuggerrespondsasshownin Figure2-5.
Extended iRllx II SYSTEMDEBUGGER,
Vx.y
Copyright
[]
[]
[(count)]
Displays DùlB for physical device.
Display sysrern call.
Display job,s objècr direcrÒry.
Dispì-ays number of free slots available ro user.
Display help inforrnation.
Display job hierarchy from specified 1evel.
Display ready and sleeping rasks.
Display list of objects for specified job.
Display I/0 RequestlResulr Segmènr.
Display stack and syscem caLl informaLion.
Display iRMX tl object.
Unwind task stack, displaying system calls.
Figure2-5. I'ormatof VH Output
Anglebracketssurroundrequiredvariablefields.
Squareandan_ule
brackets
surroundoptionalfields.
NOTE
The systemusesdefaultvaluesif vou speci|rzero (0) for anyof the optional
parametersin Figure2-5. LJsing
zerofor requireclparameterscausesthe
systemto displaythe followingmessrìge:
SystemDebugger
2-t7
from the levelyou
The VJ commanddisplaysthe portionof thejob hierarchythat descends
sDecifu.
PARAMETER
job token
The tokenof thejob for whichyou want to displaydescendant
jobs.
If you do not specifya job token,or you specifuzero (0), VJ
jobs.
displaysthe root job and its descendant
the
ofjob descendants,
If thejob hasmorethan44 generations
the displayat the 44th
SystemDebuggerdisconîinues
and promptsfor
message,
level,
displays
an
error
descendant
anothercommand.
DESCRIPTION
job and the tokensof all its
The VJ commanddisplaysthe tokenof the specified
jobs.
(and
at the same
their descendants)
It alsodisplaysthe tokensofjobs
descendant
jobs are indentedthreespacesto
levelas the specifiedjob. The tokenslbr descendant
job's
showsthe format of thejob hierarchy
position
hierarchy.
Figure
2-6
in the
showtheir
disolav.
iRMx@ Il
Job Tre e
tokenl
token2
token3
token4
tokent
t o k e n ,o
Rooc Job
HurnanI ntè rface
Command
Line Inte rpre ter
A p pI l c a t í o n
EIOS
BIOS
Figure 2-6. Formal of VJ Oulput
2-l8
Sysfem Debugger
VJ-.DISPI-AYJOB IIIERARCTIY
The fields in Figure 2-6 are
tokenl
The tokenyou specifiedasjob token(recallthat the rootjob
token is the default).
token2...token6
jobs of token
The tokensfor the descendant
1.
In Figure2-6,the HumanInterface,EIOS,and BIOS Jobsare indentedthreespacesto
signifythat they are childrenof the RootJob. Similarly,the CommandLine Interpreter
Job is the child of the HumanInterfaceJob,and the ApplicationJob is the child of the
CommandLine InterpreterJob.
ERRORMESSAGES
SyntaxError
An error wasmadein enteringthe command.
TOKEN is not a Job
A validtokenwasenteredthat is not ajob token.
TOKEN ***
SDBjob nestlimit
exceeded
The valueenteredfor the tokenis not a valid token(as
definedin "CheckingValidityof Tokens"earlierin this
chapter).
job (or the defaultjob) has
The specified
more than44 generations
ofjob descendants.
EXAMPLES
Ifyou want to examinethe hierarchyof the root job, enterthe followingcommand:
with the followingjob tree:
Supposethe SystemDebuggerresponds
lRMx@ II
Job Tree
0258
0F38
1670
2460
0888
0E00
Figure2-7showsthisjoh tree:
SystemDebugger
2-19
VJ--DISPL{YJOB HIERARCHY
Root Job
( 0 2 5 8)
l l u m an I n t e r f a c e
( 0 F 3 8)
/
EIOS
( 0 8 8 8)
/
/
Co r n n a n d L i n e I n t e r p r e t e r
(1610)
AppI icat ion
(2460)
Figure2-7. iRMXo ll Job Tree
jobs of "0E88",enterthe followingcommand:
If you want to displaythe descendant
2-20
SystemDebugger
VJ..DISPT.4,YJOB HIERARCTIY
The SystemDebuggerdisplaysthe following:
ÍR-ì{XO II
JOb T r e e
0E88
0E00
0F38
1670
2460
Note that the tokensfor alljobs at the samelevelasthe specifiedtoken (0E00and 0F38),
and their descendants
(1ó70antJ2460),are alsodisplayed.
SystemDebugger
2-21
The VK commanddisplaysthe tokensfor tasksin the readyand sleepingstates.
PARAMETERS
This commandhasno parametersDESCRIPTION
The VK commanddisplaysthe tokensfor tasksthat are readyand asleep,in the format
shownin Figure 2-8.
Ready casks:
xxxx
xxxx
Sleeping tasks:
xxxx
xxxx
Figure 2-8. Format ofVK Output
The fields in Figure 2-8 showthe following:
Readytasks
The tokensfor all tasksin the readystate. The first token in this
lìst representsthe running task
Sleepingtasks
The tokensfor all tasksin the sleepingstate.
ERROR MESSAGES
SyntaxError
An error wasmadein enteringthe command.
Readytasks:Can't locate
The systemis corrupted.
Sleepingtasks: Can'tlocate
The mostcommonreasonfor this type of error ts
not initializing the Nucleus. To recoverfrom this
error,reinitializethe system.
2-22
SystemDebugger
VK..DISPI-AY READYAND SLEEPING TASKS
EXAMPLE
To displaya iist of all the ready and sleepingtasksin your system,enter the following
command:
The SystemDebuggerrespondswith the following:
Ready tasks:
2F00
Sleeping taeks:
26F0
2020
20D0
SystemDebugger
2588
1FF8
0300
2688
2698
2200
2238
2180
2118
2090
2668
2588
2638
2050
2768
2-2i
The VO commanddisplaysthe tokensfor the objectsin the specifiedjob.
PARAMETER
The tokenof thejob for whichyou want to displayobjects.
job token
DESCRIFTION
semaphores,
The VO commandliststhe tokensfor a job'schildjobs,tasks,mailboxes,
composites,
and bufferpoolsin the formatshownin Figure
regions,segrnents,
extensions,
t_o
Child Jobs
Tasks :
Mailboxes:
Sernaphores
XXXX
XXXX
XXXX
XXXX
XXXX
XXXX
XXXX
XXXX
XXXX
XXXX
xxxx
XXXX
XXXX
XXXX
Segnents:
Extens ions
Cornposites
XXXX
xxxx
xxxx
xxxx
XXXX
XXXX
XXXX
XXXX
XXXX
XXXX
Buffer
XXXX
xxxx
XXXX
Pools:
Figure2-9. Formatof VO Output
The fieldsin Fizure2-9are asfollows:
2-24
ChiìdJobs
job's offspringjobs.
The tokensfor the specified
Tasks
The tokensfor the tasksin the specifiedjob.
Mailboxes
The tokensfor the mailboxes
in thejob. An "o" followinga
mailboxtokenmeansthat one or more objectsare queuedat the
maìlbox.A "t" followinga mailboxtokenmeansthat one or
more tasksare queuedat the mailbox.
SystemDebugger
VO..DISPLAYOBJECTSIN A JOB
Semaphores
The tokensfor the semaphores
in the specifiedjob. A "t,'
followinga semaphore
tokenmeansthat one or more tasksare
queuedat the semaphore.
Regions
The tokensfor the regionsin the specifiedjob. A,'b" (busy)
followinga regiontokenmeansthat a taskhasaccessto
information
guardedby rheregion.
Segments
The tokensfor the segments
in the specifiedjob.
Extensions
The tokensfor the extensionsin the specifiedjob.
Composites
The tokensfor the compositesin the specifiedjob. A ,'s,'
following a compositesigrifies a port with a signalwaiting. An
"m" signifiesa port with a message
waiting.A "t" signifiesa port
with a taskwaiting.
Buffer Pools
The rokensfor the buffer pools in the specifiedjob.
ERRORMESSAGES
Svntax
Error
oran
I:J.T:Tff:Jff:ffil?',lTJ*command
TOKEN is not a Job
A valid tokenwa, .nt"."dlho*"uer, it is not a job token.
... INVALID TOKEN ***
The valueenteredfor the tokenis not a valid token(as
defined.in"CheckingValidityof Tokens"earlierin this
cnaDter
ì.
SystemDebugger
,-)<
VO.-DISPI-AYOBJECTSIN A JOB
EXAMPLE
If you want to look at the objectsin thejob havingthe token"1670",enterthe following
command:
The SystemDebuggerrespondswith the following:
Child j obs
Tasks :
Mailboxes:
Sermphores
RegÍons:
Sègnents:
Extens ions
Conposites
Buffer pools:
2460
1688
L720
17A0
t178
1128
17A8 r
1788
1738 r
1940
1740 r
1950
1760 r
2FF8
1768 r
16D8
1750
1958
1960
2FE8
2Fc8
1690
16F0
1710
1828
1848
1980
semaphores,
regions,
This displayshowsthe tokensfor the childjobs,tasks,mailboxes,
and bufferpoolsin thejob. It alsotellsyou that tasks
segments,
extensions,
composites,
and one semaphore.
arewaitinsat four mailboxes
2-26
SystemDebugger
The VR commanddisplaysinformationaboutthe iRMX ll BasicI/O SystemI/O
Request/Result
Segment(IORS) that corresponds
to the segmenttokenyou enter.
PARAMETER
Segmenttoken
The tokenfor a segmentcontainingthe IORS you want to
display.If thissegment
is not an IORS,the VR command
returnsinvalidinformation.To obtaina list of the segment
tokensin a iob.usethe VO command.
DESCRIPTION
The VR commanddisplaysthe namesandvaluesfor the fieldsof a specificIORS. The
contentsof the IORS reflectthe mostrecentI/O operationin whichthis IORS wasusec.
Exceptfor ensuringthe specifiedsegmentis between45 and 65 byteslong,the System
Debuggercannotdeterminewhetherthe segmentcontainsa valid IORS,soyou must
ensurethat it does. If the parameteris a valid segmenttokenfor a segmentcontaining an
IORS,the SystemDebuggerdisplaysinformarionaboutrhe IORS asshownin Figure2-10.
For more informationon l/O Request/Result
Segments,
seetheExtended
|RMX II Basic
I/O SystemUser'sGuide.
For more detailedinformationaboutthe IORS contents,seetheExtended
|RMX II Device
Diven User'sGuide.
SystemDebugger
2-27
SEGMENT
I/O REQUEST/REST]LT
VR..DISPT-AY
l/O
Request Result
Status
Device
Function
count
Device location
Resp mailbox
Link forward
Done
Connection token
Segment
xxxx
xxxx
xxxxxxx
xxxx
xxxxxxxx
xxxx
xxxx:xxxx
xxxxx
xxxx
Unit status
Unit
Subfunction
Actual
Buffer pointer
Aux pointer
Link backward
Cancel ID
xxxx
xx
xxxxxxx
xxxx
xxxx:xxxx
xxxx:xxxx
xxxx:xxxx
xxxx
Figure2-l{ì. Formatof VR Output
The fieldsin Fisure2-l0 are asfollows:
Status
T h e c o n d i t i o nc t r t F f o r t h e l / O o p e r a t i o n .
Unit status
Additionalstatusinformation.The contentsof this field are
meaningfulonlywhenthe Statusfield is setto the E$lO
condition(0028H).lf the Statusfieldis not setto E$lO,the
"N/A"
Unit Statusfielddisplays
Device
The numberof the devicefor whichthis I/O requestis intended.
Unit
The numberof the unit for whichthis l/O requestis intended.
Function
The operationperformedby the BasicI/O System.The
possiblefunctionsare
Function
SvstemCall
Reaci
Write
Seek
Special
Att Dev
Det Dev
Open
Close
RQ$A$READ
RQ$A$WRITE
RQ$A$SEEK
RQ$A$SPECIAL
RQ$A$PHYSICAL$ATTACH$DEVICE
RQ$A$PHYSICAL$DETACH$DEVICE
RQ$A$OPEN
RQ$A$CLOSE
an invalidvalue,the System
If the Functionfieldcontains
Debuggerdisplaysthe actualvaluein this field,followedby a
spaceand two questionmarks.
2-28
SystemDebugger
VR.-DISPI-AYI/O REQUEST/RESULTSEGMENT
Subfunction
A furtherspecification
of the functionthat appliesonly whenthe
Functionfield contains"Special"
from the BIOS
RQ$A$SPECIALsystemcall. Possiblesubfunctions
lnci their
descript
ionsare
Subfunction
Description
For/Que
Satis!
Notify
Devicechar
Get TermAttr
SetTerm Attr
Signll
Rewind
ReadFileMark
Write File Mark
Retention
Trpe
Set Font
Set Bad Info
Get Bad Info
Formator Query
Streamfile satisfyfunction
Notify function
Devicecharacteristics
Get terminalattributes
Setterminalattributes
Signalfunction
Rewindtape
Readfile markon tape
Write file mark on taoe
Takeup slackon tlpi
Setcharacterfont
Setbad track/sectorinformation
Get bad track/sectorinformation
If the Functionfield doesn'tcontain"Special,"
thcn thc
Subfunction
field contains"N/A." If the Subfunctionfield
containsan invalidvalue,the SystemDebuggerdisplaysthe
valucof the field followedby a spaceand two questionmarks.
Count
The numberof bytesof datacalledfor in the I/O request.
Actual
The numberof bytesof datatransferredin responseto the
requ(st.
Devicelocation
The eight-riigithexadecimal
addressof the byteor logicalblock
wherethe I/O operationbeganon the specifieddevice.
Bufferpointer
The adclress
of the bufferthe BasicI/O Systemreadfrcm, or
wr(ìtct(ì.in response
to the request.
Respmailbox
A tokenfor the response
mailboxto whichthe devicesentthc
IORSafterthe operation.
Aux pointer
The pointerto the locationof auxiliarydata,if any. This field is
significantonlywhenthe Functionfield contains"Special."
Link forward
The adclress
of the nextIORS in the queuewherethe IORS
waitedto be processed.
Link backward
The addressof the previousIORS in the queuewherethe IORS
waitedto be orocessed.
SysternDebugger
2-29
VR--DISPT-AY
I/O REQUEST/RESULTSECMENT
Done
This field is alwayspresentbut appliesonly to IORSs for I/O
it
devices.When applicable,
operationson random-access
indicateswhetherthe I/O operationhasbeencompleted.The
possiblevaluesare TRUE (0FFH) and FAI-SE (00H).
CancelID
A word usedby devicedrivers to identi! I/O requeststhat need
to be canceled.A valueof zero (0) indicatesa requestthat
cannotbe canceled.
Connectiontoken
The token for the file connectionusedto issuethe requestfor
the I/O ooeration.
ERROR MESSAGES
SyntaxError
No parameterwasspecifiedfor the commandor an
error wasmadein enteringthe command.
TOKEN is not a SEGMENT The tokenenteredis validbut not a segmenttoken.
*** INVALID TOKEN *** The valueenteredfor the tokenis not a valid token (as
definedin "CheckingValidityof Tokens"earlierin this
chapter).
SECMENT wrong sizenot an IORS
2-30
The specifiedsegmentis not berween45 and
65 byteslong,so it is not an I/O Request/Result
Sesment.
SystemDebugger
The VS commandidentifiessystemcalls(asdoesthe VC command)and displaysthe stack.
PARAMETER
A decimalor hexadecimal
valuethat specifiesthe numberof
words from the stackto be includedin the display. A suffix of T,
as in l6T, meansdecimal.No suffixor a suffir of H indicates
hexadecimal.
If you do not specifya count,or you specifya countof zero (Lr,
the numberofwords in the displaydependson the numberof
parameters
for the systemcall at the CS:IP. Or, in the case
whenCS:IPis not pointingto a systemcall,the entirecontents
of the stackis disolaved.
DESCRIFTION
The VS commandidentifiesiRMX II systemcallsfor all iRMX II subsystems
(asdoesthe
VC command)and interpretsthe systemcall parameterson the stack. If the stackdoesnot
containa systemcall,the VS commanddisplayseitherthe numberof stackelementsyou
specifuor all of the stackcontents,whicheveris least. If a parameteris a string,the System
Debuggerdisplaysthe string. For additionalsystemcall information,seethe appropriate
iRMX II Volume3 systemcall manual.
The VS commandinterpretsthe CALL instructionat the currentCS:IP. If you want to
interpreta CALL instructionat a differentCS:IPvalue,you mustmovethe CS:IPto that
value. To movethe CS:lPusingthe iSDM monitor,usethe GO (G) commandor the
EXAMINE/MODIFY REGISTERcommand(X with CS or lP specifiedasthe 80286or
80386register).If you are usingthe D-MON386monitor,useonly the GO command.
If the instructionis not a CALL instruction,VS displaysthe contentsof the wordson the
stackand no message.If the instructionis a CALL but not a systemcall (for example,a
PLIM-286call to a procedure),VS displaysthe stackcontentsand a message
informing
you that the CALL wasnot a systemcall.
SystemDebugger
2-31
VS..DISPT.AYSTACK AND SYSTE]ITCALL INFORMATION
(StackSegment:Stack
Pointer)registers
usescurrentvaluesof theSS:SP
TheVScommand
is aniRMX ll system
call,VS displays
to displaythecurrentstackvalues.If theinstruction
asshownin Figure2-11.
thesystem
callandthestackinformation
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
Figure2-ll. Formatof VS Output
The fieldsin Figure2-l l are as folÌows:
xxxx:xxxx
The contentsof the SS:SP(stackmemoryaddresses).
)oofi
Values(tokens)currentlyon the stack.The numberof stack
valuesvaries,dependingon the numberof parametersin the
systemcall.
parameters
The namesof the stackvaìues.The parameterscorrespondto
the stackvaluesdirectlyabovethem. The maximumnumberof
displayedparametersis 24.
The threeremainingfieldsin Figure2-11are identicalto thosein the VC command:
) -7)
gate#NNNN
The gatenumberassociated
with the systemcall.
(subsystem)
The iRMX ll OperatingSystemlayerthat the systemcall is part
of.
systemcall
The nameof the iRMX II systemcall.
SystemI)€bugger
VS--I)ISPLAYSTACKAND SYSTEMCALL INFORMATION
ERRORMESSAGES
SyntaxError
An error wasmadein enteringthe command.
Not a systemCALL
The CS:IPis pointingto a CALL instructionthat is not an
call.
iRMX II system
Unknownentrycode This message
indicatesthat one of two infrequenteventshas
occurred.One is that the SystemDebuggerhasmistakenan
operandbelongingto someinstructionin the objectcodefor the
FAR CALL instruction.The other eventis that a softwarelink
from usercodeinto iRMX ll codehasbeencorrupted.To
recoverfrom systemcorruption,rebootthe system.
EXAMPLES
'1906:07CA
(usingthe iSDM Monitor'sX
Supposeyou determinethat the SS:SPis
command,for example)then usethe VS commandby enteringthe followingcommand:
with the following:
The SystemDebuggerresponds
gate /10360
1906:07cA 0808
1906:07DA 19A0
1980
0820
1EA8
0s80
1980
1EA8
1980
1EA0
0000
1EE8
0800
0000
1908
0000
(Nucleus) delete mailbox
| . . e x c e p $ p .. | . r n b o x I.
The parameternamesidentifothe stackvaluesdirectlyabovethem. That is, the "excep$p"
to the
parameternamesignifiesthat the first two wordsrepresenta pointer(1980:0808)
exceptioncode. Similarly,the "mbox"parametersignifiesthat the third word (18A8) is the
tokenfor the mailboxbeingdeleted.
Now,supposethat you movethe SS:SPto 2906:07D0.If you invokethe VS commandby
enteringthe followingcommand:
SystemDebugger
2--l-l
VS.-DISPLAYSTACKAND SYSTEMCALL INFORMATION
The SystemDebuggerdisplaysthe followingstackand a message
informingyou that the
instructionis a CALL instructionbut not an iRMX II systemcall:
2906:07D0
2906:0780
2980
2 7C 8
2980
27C8
0000
25C8
0600
25C8
2908
25C8
29A0
25C8
0020
25C8
1s80
25C8
Not a systen CALL
When an iRMX II systemcall is executed,
its parametersarepushedonto the current
stack,and then a CALL instructionis issuedwith the appropriatestackaddress.If the call
hasmoreparametersthanwill fit on one line,the SystemDebuggerautomatically
displays
multiplelinesof stackvalues,with corresponding
multiplelinesof parameterdescriptions
directlybelowthem.
For example,supposeyou usethe VS commandasfollows:
gate i10310
z l c c : Q F 9 A 0 1 58
27cc:OFAA 20E8
27CC:0FBA 2608
20 C 8
0028
tA58
0000
0000
1AF8
20c8
0000
2608
20c8
20C8
0000
0000 0600
OOEO 2FF8
0000 0000
l1c8
2FF8
0000
(Nucleus) create job
l . . . e x c e p g pI . t.$. f l g s . s t k s z e l . . s p .. 1. . . . l . . ds. . l . . ip . . I
""
. e x p $i n f o $ p . . I maxpri
l . . c s . . l . . p rIi .
Inaxtsk I maxobjI
p
a
r
a
m
.
.
.
o
l
r
s
1
z
lpoolm-x
lpoolrnn
I
I
This displayindicatesthar the CALL instructionis a NucleusRe$CREATE$JOBsystem
callwith 18parameters.The namesof theseparameters
are shownbetweenthe vertical
bars( | ). The wordson the stackcorrespondto the Darameters
directlvbelowthem.
2-34
SystemI)ebugger
VS--DISPI-AYSTACK AND SYSTEMCALL INFORMATION
The followingdisplayshowsthat theCALL instructionis a BasicI/O System(BIOS)
RQ$A$ATTACH$FILEsystemcallwith five parameters.The "subpath$p"
parameter
pointsto a stringsevencharacters
long:theword"example."
gate /10500
27CC|0F4E 0F88
27CC:0F5E 2608
17c8
1C10
25F8
2600
0000
1320
2600
26D0
29AO 0000
0F78 0DF8
2600
2FF8
( B I o s ) a È t a c hf i 1 e
l . . . . e x c e p $ p . .l.. r n b o xl .. . s u b p a t h $ pl...p r e f i x l . u s e r l
subpath--) 07' exarnple'
The followingdisplayindicatesthat the CALL instructionat CS:IPis an ExtendedI/O
SystemRQ$S$RENAME$FILEsystemcallwith threeparameters.Two of the parameters
havestrings:the "new$path$p"
parameterpointsto a stringfour characters
long ("XY70");
the "path$p"parameterpointsto anotherstringfour characters
long ("temp").
gate /f06E8
27AC:0F98 0148
27CC:0F48 17c8
20c8
2088
0858
0028
20E8
1320
0640
0000
2088
20c8
0000
0008
0600
2600
l . . excepgp. . l . . newgpathgp. . l . . . path$p . . . I
new path- -> 04'XY70'
paEh- -> 04' teurp'
NOTE
If a string is more than 50 characterslong, the SystemDebuggerdisplaysonly
the first 50 characters.If the pointeris pointingto a nonreadable
segment,the
SystemDebuggerdoesnot displaythe string.
SystemDebugger
2-35
with the token
The VT commanddisplaysinformationaboutthe iRMX II objectassociated
you enter.
PARAMETER
token
The tokenof the objectfor whichyou want to display
information.
DESCRIPIION
The VT commanddeterminesthe typeof iRMX II objectrepresented
by the tokenand
displaysinformationaboutthat object.Both the informationand the format in whichthe
SystemDebuggerdisplaysthe informationdependon the typeof object.
The followingsectionsare dividedinto displaygroupsillustratingthe displayformatfor
theseiRMX II objects:
.
Jobs
.
Segments
.
Tasks
o
Extensions
.
Mailboxes
.
Compositeobjects(six types)
r
Semaphores
.
Buffer Pools
.
Regions
ERRORMESSAGES
2-36
Svntax
Error
oran
}:ffixTil::Jtr:i:;il:1i"JJ*comman'lr
*** INVALID TOKEN +**
The valueenteredfor the token is not a valid token (as
definedin "CheckinsValiditvof Tokens"earlierin this
chapter
).
SystemDebugger
VT--DISPI,AYiRMX@II OBJECT
JOB DISPI,AY
If the parameteryou specifyis a validjob token,the SystemDebuggerdisplaysinformation
aboutthejob havingthat token,asFigure2-12shows.
Objecttype:1Job
Current tasks
Current obj ects
Directory
s ize
Except handler
Pool min
Borro!.red
XXXX
XXXX
XXXX
xxxx : xxxx
XXXXX
Max tasks
Max obj ects
Entries used
Except rnode
PooI max
xxxx
xxxx
xxxx
xx
xxxxx
Max priority
Paraneter obj
Job flags
Parent job
size
Initial
xx
xxxx
xxxx
xxxx
xxxxx
XXXXX
Bvte ranse
Number chunks
22 - 44H
44 - 81-!H
8 4- 2 0 0 H
2 0 0 H -1 K
1 K -2 K
2K-4K
4 K -8 K
8 K -3 2 K
+ 32 K
Largestchunk
Total memory
xxxxxxxx
XXXXXXXX
XXXXXXXX
XXXXXXXX
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
XXXXXXXX
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
xxxxxxxx
XXXXXXXX
xxxxxxxx
xxxxxxxx
Figure2-12. FormatofVT Output: Job Display
The fieldsin Figure2-12(from Ieli to right) are asfollows:
Currenttasks
The numberof taskscurrentlyexistingin thejob. If the Max
tasksis not 0FFFFH (no limit), the numberof Currenttasksis
equalto the Currenttasksof thisjob plusall of its childrenMax
tasks.
Max tasks
The maximumnumberof tasksthat canexistin thejob
This valuewassetwhenthejob wascreated.
simultaneously.
l\{a-rpriority
The maximum(numericallylowest)priority allowedfor anyone
taskin thejob. Thisvaluewassetwhenthejob wascreated.
Currentobjects
The numberof objectscurrentlyexistingin thejob.
Max objects
The maximumnumberof objectsthat canexistin the job
Thisvaluewassetwhenthejob wascreated.
simultaneously.
SystemDebugger
2-37
W..DISPI,AY iRMX@II OBJECT
2-38
Parameterobj
The tokenfor the objectthat the parentjobpassedto thisjob.
This valuewassetwhenthejob wascreated.
Directory size
The maximumnumber of entriesthe job can havein its object
directory. This valuewasspecifiedby the first parameterwhen
thejob wascreatedwith the NucleusRQ$CREATE$JOB
systemcall or the RQE$CREATE$JOBsystemcall.
Entries used
The number of objectscurrentlycataloguedin the job's object
directory.
Job flags
The job flagsparameterspecifiedwhenthe job wascreated.It
containsinformationthe Nucleusneedsto createand maintain
thejob.
Excepthandler
The start addressof thejob's exceptionhandler. This address
wassetwhenthejob wascreated.
Exceptmode
The value that indicateswhen control is to be passedto the new
job's exceptionhandler.This valuewassetwhenthejob was
created.
Parentjob
The token for the specifiedjob's parent.
Poolmin
The minimumsize(in 16-byteparagraphs)
of thejoh,smemory
pool. Thisvaluewassetwhenthejob wascreated.
Poolmax
The maximumsize(in 16-byteparagraphs)
of thejob's memory
pool. This valuewassetwhenthejob wascreated.
Initial size
The initial size(in 16-byteparagraphs)
ofthejob,s memory
pool.
Borrowed
The currentamount(in 16-byteparagraphs)
of memorythat the
job hasborrowedfrom its ancestor(s).
Free Space
All free memory in a job's pool is accountedfor, via several
double-linked
lists. Eachlist containsa rangeof chunksizes.A
chunkis a pieceof contiguous
memory. Columnone of the free
spacetableshowsthe sizerangesfor the list. Columntwo shows
the numberofchunkson eachlist. Columnthreedisnlavsthe
largestchunkon eachiist. Columnfour showsthe toial amount
of memoryon eachlist.
SystemDebugger
VT--DISPT.AY
iRMX@II OBJECT
TASKDISPI"AY
The SystemDebuggerdisplaysinformationabouttasksin two differentways.Figure2-13
showsthe displayfor non-interrupttasks,andFigtre 2-14showsthe displayfor interrupt
tasks.
Objecttype-2Task
C È - È i ^
r La Lre
- - t
P!r
Suspend depth
Except handler
Concalning job
xx
xxxx: xxxx
xxxx
Dynamic pri
Delay req
Except mode
Interrupt task
xx
xxxx
xx
no
Last exchange
Task flags
K-saved SS:SP
xxxx
XX
xxxx : xxxx
Figure 2-13. Format ofVT Output: Non-Interrupt Task
Objecttype-2Task
Suspend depth
Except handler
Containing job
Master nask
Max interrupts
xx
xx
xxxx : xxxx
XXXX
XX
xx
n,,-^-i
^
ujl rrdu' r L
--i
Pr r
Delay req
ExcepL mode
InLerrupt task
Slave rnask
K-saved SS:SP
'r^^1.
^r^,^
xxxx
Last exchange
xx
Task flags
yes
Int level
xx
Pending int
xxxx: xxxx
XXXXXXXXX
xxxx
xx
XX
XX
Figure 2-14. Format of VT Output: Intemrpt Task
The fields in Figures2-13 and2-14(from left to right) are as follows:
Staticpri
The maximumprioriryvalueof the task. This valuewassetby
the max$priorityparameterwhenthe task'scontainingjob was
createdwith RQ$CREATE$JOBor RQE$CREATE$JOB.
Dynamicpri
A temporarypriority that the Nucleussometimesassigns
to the
task to improve systemperformance. For example,if a higher
priority taskwantscontrolof a regionthat belongsto a currently
executinglower priority task,the Nucleusassignsthe lower
priority taska priority equalto that of the higherpriority task.
This increasing
of a task'spriority,in this case,improvesthe
overallsvstemoerformance.
SystemDebugger
2-39
vT--DISPLAYiRMX@II OBJECT
Taskstate
The stateof the task. The twelveoossiblestates.as thevare
are
displayed,
State
Descriotion
rea is entered at the Hl prompt. rhe task calletl lnit runs
first, creating a mailbox it catalogsin the rod directory under the name,'master.',lt
createsthe tasksAlphonse and Ga:itorìthen suspenclsitself.
When Gaston receivescontftrl, 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 creatcsa segment(in
which it will place a message)and a responsemailbox (to which Alphonse will send a
reply). Next it goes into a loop in which ìt placesa messagein the segment(after
d i s p l a y i n gi t o n t h e s c r e e n ) s, e n d st h e s e g m e n t o t h e m a s t e rm a i l b o x ,t h e n w a i t s a t t h e
responsemailbox for a repÌy.
When Alphonse receivescontrctl,it also sets the token lbr the mailbox created by Init (by
looking up the name in the root job's objcct clirectory). It rhen goes into a loop in which it
waits at the maiìbox for a messagcand checksto see if the token it received is a segment.
If it is a segment,Aìphonse placesits own messagein the segment(alier displayingit on
the screen),then sendsthe segmentto the responsemailhox. If it isn't a segment,
Alphonse drops out of the loop anri deletesitself.
SystemDebugger
3-l
SAMPLEI)EBUG SESSION
Gaston
By usingthe two mailboxes,
the tasksAlphonseand Gastonare synchronized.
sendsa message
to the first mailboxandwaitsat the secondone beforecontinuing.
it sendsa replyto the
Alphonsewaitsat the first mailbox.When it receivesa message,
secondmailboxandwaitsat the first for anothermessage.This cyclecontinuesfor 6
messages.
After sendingits sixthmessage,
Gastondropsout of the loop. Insteadof sendinga
segmentto the m:ìstermailbox,Gastondisplaysa final message
to the screenthen sends
the tasktoken(thetokenfor the Init trìsk)to the mailbox.WhenAlphonsereceives
this
tokenand findsit is not a segment,
Alphonsedropsout of its loop and deletesitself.
(remember,the
To finishthe processing,
Gastoncausesthe Init taskto resumeprocessìng
Init tasksuspended
itselfearlier). When Init takesover,it deletesboth offspringtasksand
issuesan EXIT$IO$JOBsvstemcall to returncontrolto the Humanìnterfacelevel.
compacf
init:
DO;
DECI-ARE token
DECI,ARE fifo
DECI-ARE seÌf
D E C I A R Et a s k $ p r i o r i t y
D E C I ^ A R Ec a 1 1 i n g $ t a s k
DECIARE c a11ing$ tasks $j ob
D E C I - { R Em a s t e r $ m b o x
DECI,ARE status
DECI^AREini t$ task$ t oken
DECIARE gas ton$ task$ token
DECI-AREalphons e $ tas k$ token
DECIARE aÌphonse$start$add
D E C I - { R Eg a s t o n q s t a r t S a d d
DECLARE ga s ton$ds
DECI"{RE alphons e $ ds
D E C L A R Es t a c k $ p o i n t e r
DECI-{REstack$size
D E C L A R Et a s k $ f l a g s
LITEMLLY
LITEMLLY
LITEMLLY
BYTE;
TOKEN;
, S E L E C T O; R '
'0';
,0,;
TOKEN
TOKEN
WORD
;
TOKEN
TOKEN
TOKEN
POINTER;
POINTER;
WORDEXTERNAL;
WORDEXTERNAL;
POI NTER;
WORD
;
T.IORD
;
gas ton :
PROCEDUREEXTERNAL;
END gaston;
alphonse:
PROCEDUREEXTERNAL;
END alphonse;
Figure3-1, ExamplePL/M-286Application(Init)
3-2
SystemDebugger
SAMPLEDEBUG SESSION
$include (/rmx2 86/inc/nuclus .ext )
$ include (/rmx286 / inc / eio s . ext)
( NFI L ) i
calling$tasks$job:
SE L E C T o R $ O
calling$task : SELECToR$OF(NIL);
g a st o n $ s t a r t $ a d d : @ g a s t o n ;
a l p h o n s e$ s t a r t $ a d d : @ a l p h o n s e ;
stack$pointer : NIL;
stack$size : 500;
task$f1ags : 0;
init$task$token
self ,
Gstatus ) ;
,/*
/*
/*
/*
/*
,/*
Directory obj cataloged in
vill
îask whose priority
be gotter' */
Set up scart addresses for
Lasks */
Values for creating tasks
: R Q $ G E T $ T A S K $ T 0 K( E N S, / * G e t t o k e n f o r
init
task
*/
*/
*,/
*/
*/
CALL RQ$0ATALoG$oBJ
ECT (
calling$tasks$job,
inic$task$token,
@(4,'init'),
@ sr a t u s ) ;
/*
/*
/*
catalog task token in
directory of calling
task's job */
*/
x/
n a s t e r $ n b o x : R Q $ C R E A T E $ M A I L B(O X
fifo,
Gstatus ) ;
/*
/*
Create mailbox tasks use
to Pass messages
*/
x/
C A L L R Q $C A T A L O C $ OEBCJT (
calling$tasks$job,
master$mbox,
@(6,'master'),
@ sc a t u s ) ;
/* Catalog mailbox in
/* directory of calling
,/* task's job
*/
*/
*/
: R Q $ G E T $ P R I O R I T( Y
task$prlority
calling$task,
@ st a t u s ) ;
./* Get priority
/* xask */
*/
taskSnrioritv:
task$príority I Ii
of calling
/x Pick lowerprioriry for
,/* ne!{ tasks
*/
*/
Figure 3-1. Example PL/M-286 Application (Init) (continued)
SystemDebugger
3-3
SAMPLEDEBUGSESSION
a l p h o n s e $ t a s k $ t o k e n : R Q $ C R E A T E $ T A(S K / *
r.
clzQ-Fi
^ri
create rasks
*/
r"
aÌphonse$start$add,
G aI p h o n s e $ d s ) ,
S E L E C T O R $ O( F
s dÉr
^^..-c
. uuu
L ,
G st a t u s ) ;
END;
ENDalphonse;
alphonse$code;
,/* FOREVER
,/* Alphonse
Figure3-2. ExamplePL/M-286Application(Alphonse)(continued)
3-6
SystemDebugger
SAMPLEDEBUG SESSION
9compact
oacr-^nq^^.la'
nn'
DECI-AREtoken
$i n c l u d e
$ include
$ include
,SELECTOR,
;
LITEMLLY
(/rmx2 86/inc/nuc lus . ext )
( /rrnx286 / inc / e io s . ext)
( /rmx286 / íne /hi . ext)
gas con :
P R O C E D U RPEU B L I C ;
D E C I A R EC R
LITERALLY
DECI-ARELF
LITEMLLY
DECLARE
fifo
LITERALLY
D E C I " A Rw
Ea i t $ f o r e v e r
LITERALLY
D E C I A R Ep a r e n t $ t a s k
TOKEN;
DECIAREcal l ing$ tasks $j ob
TOKEN;
D E C I A R Em a s t e r $ m b o x
TOKEN;
D E C I A R Er e s p o n s e $ m b o x
TOKEN;
DECLAREstatus
ITORD;
DECI"ARE
time$linit
IIORD;
DECI-AREcount
WORD;
D E C I A R Ef i n a l $ c o u n t
WORD;
DECIAREgaston$ds
latORD
PUBLIC;
D E C I " A R sEe g $ t o k e n
TOKEN;
D E C I - A R sEe g $ si z e
WORD;
D E C I A R Er n a i n $ m e s s a g(e* )
BYTE
CR,LF, 'After you, Alphonse', CR, LF);
D E C I A R Ef i n a l $ m e s s a g e ( * )
CR,LF, 'If you insist,
BYTE
Alphonse', CR, LF);
D E C I ^ A RrEn e s s a g eB A S E Ds e g $ t o k e n
count : 0;
flnal$count : 6;
time$linit : 25;
seg$size : 32;
calling$tasks$job
DATA(
DATA(
STRUCTURE(
count
rexr(27)
,/*
,/*
/*
/*
/*
: S E L E C T O R $ O F ( NjI L ) , / *
/*
'I3':
' 10 '
;
'0,
;
,OFFFFH,
;
BYTE,
BYTE);
Initialize
count
Set nurnber of loops
Delay facror for display
to screen
Size of message segment
Directory in which to look
up obj ect
*/
*/
*/
*/
*,/
x/
Figure 3-3. Example PL/M-286 Application (Gaston)
SysternDebugger
J-l
SAMPLEDEBUGSESSION
rnaster$rnbox : RQ$LOOKUP$OBJ
ECT (
cal l ing$ tasks $j ob,
,/* Look up message mailbox
*/
@(6,'master'),
wait$forever,
G st a t u s ) ;
response$mbox :
fifo,
R Q $ C R E A T E $ MLABI O X (
/*
Create response
rnailbox
/*
Create message segment
*/
@status ) ;
s e g $ t o k e n - R Q $ C R E A T ES$E G M E N(T
seg$s ize ,
Q st a t u s ) ;
DO WHILE count < final$count;
nessage.count:23;
C A L L M O W ( @ m a i n $ r n e s s a g e@
, m e s s a g et.e x t ,
C A L L R Q $ C $ S E N D $ C 0 $ R E S P O N(S E
NIL,
/*
*/
SIZE(main$message) ;
Send rnessage to
screen
*/
0,
Arîa(<,oa
^^'1nf
@status ) :
CALL RQ$SLEEP(
time$l-init,
/* ilair
,/* time
a while ro give user
Lo see the messa€le
*/
x/
Gstatus ) ;
C A L L R Q $ S E N D $ M E S S A G( E
naster$mbox,
seg$ token,
/*
Send message to mailbox
*/
rp runs,the systemdisplaysthe
following message:
Interrupt
13 at 2C38:0199 General Protection
EC0DE:0000
arewherethe CS:IPwaspointingwhenthe programhalted. The
The values2C38:0199
protected-mode
prompt (..) indicatesthat we are in the iSDM monitor. However,sincethe
the code.
programhasbeenexecuted,
we mustre-enterthe iSDM monitorto re-execute
We canusethe Cll-restart featureto returnto the CommandLine Interoreter.Enter the
followinscommand:
The systemrespondswith the Human Interfaceprompt(-). Next,enterthe following
command:
with the following:
The systemresponds
Interrupt
3 a t 2 A 7 0 :F F F F
Use the iSDM monitor'sGO (G) commandto seta breakpointat the instructionwherethe
programhalted(rememberthe CS:IPvalueis givenin the interruptmessage
displayed
whenthe programhalts). The codesegment(CS)valuewill changeeachtime you re-enter
the iSDM monitor,but the instructionpointer(IP) will remainthe same.Enter the
followinscommand:
-ì-10
SystemDebugger
SAMPLEDEBUCSESSION
To find out wherewe are in the code,usethe iSDM monitor'sD (DISPIAY
MEMORY/DESCRIPTOR TABLES) commandto displaya disassembled
blockof code.
Enter the followingcommand:
The systemdisplaysthe followingcode:
2500: 0199
2500:0198
2500: 019E
2500: 01A0
F2A5
REP
880000
MOV
SBDO
MOV
52
PUSH
25 0 0: 0 1 A l
50
PUSH
2500:01A2 680000
PUSH
2 5 0 0 : 0 1 A 5 8 E 0 6 3 8 0 0 MOV
25 0 0: 0 I A 9
880000
M0v
2500:01AC 06
PUSH
2500; 0lAD 5 0
PUSH
MOVSW
A X ,0 0 0 0
DX,AX
DX
AX
0000
E S ,[ 0 0 3 8]
A X ,0 0 0 0
ES
AX.
The instruction
at address
2-500:0199
is a MOVE STRINGWORD command.The only
moveword instructionin the sampleprogramis the PL/M-2t16MOVW callwhenCaston
entersthe loop aftercreatingthe segment.The lbllowingdisplayshowsthis sectionof
code:
SystemDebugger
3 - lI
SAMPLEDEBUGSESSION
*/
r e s p o n s e S m b o r = R Q S C R E A T E $ U A I L B O (X
fifo,
Gstatus);
/.
Create
S E g SI O K E N = R QS CR E A T E9 S E G M E N(T
s e g 9s i z e .
!astatus);
/i
C r e a t e m e s s a g es e g m e n t r /
response mailbox
DO wHILE count
IinalScount;
.^,'^r = ?ì.
CÈIL r|Ottx(enal n$nessage, 0nessage.tert,
(
CALL RQSCSSEND$COSRESPONSE
NIL,
SIZE(nain$rcssagè]
,/t Send message to
Ii
screen r/
0,
ry'Irs54Ys.LUurrLt
0status ) ;
Figure 3-,1. MO!'W in Gaston Code
lf displayingthe instruction doesn't provide enough information about why the program
halted,we can look at the surroundingcode by displayingfor-wardor backward from the
CS:IP. The comma we specifiedin the DX command enablesus to enter just a comma (,)
now to displayforward another ten instructionsfrom the current CS:lP. (Displaying
backwardfrom the CS:IP is shown in Example #2.)
However, since the instruction where the exceptionoccurred is traceableto the sample
code, we know where the program fails. To ex:rminewhat happenswhen the systemtries
to move the message,we'll return to the protected-modeprompt (by entering a carriage
return ) and examine registercontentsbefore and alìer MOVSW is executed.
Enter the following command:
3-12
System l)ebugger
SAMPLEDEBUCSESSION
The systemdisplaysthe following:
AX-OOOO
BX*0034
cx-0017
DX:2680
CS_2500
SS:2638
Ds:2530
ES:2680
IP-0199
F I . F O 2 9 3 R G D T . B A S E : O O 2 O O.O
LIMIT:2FFF
SP:01F2 BP:O1F2 RfDT .BASE:OO5OO
. LOI M I T : O 3 F F
sI-0042 MSW:FFFB
Dr:0001
TR=0278 RLDT:02A0
To executethe MOVSW instruction,enterthe lblkrwingcommancl:
The systemdisplays
the folltrwing:
Entera comma(,).
The systemresponds
with the following:
I n c e r r u p t 1 l a t 2 5 0 0 : 0 1 9 9G e n e r a l P r o r e c r i o n E C O D E * O o 0 0
T o s e eh o w e x e c u t i n gt h i s i n s t r u c t i o nc h a n g e dr e g i s t e rc o n t e n t s e, n t e r t h e f b l l o w i n g
command:
The systemdisplaysthe folÌowing:
AX-OOOO
BX:0034
CX:OOO6
DX:26C0
CS-2800
SS:26D8
DS:2888
ES:26C0
SystemDebugger
IP_0I99
SP:01F2
SI : 0 0 6 2
Dl=0021
F I , : O 2 9 3 R G D T . B A S E : O O 2 O O.O
LIMIT:2FFF
BP:01F2 RIDT .BASE:OO5OO
. LOI M I T - O 3 F F
MSW:FFFB
TR:0278 RLDT:02A0
3- t3
SAMPLEDEBUGSESSION
the sourcedata
In the ASM286AssemblylanguageMOVSW instruction,DS:SIrepresents
seethe
on
MOVSW,
(For
more
intbrmation
is movingfrom; ES:DI is the destination.
Manual.) To checkthe limit of the ES register,
ASM286AssemhlyLanguageReference
command:
enterthe following
The systemdisplaysthe following:
c D T ( 1 4 2 7 T ) D S E GB A S E : 0 9 0 4 8 4L l t f r r : o o l F
P*l DPIFOED:O ll-1 A:1 sR*0000(Es)
The LIMIT parametershowsthat the segmentlimit is 1FH (31 decimal).Sincethe system
in Gaston.
to seg$size
countsfrom zero,the limit is 32 decimalwhichis the valueassigned
The DI register(shownin the previousdisplay)contains2lH (33 decimal),indicatingthe
systemwastryingto write pastthe segmentlimit whenthe programhalted. This fact
suggests
the PL/M-286 MOVW call shouldbe changedto MOVB. Here we couldexit the
iSDM monitor,changethe PLIM-286code,then recompileand run it.
However,we canusethe iSDM monitor'sEXAMINE/MODIFY REGISTERS(X)
commandto changea registerv:rlueand the GO (G) commandto executethe program.
with the X and S (SUBSTITUTEMEMORY) commandsenablesus ttr
Makingchanges
testcodewithouthavingto recompileand bind it.
the countin
The CX registercontainsthe countofbytesor wordsmoved. If we decrease
we shouldbe ableto
the CX registerto l5 before\ryeexecutethe MOVSW instruction,
monitor
and
set
a
breakpoint
at the MOVSW
moveall the data. Re-enterthe iSDM
instructionby enteringthe followingcommands:
Setthe CX registerto 15. E,nterthe fbllowingcommand:
Now, executethe restof the programby enteringthe followingcommand:
3 -l 4
SystemDebugger
SAMPLEDEBUG SESSION
The systemrespondswith the following:
After
you,
AfÈer you, Gaston
Interrupt
1 3 a t 2 4 7 0 : 0 1 9 9G e n e r a l P r o t e c t i o n
ECODE-0000
Sinceour changewasvalidfor one passthroughthe code,the first passthroughthe Gaston
loop worked. The nextpassfailed. To returnto the CommandLine Interpreter,enterthe
followingcommand:
This partiallysuccessful
run shclws
that if we reducethe numberofwords moved,the
programworks. Therefore,to makea permanentfix, we shouldchangethe PLIM-286
MOVW call to MOVB in the samplecode.then recomnileand bind it.
EXAMPLE#2:
We canalsomakechangesin the disassembled
code. Suppose
we haverun the program
for the first time,and the systemdisplayedthe followingmessage:
Interrupt
13 at 2A70:0199 General Protection
EC0DE-0000
Restartthe systemusingthe CLI-restartlèatureasyou did in Example#1, then re-enter
the iSDM monitorby enteringthe lbllowingcommand:
Seta breakpointat the instructionthat wasexecuting
whenthe programfailedand display
a blockof disassembled
codeby enteringthe followingcommands:
. .
SystemDebugger
3-15
SAMPLEDEBUCSESSION
The systemdisplaysthe following:
1258:0199
1258:0I9B
1258:019E
1258:01A0
1 2 5 8 :O 1 A 1
F2A5
880000
SBDO
52
50
REP
MOV
MOV
PUSH
PUSH
MOVSW
Ax, 0000
DX,AX
DX
AX
To lookat the instructions
preceding
MOVSW,enterthe followingcommand:
The systemdisplaysthe followingcoclc:
L258 o l l 4
7258 0 1 78
1258 0 1 7C
1 2 s 80 1 7E
t2s8 0181
1 2 5 80 1 83
t258 0 1 87
r258 0 1 8C
1 2 s 80 1 8E
1 2 5 80r92
L258 0 1 95
1 2 5 80 1 98
t258 0 1 99
t258 0 1 9 8
1258 0 1 9E
88063800
MOV
38 06 3 A 0 0
CMP
JB
7203
897600
JMP
81l7
MOV
8 E 0 6 3 E 0 0 MOV
2 6 8 8 0 E 0 0 0 0 MOV
8500
MOV
8E063800
MOV
8F0100
MOV
BE4200
MOV
FC
CLD
F2A5
REP
880000
MOV
SBDO
MOV
Ax,I00381
Ax,1003Al
A=0181
A : O1 F7
CL,Il
E S ,[ 0 0 3 E]
Es:[0000],cL
cH,00
E S ,[ 0 0 3 8]
DI ,0001
sr ,0042
MOVSW
Ax, 0000
DX,AX
M O V S W i s a r e p e t ì t i v em o v e f r o m D S : S It o E S : D l . L o o k i n ga t t h e p r e c e d ì n gi n s t r u c t i o n s ,
w e s e e 1 2 5 1 J : 0 1m
8 1o v e s 1 7 H i n t o C L , w h i c h i s t h e l o w - o r d e rr e g i s t e ro f C X . R e m e m b e r
that CX is the count of bytes or wortls moved. (For more information on the register set,
see the ASM286 AssentblyLanguage Rat'erenceManual). lf we display the ES register
c o n t e n t su s i n g" d d t ( e s )< C R > " a s w e d i d i n t h e l a s te x a m p l ew
, e c a n c h e c kt h e l i m i t . S i n c e
the limìt is 32 (decimal) and the systemis trying to write l7H words, rhe systemlirils when
it tries to write past the segmentlimit. f f we reduce this count we shouÌd be abÌe to move
t h e d a t a . W e m u s t r e - e n t e rt h e i S D M m o n i t o r ,t h e n u s i n gt h e i S D M m o n i t o r ' s
S U B S T I T U T E ( S ) c o m m a n d ,w e c r n c h a n g et h e c o d ea t l 2 5 t l : 0 1 8 1 S
. e m i c o l o n s( ; )
p r e c e d et h e e x p l a n a t i o n isn t h e f o l l o w i n gc o c l e e; n t e r t h e i n f o r m a t i o na p p e a r i n gi n b l u e :
-l-t6
SystemDebugger
SAMPLEI)EBUG SESSION
;enter monitor conunandto substitute
menory at lp:0181
;enter a conma ro srep to the counÈ
;enter the neù counr
code execution
;re-start
1258:0181 81 1258:0182 17 -
The systemrespondswith sixiterationsof the following:
After
After
you, A1
you, Gaston
After six iterationsof the previousscreen,the monitordisplaysthe following:
If
you lnsist,
Alphonse
3.4 VIEWINGSYSTEMOBJECTS
Consider that we have a deadlockproblem. tsy looking at systemobjectsat various stages
of execution,we can observehow synchronization(or lack of it) is occurring.
We can view any object in a job using the VO command (specifyingthe job's token) to
provide the broad picture of the systemstate,then the VT command to focus on individual
elements. Suppose,we want to view the state of thc olrjectsbelbre entering the loop in
which Gaston and Alphonse exchangemessages.Assume we have steppedthrough the
code, verifying systemcalls until we located the CS:lP lbr the Nucleuscreategsegment
systemcall in Gaston. Re-enter the iSDM monitor and set a breakpoint at this CS:lP by
entering the fol-lowingcommands:
- D e b u g < n a n e o f O B J E C Tf i l e
. .9,16d
SystemDebugger
speclfied
1n BND286>
3-t7
SAMPLEDEBUGSESSION
'I'o
get thejob token,enterthe followingcommand:
the frrlltrwing:
The systemclisplays
iRMX@ll
Job Tre e
0258
0F38
1670
2460
0E88
0E00
Note that "2460"is the token for the applicationjob. To view objectsfor this job, enter the
following command:
T h e s y s t r md i s p l a y st h e f o l l o w i n g :
Child Jobs
Tasks:
Mailboxes:
Semaphores
Segments:
E x t e n si o n s
C o n p o si t e s
26D0
25C0 t
26F0
1AB8
1AC8
1 90 0
2580
25E8
25E0
2650
2528
2480
2418
24A0
At this stageof program execution,two mailboxesexist. The "t" following mailbox 25C0
m e a n so n e o r m o r e t a s k sa r e w a i t i n ga t i t ( A Ì p h o n s ew a s c r e a t e df i r s t a n d i s w a i t i n gf o r a
messagefrom Gaston). Examine mailbox 25C0 by entering the follorvingcommand:
3-18
Syst€m I)ebugger
SAMPLEDEBUGSESSION
The systemrespondswith the following:
object
Èype - 3
Mal]box
1900
Task queue head
Queue di sc ipl ine
ContaÍning job
FIFO
2460
O b je c t q u e u e h e a d
o b j e c t c a c h e depth
0000
08
1900
VU commandto viewthe waitingtask'sstack.To unwindthe
Use the SystemDebugger's
stack,enterthe followingcommand:
The systemdisplaysthe folkrwing:
gate /10430
Rpr,,rn.q
ín
-
16C8:01E6
(Nucleus ) receive
lnlR'OzqF
0086
1D28
0084
1D28
FFFF
17E0
0000
message
l . . . e x c e p $ p.. . l . . . . r e s p $ p -. . l . t i m e . I . r n b o xI.
We cancontinueto examineobjectsor set a breakpointat the return CS:lP. Settingthe
CS:IP(g, 29f < CR > ) in the sampleprogramcausesthe iSDM monitorto displaythe
followins:
lnterrupt
L3 at 21F0:0199 Ceneral Protecîrion ECODE:0000
is the
This message
indicatesthat the programhaltsin Gastonand that 21F0:0199
when
it
drcs.
instructionexecutins
SystemDebugger
l-19
SAMPLEDEBUG SESSION
This chapterhasshowntwo waysto find an error and two waysto maketemporaryfixes
from the SystemDebugger.The message
whenthe programhaltscontainsthe
clisplayed
CS:IPof the lastinstructionexecuting.If settingthe CS:IPat this instructionand
displayingthe surroundingcodedoesn'tgiveyou enoughinformationaboutwherethis
point is in your applicationcode,you canusecombinations
of VJ, VO, VT, VU, and VS to
Iocatethe runningtask. Then setthe breakpointat the CS:IPof the lastexecuting
instructionand displaycode,objects,and registersto determinehow the systemis
executinsthat instruction.
J-20
SystemDebugger
APPENDIX
A
iSDM"MONITOR
COMMANDS
4.1 INTRODUCTION
This appendirbrieflydescribes
the iSDM SystemDebugMonitor commandsin
alphabetical
order. A commanddirectorylistingthe functionalgroupsand pagereferences
precedeslhe commanddescriptions.For examples
and more detailedinformaîionabout
the commands,seethe ISDM Sy,stem
DebugMonitor User'sGuide.
A.2 COMMAND
DIRECTORY
This section provides a brief summ:rryof all iSDM monitor comm:rndslisted by functions.
Each entry in the following summary containsalong with the command name a brief
descriptionof the command and a page referencewhere you can find more information on
the command.
Command
FunctionPerformed
Pa,qe
PROGRAM LOADING AND EXECUTION
dP
secondary
rwúu
d'
storage
jnto
ÈJrr
tlre Larget
sli s(r'u
system's
5
memory....
C
: ^^'
q Pnr n/ 'r
B e e i n P " è r r t i' nr . eE J e
L*
Load an 8086 absolute object fiLe or an 80286
object file from a development system into
P ' u É , d , , , . . . . . . . .
. .
A-5
A- 6
rsrvry.
at
a time
N
Execute one or more instfuctions
R*
Load and execute an 8086 absolute object file
or an
80286absolute object file
in target system nemory...
iSDM" SyslemDebugger
A-3
A 6
A-8
A-l
iSDM" MONITOR COMMANDS
Function
Performed
Command
Page
I/O PORT INPUTAND OUTPUT COMMANDS
I
O
Input and display
porc...
F
M
or word from
the
specified
A-5
Output a byte or word to the specified port..........
BLOCK
C
a byte
A-1
MANIPUI-A,TION
Conpare the contents of
that of another block..
one block
A-4
Search the specified
block
of hexadecirnal digits
Copy che content of
hlnnlr nf mprnnrv
of memory t^'ith
a block
of memory for
a sequence
A-5
of memory to
another
..
A-6
MEMORY/REGISTER DISPIAY AND MODIFICATION
D
S
X
L-2
Display the
entries.
contents
of
mernory and descriptor
A-4
Display and (optionally)
modify
descripLor tabl e entri es
Display and/or modify
segment contenls.
table
nemory locations
CPU/NPX register
and
A- 8
or
rask
state
A- 9
iSDM" SystemDebugger
iSDM" MONITOR COMMANDS
Page
FunctionPerformed
Command
MISCELI-ANEOUS COMMANDS
E*
P
DÍsplay che base and offset
or an expression....
Enable Protected
mode). .
Display
outDut
Virtual
and define
C o m m a n dr e q u i r e s
control
to
the
..
Echo al1
Y*
console
Return
K*
Q
*
Exit the loader program.
developnent sys tem.
to
A-5
a fi1e.
portion
A-4
of
an address
A'-1
Address Mode (protected
A-1
symbol inforrnation.
an attached
development
.
A-9
system.
A.3 COMMANDDESCRIPTIONS
for iSDM monitorcommandsin an easily
This sectionprovidesbrief descriptions
syntax,and
order. For more informationon commandparameters,
referencedalphabetical
options,refer to the iSDM tstem DebugMonitor User'sGuùúe.
A.3.1 B-BootstrapLoad
controlto the bootstraploaderto load absoluteobjectcodefrom
The B commandpasses
secondary
storageinto your targetsystemmemory.The BootstrapLoaderloadsthe file
into the targetsystemat the memoryaddressspecifiedin the file. After the bootstrap
loaderfinishesloadingthe file, the codebeginsexecuting.To usethe B command
correctly,you mustbe operatingin real mode.
If eitherthe file you specifiedor the defaultfile doesnot exist,the bootstraploaderhalts
and takesactionaccordingto how it is configured.
Debugger
iSDM" System
A.3
iSDM. MONITOR COMMANDS
A.3.2 C-Compare
The C commandcomparesthe contentsof oneblockof memorydefinedby a rangewith
the contentsof anotherblockof memorythat beginsat a destinationaddress.The iSDM
monitorexpectsthe blocksto be equalin length. If the iSDM monitorencountersany
mismatched
bytes,it displaysthem in the folìowingformaL.
aaaa:bbbb xx
yy
aaaa:bbbb
where "aaaa:bbbb"are the addressesof the bytesthat do not match and "xx" and "yy" are
the bytes themselves.
4.3.3 D-Display Memory/Descriptor
Tables/Disassembled
lnstructions
The D commandis actuallythreecommandsin one. You canuseit to displaythe contents
of a specifie<.I
blockof memory,the contentsof an 80286/80386
descriptortable,or the
contentsof a specifiedblockof memoryin disassembled
form. Ifyou are operatingin reat
mode,you cannotdisplaydescriptortableentries.However,ifyou are operatingin
protectedmode,you canuseboth functionsof this command.
A.3.4 E-Exit
The E commandenablesyou to exit the loaderprogramby returningcontrolfrom the
loaderprogramto the development
operatingsystem.Upon return,the iSDM monitor
losesall symbolinformation.
Whenusingthe E command,you mustuseit on a line by itself;do not usemultiple
commandson a line with the E command.Also,your systemmustincludean attachetl
development
systembeforeyou can usethis command.
Whenyou reinvokethe iSDM monitorafter exitingthe loaderprogram,one of two things
happens:
.
The iSDM monitorprintseithera singleor doublepromptdependinguponwhether
you were operatingin real or protectedmodewhenyou exited.
.
The iSDM monitorprintsits usualsign-on
message
andre-initializes
itselfif you reset
your targetsystembetweenthe time you exitedthe loaderand the time you reinvoked
the iSDM monitor.
A-4
iSDM" System I)ebugger
iSDM" MONITOR COMMANDS
4.3.5 F-Find
TheF command
searches
theblockof memoryyouspecified
to determine
if it contains
the
sequence
of hexadecimal
digitsyouchosein thedataparameter.
EachtimetheiSDM
monitorfindsa match,it displays
theaddress
of thefirstmatching
byte.
A.3.6 G-Go
The G commandinstructsthe iSDM monitorto beginexecuting
your applicationprogram.
In responseto the G command,the iSDM monitorsinglestepsthe first instruction,then
executesall succeedinginstructionsat full speed.
Your applicationprogrammusthaveat least12bytesof stackavailablefor lhe iSDM
monitorto use. If you are operatingin protectedmode,eachtaskin your programmust
containat least12bytesof stackat privilegelevel0 for the iSDM monitorto use.
With 80286and 80386boards,a specialsituationariseswhenyou executethe G command
and you speci! a breakpointaddressbut not a startingaddress.If the breakpointis in an
interrupthandlerand the currentCS:IPis at a softwareinterruptinstruction(INT x,
INTO, BOUND), the iSDM monitorsinglestepsthe interruptinstruction,executingthe
interrupthandlerat full speedand bypassing
the breakpointyou set. To get arountlthis
8028ó/8038ó
operationalanomaly,makesurethat the CS:IPis pointingto the (or any)
instructionprecedingthe softwareinterruptinstructionbeforeyou executethe
G command.
A.3.7 l-Port lnput
The I commandretrievesand displaysa byteor word from the port you specify.Byte and
word formats are different. (Seethe ISDM SystemDebugMonítor User'sGuide for byte and
word format descriptions).
4.3.8 K-Echo File
The K commandcopiesall consoleoutputto a development
systemfile you specify.
Repeatingthe K commandwithoutspeciling a file causesthe iSDM monitorto stop
copyingconsoleoutput. Your systemmustincludean attacheddevelopment
systemin
orderto usethiscommand
iSDM" SystenDebugger
A-5
iSDM" MONTTORCOMMANDS
A.3.9 L-Load AbsoluteObjectFile
The L commandloadsabsolute8086or 80286objectfilesinto targetsystemmemory. The
iSDM monitorloadsthe datafrom the file into the memorylocationthat you specified
whenyou usedthe LOC86or BLD286commands.Whenloadingthe data,the iSDM
monitordiscardsall previouslyloadedsymbolinformationand loadsthe new symbol
symbols.If the file containsa register
information,but it retainsall user-defined
initializationrecord,the iSDM monitorsetsthe appropriateregistersto the valuesthe file
systemin order to usethis
specifies.Your systemmustincludean attacheddevelopment
command.
The L commandcannotload relocatable
modules.Ifyou are operatingin real mode,you
canload only 808óabsoluteobjectfiles. Ifyou are operatingin protectedmode,you can
load only 80286absoluteobjectfiles.
Whenyou load an 80286objectfile, the iSDM monitorinitializesthe first 40 global
descriptortable(GDT) entriesfor its own use. In addition,the iSDM monitor initializes
anyuninitializedinterruptdescriptortable(lDT) entries.If the access
byte is equalto
zero,the iSDM monitorassumes
that the descriptortableentry is not initialized.Referto
Intel's Microprocessor
and PeipheralHandhook,MicroststemComponentsHandbook,or
IAPX 286 OperatingSystemWiter's Guidefor more information about the descriptortahles.
4.3.10 M-Move
The M command copiesthe contentsof a block of memory to a memory addressyou
specif.
4.3.1I N-ExecuteSingleInstructions
The N commanddisplaysand executes
one or more disassembled
instructions
at a time.
Goingthroughyour applicationline-by-lineis called"single-stepping."
SingJe-stepping
allowsyou to beginat a CS:IPyou specifyand checkyour applicationfor problemsin an
instruction-by-instruction
manner.
Your applicationprogrammusthaveat least12bytesof stackavailablefor the iSDM
monitor to use. Ifyou are operaîingin protectedmode,eachtaskin your programmust
containat least12bytesof stackat privilegelevel0 for the iSDM monitorto use.
Whenyou are single-stepping
you shouldbe awareof somespecial
instructions,
considerations.Seethe ISDM S1,sîem
DehugMonitor User'sGuide îor more information
aboutthesespecialconsiderations
whenusingthe N command.
A-6
iSDM" Sysfeml)ebugger
iSDM" MONITOR CONI]!IANI)S
4.3.12O-PortOutput
The o commandallowsyou to enterdata(a byteor word) at the consoleand sendit to a
port you select.
4.3.13P-Print
The P commandallowsyou to displayeitherthe valueof an expression
or the valueof the
base(or selector)and offsetportionsof an address.The valuesare tJisplayed
on your
consoleterminalscreen.The iSDM monitoralwaysdisplaysan addressin hexaclecimal
form. Ifyou enter"P"plusan expression,
the iSDM monitorprintsthe valuein
hexadecimal.
If youenter"Pl-'or "PS"plusan expression,
the iSDM monitorprintsthe
valuein decimalor signeddecimalform, respectively.
In thiscommand,
thecommaactingasa separator
alsocauses
the iSDM nronit.rto adda
spacebetweenthe addresses
or exltressions
it displays.
4.3.14 Q-EnableProtection(80286/80386
Onty)
The Q command changesthe [ì02tlfi-or 803iJ6-based
systemfrom real ntode to protected
mode. The iSDM monitor displaysthe lbllowing mcssagewhen you use rhe e command:
Now in
Protected
Mode
Whenyou invokethiscommand,
the iSDM monitorinitializes
the entriesit needsin the
GDTandthelDT. The iSDM monirorthenplacesitselfat privilege
levelzero. Ifyou are
alreadyoperatingin protectedmodewhenyou invokethis command,the iSDM monitor
re-initializes
the GDT and IDT entries.The onlywayyou canreturn to real mocleis to
resetthe 80286or 80386hardwarc.
iSDM" SystemDebugger
A-7
iSDM* MONITORCOMMANDS
A.3.15R-Loadand Go
of the Loadcommand(L) andthe Go command(G)
The R commandis a combination
systeminto targetsystem
This commandloadsan absoluteobjectfile from a develrrpment
the
iSDM
monitorto discard
program.
This
command
causes
then
executes
this
memory
all previouslyloadedsymbolinformationand load newsymlxrlinformation;however,the
symbols.Your systemmustincludean attached
iSDM monitorretainsall user-defined
systemin order to usethis command.
development
The iSDM monitorloadsthe datafrom the file into the memorylocalionthat you specified
whenyou usedthe LOC86or BLD2ttficommands.If the file containsa register
registers
to thevaluesthe file
initialization
record,the iSDM monitorsetsthe appropriate
specifies.
in real-addressing
modules.If you areoperating
The R commandcannotloadrekrcatable
in protected
mocle,
absolute
objectfiles.Ifyou areoperating
mode,youcanloadonlyf1086
youcanloadonly80286bootloadable
(ahsolute)
files.
Whenyou load an 80286objectfile, the iSDM monitorinitializesthe first 40 global
descriptor
table(GDT) entriesfor itsown use.In addition,the iSDM monitorinitializes
any uninitializedinterruptdescriptortable(lDT) entries.Relèr Ío Intel'sMicroproces.sor
ComponentsHandhook,or APX 286 Operatíng
and Peipheral Handhook,Microsy.îtem
descriptortahles.
SystemWiter'sGuidefor more informationaboutthe 80286component's
to thevaluesthe
After the iSDM monitorloadsthefile andsetsthe appropriate
registers
file specifies,
it beginsto executethe programat the locationspecifiedby the CS and IP
regrsters.
Your applicationprogrammusthaveat lcast l2 bytesof stackavailablefor the iSDM
monitorto use. Ifyou areoperating
in protected
mode,eachtaskin yourprogrammust
containat leastl2 bytesof stackat privilege
level0 for the iSDM monitorto use.
A.3.16 S-SubstituteMemory/Descriptor
TableEntry
The S commandis actually
two commands
in one. You canuseit to displayand
(optionally)modifoeitherthe contentsof memoryor the contentsof descriptortable
entries.If you areoperaîing
in realmode,voucannotdisplayand modi! descriptor
tabÌe
entries.However,ìf ycluare operatingin protectedmode,you canuseboth functionsof
thiscommand.
A-8
iSDM" SystemDebugger
iSI)M* I\fONITOR CONII\'IANI)S
If you enterthe S commandwithoutan equalsign( = ), the |SDM monitordisplays
a
specialhyphen(-) prompt. Then,it waitsfor you to entereither
o A continuation
commainstructing
the iSDM monitorto tlisplaythe nextmcnìory
location.
.
A singleexpression
or a list of expressions
(/). By enteringan
separatedby slashes
expression
(or expressions),
you instructthe iSDM monitorto substitutethesevaluesin
placeof thosealreadyin the memorylocationyou specified.
The iSDM monitorcontinues
to issuehyphenpromptsuntilyou enterî carriagereturn.
4.3.17 X-Examine/Modify
Registers
The X commandallowsyou to examine
and(optionally)
rrodifythe contents
of your
system's
NPX antlmicroprtress,tr
rcgislcrs.
If you usethe X commandwith no parametcrs,
the iSDM ntonitordisplays
all ol the 8(Ìbo,
286,and 386registers.
If you useboththe registernameandan expression,
(for exrmple,CS = XXXX), thevalue
you entered(XXXX) is placedin the specifiedregister.
You can usethe X commandto setthe tl0tl6familyand NPX registerslnd the taskstate
segment
contents
to anyvalue.lfyou usedanyinvalitlvalues.
the iSDM monitorreports
them whenyou executethe applicationprogram.
4.3.18 Y-Symbols(80286or 80386Only)
The Y commandallowsyou to rJisplay
and definesymbolinformationgeneratedby 8028tr
translators.
If you usethe Y command
with no parameters,
the iSDM monitordisplays
all
the symbols
storedin thecurrentdomainmoduleor in all modulesif yousetno domuin.
You canalsochooseto havethe iSDM monitordisplaythe symbols
andtheirvaluesin a
particularmoduleor you can usethiscommandto defineyour own symbols.To usethis
command,
you mustbe operating
in protected
mode,with an attached
development
system.
iSDM" SystemDebugger
A-9
APPENDIX
B
D-MON386
COMMANDS
8.1 INTRODUCTION
This appendixbrieflydescribes
rhe 80386DebugMonitor (D-MoN3tì6) commancls
in
alphabetical
order. A commanddirectorylistingthe functionalgroupsand pagereferences
precedesthe commanddev:riptions.For examples
and more detailedinformationabout
the commands,seethe D-MONJ86DebugMonitorfor the 8038óllser'sGuide.
8.2 ENTERING
COMMANDS
To enterD-MON386commands,
followthe gui
)
key. A commandline canconsistof one or more commands.
.
Separatemultìplecommandson a singleline usinga semicolon(;).
o
Continuecommandsfrom one line to anotherby enteringthe slash(/) just before
terminatingthe line with rhe ENTER key or RETURN key.
.
Enter commandsusingupperor lowercasecharacters.
o
Use CTRL-C (pressingthe controlkey downwhile at the sametime pressingthe C
key) to aborta commandbeingconstructed
on the commandline.
D-MON3EóSystemDebugger
B-l
I)-MON386COMMANDS
DIRECTORY
8.3 COMMAND
This sectionprovidesa brief summaryof all D-MON386commandslistedby functions.
contains
alongwith thecommandnamea brief
Eachentryin thc followingsummary
descriptionof the commandand a pagereferencewhereyou canfind more informationon
thecommantl.
Page
FunctionPerformed
Command
BI-OCK
C O U N T / E N D C O U N TP r o v i d e s m o l ì i t o r c o m m a n d c o n t r o l
These structures enabÌe you
structures.
to enLer and repeat execution of several
cornmands
nonitor
B-5
CONTROLVARIABLES
BASE
N0-N9
$
Display or set the base nurnber system to
to either binary, octal, decimal , or
hexadecirnal
Display or set scratch registers zero
through nine...
Display or set the current execution point..
B-5
B-B
B-5
DISPLAY
EXPRESSION
EVAL
EvaLuates an expressíon
resul ts
and dispì-ays
the
8-6
EXECUTIONENVIRONMENT
G0
ISTEP
SWBREAK
ShREMOVE
B-2
Controls high-1evel execution environment. . .
EnabLes single step execution.
D i s p l a y s a n d s e t s s o f t w a r e c o c l eb r e a k s . . . . . .
Removes software code breaks.
B-1
B-8
B-9
B-10
D-MON3116
SystemDebugger
I)-MON3II6COMMANI)S
Command
FunctionPerformcd
Page
DESCRIPTORTABLE ACCESS
GDT
LDT
IDT
DT
Displays
specific
Displays
specific
Displays
specific
Displays
tabÌes.
the clobal Descriptor Table or
entries
the Local Descriptor Table or
entries.
the Interrupt
Descriptor Table or
entries
the Global or Local Descripror
B_1
B-g
B_7
ts_6
MEMORY ACCESS
ASM
BYTE
DWORD
INTn
ORDn
USE
WORD
Disassembles memory as 80386 assembler
mnemonrcs
Reads or writes bytes of memory.
Reads or writes double words of menory. ..
Reads or writes 1- , 2,, ot 4-byte integers
in memorl/.
.
Reads or \rrites 1 , 2-, or 4 byte ordinaÌs
in memory.
..
Initializes
the default for disassembling
code ro L6-bir or 32-bit.
Reads or writes rvorclsof nemory.
B _5
B-5
8-6
B _7
B_g
B-10
B-10
PAGE TABLE ACCESS
PD
Displays the Page Table Directory
table entri es
D-MON.l8óSystemDebugger
or page
B_g
Ir-3
D-MON38óCOMMANDS
Page
FunctionPerformed
Commancl
PoRTr/O
DPORT
PORT
WPORT
Reads or wrítes
Reads or \trites
Reads or writes
B 6
B-9
B-11
32-bit ports..
8-bit ports..
16-bit ports. .
REGISTERACCESS
CRECS
FLAGS
Register-name
RECS
SRECS
Disptays
Displays
register
Displays
Displays
group. .
Displays
the control registers
the lower 16 bits of the EFI-A.GS
in nnemonic form.,.
registers. . .
or modifies lndividual
as a
s
e
l
e
c
t
e
d
r
e
g
i
s
t
ers
a set of
the segmerìt registers
as a group...
8-6
B 6
B-9
B-9
B-9
TASK STATE SEGMENT ACCESS
TSS
Disptays the contenls
segment.
of
a task
state
B-10
USER AID
B
HELP
HOST
VERSION
Executes
Displays
Provides
P M O Nh o s t
DisDlavs
a real mode incerface program......
the help screen.
the capabiliLy for operation wiLh
software.
Lhe version of D-MON386
B-5
B-l
B-l
B-10
DESCRIPTIONS
8.4 COMMAND
brief cìescriptions
for D-MON3fificommandsin an easilyreferenced
This sectionprovicles
alphabetical
order. For on-linesyntaxhelp,referto the HE,LPcommand.For more
Dehug
syntax,and options,refer to the D-,ttON-18ó
informationon commandparameters,
Mottitorfor tlrc 8038(tUser'sGuitle.
B-rl
D-MON3tl6SystemDebugger
D-MON3116
COMMANI)S
8.4.1 $
This commanddisplaysor modifiesthe currentexecutionpoint via the executionaddress
register(CS:ElP). The contentsof CS:EIPdeterminewhichASM3tì6statementexecutes
next. Entering$ by itselfdisplaysthe currentcontentsof CS:EIP.
8.4.2 ASM
This commanddisassembles
codeinto ASM386opcodemnemonics.Usingthis command
you supplywith it, you candisassemble
and the addresses
from one to severallinesof code.
Disassembled
codeappearson the screenin columnform. Eachrow of columnscontains
an address,a hexadecimal
objectvalue,an opcodemnemonic,anyoperands,and
commentsappendedto the operands.
8.4.3 B
This commandinvokesa user-supplied
real modeinterfaceprogram.The B commandis
intendedprimarilyfor includinga bootstraploatJerprogram.
8.4.4 Base
This commanddisplaysor modifiesthe numberbase.Availablenumberbasesinclude
baseis the monitordefaultbase.
binary,octal,decimal,and hexadecimal.
The hexadecimal
EnteringBASE by itselfdisplaysthe currentbase.EnteringBASE followedby an
to 2, 8, 10,or 16(all tlecimalnumbers)setsthe baseto binary,
expression
that evaluates
octal,decimal,or hexadecimal,
respectively.
B.4.5 Byte
This commanddisplaysor modifiespartitionsof memoryusinga byteformat. You can
specifythe partitionasa singlebyteor a rangeof bytes.Enteringthe commandBYTE
causesthat partitionof memoryto appearon
followedby an addressor rangeof addresses
the screen.Enteringthe commandBYTE asan equationcausesthe partitionof memory
on the left sideof the equationto be replacedwith the contentsof memoryor valueof the
right sideof the equation.
8.4.6 Count/Endcount
groupsof D-MON386commandsin a specifiedorder for a
This commandexecutes
specifiednumberof times. After enteringCOUNT expr,simplyenterin commandsyou
wishto execute.After enteringENDCOUNT,one iterationof the commandswill have
alreadybeenexecuted.The entiregroupof commandsthencontinuesto executefor expr1 numberof times.
D-MON386SystemDebugger
B-5
D.MON38óCOMMANDS
8.4.7 Cregs
This commanddisplaysthe contentsof the controlregistersand the EFI-AGSregister
whenthe processoris in real mode. lf the processor
is in protectedmode,the CREGS
commandalsodisplaysthe systemaddressregistersTR and LDTR. The displayappears
numberbase.
usinea hexadecimal
8.4.8 Dport
This commandreadsor writesa 32-bitport. EnteringDPORT with the physical
input/outputaddressspaceasa l6-bit unsignedquantitycausesthe specifiedport to be
readand the contentsto appearon the screen.If you supplyan expression
to the right of
the equalsignwhenenteringthiscommand,the addressed
port is writtenwith the value
the expression
equals.
8.4.9 DT
This commanddisplaysdescriptors
from eitherthe LDT or the GDT dependingupon the
indexsuppliedwith îhe commanct.
B.4.10Dword
This commanddisplaysor modifiespartitionsof memoryusinga doubleword format. You
can displaya specificdoubleword or a rangeof doublewordsby enteringDWORD
followedby the singleaddressor the rangeof addresses.
Enteringthe DWORD command
asan equationcausesthe partitionof memoryspecifiedon the left-handsideof the
equationto be replacedwith the contentsof memoryor valueof the right-handsideof the
equation.
8.4.11Eval
This commandevaluates
the expression
enteredin after the kepvordEVAL. The results
of the expression
appearon the screenin binary,octal,decimal,hexadecimal,
and ASCII
formats.
8.4.12Flags
This commanddisplaysthe contentsof the lower 1óbits of the EFI-AGSregister.The
displayappearsin a mnemonicform. The presence
of a mnemonicindicatesa flag is set.
The absenceof a mnemonicin the disnlavindicatesa flaqis not set.
B-6
I)-MON3lt6SystemDebugger
D.MON]116COMMANDS
8.4.13GDT
This commanddisplaysthe entireGlobalDescriptorTable(GDT) or individualGDT
GDT by itselfcausesthe entireGDT to appear.
descriptors.Enteringthe key"lvord
EnteringGDT followedby an indexexpression
causesa specificdescriptorto appear.
8 . 4 . 1 4G o
This commandsupplieshigh-levelexecutioncontrol. Use of the GO commandenablesyou
to beginand end programexecutìonusingspecificpointsin the application.You canalso
clearand specifybreakconditionsusingthe GO command.
8.4.15 Help
This commanddisplaysthe major D-MON3lì6commandsalongwith their generalsyntax.
For examplesand more detailedinformationaboutthe commands,seetheD-MON38ó
DebugMonitorfor the 80386User'sGuide.
8.4.16Host
This commandprovidesthe capabilityfor operationwith PMON hostsoftware.When
enteringthis command,be sureto pressonly the E,NTERkey or a carriagereturn
immediatelyafter HOST.
8.4.17IDT
This commanddisplaysthe entireInterruptDescriptorTable(lDT) or individualIDT
descriptors.Enteringthe kepvordIDT causesthe entireìDT to appear.EnteringIDT
followedby an indexcausesa specificdescriptorfrom the IDT to appear.
8 . 4 . 1 8l N T n
This commanddisplaysor modifiespartitionsof memoryusingan integerf ormat. When
youcansubstitute
the numbers1,2,or 4 for n. Thus,the integer
enteringthecommand,
type(s)referencedin memoryare either 1-,2-,or 4-byteintegers.You can specifythe
partitionasa singleINTn valueor a rangeof INTn values.Enteringthe commandINTn
causesthat partitionof memoryto appearon
follo'xedby an addressor rangeof addresses
the screen.Enteringthe commandINTn asan equationcausesthe partitionof memoryon
the left sideof the equationto be replacedwith the contentsof memoryor valueof the
right sideof the equation.
D-MON3E6SystemDebugger
B-7
D-MON386COMMANDS
8.4.18lstep
This commandperformssingle-step
execution.You canusethis commandto single-step
throughthe executable
one
statements.ISTEPalsoprovides
codefrom
to 255executable
the capabilityto beginexecutionfrom a point otherthanthe currentexecutionpoint.
B.4.19LDT
This commanddisplaysthe entireLocalDescriptorTable(LDT) or individualLDT
descriptors.Enteringthe keyrvordLD f causesthe entireLDT to appear.EnteringLDT
followedby an indexcausesa specificdescriptorfrom the LDT to appear.
8.4.20 N0-N9
This commanddisplaysor altersscratchregisterszero throughnine. EnteringNn (wheren
is a number0 through9) by itselfcausesthe valueof the appropriateregisterto appeuron
the screen.You canenterNn followedby an equalsignand an expression
to alter the
contentsof the appropriatescratchregister.
8.4.21ORDn
This commanddisplaysor modilìespartitionsof memoryusingan ordinalformat. When
enteringthe command,
youcansubstitute
the numbers1,2,or 4 for n. Thus,the ordinal
type(s)referencedin memoryare either l-, 2-,or 4-byteordinals.You canspecifythe
partitionas a singleORDn valueor a rangeof ORDn values.Enteringthe command
ORDn followedby an addressor rangeof addresses
causesthat partitionof memoryto
appearon the screen.Enteringthe commandORDn asan equationcausesthe partitionof
memoryon the left sideof the equationto be replacedwith the contentsof memoryor
valueof the right sideof the equation.
8.4.22 PD
This commandexaminesthe PageTableDirectoryand pagetables.When pagingis
enabled,the 80386usestwo levelsof tablesto translatea linearaddressinto a physical
address:the PageTableDirectoryand the pagetablesthemselves.Enteringthe PD
commandby itselfcausesthe entire4K PageTableDirectoryto scrollto the screen.You
can,however,supplyan indexwith the PD commandto viewa particulardirectoryentry
within the PageTableDirectory.Also,you canusethe additional,PT optionwith an index
to view a particularpagetahleentry.
B-8
D-MON-1t|6
Sysfem Debugger
D.MON38óCOMMANDS
8.4.23 Port
This commandreadsor writesa 8-bitport. EnteringPORTwith the physicalinput/output
addressspaceasa 16-bitunsignedquantitycausesthe specifiedport to be readand the
contentsto appearon the screen.Ifyou supplyan expression
to the right of the equalsign
whenenteringthis command,the addressed
port is writtenwith the valuethe expression
eouals.
8.4.24 Register-name
D-MON386enablesyou to displayor alterthe contentsof 80386registers.To gainregister
access,
enterthe nameof the registerEnteringthe nameof the registeronÌycausesthe
contentsof the registerto appearon the screen.Enteringthe nameof the register
followedby an equalsignand a valid expression
causesthe contentsof the registerto be
writtenwith the valueof the expression.For a completelist of registernames,refer to the
u-MON386DebugMonitorfor the 80386User'sGuide.
NOTE
Registermodificationis dependenton the currentprocessorprotectionmodel.
You cannotmodifyprotectedregisters.
8.4.25 Regs
This commanddisplaysthe contentsof a set of registersasa group. The registerset
dependson whichmodethe processoris currentlyoperatingunder(realor protected).
The displayis alwaysin hexadecimal,
and it provideslessdetailfor the segmentand control
that
designedfor thosegroupsof registers,
registersthan the commandthat are specifically
is SREGSand CREGS,respectively.
8.4.26 Sregs
This commanddisplays,
in hexadecimal,
the contentsof the segmentregisters(CS,DS, SS,
ES,FS,and GS).
8.4.27 Swbreak
This commanddisplaysor setscodepatchbreaks.EnteringSWBREAK by itselfcausesall
currentsoftwarebreakdefinitionsto appear.If you enterSWBREAK folÌowedby an
the commandsetsa softwarebreakat the specified
equalsignand one or more addresses,
addressor addresses.
D-MON3EóSyslemDebugger
B-9
D-MON386COMMANDS
NOTE
the addressmustbe ableto be
When specifying
softwarebreakaddresses,
written,presentin physicalmemory,and on an instructionboundary.A
maximumof 16softwarebreaksmavbe in effectat one time.
8.4.28 Swremove
This commandremovesall or selectedcodepatchbreaks.Enteringthis commandfollowed
with the
by ALL removesall currentsoftwarebreaks.If you supplyone or more addresses
command.the softwarebreaksat thoseaddresses
aloneare removed.
8.4.29 TSS
This commanddisplaysthe contentsof a taskstatesegment.TSSsupportsboth 80386and
80286taskstatesegments.Taskstatesegments
appearusingthe componentnames.
8.4.30 Use
This commandspecifiesthe default(16-bitor 32-bitcode)for disassembling
codefrom
physicalor linearaddresses.
Whenenteringthe command,the expression
to the right of
the equalsignmustevaluateto either l6 or 32 (decimal).
8.4.31 Version
This commanddisplaysthe versionnumberof the D-MON386softwareyou are using.
8.4.32 Word
This commanddisplaysor modifiespartitionsof memoryusinga word format. You can
specifythe partitionasa singleword or a rangeof words. Enteringthe commandWORD
followedby an addressor rangeof addresses
causesthat partitionof memoryto appearon
the screen.Enteringthe commandWORD as an equationcausesthe partitionof memrtry
on the left sideof the equationto be replacedwith the contentsof memoryor valueof the
risht sideof the equation.
B-10
D-MON-ì86SystemDebugger
D-MON386
COMN{ANDS
8.4.33 Wport
This commandreadsor writesa 16-bitport. EnteringWPORT with the physical
input/outputaddressspaceasa l6-bit unsignedquantitycausesthe specifiedport to be
readand the contentsto appearon the screen.Ifyou supplyan expression
to the right of
the equalsignwhenenteringthis command,the addressed
port is writtenwith the value
the expression
equals.
D-MON3tì6SystemDebugger
B - tI
INDEX
A
Alteringdescriptortableentries A-8
Altering memorycontentsA-[t, B-5,6, 7, 8, 10
Altering registercontents3-1,1,
A-9, B-8,9
B
Bootloadingfrom the monitor A-3, B-5
BootstrapLoaderDEBUG switch l-3
Breakpoints1-3,3-10,B-9,10
c
Changingcurrentinstructionpointer B-5
Changingdisassembled
code 3-15,16
ChangingdescriptortableentrycontentsA-8
ChangingmemorycontentsA-8, B-5,6, 7, 8, 10
Changingmodes A-7
Changingregistercontents3-14,A-9, B-8,9
Cl-l-restart1-3,2-3,3-10
Codeblocks,displaying3-12,ló
Commands
D-MON386B-l
Directory 2-4
iSDM" A-1
Overview 1-3
Synta\ for debugger l-3
Tokenvalidity 2-l
vB 2-5
vc 2-9
vD 2-12
vF 2-14
vH 2-16
vJ 2-18,3-18
YK 2-22
YO 2-24,3-t7,
t8
vR 2-27
SystemDebugger
lndex-.1
INDEX
Commands (cont.)
vs 2.31
w 2-36,3-17,18
vu 2-62,3-19
Comparingblocksof memory A-4
Configuration1-2
Contentsof the stack 2-31
iv,2-1
Conventions
Copyingblocksof memory A-6
Currentinstruction,displaying3-11,B-5
D
D-MON386monitorcommanddirectoryB-2
D-MON386monitorcommandoverviewB-1,5
D-MON386monitorcommands
$ B-5
Asm B-5
B B-5
Base B-5
Byte B-5
Count/EndcountB-5
Cregs 8-6
Dport 8-6
DT 8-6
Dword 8-6
Eval 8-6
Flags 8-6
GDT B-7
Go B-7
Help B-7
Host B-7
IDT B.7
INTn B-7
Istep B-8
LDT B-8
N0-N9 B-8
ORDn B-8
PD 8.8
Port B-9
Registername B-9
Regs B-9
SregsB-9
SwbreakB-9
Index.2
SystemDebugger
INDEX
D-MON386monitorcommands(cont.)
SwremoveB-10
SyntaxB-l
TSS B.1O
Use B-10
VersionB-10
Word B- l0
Wport B-11
Deadlock3-17
DEBUG command1-2,3-10
Debugsession,
sample3-1
Descriptortables,displayingA-4, 8-6, 7,8
Determiningthe baseand offsetof an addressA-7
code,displaying3-15,A-4, B-5, l0
Disassembled
Displayingblocksof code 3-12,A-4
DisplayingsymbolinformationA-9
Displayingthe numberbase B-5
DUIB information,displaying2-5
E
Echoingconsoleoutput A-5
ES registerlimit, checking3-14
Examininga mailbox 3-18
Examiningpagetabledirectoryand tablesusingD-MON3[ì6 B-fì
Examiningregistercontents3-12,13,8-6, 9
Examining
stackcontents3-19
Exampledebugsession3-l
Executinga program 3-14,15,A-5, 8, B-7
Executinga sing.le
line of code 3-13,A-ó, B-8
Exitingthe monitor A-4
Expression
evaluationA-7, 8-6
F
Findingtext A-5
G
GDT slots,displayingfree amount 2-14
Gettinghelp 2-16,B-7
H
requirements1-2
Hardware/Software
Help 2-16,B-7
SystemDebugger
lndex-3
INDEX
I
I/O ResultSegment(IORS) 2-27
Identifuingsystemcallparameterson the stack 2-31
Interpretingsystemcallparameterson the stack 2-31
Invocation1-2,3-10
IORS,displaying2-27
ISDM* monitorcommanddirectoryA-1
ISDM' monitorcommandoverviewA- 1
ISDM" monitorcommands
B - bootstrapload A-3
C - compareA-4
D - Display3-11,A-4
E - exit A-4
F - find A-5
G - go 3-10,14,15,A-5
I - port input A-5
K - echofile A-5
L - load A-6
M - move A-ó
N - singleinstructionexecution3-13,A-ó
O - port output A-7
P - print A-7
Q - enableprotectionA-7
R - load and go A-8
S - substituteA-8
X - examine/modify3-12,13,14,A-9
Y - symbols A-9
J
job tokens,displaying2-18
Job and descendent
L
Loading object files A-6, 8
Locatingrunningtasks 3-20
Loopingwithin D-MON386 B-5
M
Mailboxexamination3-18
ManualOverviewiii
Modi$ringthe numberbase B-5
Mode changìngA-7
Monitor 1-1
Index-4
SystemDebugger
INDEX
Monitorcommands
iSDM" A.1
D-MON386B-1
Movingblocksof memoryA-6
o
Object directory,displaying 2-12
Objects,displaying 2-24,3 -18
P
Ports
Displayingdata A-5, 8-6, 9, 11
Enteringdata A-7, 8-6, 9, 1l
Productoverviewiii, l-1
Programcodeexecution3-l3
o
Quittingthe debuggerl-4, A-4
R
Re-enteringthe iSDM" monitor 3-10,l5
Readerlevel iii
Redirectingconsoleoutput A-5
RemovingBreakpoints
with D-MON3U6B- 10
Registercontents,examining3-12,13
Returningto your applicationl-4
s
Sampledebugsession3-l
Searching
for text A-5
Settingbreakpointsl-3, 3-10,B-9
Single-step
executionA-6, B-8
Stackcontents2-31,3-19
Startingthe debugger1-2
Strings,displaylimitations2-35
Support 1-2
Symbolinformation,displayingA-9
Syntaxfor D-MON38(rcommandsB- I
SystemDebugger
Index-5
INDEX
Syntaxfor debuggercommands1-3,2-2
displaying
2-9
callinformation,
System
Systemcall parameterson the stack,clisplaying2-31
Systemrequirements1-2
T
Tasksystemcalls,displaying2-62
Tasktokens,displaying2-22
Tokens,displaying2-36,3-1tl
U
UsingPMON hostsoftwarewith D-MON386 B-7
Usingthe debuggerl-3,3-9
v
VB command2-5
VC command2-9
VD command2-12
Versionnumberof D-MON386,displayingB- lt)
VF commanti2-'14
VH command2-l6
VJ command2-18
VK command2-22
VO command2-24,3-17
VR command2-27
VS command2-31
VT command
Bufferpool display2-60
Compositeobjectdisplay2-47
Extensionobjectdisplay2-47
Job display2-37
Mailboxdisplay2-42,3-1Íl
Regiondisplay2-45
Segmentdisplay2-46
Semaphoredisplay2-44
Taskdisplay2-39
VT command2-36
VU command2-62
w
Warm-start 1-3,2-3
Index-6
SystemDebugger
E X T E N D EiD
RMX@II
D I S KV E R I F I C A T I O N
CA
EN U A L
U T I L I TR
Y E F E R E NM
I n t e lC o r p o r a t i o n
3 0 65 B o w e r sA v e n u e
5 an t a c l a r a c, al i f o r nr a9 5 0 5 1
C o p y r i g h 't' 1 9 8 8 ,l n t e l C o r p o r a t r o nA, l l R r g h t sR e s e r v e d
PREFACE
INTRODUCTION
tool thatrunsasa HumanInterface
Utilityis a software
The iRMX II DiskVerification
of iRMX namedand physical
the
datiì
structures
commandverifyingand modifying
volumes.
of all utility
descriptions
the utility invocationand containscìetailed
This manualdescribes
volume
of backingup andrestoring
the iRMX Il capability
commands.It alsodocuments
file descriptornodes(fnodes).
of iRMX namedvolumesasusersmustbe
the structure
In addition.the manualdescribes
Utility.
of the DiskVerification
to usethe full capabilities
familiarwithvolumestructure
READERLEVEL
of the operating
whtt havean understanding
This manualis intendetlfor programnrers
layers.To usethis
and HumanInterface
the Basicl/O System
andparticularly
system,
volume
structure.
with
iRMX
shoulcl
be
familiar
programmers
manualeffectively,
a briefrevicwof iRMX namedvolumestructure.However,thisis
AppendixA provides
anclnot asa tuttlrial.
intendedasa reference
MANUALOVERVIEW
Thismanualis organizedasfollows:
ChapterI
Disk Verification
This chapter describestwo ways of invoking the Utility: sing.l€command mode or interactivemode. It explainssingle-command
mode and how to interpret output and error messagesfrom the
single-commandverification. lt also describesthe invocation in
interactivemocleand the interactivemocleerror messages.
C o m m a n d sf o r t h e i n t e r a c t i v em o d e a r e e x p l a i n e di n C h a p t e r2 .
|ll
PREFACE
Chapter2
of the Disk Verification
This chaptercontainsdetaileddescriptions
discussed
in alphabetical
Utility commands.The commandsare
order. Whenverifyinganclmodifyingvolumes,vou shouldrefer to
this chapterfor specificinformationaboutthe format and
parametersof the commands.
Chapter3
This chapterexplainsthe fnodebackupand restorefeaturein
detail. This featureprovidesa limitedmechanismfor attempting
to recoverdatawhenthe volumelabelor the fnodefile hasbeen
damaged.
AppendixA
This appendixprovidesinformationon the format of iRMX named
volumes.lt includesdetailsof the volumelabeland fnodefile,
betweenlongand shortfiles,and format information
differences
specificto diskettes.Programmers
shouldbe familiarwith this
informationbeforeattemptingto modifya volume.
CONVENTIONS
Thismanualusesthe following
conventions:
.
whenshownin keyboard
Informationappearingas UPPERCASEcharacters
examplesmustbe enteredor codedexactlyasshown.You may,however,mix lower
whenenteringthe text.
and uppercase
characters
.
Fieldsappearingaslowercase
characters
within anglebrackets( < > ) whenshownin
keyboardexamplesindicatevariableinformation.You mustenteran appropriate
valueor symboltbr variablefields.
.
User input appearsin one of the followingforms:
as bolded
lv
text
\ríthin
a screen
.
text is usedto indicatethe first occurrence
of eachcommanddescribedin
Chapter2; subsequent
occurrences
are printedin blackink.
.
The terms"iRMX II. and "OperatingSystem"refer to the ExtendediRMX II
OperatingSystem.
.
The term "ìRMX I'refers to the iRMX I OperatingSystem(ìRMX 86 Operating
System).
.
All numbersunlessotherwisestatedare assumedto be decimal.Hexadecimal
numbersincludethe "H" radixcharacter(for example,OFFIì).
Disk Verification
CONTENTS
CHAPTER1
OISKVERIFY
INVOKING
PAGE
CHAPTER2
DISKVERIRY
COMMANDS
PAGE
Disk Verilication
CONTENTS
CHAPTER2 (continued)
PAGE
CHAPTEF3
PAGE
APPENDIX
A
PAGE
vl
Disk Verification
CONTENTS
APPENDIX
A (continued)
PAGE
TABLES
PAGE
TABLE
A-1
8-lnchDisketteCharacteristics...
5 1/4-lnchDisketteCharacteristics
.............4-21
........4-22
F IG U R E S
FIGURE
a i
a a
l-t
2-4
t <
A-t
A-2
Disk Verification
Yll
CHAPTER
1
INVOKINGDISKVERIFY
1.1 INTRODUCTION
When usingan iRMX lI applicationsystem,you will needto storedataon secondary
storagedevices.Unfortunately,occasional
powerirregularities
or accidentalresetmay
destroythe indexto the dataon thesedevices,makingthe informationinaccessible
to the
system.In somecases,
losingevcna smallamountof datacan renderan entirevolume
useless.
You needa tool to examineand fix the damagedvolume. This tool shouldenableyou to
determinehow muchof the datawasdamagedand helpyou recreatefile structureson the
damagedvolume. The iRMX II Disk VerificationUtility (DISKVERIFY) is a tool that
enablesyou to verify the consistency
and recoverdamageddataon iRMX volumes.
The Disk VerificationUtility inspects,
verifies,and correctsthe datastructuresof iRMX
namedvolumes.It canalsoverifoan iRMX physicalvolume. The Disk Verification
Utility canreconstructthe fnodefile, the volumelabel,the file descriptornodes(fnodes)
map,the volumefree spacemap,and the bad blocksmap of the volume. In addition,with
DISKVERIFY you canmanipulatefnodes,bad trackinformation,and the actualdataon
the volumes.The Disk VerificationUtility alsosupportsauto-volumerecognitionwhich
meansyou canveri! anyiRMX namedvolumewithoutdetachingand attachingthe
devicewith the correctDUIB.
You can useDISKVERIFY in one of two ways:
o As a singlecommandthat verifiesthe structuresof a volumeand returnscontrolto
the Human Interfàce
o
As an interactiveprogramthat enablesyou to checkand modifydataon the volume
by enteringdiskverificationcommands
To take full advantage
of this utility,you mustbe familiarwith the structureof iRMX
(eitheriRMX I or iRMX II asthevolumestructure
is almostthe samefor both)named
volumes.AppendixA containsdetailedinformationaboutvolumestructure.If you are
unfamiliarwith the iRMX lI volumestructure,you shouldavoidusingthe DISKVERIFY
commands.Somecommands,
if not usedcorrectly,can renderyour volumesunusable.
However,evenifyou knownothingaboutiRMX volumestructures,
you canstill usethe
Disk VerificationUtility asa singlecommandto verifythat the datastructureson an
iRMX volumearevalid.
Disk Verification
l-l
INVOKING DISKVERIFY
1.2 TNVOCATTON
To invokeDISKVERIFY, enterthe followingcommand:
where:
t-2
:logicalname:
Logicalnameof the secondary
storagedevicecontainingthe
volumeto be verified.
TO
Copiesthe outputfrom the Disk VerificationUtility to the file
specifiedin OUTPATH. If no "TO" is specified,output is directed
to the consolescreen(:CO:).
OVER
Copiesthe outputfrom the Disk VerificationUtility overthe
specifiedfile.
AF'TER
Copiesthe outputfrom the Disk VerificationUtility beginningat
the en
Vx.x
1 R M XI I D i s k V e r i f y U t i Ì i t y ,
Copyright Intel Corporation
At the asteriskprompt,you canenteranyof the DISKVERIFY commandslistedin the
DISKVERIFY COMMANDS chapterof this manual.If you enteranythingelse,the
utility will displayan error message.
NOTE
Althoughyou canuseDISKVERIFY to veriff the systemdevice(:sd:),
note that all connections
to this deviceare deletedby the operatingsystem.
After exiting,you must reboot the systemor usethe warm start feature
(see the Extended|RMX II SystemDebuggerRet'erenceManual).
1.4 INVOCATION
ERRORMESSAGES
The followingis a list of error messages
you mightencounterwheninvokingthe Disk
Verification Utility.
l-6
argumenterror
The optionspecifiedis not valid.
, invalidlogical
name.
The logicalnamedoesnot exist;was
longerthan 12characters;contained
invalidcharacters;
or wasmissinga
matchingcolon.
0045: E$LOG NAME NEXIST
or .logical
name
doesnot exist
A nonexistent was
specified
in eitherihe:logical
name:or
outpathparameter.
0038:
E$ALREADY_ATTACHED
The outputwasdirectedto a file on the
volumebeingverified.
commandsyntaxerror
A syntaxerror wasmadewhen entering
the command
Disk Verilication
INVOKING DISKVERIFY
< logicalname>, outstanding
connectionsto the devicehave
beendeleted.
Thiswarningis not fatal andwilì occur
everytime you try to verifu the system
deviceor anyothervolumeon whichfiles
havebeenattached.
< log.icalname> or < outpath> .
invalid wildcard specification
The logicalnameor outputpathname
containeda wildcardcharacter
< logicalname> , can'tattach
device
The devicecannotbe attachedand read.
sizein
devicesizeinconsistent
=
volumelabel :
computedsize= < value2>
When the Disk VerificationUtility
computedthe sizeof the volume,the size
it computeddid not matchthe
informationrecordedin the iRMX II
volumelabel. The volumelabelmay
containinvalidor corruptedinformation.
Thisis not a latalcrrttr,hut it is an
indicationthat furthererror conditions
mayresultduringthe verificationsession.
You may haveto reformatthe volumeor
usethe Disk VerificationUtility to
restorethe volumelabel.
not a named disk
A NAMED, NAMEDl, or NAMED2
verificationwasrequestedfor a physical
volume.
< partiallogicalname>,
0081:E$STRING_BUFFER
The logicalnamewaslongerthan 14
in length,not includingcolons.
characters
< logicalname> , devicedoesnot
belongto you
An attemptwasmadeto verify a device
that wasattachedby anotheruser. For
example,the systemdeviceis :SD:and
USER is not the superuser.
< logicalname> , devicesizeis
zeÍo
The logicalnameentereddoesnot deline
a massstoragedevice.For example,you
cannotperformDISKVERIFY on a line
printer.
Disk Verification
r-7
CHAPTER
2
DISKVERIFY
COMMANDS
2.1 INTRODUCTION
Whenthe DiskVerification
(*) prompt,youcanenter
Utilityissues
the asterisk
infurmation
on thevolume.
DISKVERIFYcommands
to examine
or changefile structure
This processusuallyinvolvesreaclinga portionof the volumeinto a buffer,modiryingthat
buffer,andu'ritingthe informationbackto the volume. This chlpter describes
the
commands
thatenablevouto perfbrmthescoperations.
The commands
ìn thischapterarepresentcrl
in alphabetical
orderregardless
of their
function.The onÌyexception
is whentwo commancis
aresimilar,suchasDISPIAYBYTE
in its alphabetical
and DISPLAYWORD.In thiscase,the lirstcommantlis explained
order,andthe second
comnrancl
followsit with onlythe differences
described.
on the
The firstoccurrence
of eachcommandn:rmeis printedin blueink andappears
outsitleuppercornerof the page;subsequent
occurrences
are printedin blackink. Blue
or boldedtextis alsousedto indicatean entryvou makefromvourterminaÌ.
the individual
commancls,
thischapterdiscusses
commandsyntax,
Beforedescribing
It alsoprovides
a
commandnames,parameters,
inputradices.
anclerrormessages.
gives
commund
and
the
page
number
commanddictionary
that
a hriefdescription
of each
on whichthecommancl
is founcl.
2.2 COMMANDSYNTAX
in this chapter is presentedin a "railroad track'
The syntaxfor each commanclclescribeci
schematic,with syntiìcticelemeiltsscatteredalong the track. Your entrance to any given
schematicis alwaysfrom lcfì to right, beginningwith the command name entry.
Elements shown in uppercasechuractersmust tre typed in a comnrandline exactlyas
s h o w ni n t h e s c h e m a t i ch, o w e v e r y, o u m r y e n t e r t h c m i n e ì t h e r u P l ) e r c a soc r l o w e r c a s e .
Syntacticelementsshown in lowercasearc qeneric terms, which meansyou must supply
t h e s p e c i f i ci t e m , s u c ha s t h e p a t h n a n r eo l a f i l e .
Disk Verifìcation
2-l
DISK VERIFYCOMMANDS
"Railroadsidings"go throughoptionalparameterelements.In somecases,you havea
oneof several
sidings
before
returning
to themaintrack.In still
choice
of goingthrough
othercases,the maintrack itselfdivergesinto two separatetracks,whichmeansyou must
selectone trackor the otherbut not both. For example,a commandthat consistsof a
wouldlook like this:
commandnameand two ontionalnarameters
C O MM A N D
p a r a ml
F0213
You can enter this command in any one of theseforms:
The arrowsare usedhereto illustratethe possibleflow throughthe tracks.They do not
appearin the schematics
in the rest of this chapter.
2.3 COMMAND
NAMES
Whenyou entera DISKVERIFY command,you canenterthe commandnameor its
abbreviation(listedin this chapter),or you canenteranyuniqueportionof the command
name. For example,whenspecifying
the DISPLAYFNODEcommand,you can enterany
of the followins:
You canalsoenteranyotherpartialform of the word DISPLAYFNODEthat containsat
leastthe characters
DISPIAYF.
4 , .
Disk Verification
DISKVERIFT COMMANDS
2.4 PARAMETERS
SeveralDISKVERIFY commandshaveoarametersdescribedasbeine in this form:
in this form:
You canalsoentertheseDarameters
For example,both of thesespeci! a FREE command:
2.5 INPUTRADICES
format. You can
DISKVERIFY alwaysproducesnumericaloutputin hexadecimal
provide input to DISKVERIFY in any one of the following three radicesby includinga
are
radixcharacterimmediatelyafter the number.The valid radixcharacters
radix
character
example
hexadecimal
horH
16h,7CH
decimal
t or T
23t, 1007
octal
o, O, q, or Q
27o,33Q
the numberis hexadecimal.
If you omit the radixcharacter,DISKVERIFY assumes
Disk Verification
2-3
DISKVERIFY COMMANDS
2.6 ABORTINGDISI(\/ERIFY
COMMANDS
You canabort the followingDISKVERIFY commandsby enteringa CONTROL-C,
whichterminatesthe commandand returnscontrolto the Disk VerificationUtilitv lnot
the Human Interfacecommandlevell.
DISK
DISPT-AYBYTE
DISPI-AYDIRECTORY
DISPI.A,YFNODE
DISPT-AYNEXTBLOCK
DISPI-A,YPRE\'IOUSBLOCK
DISPI-A,YWORD
EDITFNODE
EDITSAVEFNODE
FIX
GETBADTRACKINFO
LISTBADBLOCKS
SUBSTITUTEBYTE
SUBSTITUTEWORD
VERIFY
2.7 DISKVERIFY
ERRORMESSAGES
EachDISKVERIFY commandcangeneratea numberof error messages,
whichindicatc
errorsin the way the commandwasspecifiedor problemswith the volumeitself. The
followingmessages
canbe generatedby manyof the commands(eachcommand
descriptionliststhe error messages
generatedby the particularcommand):
2-4
blockI/O error
The utility attemptedto reador write a blockon the
volumeand foundthat the blockwasphysically
damagedand therefore,couldnot completethe
requested
command.Or, an attemptwasmadeto
write a blockto a diskvolumethat is write
protected.The error message
stateswhetherread
or write wasperformedand the numberof the
hlockcausing
the error.
commandsyntaxerror
A syntaxerror wiìsmadein a command.
illegalcommand
The commandspecifiedis not a valid
DISKVERIFYcommand.
Disk Verification
DISK !'ERIFY COMMANI)S
fnodefile/spacemap
file inconsistent
One of the files,R?SAVEor R$FNODEMAP,is
damagedand DISKVERIFY cannotperform
furtherverification.
argumenterror
The commandwasmissingan argument,or the
argumentwas illegallyspecified.
not a nameddisk
The deviceis not a namedvolume(a tape,for
example)or the iRMX volumelabel,obtainedwhen
containsinvalitJ
DISKVERIFY beginsprocessing,
information.If the labelcontainsinvalìd
information,the utiliry(in somecases)canassume
that a namedvolumeis a physicalvolume. In this
case,the commandsthat applyto namedvolumes
onÌy(suchasDISPTAYFNODE,
DISPTAYDIRECTORY,
andVERIFY NAMED)
issuethis message.If you are surethe volumeis a
may indicatethat the
namedvolume,this message
iRMX II volumelabelis corrupted.(If the file was
formattedwith the RESERVEoptionof the
FORMAT command,DISKVERIFY issuesthis
message
only if both volumelabelsare corrupted.
Whenonly the volumelabelis invalid,the duplicate
in the saveareais used.)
seekerror
The utility unsuccessfully
attemptedto seekto a
locationon the voÌume.This error normallyresults
from invalidinformationin the iRMX II volume
labelor in the fnodes.Or. a newvolumewas
insertedafter DISKVERIFY wasinvoked.
2.8 COMMANDDICTIONARY
The commanddictionarybelowliststhe DISKVERIFY commandsin alphabetical
order
and providesa brief functionaldescriptionof eachcommand.Followingeachcommand
you can locatethecommand
nameis its uniqueabbreviation,
if any. For quickreference,
usingthe pageheadersremainingin this chapter.
Command
Synopsis
ALLOCATE
Marksa particularfnodeor volumeblock
asallocated
BACKUPFNODES
BF
Copiescurrentfnodefile into a backup
file namedR?SAVE
Disk Verification
t-<
DISK VERIFY COMMANDS
2-6
Command
Synopsis
DISK
Displavsthe attributesof the volume
beingverified.
DISPI-A,YBYTE
DB or D
Displaysthe working buffer in byte
format
DISPI-A.YWORD
DW
Displaysthe working buffer in word
format
DISPI-A,YDIRECTORY
DD
Displaysdirectorycontents
DISPI-A,YFNODE
DF
Displaysthe specifiedfnode information
DISPI.A.YSA\'EFNODE
DSF
Displaysthe fields of a singlefnode in the
R?SAVE fiIC
DISPI-AYNEXTBLOCK
DNB or > or
Displaysthe "next"volume block
DISPI-A.YPREVIOUSBLOCK
DPB or <
Displaysthe"previous"volumeblock
EDITFNODE
EF
Edits the specifiedfnode
EDITSAVEFNODE
ESF
Edits the specifiedsavedfnode
EXIT
E
Exits the Disk Verification Utiìiry
FIX
Verifies the disk and fixesinconsistencies
FREE
Marks a particular fnode or volume block
as free
GETBADTRACKINFO
GB
Displaysthe bad track information
Disk Verifrcation
DISKYERIFY COMMANDS
Command
Synoosis
HELP
H
Liststhe DISKVERIFYcommands
LISTBADBLOCKS
LBB
Displaysall the bad blockson the volume
MiscellaneousCommands
Perform usefularithmetic and conversion
functions;the commandsincludeADD,
SUB,MUL, DIV, MOD, HEX, DEC,
ADDRESS,andBLOCK
QUIT
Exits the Disk Verification Utility
READ
R
Readsa volumeblock into the working
buffer
RESTOREFNODE
RF
Copiesone fnode(or rangeof fnodes)
from the R?SAVE file to the fnode file
RESTOREVOLUMEI-ABEL
RVL
Copiesthe duplicatevolume label to the
volume label offset on track 0
SAVE
Writes the updatedfnode map, free space
map, and bad block map to the volume
SUBSTITUTEBYTE
SB or S
Modifies the contentsof the working
buffer in byte format
SUBSTITUTEWORD
SW
Modifies the contentsof the working
buffer in word format
VERIFY
Verifies the volume
WRITE
Writes the workins buffer to the volume
o
w
Disk Verilication
a n
andvolumeblocksasallocated.
nodes(fnodes)
file descriptor
designates
Thiscommand
to designate
oneor a rangeof volumeblocksas"bad"
You canalsousethiscommand
command
is
asfollows:
the
ALLOCATE
Theformatof
INPUT PARAMETERS
fnodenum
Numberof the fnodeto allocate.This numbercan rangefrom 0
through(maxfnodes- 1),wheremaxfnodesis the numberof
fnodesdefinedwhenthe volumewasoriginallyformatted.Two
fnodevaluesseparated
by a commasignifiesa rangeof fnodes.
blocknum
Numberof the volumeblockto allocate.This numbercanrange
from 0 through(maxblocks- 1),wheremaxblocksis the number
of volumeblocksin the volume. Two blocknumbersseparatedby
a commasignifiesa rangeof blocknumbers.
OUTPUT
If you are usingALLOCATE to allocatefnodes,ALLOCATE displaysthe following
message:
is the numberof the fnodethat the utility designated
asallocated.
If you are usingALLOCATE to allocatevolumeblocks,ALLOCATE displaysthe
following message:
is the numberof the volumeblockthat the utilitv desienated
as
allocated.
2-8
Disk Verification
ALLOCATE
If you are usingALLOCATE to designate
one or morevolumeblocksas"bad,"
ALLOCATE displaysthe followingmcssage:
(blocknun>,
block narked bad
where < blocknum> is the numberof the volumeblockthat the utility desigrrated
as"bad."
If this block was not allocatedbeforeyou attempt to designateit as "bad,"ALLOCATE
alsodisolavs
,
bLock rnarked aÌlocated
ALLOCATE checksthe alìocationstatusof fnodesor blocksbefore allocatingthem.
Therefore,ifyou speci! ALLOCATE for a block or fnode alreadyallocated,
ALLOCATE returns one of the following messages:
,
fnode
already
marked allocated
, block out of range
The block number specifiedwaslarger
than the largestblock number in the
volume.
< fnodenum> , fnode out of range
The fnode number specifiedwas larger
than the largestfnodenumberin the
volume.
no badblocksfile
The volume doesnot havea bad blocks
couldappearif an
file. This message
earlierversionof the HumanInterface
FORMAT commandwas usedwhen the
disk wasformatted.
Disk Verification
fnoclebackupfile named
This commandcopiesthe currentfnodefile into a designated
R?SAVE. R?SAVEmusthavebeenreservedwhenthe volumewastbrmatted.(That is,
the RESERVEoptionof the FORMAT commandmusthavebeenspecifietl.)The format
of the BACKUPFNODEScommantlis asfollows:
PFNODES
BACKU
INPUT PARAMETERS
None.
OUTPUT
BACKUPFNODESdisplaysthe followingmessage:
fnode
file
backed up to
save area
DESCRIPTION
commandensuresag:ìinstdatalossthat occurswhenthe fnode
The BACKUPFNODE,S
file is damagedor destroyed.To usethis command,you musthaveformattedthe volume
area(R?SAVE)
reserve
usingthe FORMAT command(V1.1or later)to createa special
the
creationof
(the
switch)
controls
RESERVE
A switchin the FORMAT command
R?SAVE. If you did not specifythe RESERVEparameterwhcn the volumewas
commandwill he unableto copythe fnodef ile to
formatted,the BACKUPFNODE.S
will be returnedindicatingthat no saveareilhasbeen
R?SAVE. An error message
reserved.In thiscase,the volumemustbe refìrrmattedif you wishto usethe
BACKUPFNODESctrmmanti.
The FORMAT commandwritesthe initializedcopyof the fnodefile into R?SAVE
Therefore,you do not haveto useBACKUPFNODIISto backup a newlyformatted
you can routinely(for example,oncea ciay)backuptiodcs to
volume. Subsequently,
thedatain the fnodefile. You cando thisby
in
R?SAVE
matches
the
data
assurethat
commandor thc HumanInterficeSHUl'DOWN
usingeitherthe BACKUPFNODES
seethe
on SHI.J-I'DOWN,
with the BACKUPoption.(For moreinformation
commantl
Intarfitce.)
II
Human
Operator'sGuideto the Extanded|RMX
Disk Verification
2-tl
BACKUPFNODES
NOTE
Be sure that the current fnode file is valid before executingthe
BACKUPFNODE command(usingNAMED verification).
ERROR MESSAGES
argumenterror
Whenthe commandwasentered,an
argumentwassupplied.
BACKUPFNODESdoesnot acceptan
argument.
no saveareawasreservedwhen
volumewasformatted
The volumehasnot beenformattedto
supportfnodebackup.To allowfuture
useof backupfnodes
on this volume,you
shouldinvokethe Human Interface
BACKUP commandto savethe dataon
the volume,reformatthe volumewith a
savearea(usingthe RESERVEoptionof
the FORMAT command),and finally,
restorethe volumedata.
not a nameddisk
The volumespecifiedwhenthe Disk
VerìficationUtility wasinvokedis a
physicalvolume,not a namedvolume.
EXAMPLE
super- dlskvertfy
: sd: (CR.>
1 R M XI I D i s k V e r i f y U t j - l i t y , V x . x
Copyríght Intel Corporat i on
:sd:, ouÈstanding connections Èo device have been deleted
ìtsverify NAI{ED
B I T M A P SO .K .
*backupfnodes or bf
fnode ffle backed up to save area
2-t2
Disk Verilication
This commanddisplaysthe attributesof the volumebeingverified. You can abortthis
commandby typinga CONTROL-C. The formatof the DISK commandis asfollows:
INPUT
None.
OUTPUT
The output of the DISK commantldependson whetherthe volumeis formattedas a
physicalor namedvolume. For a physicalvolume,the DISK commanddisplaysthe
following information:
devfce
P'rysrLdr
narne
uaDN
devlce granularity
block size
mrnber of blocks
volune s ize
(numblocks)
wnere:
< devname>
Nameof the devicecontainingthe volume. This is the physical
nameof the device,as specifiedin the ATTACHDEVICE Human
Interfacecommand.
Granularityof the device,asdefinedin the DeviceUnit
InformationBlock(DUIB) for the device.Referto the Guideto
the Ertended .RMX II Interactive Configuration Utility for more
informationaboutDUIBs. For physicaldevices,this is alsothe
volumeblocksize.
>
< numblocks
Numberof volumeblocksin the volume.
< size>
Sizeof the volume,in bYtes.
Disk Verification
2-13
DISK
For a nametlvolume,the DISK commanddisplaysthe followinginformation:
named disk,
ucvrrE
device
volume
Ér
d,,urdr
narne
narne
r LJi
block s ize
nurnber of blocks
nunber of free blocks
volune size
interleavè
extension size
nunber of fnodes
nuxober of free fnodes
save area reserved
{numblocks)
(nurnfree fnode s)
(yeslno)
fieldsarethe sameasfor
The ,,,and
physicalfiles. The remainingfieldsare asfollows:
Nameof the volume,asspecifiedwhenthe volumewasformatted.
Volumegranularity,as specifiedwhenthe volumewasformatted.
< numfreeblocks
>
Numberof availablevolumeblocksin the volume.
The interleavefactorfor a namedvolume.
Size,in bytes,of the extensiondataportionof eachfile descriptor
node(fnode).
< numfhodes
>
Numberof fnodesin the volume.The fnodeswerecreatedwhen
thevolumewasformatted.
< numfreefnodes
>
Numberof availahlefnodesin the namedvolume.
saveareareserved
Indicateswhetherthe R?SAVEfile is reservetllbr volumelabel
and fnodefile backups.
Referto AppendixA of this manualor to the descriptionof the FORMAT commandin
the Operetor'sGuideto the Ertended|RMX II Human Interfacefor more information about
the nameddiskfields.
DESCRIPTTON
The DISK commanddisplaysthe attributesof the volume. The format of the outputfrom
DISK dependson whetherthe volumeis formatted:rsa namedor physicalvolume.
ERRORMESSAGES
None.
2-11
Disk Verifìcation
DISK
EXAMPLE
The followingexampleshowsthe outputof the DISK commandfor an 5.25-inchdiskette.
:f0:
super- dlskverlfy
iRMx ll Disk Verify Utility. vx.x
Copyright Intel CorporatÍon
*dfsk
device name
named disk, volume narne
device granularicy
block size
nurnber of b I ocks
n u m b er o f f r e e b l o c k s
volume size
i n t e r 1 ea v e
extension size
nurnber of fnodes
nurnber of free fnodes
s a v e a r e a r e s er v e d
Disk Verification
wnfdx0
rmx2 8 6
0200
0200
0000027c
000001E9
0004F800
0005
03
OOCF
008[
no
2-15
displays
portionof theworkingbufferin BYTEformat.It
Thiscommand
thespecified
displays
thebufferin 16-byte
rows.Youcanabortthiscommand
bytypinga CONTROLC. Theformatof theDISPI-AYBYTE
command
is asfolìows:
INPUT PARAMETERS
startoffset
Numberof the byte,relativeto the startof the buffer,that begins
the display.DISPI-AYBYTEstartsthe displaywith the row
containingthe specifiedoffset. Ifyou omit this parameterand the
endoffsetparameter,DISPI-A.YBYTEdisplaysthe entireworking
buffer.
endoffset
Numberof the byte,relativeto the startof the buffer,that endsthe
display.If you omit this parameter,DISPII,YBYTE displaysonly
the row indicatedby startoffset.However,ifyou omit both
startoffsetand endoffset,DISPLAYBYTE displaysthe entire
workinsbuffer.
OUTPUT
In responseto the command,DISPI-AYBYTEdisplaysthe specifiedporrionof the
workingbuffer in rows,with 1óbytesdisplayedin eachrow. Figure2-l illustratesthe
format of the disolav.
2-16
Disk Verification
DISPLAYBYTE
As Figure 2-1 shows,DISPT-AYBYTEbeginsby listing the block numberwhere data
residesin the working buffer. It then lists the specifiedportion of the buffer, providing
the columnnumbersasa headerand beginningeachrow with the relativeaddressof the
of
first blte in the row. It alsoincludes,at the right of the listing,the ASCII equivalents
printable
the bytes,if the ASCII equivalents
are printablecharacters.(lf a byteis not a
position.)
character,DISPIAYBYTE displaysa periodin the corresponding
*dlsplaybyÈe 7,13
BLOCKNUHBER- blocknum
A B c D E F
2 3 4 5 6 7 I9
offset 0 |
0000 00 01 02 03 04 05 06 07 08 09 0A 0B 0c 0D 0E 0F
0010 61 6E 20 65 F8 61 6D 70 6C 65 20 20 20 20 20 20
AscII STRING
an example
Figure2-1. DISPLAYBYTEFormat
DESCRIPIION
DISKVERIFY maintainsa workingbufferfor READ and WRITE commands.The size
of the bufferis equalto the volume'sgranularityvalue. Alier you reada volumeblockof
memoryinto the workingbufferwith the READ command,you can displaypart or all of
that buffer,in BYTE format,by enteringthe DISPT-AYBYTEcommand.
DISPI-A,YBYTE displaysthe hexadecimalvalue for eachbyte in the specifiedportion of
the buffer.
DISPI-A.YBYTEdisplaysthe entireblockstoredin the
If you omit all parameters,
working buffer.
ERRORMESSAGES
argumenterror
A syntaxerror wasmadein the command
or a nonnumericcharacterwasspecified
in one of the offsetparameters.
< offset>, invalid offset
Either a largervalue wasspecifiedfor
startoflsetthanfor endoffsetor an offset
valuelargerthan the numberof bytesin
the blockwasspecified.
Disk Verification
2-17
the
command,
exceptthatit displays
Thiscommand
is thesameasthe DISPL.AYBYTE
pcr row, Thetbrmatof theDISPT-AYWORD
workingbufferin WORDformat,fì-words
command is as follows:
EXAMPLES
Assuming
that thevolumegranularìty
is 128bytesandthatyou havereadblock20H into
theworkingbufferwith the READ commanrl,
theftrllowing
commanci
thatblock
clisplays
in WORD format.
*DISPIAYTJOR.D
BLOCK NUHBER:
20
offset
0000
0010
0020
0030
0040
00s0
0060
0070
o
0000
0000
0000
1F25
0001
0000
0000
0000
2
0000
0080
0000
0000
0000
0000
0000
0000
4
0000
0000
0500
002E
0001
0000
0000
OOOl
6
0000
0000
0000
0000
0080
0000
0000
FFOF
8
A
0000 0000
0000 0001
0000 0025
1 F 2 5 0000
0 0 0 0 0000
0 0 0 0 0000
0000 0000
OOFF 0 0 0 0
C
E
0000
FFOt'
0108
002B
0000
0000
0080
0000
0000
00FF
FFFF
0000
0000
0000
0000
0500
The ibllowìngcommanddisplaysthe portionof the blockthat containsthe offsets3 I h
through45h(wordsbeginning
at odd addrcsses).
*DI{ 31, 45
: 20
BLOCKNUMBER
offset
0 03 1
0041
2-18
O
2
4
6
8
C
E
0 0 l F 2E 0 0 0 0 0 0 2 5 0 0 0 0 l F 2 8 0 0 0 0 0 0 0 1 0 0
0000 0100 8000 0000 0000 0000 0000 0000
Disk VerifÍcalion
DISPLAYWORD
The followingcommanddisplaysthe portionof the blockthat containsthe ollsets30h
through45h (wordsbeginningat evenaddresses).
*DIS PIAYSORD30, 45
BLOCKNUMBER- 20
offset
0030
0040
Disk Verification
C
E
8
A
4
6
0
0
2
8
0000
0000
rF25 0000 002E 0000 1F25
0001 0000 0 0 0 1 0 0 8 0 0000 0000 0000 0000
O
2
2-r9
Thiscommand
listsall thefilescontained
in a directory.Youcanabortthiscommand
by
a
CONTROL-C.
The
format
of
the
DISPLq.YDIRECTORY
command
is
as
ryping
follows:
INPUT PARAMETER
fnodenum
Numberof the fnodethat corresponds
to a directoryfile. This
numbercanrangefrom 0 through(maxfnodes- 1),wheremax
fnodesis the nurnberof fnodesdefinedwhenthe volumewas
originallyformaued. DISPI-AYDIRECTORY lists all files or
directoriescontainedin this directory.
OUTPUT
In responseto the command,DISPI-AYDIRECTORYlistsinformationaboutall files
containedin the specifieddirectory. The format of this dìsplayis as follows:
FILE NAME FNODE TYPE
(fnode) (type)
FILE NAMEFNODE TYPE
(filenam)
(filenam)
(fnode)
(fnode)
(type)
(fnode)
Nameof the file or directorycontainedin the directory.
< fnode>
Numberof the fnodethat describes
the file.
2-20
Disk Verification
DISPLAYDIRECTORY
type>
Type ofthe file. The can be
Tlpe of file
Descrintion
DATA
DIR
SMAP
FMAP
BMAP
VI-A.B
data files
directoryfiles
volume free spacemap
free fnodesmap
bad blocksmap
volumelabelfile
DESCRIPTION
DISPI-AYDIRECTORYdisplaysa list of filescontainedin the specifieddirectory,along
with their fnodenumbersand tvoes.You canthen useotherDISKVERIFY commandsto
examinethe individualfiles.
ERRORMESSAGES
argumenterror
A nonnumericcharacterwasspecifiedin
the fnodenumparameter.
< fnodenum> , fnodenot
allocated
The numberspecifiedfor the fnodenum
parameterdoesnot correspondto an
allocatedfnode. This fnodedoesnot
representan actualfile.
,not a directory
fnode
The numberspecifiedfor the fnodenum
parameteris not an fnodefor a directory
file.
< fnodenum> , fnodeout of range
The numberspecifiedfor the fnodenum
parameteris largerthan the largestfnode
numberon the volume.
Disk Verification
2-21
DISPLAYDIRECTORY
EXAMPLE
The following command lists the files contained in the directorv whose fnode is fnode 6.
*DISPIAYDIRICTORY6
FILE NAME FNODETYPE FILE NAME FNODETYPE
FILE NAME FNODETYPE
R?SPACEMAP OOO1SMAPR?FNODEMAP OOO2FMAPR?BADBLOCKMAPOOO4BMAP
R?VOLUMEU,BEL OOO5VTAB
R?SAVE 0007 DATA
Rlfl(286 0008 DIR
M1TILE
OOO9DATA YOURFILE OOOADATA
ONEFILE OOOBDATA
) -)7
Disk Verification
with an fnode. You canabortthis command
This commanddisplaysthe fieldsassociated
by typinga CONTROL-C. The formatof the DìSPTAYFNODEcommandis asfollows:
INPUT PARAMETER
Numberof the fnodeto be displayed.This numbercanrangefrom
0 through(maxfnodes- l), wheremaxfnodesis the numberof
fnodesdefinedwhenthe volumewasorisinallyformatted.
fnodenum
OUTPUT
In responseto this command,DISPIAYFNODE displaysthe fieldsof the specified
fnode. The formatof the displayis as follows:
Fnode nuuber -
flags
tYPe
t.. ^ l
LLL-
--^^
ÉLdtt/
OIJTìET
create ,access,mod t imes
t^È^r
Ltr.-
bl-ock pointer
block pointer
(1)
(2)
hl
/?\
nrlz
nnJ nrpr
block pointer
(4)
t'l^-L
^^i-r-r
/5\
hl nrlz
nai ntar
l6ì
block
block
n..ahÈ
pointer (7)
(8)
pointer
this size
id count
accessor (1)
aeeessor (2)
accessor (3)
rh or lz
, ,
,
,
,
,
,
,
,
, ,
,
,
t-t1
DISPLAYFNODE
where:
< fnodenum>
Number of the fnode being displayed.If the fnode doesnot
describean actualfile (that is, if it is not allocated),the following
message
appearsnextto this field:
*** AILOCATION STATUSBIT IN THIS FNODE NOT SET ***
In this case,the fnode fields are normally set to zero.
< pathname>
FulÌ pathnameof the file describedby the fnode. This field is not
displayedif the fnode doesnot describea file.
< flgr >
A word defining the attributesof the file. Significantbirs of
this word are as follows:
Bit
Meaning
0
Allocationstatus.This bit is set to 1 for
allocatedfnodesand 0 for free fnodes.
1
Long or shortfile attribute.This bit is set to 1
for long files and 0 for short files.
5
Modificationattribure.This bit is set to 1
whenevera file is modified.
ó
Deletionattribute.This bit is setro 1 to
indicatea temporaryfile or a file to be deleted.
The DISPLAYFNODEcommanddisplaysa message
nexrto this
field to indicatewhetherthe file is a longor shortfile.
< typ >
Type of file. This field containsa value and a descriptionwhich is
displayednextto the value. The possiblevaluesand descriptions
are as follo\À's:
Value
Descriptions
00
01
02
03
04
06
08
09
fnode file
volumemap file
fnodemap file
accountfile
bad block file
directoryfile
data file
volumelabelfile
< gran >
File granularity,specifiedasa multipleof the volumegranularity.
User ID of the ownerof the file.
2-24
Disk Verification
DISPLAYFNODE
< acctime>
and
Time and dateof file creation,lastaccess,
last modification. Thesevaiuesare expressedas
the time,in seconds,
sinceJanuary1, 1978.
< totsize>
Total size,in bytes,ofthe actualdata in the fiìe.
Total numberof volumeblocksusedby the file, includingindirect
block overhead.
< blks>, < blkptr >
Valuesthat identify the data blocksof the file. For short files, each
< blks> parameterindicatesthe numberof volume blocksin the
data block,and each is the number of the first such
volumeblock. For long files, each parameterindicatesthe
number of volumeblockspointed to by an indirect block, and each
is the block number of the indirect block.
< thissize>
Sizein bytesof the total data spaceallocatedto the file, minus any
spaceusedfor indirect blocks.
< count>
with the file.
Numberof userIDs associated
< access> , < id >
Each pair of fields indicatesthe accessrights for the file and the ID
ofthe userwho hasthat accessID. Bits in the field are
set to indicatethe following accessrights:
Bit
Data File
Ooeration
Directory
Operation
0
1
2
3
delete
read
append
update
delete
list
add entry
changeentry
The first ID listedis the owner'sID.
Fnodenumberof the directoryfile that containsthe file.
Checksumof the fnode.
Auxiliary bytesassociatedwith the file.
Appendix A containsa more detaileddescriptionof the fnode fields.
DESCRIFTION
Fnodesare systemdatastructureson the volumethat describethe fileson the volume.
The fnode structuresare createdwhen the volume is formatted. Each time a file is
createdon the volume,the iRMX II BasicI/O Systemallocatesan fnodefor the file and
fills in the fnode fields to describethe fiìe. The DISPI-A.YFNODEcommandenablesyou
to examinethesefnodesand determinewherethe datafor eachfile resides.
Disk Verification
)-r\
DISPLAYFNODE
ERRORMESSAGES
argumenterror
The valueenteredfor the fnodenum
parameterwasnot a legitimatefnode
number.
< fnodenum >,fnode out of range
The number specifiedfor the fnodenum
parameteris largerthanthe largestfnode
numberon the volume.
The pathnamespecifiedcouldnot be
retrieved.Possible
causesof this error
are seekerror,I/O error,or invalid
parent.
Unable to get pathname
< reason>
EXAMPLE
The followingexampledisplaysfnode 10of a volume. This fnoderepresents
a directory.
XDISPIAYFNODE 10
Fnode number
nr
rh
n.mo
:
I0
/M\'nTP
flaoc
tyPe
create
cotal
ollTte r
a
c
c
e
s
s
,
m
o
d
times
,
size, total
b locks
hl ^.L n^ínrar
/ I I
block polnter
(2)
hl anlr
nni nrar
t ìl
L9 rlv^L ^^ 1 .
-^i-+^P9llrLq!
\Y/
h l arlz
nni ntar
r ( \
h l nalz nnJnrar
i'At
hìnnlr
nnintar
/7\
h1 nnL
-^i
/ e\
//,\
^t-r
this size
fd count
n.ranr
ecno<short fi Ie
06:)directory fl le
01
FFFF
I02L9017, 10219E58,1 0 2 1 9 E s 8
0 0 0 0 0 3 6 0 0, 0 0 0 0 0 0 1
0001, 000050
0000,000000
0000,000000
0000,000000
0000,000000
0000,000000
0000,000000
0000,000000
00000400
0 00 1
OF, FFFF
00,0000
00,0000
0006, 0000
000000
Disk Verifìcation
This commandis identicalto DISPI-AYFNoDE,exceptthe DISPLAYSAVEFNoDE
takesthe fnodeinformationfrom the R?SAVEfile, and displaysthe fnodeas saved.
R?SAVEmusthavebeenreservedwhenthe volumewasformatted.(That is, the
RESERVEoptionin the FORMAT commandmusthavebeenspecified.)The format of
commandis asfollows:
the DISPT-AYSAVEFNODE
D I S P L A Y S AFVN
EO D E
f n o d e n um
F0212
ERRORMESSAGES
argumenterror
Whenthe commandwasentered,no
argumentwassupplied.
requiresa
DISPTAYSAVEFNODE
designation
of the fnodenumber.
< fnodenum> , fnodeout of range
The numberspecifiedfor the fnodenum
parameteris largerthan the largestfnode
numberon the volume.
no savearea was reservetlwhen
volume was formatted
The volumewasnot formattedto support
backupfnodes.This meansthe
RESERVEoptionwasnot specified
whenthe volumewasformatted.
Unableto get pathname
< reason>
The pathnamespecifiedcouldnot be
retrieved.Possiblecausesof thrserror
are seekerror, I/O error,or invalid
parent.
Disk Verífication
2-27
This commanddisplaysthe "next"volumeblock. (The "next"volumeblockis the block
formatcan
immediately
following
theblockcurrently
in theworkingbuffer.)Thedisplay
be either WORD or BYTE. The utility remembersthe mode in which you displayedthe
volume block currently in the working buffer, and it displaysthe next block in that format.
So, if you usedDISPI-AYBYTE to displaythe current volume block, the next volume
blockappearsin BYTE format;if you usedDISPLAYWORD,the nextvolumeblock
appearsin WORD format. DISPLAYNEXTBLOCKusesthe BYTE format as a default
ifyou havenot yet displayeda volumeblock. You canabortthis commandby typinga
CONTROL-C. The format of the DISPTAYNEXTBLOCK commandis as follows:
DI5PLAYNEXTELOCK
CARRIAGERE-TU
RN
F 0.205
OUTPUT
In responseto the command,DISPI-AYNEXTBLOCKreadsthe "next"volumeblockinto
the workingbufferand displaysit on the screen.
DESCRItrTION
The DISPI,AYNEXTBLOCKcommandcopiesthe "next"volumeblockfrom rhevolume
to the workingbufferand displaysit at your terminal. It destroysanydatacurrentlyin the
workingbuffer. Oncethe blockis in the workingbuffer,you canuse
SUBSTITUTEBYTEand SUBSTITUTEWORDto changethe datain the block. Finally,
you canusethe WRITE commandto write the modifiedblockbackout to the volume.
NOTE
If you specifothe DISPI-AYNEXTBLOCKcommandar rhe end of the
volume,the utility'Vrapsaround"and displaysthe first blockin the
votume.
2-28
Disk Verification
This commandis identicalto DISPLAYNEXTBLOCK exceptthat it displaysthe volume
blockprecedingthe currentblockin the workingbuffer. The format of the
DISPI-AYPREVIOUSBLOCKcommandis asfollows:
F0206
Disk Verification
2-29
This commandallowsyou to edit valueswithin a specilìedfnode. It canbe abortedby
enterinsCONTROL-C. The formatof the EDITFNODE commandis
INPUT PARAMETER
fnode
Numberof the fnodeto edit. This numbercanbe in the rangeof 0
through(maxfnodes- l), wheremaxfnodesis the numberof fnodes
definedwhenthe volumewasorisinallvformatted.
OUTPUT
When EDITFNODE is invokedit displaysthe followingmessage:
Fnode nurnbe r -
nnnn
wherennnn is the numberof the fnodeyouwant îo edit. The first field of the fnodeis
displayedwith its currentvalue,asfollows:
f lags(xxxx) :
wherepoo
No modificationto the field.
numericalvalue < CR >
The newvalueto be assigned.
This valueis alwaysinterPreted
ashexadecimal.
Quit or Q or c1< CR >
Skipthe remainingfieldsand
displaythe query.
and
other thanthoselistedabove,causesthe field to remainunchanged,
Any response,
the nextfield to be displayed.
Oncethe fnodehasbeenupdated,you canuseDISPLAYFNODE to examinethe
you made. Changingthe contentsof an fnode
contentsof the fnodeand the changes
causesit to havea bad checksum.UseFIX with the NAMED1 optionto correctit. For
of FIX later in thischapter.
more details,seethe ex?lanation
ERRORMESSAGES
argumenterror
The optionspecifiedis not valid.
, fnodeout of
range
The fnodenumberspecifiedwaslarger
than the largestfnodenumberon the
volume.
Errorin Input
Invalidinputwasenteredwhile editingan
entry.
Disk Verification
2-l t
EDITFNODE
EXAMPLE
The followingexampleillustratesusingEDITFNODE to edit fnode 10.
*edltfnode
10
fnode nurnber - 10
flags(0025):
type(0006):
flle gran/vol gran(01) :
owner(0FFFF): 0
créatè time(1O2I9CR2): q
Encering "q'r causes the modified fnode to be displayed.
fl ags
tYPe
s.:1^
r r rE
-,-.^
ó!drrl
vur
ÉLdrr
OIJTìE r
c r e a t e , a c c e s s ,m o d t i n e s
t o t a L s i " z e ,t o t a l b l o c k s
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
1R\
n^int
ar
this size
i.d count
accessor (1)
accessor (2)
accessor (3)
nr rén t_
e h a r l z< " -
aux ( *)
l,lrice back? yes
Fnode has been updated
2-32
0025 -)short
OA:>rlirartnrrr
fi Ie
fí1a
01
0000
1 0 2 1 9 C 8 21,0 2 1 9 C C 81 ,0 2 1C
9C8
0 0 0 0 0 3 6 0 0, 0 0 0 0 0 0 1
0001, 0000s0
0000, 000000
0000,000000
0000,000000
0000, 000000
0000, 000000
0000,000000
0000, 000000
00000400
0001
OF, FFFF
00, 0000
00, 0000
0006, 0000
000000
Disk Verification
EDITSAVEFNODE is identicalto EDITFNODE, exceptthat it allowsyou to edit an
fnodefrom the R?SAVEfile. (R?SAVEmusthavebeenreservedwhenthe volumewas
the fnodeassavedwhendisplayingthe fnode
formatted.)In addition,it designates
number. You can abortthis commandby enteringCONTROL-C. The format of the
EDITSAVEFNODE commandis
ERRORMESSAGES
are the sameasin EDITFNODE with the additionof the following
The error messages
messaqe.
no saveareawas
reseryedwhenvolume
wasformatted
Disk Verification
The volumewasnot formattedto support
backupfnodes.This meansthe RESERVEoption
wasnot soecifiedwhenthe volumewasformatted.
2-33
This commandexitsthe Disk VerificationUtility and returnscontrolto the Human
Interfacecommandlevel. The format of the EXIT commandis asfollows:
r o20t
This commandis identicalto the QUIT command.
NOTE
Althoughyou canuseDISKVERIFY to verify rhesysremdevice(:sd:),
note that all connections
to this deviceare deletedby the operatingsystem.
After exiting,you mustrebootthe systemor usethe warm startfeature
(see the ErtendediRMX II SystemDebuggerRet'erence
Manual).
2-34
Disk Verification
This commandverifiesthe volumein the samewayasthe VERIFY commandto
determineif the dataon the volumeis consistent.In addition,this command"fixes"
variouskindsof inconsistencies
discovered
duringverification.You can abortthis
commandby enteringCONTROL-C. (CONTROL-Cis ignoredwhenFIX is writingto
the volumein order to preventinconsistencies
on the volume.)
BecauseFIX and VERIFY performthe sameverificationfunctionsand generatethe
sameerror messages,
only the additional
the commanddescriptiongivenbelowdescribes
functionsof FIX. For a completeexplanation
of the veriff functions,seethe VERIFY
commanddescribed
later in this chanter.The formatof the FIX commandis:
Disk Verification
2-35
Ftx
INPUT PARAMETERS
NAMED1 or N1
PerformsNAMEDl verification and fixesthe following
inconsistencies:
.
Fixesbad checksums
.
Attachesorphanfnodesto their parents.An orphanfnodeis
an fnodecontainedwithin a directoryandwhoseparentfield
doesnot point backto this directory.If the parentfield of the
specifiedfnode points to a secondvalid directory,and the
seconddirectory alsopoints to the fnode, no fix is performed
sincethe specifiedfnode belongsto an existingdirectory. This
(discussed
in NAMED2).
is a caseof multiplereferences
If the parentfield doesnot point to a valid parent,the parentfield
is fixed to point to the directorythat containsthis fnode in its fiìe
list.
NAMED2 or N2
PerformsNAMED2 verification and fixesthe followins
inconsistencies:
.
Removesfnodesfrom their iilegalparents.If there is a multiple
referenceto an fnode,the fnodeis removedfrom the
directoriesthat it doesnot point to (if FIX wasperformedwith
NAMEDl, the fnodeshouldnow point to onevalid parent).
r
Savesfnodeand blockbit mapson completionof NAMED2.
NAMED or N
Performsboth the NAMEDI and NAMED2 verificationfunctions
on a namedvolumeand fixesthe inconsistencies
definedfor these
options.
ALL
Performsall operationsappropriateto the volume.For named
volumes,this optionperformsboth the NAMED and PHYSICAL
verificationfunctions.For physicalvolumes,this optionperforms
only the PHYSICALverificationfunction.For both NAMED and
PHYSICAL volumes,ALL performsthe fixesfor the relevant
verifications.
PHYSICAL
PerformsPHYSICALverificationand savesthe bad blockbit man.
LIST
Liststhe file informationdisplayedin Figure2-3for any
verificationthat includesNAMED l.
2-36
Disk Verilication
FIX
OUTPUT
(seeFigures
2-3,2-4,and2-5)
FIX produces
thesameoutputastheVERIFYcommand
withadditional
messages
displayed
whenaninconsistency
is fixed.NAMEDl output
includes
thesemessases.
Checksum Fixed
fnode nnnn was a t t a c h e d
to parent
nnnn
The first messageappearsafter a bad checksumis fixed. The secondmessageis displayed
whenthe parentfield of an fnodeis modifiedto point to a valid parent.
is removedfrom
whenan fnodewith multiplereferences
NAMED2 displaysthis message
the directory.
fnode
rernoved frorn this
dlrectory
FIX
but hasnot beenreferenced,
If an fnodeexistson a diskand is markedallocated,
issuesa warningmessage
and asksif you wantto savethe bit maps.This preventsSAVE
from freeing this fnode and its blocksand possiblycausinga file to be lost.
Disk Verification
2-37
It also
fnodesandvolumeblocksasfree(unallocated).
designates
Thiscommand
is as
volumeblocksfromthebadblocksfile. Theformatof theFREEcommand
removes
follows:
INPUT PARAMETERS
fnodenum
Numberof the fnodeto free. This numbercan rangefrom 0
through(maxfnodes- l), wheremar fnodesis the numberof
fnodesdefinedwhenthe volumewasoriginallyformatted.Two
by a commasignifya rangeof fnodes.
fnodevaluesseparated
blocknum
Numberof the volumeblockto free. This numbercanrangefrom
0 through(maxblocks- 1),wheremar blocksis the numberof
volumeblocksin the volume. Two blocknumbersseparated
by a
commasignif a rangeof blocknumbers.
OUTPUT
Ifyou are usingFREE to deallocatefnodes,FREE displaysthe followingmessage:
, fnode narked free
where is the numberofthe fnodethat the utilitv desisnated
asfree.
If you are usingFREE to deallocate
volumeblocks,FREE displaysthe followingmessage:
,
block
marked free
where < blocknum> is the numberof the volumeblockthat the utilitv desisnated
as free.
2-18
Disk Verification
FREE
Ifyou are usingFREE to designate
one or more "bad"blocksas"good,"FREE displays
the following message:
,
block marked good
where < blocknum> is the numberof the volumeblockthat the utilitv desisratedas
"good."
FREE checksthe allocationstatusof fnodesor blocksbeforefreeingthem. Therefore,if
you specifyFREE for a blockor fnodethat is alreadyunallocated,
FREE returnsone of
the followingmessages:
, fnode already
marked free
(blocknum>,
block
already
marked free
(blocknun>,
block
already
marked good
DESCRIPTION
Free fnodesare fnodesfor whichno actualfilesexist. FREE designates
fnodesas free by
updatingboth the F[-{GS field of the fnodeand the free fnodesmap file.
Freevolumeblocksare blocksthat are not part of anyfile; theyare availableto be
assigned
to any newor currentfile. FREE designates
volumeblocksasfree by updating
the volumefree spacemap.
Whenyou usethe FREE commandto designate
one or more bad blocksas "good,"it
removesthe blocknumberfrom the bad blocksfile. However.FREE BADBLOCK does
not designate
the blocksasfree. To updatethe volumefree spacemap and designate
theseblocksas free,usethe FREE BLOCK command.
ERRORMESSAGES
argùmenterror
A syntaxerror wasmadein the command
or a nonnumericcharacterwasspecified
in the blocknumor fnodenumDarameter.
< blocknum> , block out of range
The block number specifiedwaslarger
than the largestblocknumberin the
volume.
< fnodenum> , fnodeout of range
The fnodenumberspecifiedwaslarger
thanthe largestfnodenumberin the
volume.
Disk Verification
2-39
FREE
no badblocksfile
The volume doesnot havea bad blocksfile. This messagecould
of theHumanInterface
because
anearlierversion
appear
FORMAT commandwasusedwhenthe diskwasformatted.
not a nameddisk
2-40
FREE wasperformedon a physicalvolume.
Disk Verification
This commanddisplaysthe volume'sbad trackinformation.It canbe abortedby entering
CONTROL-C. The format of GETBADTRACKINFO is
x.1599
INPUT PARAMETERS
None.
OUTPUT
The GETBADTRACKINFO commanddisplaysthe volume'sbad track informationas
written by the manufactureror the HumanInterfaceFORMAT command.The output
displayedby the GETBADTRACKINFOcommandis compatiblewith the format
required by the Human InterfaceFORMAT commandwhen writing bad track
informationon the disk. To usethe outputasinput to FORMAT, removethe first two
lines,leavingonly the actualbad track information data. The displayis as follows:
Bad track
L-/
!
cccc
cccc
information:
L^-r
hh
hh
ss
ss
whereccccis rylindernumber,hh is the headnumberand ssis the sector number(always
zero for all devicessupportedin this releaseof the operatingSystem).
Disk Verification
2-41
GETBADTRACKINFO
As mentionedabove,the outputof the GETBADTRACKINFOcommandcanbe usedas
file. The
whencreating
thebadtrackinformation
inputto theFORMATcommand
examplebelow showshow to useGETBADTRACKINFO this way.
-atÈachdevlce wnfdxo as :v:
*exLt
and removethe
After exitingDISKVERIFY and rebootingthe system,edit :w:bad.lst
headerlines. The file canthenbe usedasinDutto the bad track informationfile created
by the FORMAT command.
ERRORMESSAGES
2-42
I/O error whiletryingto readbad
track information
An I/O error occurredwhile readingthe
bad trackinformation.
No valid bad track info found
Bad track information is not valid and
cannotbe displayed.
No bad track info found
The areadesignated
for bad track
informationis emDtv.
l)isk Verification
This commandlistsall availableDisk VerificationUtilify commandsand providesa short
descrintionof eachcommand.The formatof the HELP commandis
F0214
OUTPUT
In response
to thiscommand,
HELPdisplays
thefollowing
information:
*heIp
aLlocace/free
fnodes (bî /r î)
Control C
di sk
( d, db/dw)
display byte/vord
(dd)
display
directory
display fnode (df )
display next block (>, dnb )
display previous block (<,dpb)
dlsplay save fnode (dsf)
exÍ t, qui t
bad blocks (lbb)
list
read (r)
restore volune label (rvl)
save
(s, sb/sw)
substltute
byte/word
ver ify
\,Iri te (Lr)
edit fnode (ef)
edi t save fnode (esf)
fix
get bad track info (gb)
nisc connands address
block
hex/dec
add, +, sub, - , nul , *, div, /, rnod
backup/restore
DiskYerification
a1l-ocate/free
fnodes, space blocks, bad blocks
to,/from save area
backup/restore Inode file
abort the comnand in progress
display disk at tr ibute s
format)
display
the buffer
in (byte/word
display
the directory
contents
fnode information
display
'next'
volune block
read and display
'previous'
volume block
read and display
display
saved fnode information
^..: c
gur L
r . ' ^ 1 , . .w^ E- :! ft -! ,)
ursF
bad blocks on the vol.ume
list
read a disk block into the buffer
copy volurne 1abel from save area
save free fnodes, free space & bad block
(byte/word
format)
rnodify the buffer
..^-:
8..
ÈL^
naps
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
c o n v e r t a b s o l u t e a d d r e s s t o b l o c k n u r n b er
display
number as hexade c imal/de c imal nurnber
operations
on unsigned nurnbers
afithmetic
2-4i
all thebadblockson a namedvolume.Youcanabortthis
Thiscommand
displays
commandby tlping a CONTROL-C.Theformatof the LISTBADBLOCKScommandis
as follows:
F0208
OUTPUT
In responseto thiscommand,LISTBADBLOCKSdisplaysup to eightcolumnsof block
numbersthat you specifiedas"bad."Figure2-2 illustratesthe format of the display.
Badblocks on Volune:
volumenurn
(b I o cknurn)
(blocknurn)
(blocknr.uÈ
(blocknurn)
(blocknurn)
(blocknum>
Figure2-2. LISTBADBLOCKSFormat
lf noneof the blockshavebeenmarkedas"bad",LISTBADBLOCKSdisplaysthe
following message:
no badblocks
NOTE
Bad tracksand bad blocksare different. Bad tracksare handledby the
devicedriversin conjunctionwith the hardware,whereas,bad blocksare
handledby the iRMX II BasicI/O System.
2-44
Disk Verification
LISTBADBLOCKS
ERRORMESSAGES
no badblocksfiÌe
Disk Verification
The volume doesnot havea bad blocksfile. This messagecould
appearbecause
an earlierversionof the HumanInterface
FORMAT commandwasusedwhenthe diskwasformattedor
because
the diskis a ohvsicalvolume.
2-45
The followingcommandsprovideyou with the abilityto performarithmeticand
conversionoperationswithin the Disk VerificationUtility. The commandsperformthe
operationson unsignednumbersonly and do not report anyoverflowconditions.When
and decimalformat,it appearsin
the numberis displayedin both hexadecimal
For example:
by
the
decimal
numberin parentheses.
followed
format first,
hexa
where:
< addr >
Absoluteaddressin hexadecimal
that corresponds
to the speciîied
blocknumber.This addressrepresents
the numberof the bytethat
beginsthe blockand canrangefrom 0 through(volumesize- 1),
wherevolumesizeis the size,in bytes,of the volume.
BLOCK
The BLOCK commandis the inverseof the addresscommand.It convertsa 32-bit
absoluteaddress(in hexadecimal)
into a volumeblocknumber,so that you don't haveto
performthisconversionby hand. The formatof thiscommandis
where:
address
Absoluteaddressin hexadecimal
that BI.OCK convertsinto a
blocknumber. This parametercanrangeliom 0 through(volume
size- 1),wherevolumesizeis the size,in bytes,of the volume.
In response,
BLOCK dispÌaysthe followinginformation:
block nunber :
where:
< blocknum>
Disk Verification
Numberof the volumeblockthat containsthe specifiedabsolute
addressin hexadecimal.
The BLOCK commanddeterminesthis
valueby dividingthe absoluteaddressby the volumeblocksizeand
truncatinqthe result.
2-47
MISCELLANEOUS
COMMANDS
DEC
This commandfindsthe decimalequivalentof a number. Its format is
<'-y'--'<1:,->
where:
arg
equivalent.The
Numberfor whichthe commandfindsthe decim-al
valueof the argumentcannotbe greaterthan2'"-1. The default
baseis in hexadecìmal.
In response,
the commanddisplaysthe decimalequivalentof the specifiednumber.
DIV
This commanddividesone numberby another.Its format is
where:
argl and arg2
Numberson whichthe commandoperates.It divides-arglby arg2.
The valueof eachargumentcannotbe greaterthan 2rz-1.
In response,
the commanddisplaysthe unsignedintegerquotientin both hexadecimal
and
decimalformat.
2-48
Disk Verification
MISCELLAN
EOUSCOMMANDS
HEX
This commandfindsthe hexadecimal
equivalentof a number. Its format is
<3>1-r->
where:
arg
Numberfor whichthe commandfindsthe hexadecimal
eouivalent.
If you are speci$ring
a decimalnumber,you mustspgify i "f'
The valueofthe argumentcannotbe greaterthan2)z-1.
In response,
the commanddisplaysthe hexadecimal
equivalentof the specìfietlnumber.
MOD
This commandfindsthe remainderof one numberdividedby another. Its format is
uoo
,/---
-e'
-.,'1]
!
''c'?
where:
argl and arg2
Numberson whichthe commandoperates.It performsthe
operationargl moduloarg2. The valueof eachargumentcannot
be greaterthan2-'z-l.
In response,
the commanddisplaysthe valueargl moduloarg2in both hexadecimal
and
decimalformat.
Disk Verification
2-19
COMMANDS
MISCELLANEOUS
MUL
This commandmultipliestwo numberstogether.Its formatis
where:
argl and arg2
The valueof each
Numbersthe commandmultiplieslo^gether.
argumentcannotbe greaterthan2'tz-1.
the commanddisplaysthe unsignedproductof the two numbersin both
In response,
and decimalformat.
hexadecimal
SUB
This command subtractsone number from another. Its li)rmat is
where:
argl and arg2
Numberson whichthe commandoperates.The command
subtractsarg2from argl. The valueof eachargumentcannotbe
ereaterthan2''z-1.
the commanddisplaysthe unsigneddifferencein both hexadecimal
and
In response,
decimalformat.
2-50
Disk Verification
MISCELTANEOUS
COMMANDS
ERRORMESSAGES
The followingerror messages
maybe returnedby anyof the Miscellaneous
Commands:
argumenterror
A syntaxerror wasmadein the
command,a nonnumericvaluefor one of
wasspecified,or a value
the arguments
for a blocknumberparameterthat was
not a valid blocknumberwassoecified.
< blocknum> , blockout of range
lf the commandwasan ADDRESS
command,the blocknumberenteredwas
greaterthan the numberof blocksin the
volume.
< address
> , addressnot on the
disk
If the commandwasa BLOCK command,
BLOCK convertedthe addressto a
volumeblocknumber,but the block
numberwasgreaterthan the numberof
blocksin the volunrc.
EXAMPLES
*l{ul, 134î, 13î
6cE ( 7142T)
*+ 8, 4
0c (
12r)
*suB 8884, 256
8 6 2 E( 3 4 3 5 0 r )
*l{oD 1225, 256T
31r)
25 (
*HEx 155T
9B
*ADDRESS15
absolute address - 0A80
*BLoCK2236
block nunber - 44
Disk Verification
2-51
This commandexitsthe Disk VerificationUtility and returnscontrolto the Human
Interfacecommandlevel. The formatof the QUIT commandis asfollows:
This commandis identicalto the EXIT command.
) -<,
Disk Verilìcation
This commandreadsa volumeblockfrom the diskinto the workingbuffer. The format of
the READ commandis
INPUT PARAMETER
Numberof the volumeblockto read. This numbercan rangefrom
0 through(maxblocks- 1),wheremaxblocksis the numberof
volumeblocksin the volume.
blocknum
OUTPUT
ln responseto the command,READ readsthe blockinto the workingbutlèr and displays
the followingmessage:
read block
nurnber:
where is the number of the block.
DESCR]PTION
The READ command copies a specifiedvoÌume block from the volume to the working
buffer. It destroysany 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 changethe data in
the block. Finally, you can use the WRITE command to write the modified block back to
the volume and repair damagedvolume data.
ERROR MESSAGES
argumenterror
A nonnumericcharacterwasspecifiedin
the blocknumparameter.
< blocknum> , blockout of range
The blocknumberspecifiedwaslarger
than the largestblocknumberin the
volume.
FFFFFFFF.blockout of ranee
No blocknumberwasspecifiedand no
previousreadrequestwasexecutedon
thisvolume.
Disk Verification
2-53
This commandcopiesan fnodeor a rangeof fnodesfrom the R?SAVEfile to the fnode
file. Beforechangingthe fnodefile, RESTOREFNODEdisplaysthe fnodenumberto be
changedand promptsyou to confirm(by enteringa "y")that the fnodeis to be restored.
R?SAVEmusthavebeenreserved(the RESERVEoptionof the FORMAT command
musthavebeenspecified)whenthe volumewasformatted.The format of the
RESTOREFNODEcommandis asfollows:
REsTORÉFNODE
fnodenum
fnodenum
1
fnodenum2
INPUT PARAMETER
fnodenum
The hexadecimal
numberof the fnodeto be restored.This number
mustbe greaterthanor equalto zeroand lessthan the m.tximum
numberof fnodesdefinedwhenthe volumewasfbrmatted.
fnodenumI
The initial hexadecimal
fnodenumberin a rangeof fnodesto be
restored.This numbermustbe greaterthan or equalto zero and
lessthanor equalto the final fnodenumberin the range
lfnodenum2l.
fnodenum2
The final hexadecimal
fnodenumberin a rangeof fnodesto be
restored.This numbermustbe greaterthanor equalto the initial
fnodenumberin the range(fnodenuml)and lessthan the
marimumnumberof fnodesdefinedwhenthe volumewas
formatted.
OUTPUT
Whenthe fnodeis restored(the response
to the confirmationqueryis "Y" or "y"):
( fnodenurn)? Y
restore fnode
r e s È o r e d f n o d e nunber :
( fnodenr.un)
2-54
Disk Verification
RESTOREFNODE
to the confirmationqueryis not "Y"):
When the fnodeis not restored(the response
restore
fnode
( fnodenur) ?
DESCRIFTION
The RESTOREFNODEcommandenablesyou to rebuilda damagedfnodefile, thereby
re-establishing
linksto datathat wouldotherwisebe lost. RESTOREFNODEcopiesan
fnode or a rangeof fnodesfrom the R?SAVE file (the fnode backupfile) to the fnode file.
Beforeeachof the specifiedfnodesis copied,RESTOREFNODEdisplaysa query
promptingyou to confirmthat the indicatedfnodeis to be restored.You mustreplyto
this querywith the letter "Y" (either"Y" or "y")to restorethe fnode. If you enterany
RESTOREFNODEwill not restorethe fnotleandwill passon to the next
other response,
fnodein the range.
SinceRESTOREFNODEoperateson the R?SAVEfile,you musthavereservedthis file
the RESERVE
whenthe volumewasformatted.(You reserveR?SAVEby specifuing
parameterwhenyou invokethe FORMAT commandto formatthe volume.) lf the
R?SAVEfile wasnot reservedwhenthe volumewasformatted,RESTOREFNODEwill
return an error message.
CAUTION
When using this comrnand,be sure that any fnodeyou restore represents
a file that has not beenmodified sincethe last fnodebackup.
RESTOREFNODEoverwritesthe specifiedfnode in the fnodefile with the
correspondingfnode in the R?SAVEfile. Ifthat fnode has not been
backedup sincethe last file modification,a valid fnode may be
fìle will be
overwrittenwith invaliddata, Thus,all links to the associated
DATA
IN
THE
FILE.
ALL
THE
and
YOU
WILL
LOSE
OF
destroyed,
ERRORMESSAGES
argumenterror
Whenthe commandwasentered,no
argumentwassupplied.This command
rctluiresan argument.
no saveareawasreservedwhen
volumewasformatted
The volumewasnot formattedto support
backupfnodes.This meansthe
RESERVEoptionwasnot specified
whenthe volumewasformatted.
Disk Verification
2-55
RESTOREFNODE
not a nameddisk
The volume specifiedwhen the Disk
Verification Utiiity wasinvokedis a
physicalvolume,not a namedvolume.
< fnodenum>, fnodeout of
range
The fnodenumberspecifiedis not in the
rangeof 0 to (maximumfnodes- 1).
allocationbit not set for saved
fnode restorefnode < fnode
num>?
The fnode you specifiedhasnot been
backedup in the R?SAVEfile. If you
respondto the querywith a "Y", THE
DATA IN THE FILE ASSOCIATED
WIT]] THE ORIGINAL FNODE WILL
BE LOST.
EXAMPLE
super- dfskverlfy
: sd:
iRl{X II Disk Verify Utility,
Vx.x
Copyrlght or
rf 9,0B
restored fnode number:
9
rescore fnode
0A? Y
restored fnode nurnber:
0A
restore fnodè
0B? Y
rescored fnode number:
0B
2-56
Disk Verification
This commandcopiesthe duplicatevolume label to the volume label on track 0. The
duplicatevolumelabelmusthavebeenconstructed
whenthe volumewasformatted.
(That is, the RESERVE option of the FORMAT commandmust havebeen specified
whenthe volumewasformatted.)The format of the RESTOREVOLUMEII,BEL
commandis as follows:
F 0 2 11
INPUT PARAMETERS
None.
OUTPUT
volumelabelrestored
DESCRIPIION
The RESTOREVOLUMELABELcommandenablesyou to rebuilda damagedvolume
label,therebyre-establishing
linksto datathat wouldotherwisebe lost.
RESTOREVOLUMEI-ABELcopiesthe duplicatevolumelabelto the volumelabeloffset
on track0. Whenyou usethe HumanInterfaceFORMAT commandto createthe
duplicatevolume label (by specifyingthe RESERVE parameter),the volume label is
automatically
copiedto the end of the R?SAVEfile. Becausethe contentsof the volume
labeldo not change,no othervolumelabelbackupis required.
If a duplicatevolumelabelhasbeenreseryedon a volume,the Disk VerificationUtility
canaccessthat volumeasa Namedvolumeevenif the volumelabelis damaged.When
the originalvolumelabelis corrupted,the Disk VerificationUtility attemptsto usethe
duplicatevolumelabel. If the backuplabelis used,a "DUPLICATE VOLUME I-ABEL
USED" message
appearswhenthe utility is invoked.
If the duplicatevolumelabelwasnot reservedwhenthe voiumewasformatted,
RESTOREVOLUMEI-ABELwill returnan error messase.
Disk Verification
2-57
RESTOREVOLUMELABEL
ERROR MESSAGES
argumenterror
Whenthe commandwasentered,an
argùmentwassupplìed.This command
doesnot acceptan argument.
no savearea was reservedwhen
volume lvas formatted
The volumehasnot beenformattedto
supportvolumelabelbackup.
not a named disk
The volumespecifiedwhenthe Disk
VerificationUtility wasinvokedis a
physicalvolume,not a namedvolume.
EXAMPLE
supèr- diskverlfy
: sd:
Vx.x
I R M XI l D l s k V e r i f y U t i l i t y ,
Copyrlght lntel Corporation
:sd:, outstandlng connections to device have been deleted
DUPLICATE VOLUMEU.BEL USED
*restorevolune labe I or rvl
, N A I 4 E D 2V
' ERIFICATION
B I T M A P SO .K .
*sAvE
savè fnode map? y
free fnode map saved
save space nap? y
free space map saved
2-60
Disk Verification
This commandenablesyou to interactively
changethe contentsof the workingbuffer(in
byteformat). You canabortthis commandby typinga CONTROL-C. The format of the
SUBSTTUTEBYTE commandis
SUASrrÌUl€BYrE
INPUT PARAMETER
Numberof the first byte,relativeto the startof the workingbuffer,
that you wantto change.This numbercanrangefrom 0 to (block
size- l), whereblocksizeis the sizeof a volumeblock(and thus
the sizeof the workingbuffer). If you omit this parameter,the
a valueof 0.
commandassumes
offset
OUTPUT
In responseto the command,SUBSTITUTEBYTEdisplaysthe specifiedbyteandwaits
for you to entera newvalue. This displayappearsas
:
val
where < offset> is the numberof the byte,relativeto the startof the buffer,and val is the
currentvalueof the byte. At this point,you canenterone of the following:
.
A valuefollowedby a carriagereturn. This causesSUBSTITUTEBYTEto substitute
the newvaluefor the currentbyte. If the valueyou enterrequiresmore than one byte
of storage,SUBSTITUTEBYTEusesonly the low-orderbyteof the value. It then
displaysthe nextbytein the bufferand waitsfor furtherinput.
.
A carriagereturn alone.This causesSUBSTITUTEBYTEto leavethe currentvalue
asis and displaythe nextbytc in the buffer. lt thenwaitsfor furtherinput.
Disk Verifìcation
2-61
SUBSTITUTEBYTE
.
A valuefollowedby a period(.) and a carriagereturn. This causes
SUBSTITUTEBYTE to substitutethe new value for the current b]'te. It then exits
from the SUBSTITUTEBYTEcommandand givesthe asterisk(*) prompt,enabling
you to enterany DISKVERIFY command.
.
A period (.) followed by a carriagereturn. This exitsthe SUBSTITUTEBYTE
commandand givesthe asterisk(*) prompt,enablingyou to enteranyDISKVERIFY
command.
DESCRIP'TION
With the SUBSTITUTEBYTE commandyou can interactivelychangebytesin the
working buffer. Once you enter the command,SUBSTITUTEBYTE displaysthe offset
and the valueof the first byte. You canchangethe byteby enteringa new bytevalue,or
you canleavethe byteas is by enteringa carriagereturn. The commandthendisplaysthe
nextbytein the buffer. In this manner,you canconsecutively
stepthroughthe buffer,
changingwhateverbytesare appropriate.Whenyou finishchangingthe buffer,you can
entera periodfollowedby a carriagereturnto exit the commantl.
The SUBSTITUTEBYTE commandconsidersthe working buffer to be a circular buffer.
That is, enteringa carriagereturnwhenyou are positionedat the lastbyteof the buffer
causesSUBSTITUTEBYTE to displaythe first byte of the buffer.
The SUBSTITUTEBYTEcommandchanges
only the valuesin the workingbuffer. To
makethe changesin the volume,you mustenterthe WRITE commandto write the
workingbufferbackto the volume.
ERRORMESSAGES
2-62
argumenterror
A nonnumericcharacterwasspecifiedin
the offsetparameter.
,invalidoffset
An offsetvaluelargerthan the numberof
bytesin the block wasspecified.
Disk Verification
SUBSTITUTEBYTE
EXAMPLE
This examplechangesseveralbytesin two portions of the working buffer. Two
SUBSTITUTEBYTE commandsare used.
*SUBSTITUTEBYTE
0000:
0001:
0002:
0003:
0004:
A0
80
E5
FF
FF
-
00
31
.
*SUBSTITUÎEBYÎE
4O
0040: 00 - E6
0041: 0O - E6
0042: 00 - .
Disk Verification
2-63
Thiscommand
is identical
to SUBSTITUTEBYTE,
exceptthatit displays
thebufferin
wordvaluesin thebuffer.Theformatof the
WORDformat,andsubstitutes
SUBSTITUTEV/ORD
command
is
EXAMPLE
This examplechangesseveralbytesin two areasof the workingbuffer. Two
SUBSTITUTEWORDcommandsare used. In the first commandthe wordsbeginon
evenaddresses,
and in the secondcommanC,
theybeginon odd addresses.
*SUBSTTTUTEgORD
0000
0002
0004
0006
0008
AOBO 0000
8 0 7 0
E51t-
FFFF
3111
FFFF
.
*SUBSTITUTEi{ORD
35
0035: 0000 - E6FF
0037: 0000 - E6AB
0039: 0000 - .
2-64
Disk Veriffcation
This commandchecksthe structureson the volumeto determinewhetherthe volumeis
properlyformatted.You canabortthis commandby t)?ing a CONTROL-C. The tbrmat
of the VERIFY commandis
VERIFY
NAMED
PHYSICAL
F 0211
INPUT PARAMETERS
NAMEDl or Nl
Checksnamedvolumesto ensurethat the infìtrmationrecordedin
and matchesthe informationobtained
the fnodesis consistent
from the directoriesthemselves.VERIFY perfbrmsthe following
operationsduringa NAMEDl verification:
.
Checksfnodenumbersin the directoriesto seeif they
correspondto allocatedfnodes.
.
Checksthe parentlhodenumbersrecordedin the thodesto see
if theymatchthe informationrecordedin the directories.
o
Checksthe fnodesagainstthe filesto determineif the thodes
specif the properfile type.
.
Checksrhe POINTE,R(n)structuresof longfilesto seeif the
indirectblocksaccuratelyreflectthe numberof blocksusedby
thefile.
.
Checkseachfnodeto seeif the TOTAL SIZE, TOTAL BLKS,
andTHIS SIZE fieldsare consistent.
o
Checksthe bad blocksfile to seeif the blocksin the file
correspondto the blocksmarkedas"bad"on the volume.
o Checksthe checksum
of eachfnode.
Disk Verilication
2-65
VERIFY
NAMED2 or N2
Checksnamedvolumesto ensurethat the informationrecordedin
the free fnodesmap and the volumefree spacemap matchesthe
actualfilesand fnodes.VERIFY performsthe following
operationsduringa NAMED2 verification:
e
Createsa free fnodesmapby examiningeverydirectoryin the
volume. It thencomparesthat free fnodesmapwith the one
alreadyon the volume.
o
Createsa free spacemapby examiningthe informationin the
fnodes.lt thencomparesthat free spacemapwith the one
alreadyon the volume.
.
Checksto seeif the blocknumbersrecordedin the fnodesand
the indirectblocksactuallyexist.
.
Checksto seeif two or morefilesusethe samevolumeblock.
If so,it liststhe filesreferringto eachblock.
e
Checksthe volumefree spacemap for anybad blocksthat are
markedas "free."
.
Checksto seeif two or more directoriesreferencethe same
fnode. If so,it liststhe directoriesreferringto eachfnode.
NAMED or N
Performsboth the NAMEDI and NAMED2 ooerationson a
namedvolume. If you specifythe VERIFY commandwith no
option,NAMED is the default.
ALL
Performsall operationsappropriateto the volume. For named
volumes,
thisoptionperformsborhthe NAMED andpHySICAL
operations.For physicalvolumes,this optionperformsonly the
PHYSICAL operations.
PHYSICAL
Readsall blockson rhevolumeandchecksfor I/O errors. This
parameterappliesto both namedand physicalvolumes.VERIFY
alsocreatesa bad blocksmap by examiningeveryblockon the
volume.
LIST
Whenyou speci! thisoption,the file informationin Figure2-3 is
displayedfor everyfile on the volume,evenif the file containsno
errors. You canusethis optionwith all parametersthat,either
explicitlyor implicitly,specifythe NAMED I paramerer.
OUTPUT
VERIFY producesa differentkind of outputfor eachof the NAMEDl, NAMED2, and
PHYSICAL options.The NAMED andALL optionsproducecombinations
of these
threekindsof outDut.
2-66
Disk Verification
VERIFY
Figure2-3 illustratesthe formatof the NAMEDI output(\ùithoutthe LIST option).
DEVICE NAI'IE:
, NAì"ÍEDI' VERIFlCATION
FILE- (
LEVEL::
PARENT::
TYPE:
FILE- (
LEVEL:<1ev>:
PAI{ENT::
TYPE:
ffle-
LEVEI--<1ev>: PARENT-:
TYPE:
1, r:
Figure 2-3. NAMEDI Verification Output
The followingparagraphs
identifothe fieldslistedin Figure2-3.
< devname>
Physicalnameof the device,as specifiedin the ATTACHDEVICE
Humanlnterfacecommand.
< devsize>
Hexadecimal
sizeof the volume,in bytes.
< blksize>
Hexadecimal
volumegranularity.This numberis the sizeof a
volumeblock.
Nameof thefile (l to 14characters).
< fnodenum>
Hexa
Hexadecimal
levelof the file in the file hierarchy.The root
directoryof the volumeis the only level0 file. Filescontainedin
the root directoryare level1 files. Filescontainedin level I
directoriesare level2 files. This numberinscontinuesfor all levels
of filesin the volume.
< parnt>
Fnodenumberof the directorythat containsthisfile, in
hexadecimal.
Disk Verification
2-67
VERIFY
File type,eitherDATA (datafiles),DIR (directoryfiles),SMAP
(volumefree spacemap),FMAP (freefnodesmap),BMAP (bad
blocksmap),or VI-AB (volumelabelfile). If VERIFY cannot
ascertainthat the file is a directoryor datafile, it displaysthe
r****ù iÍr this field.
characters
with the previously Messages
that indicatethe errorsassociated
are listed later in this
listed file. The possibleerror messages
section.
As Figure2-3shows,the NAMED1 option(withoutthe LIST option)displays
informationabouteachfile that is in error. Ifyou usedthe LIST optionwjth the
NAMED I option, the file information in Figure 2-3 is displayedfor everyfile, evenif the
that
file containsno errors. The NAMEDl displayalsocontainserror messages
immediatelyfollowthe list of the affectedfiles.
Figure2-4i.llustrates
the formatof the NAMED2 output. If VERIFY detectsan error
verification,
it displaysone or more error messages
in placeof the "BlT
duringNAMED2
MAPS O.K.' messase.
D E V I C E N A M E:
(dermame)
: DEVICE SIZE :
(devsize>
: BLK SIZE :
(blksze)
'NA.t.fED2
' VERI FICATION
B I T M A P SO .K .
Figure 2-4. NAMED2 Verificati{}nOutput
The fieldsin Figure2-4 are exactlythe sameasthe corresponding
fieldsin Figure2-3.
Figure2-5 illustratesthe formatof the PHYSICAL output.
DEVICE NAl.fE: : DEVICE SIZE : (devsize>
: BLOCKSIZE :
, P H Y S I C A L 'V E R I F I C A T I O N
NO ERRORS
Figure 2-5. PHYSICAL Verification Output
2-68
Disk Verification
VERIFY
fieldsin Figure2-3.
The fieldsin Figure2-5are exactlythe sameasthe corresponding
If VERIFY detectsan error duringPHYSICALverification,it displaysthe message:
, blockbad
The blocknumbersdisplayedin this message
are markedas"bad."
.
. invalid block number recordedin the
fnode/indirect block
One of the POINTER(n) fields in the fnode specifiesblock numberslarger than the
largestblock number in the volume.
o
directory stackoverflow
This messageindicatesthat a directoryon the volume lists,as one of its entries,itself
or one of the parentdirectoriesin its pathname.If this happens,the utiliry,when it
searches
throughthe directorytree,continuallyloopsthrougha portionof the tree,
overflowingan internalbufferarea. In thiscase,performingNAMED2 verification
may indicatethe causeof thisproblem.
.
file sizeinconsistent
total$size= :this$size= :datablocks=
The TOTAL SIZE, THIS SIZE, and TOTAL BLKS fields of the fnode are
inconsistent.
o
< filetpe >, illegalfile type
The file type of a user file, asrecordedin the TYPE field of the fnode, is not valid.
The valid file typesand their descriptionsare asfollows:
File Fpe
SMAP
FMAP
BMAP
DIR
DATA
VI-AB
.
Number
1
2
4
6
8
9
Descriorion
volumefree spacemap
free fnodesmap
bad blocksmap
directory
data
volume label file
,allocationstatusbit in this fnodenot set
The file is listedin a directorybut the flagsfield of its fnodeindicatesthat fnodeis
free. The free fnodesmap mayor maynot list the fnodeasallocated.
.
,fnodeout ofrange
The fnodenumberis largerthanthe largestfnodenumberin the fnodefile.
2-70
Disk Verification
VERIFY
.
,parentfnodenumberdoesnot match
The fi.lerepresentedby fnodenumis containedwithin a directorywhosefnode number
doesnot match the parent field of the file.
e
invalid blocknumrecordedin the fnode/indirect block
One of the pointerswithin the fnodeor within the indirectblockspecifiesa block
numberthat is largerthan the largestblocknumberin the volume.
.
insufficientmemory to createdirectorystack
There is not enoughdynamicmemoryavailablein the systemfor the utility to perform
the verification.
.
sum of the blks in the indirect block doesnot matchblock in the fnode
The file is a long file, and the numberof blockslisted in a POINTER(n) field of the
fnodedoesnot agreewith the numberof blockslistedin the indirectblock.
.
total-blocksdoesnot reflect the data-blockscorrectly
The TOTAL BLKS field of the fnode and the number of blocksrecordedin the
POINTERIn) fieldsare inconsistent.
.
Bad Checksum,
checksumis :
shouldbe:
Checksum
An invalidchecksumhasbeencalculated.
NAMED2 Messages
The following messages
can appearin a NAMED2 display.
.
< blocknumI - blocknum2>,bad block not allocated
The volumefree spacemap indicatesthat the blocksare free,but theyare markedas
"bad"in the bad blocksfile.
.
,blockallocatedbut not referenced
The volume free spacemap lists the specifiedvolume block as allocated,but no fnode
specifiesthe block aspart of a file.
r
,blockreferencedbut not allocated
An fnodeindicatesthat the specifiedvolumeblockis part of a file, but the volumefree
spacemap liststhe blockasfree.
Disk Verification
2-7|
VERIFY
.
directorystackoverflow
This message
can indicatethat a directoryon the volumelists,as one of its entries,
itselfor one of the parentdirectoriesin its pathname.If this happens,the utility,
whenit searches
throughthe directorytree,continuallyloopsthrougha portion of the
tree,overflowingan internalbufferarea. The "MultipleReference"
message
(explainedbelow)mayhelpyou find the causeof thisproblem.
o
Fnodesmap indicatesfnodes> m:u$fnode
The free fnodesmap indicatesthat thereare a greaternumberof unallocated
fnodes
thanthe maximumnumberof fnodesin lhe volume.
r
,fnode-mapbit markedallocatedbut not referenced
The free fnodesmap liststhe specifiedfnodeasallocated,but no directorycontainsa
file with the fnodenumber.
o
,fnodereferencedbut fnode-mapbit markedfree
The specifiedfnodenumberis listedin a directory,but the free fnodesmap liststhe
fnode as free.
.
Free spacemap indicatesVolumeblock > max$Volume$block
The free spacemap indicatesthat thereare a greaternumberof unallocated
blocks
than the maximumnumberof blocksin the volume.
.
insufficientmemoryto createdirectorystack
Not enoughdynamicmemoryis availablein the systemfor the utility to performthe
verification.
.
insufficientmemoryto createfnodeand spacemaps
During a NAMED2 verification,the utility tried to createa free fnodesmap and a
volumefree spacemap. However,not enoughdynamicmemoryis availablein the
systemto createthesemaps.
.
insufficientmemoryto createbad blocksmap
During a PHYSICAL verification,the utility tried to createa bad blocksmap.
However,not enoughdynamicmemoryis availablein the systemto createthe map.
o
Multiplereferenceto fnode
Pathname: < full path name>
referring fnodes:
< fnodenum> Pathname:< full path name>
Pathname:
The directorieson the volumelist morethan one file associated
with this fnode
number.
2-72
Disk Verification
VERIFY
.
Multiple referenceto block < blocknum>
referring fnodes:
Pathname:
Pathname: < full path name>
More than one fnodespecifies
this blockaspart of a file.
PHYSICAL Messages
.
< blocknum>, error
An I/O error occurredwhen VERIFY tried to accessthe speciîiedvolume block. The
volume is probablyflawed.
Miscellaneous
Messases
The followingmessages
indicateinternalerrorsin the Disk VerificationUtility. Under
(or
normalconditionsthesemessages
shouldneverappear.However,if thesemessages
verification,
other undocumented
messages)
do appearduringa NAMEDl or NAMED2
you shouldexit the Disk VerificationUtility and re-enterthe DISKVERIFY command.
directorystackempty
directorystackerror
directorystackunderflow
EXAMPLE
The followingcommandperformsboth namedand physicalverificationon a named
volume.
*VERIFY ALL
DEVICE NAÌ'IE: F1
: DEVICE SIZE : 0003E900 : BLoCK SIZE : 0080
,NAI4EDI' VERIFICATION
,NA.I{ED2'VERIFICATION
B I T } , I A P SO . K .
, PHYSICAL' VERIFICATION
NO ERRORS
Disk Verification
2-7t
This commandwritesthe contentsof the workinsbufferto the volume. The format of
this commandis
b l o c k num
F0 2 1 0
INPUT PARAMETER
blocknum
Numberof the volumeblockto whichthe commandwritesthe
workingbuffer. If you omit this parameter,WRITE writesthe
bufferbackto the blockmostrecentlvaccessed.
OUTPUT
In responseto the command,WRITE displaysthe followingmessage:
write
to block is the numberof the volumeblockto whichWRITE intendsto write
the workingbuffer. If you respondby enteringY or anycharacterstringbeginningwith y
or y, WRITE copiesthe workingbufferto the specifiedblockon the volumeand displays
the following message:
written
to block nunber:
Any other responseabortsthe write process.
DESCRIPTION
The WRITE commandis usedin conjunctionwith the READ, DISPT-AYBYTE,
DISPI-AYWORD, SUBSTITUTEBYTE, and SUBSTITUTEWORD commandsto
modifyinformationon the volume. Initiallyyou useREAD to copya volumeblockfrom
the volumeto a workingbuffer. Thenyou canuseDISPTAYBYTEand
DISPI-A,YWORD to view the buffer and SUBSTITUTEBYTE and
SUBSTITUTEWORDto changethe buffer. Finally,you can useWRITE to write the
modifiedbufferbackto the volume. By default,WRITE copiesrhe bufferto the block
mostrecentlyaccessed
by a READ or WRITE command.
A WRITE commanddoesnot destroythe datain the workingbuffer. The dataremains
the sameuntil the nextSUBSTITUTEBYTE,SUBSTITUTEWORD.or READ
commandmodifiesthe buffer.
2-74
Disk Verification
WRITE
ERRORMESSAGES
argumenterror
A syntaxerror wasmadeor nonnumeric
characters
werespecifiedin the
blocknumparameter.
< blocknum> , blockout of range
The blocknumberspecifiedwaslarger
than the largestblocknumberin the
volume.
FFFFFFFF,blockout ofrange
No blocknumwasspecifiedand no
previousreadrequestwasexecutedon
thisvolume.
EXAMPLE
The followingcommandcopiesthe workingbullèr to the blockfrom whichit wasread.
*I.RITE
wrire 48? y
wrltcen to block number: 48
Disk Verification
2-75
CHAPTER
3
BACKINGUPAND RESTORING
FNODES
3.1 INTRODUCTION
To access
dataon a namedvolume(suchasa disk),the iRMX Il OperatingSystemusesa
mechanism
commonto virtuallyall operatingsystems:it maintainsan indexto everyfile
on the disk. Thisindexis createdwhenthe diskis formattedandremainsasa permanent
structureat a dedicatedlocationon the clisk.The indexconsistsof a systemof pointers
that indicatethe locationof the datafileson the disk. Thus,whendatamustbe storedon
or retrievedfrom the disk,the operatingsystemcanfind the exactlocationof the
appropriatefile by lookingup the file namein the index.
In the operating
system,
the indexconsists
of the iRMX ll volumelabelandan fnodefile.
This volumelabelresidesat the samelocationin all devicesand seruesasthe initial entry
point into the device.The fnodefile canresidean).where
on the disk (specifiedwhenthe
disk is formatted)and containsa seriesof individualstructurescalledfile dcscriptornodes
or "fnodes."Thereis one fnodefor eachlle on the disk. The lnodecontainsinformation
essentialto accessing
and maintainingthe respective
file.
The iRMX II file structurefor a namedvolumeis organizerJ
asa hierarchicaltree. That
is,thereis a root directorywith branchesto otherdirectoriesand ultimately,to files. The
organization
of the fnodefile reflectsthis hierarchical
structure.The iRMX II volume
labelcontainsa pointerto the fnodeof the file structure'sroot directory.The root
directoryis alwaysthe startingaddressfor anyfiìe or directoryon the volume. It listsalÌ
the first levelfilesand directorieson the volume. First leveldirectoriespoint to second
levelfilesand directories,and so on, downthe hierarchical
structure.
As previouslymentioned,eachfile or directoryis represented
by an fnode. The fnode,
alongwith other datadescribingthe file or directory,containspointersto blockson the
volume. If the fnodedescribes
a shortfile, theseblockscontainthe actualfile data. If the
fnodedescribes
a longfile, theseblockscontainpointcrsto otherblockscontainingthe
actualdata. If the fnodedescribes
a directory,theseblockscontainentrieswhichdescribe
the contentsof the directorv.Eachentrvliststhe fnodenumberand nameof the
associated
file or directory,
The operatingsystemcreatesthe iRMX Il volumelabeland the lìode file whenthe disk
is formatted.
Disk Verification
3-l
BACKING UP AND RESTORINGFNODES
fnodesin the fnodefile is controlledby the FILES parameter
The numberof unallocated
fnodes,seven(with an option
of the FORMAT command.In additionto the unalìocated
whenthe fnodefile is created.Theseallocated
of eight)allocatedfnodesare established
fnodesrepresent
.
the fnode file
.
the volumelabelfile - R?VOLUMEIABEL
.
the volumefree spacemap file - R?SPACEMAP
o
the free fnodesmap file - R?FNODEMAP
o
the bad blocksfile - R?BADBLOCKMAP
.
the root directory
.
file,
the spaceaccounting
.
Optionally,the duplicatevolumelabellile - R?SAVE
For a full descriptionof thesefiles,seeAppendixA "Structureof A NamedVolume."
to the root, the
Thereafter,whenfilesor directoriesare creiìteddirectlysubordinate
operatingsystemmustadjusta pointerin the root fnodeto indicatethe fnodenumberof
clirectories
subordinate
to the root must
the new datafile or directoryfile. Subserluently,
alsohavetheir pointersadjustedwhentheybecomeparentsto a new datafile or
directory.
This methodof storingand retrievingdataon a disk hasone majordrawback.All access
to fileson the disk is throughthe iRMX II volumelabeland the fnodefile. If eitherthe
volumelabelfile or the fnodefile is damagedor destroyed,
there is no practicalway to
recoverdataon the disk.
The backupand restorefnodesfeatureenablessomerecoveryof datalost asa resultof
damageto the fnodefile or the iRMX II volumelabel. With this feature,you createa
backupversionof the volumelabeland all the fnodeson the disk. The backupversionis
storedin one of the innermosttracksof the diskwherethe chanceof accidentallossof
data is minimal. (In normaluse,the disk headsdo not extendto the innermosttracks.)
To implementthis feature,the Human InterfaceFORMAT commandhasbeenmodified
to includean optionalparameter-- RESERVE. This versionof the FORMAT command
createsa file namedR?SAVEin the innermosttrackof the volume. A copyof the iRMX
II volumelabelis placedin the front (that is,the physicalend) of the file and an fnodeis
allocatedfor R?SAVEin the fnodefile. (The fnodefor the R?SAVEfile is allocatedout
of the fnodesreservedthroughthe FILES parameterof the FORMATcommand. Thus,
ifyou specify"FILES = 3000"whenyou format,only 2999of thosefnodeswill remain
availableafter the R?SAVEfnodehasbeenallocated.)Finally,FORMAT copiesthe
fnodefile into R?SAVE.
a-)
Disk Verifîcation
BACKINC UP AND RESTORINGFNODES
Noticethat the FORMAT commandcreatesa backupof the fnodefile in its initialized
state. R?SAVEis not subsequently
updatedasfilesarewritten to or deletedfrom the
volume. Therefore,you will haveto usethe BACKUPFNODES Disk Verification Utility
commandor the BACKUP optionof the HumanInterfaceSHUTDOWN commandto
backup the fnodefile at regularintervals.If the volumelabelor the fnodefile become
you canattemptto recoverliles on the volumeby usingthe Disk Verification
damaged,
Utility commands(RESTOREFNODEand RESTOREVOLUMETABEL)to rebuildthe
index. To assistin this process,
the DISPI-AYSAVEFNODEDisk VerificationUtility
commandenablesyou to look at individualfnodesstoredin the R?SAVEfile.
Sincethe contentsof the iRMX II volumelabeldo not change,the copyof the volume
labelin R?SAVEis alwaysvalid. Therefore,you canrestorethe volumelabelat anytime
regardless
of whenthe R?SAVEfile waslastupdated.(Whenthe Disk Verification
a damagedvolumelabel,it automatically
usesthe backupvolumelabel
Utility encounters
if the R?SAVEfile is present,however,it doesnot restoreunlessexplicitlyinstructed.)
CAUTION
One noteof caution: The fnodefìle is changedeachtime a volumeis
modified (that is, eachtime a fìle or directory is created,written to, or
deletedfrom the volumel. Therefore.valid restorationcan be assured
only for fnodeswhoseassociatedfiles or directorieshavenot been
changedsincethe last backup.
If the fnodesare not backedup after eachmodificafion,the structureof
the R?SAVEfile will differ from that of the fnode file. Somefnodesin
R?SAVEmay not be assoriatedwith the samefiles as the corresponding
fnodesin the fnodefile. Attemptingto recoverfnodesunderthese
because
the RESTOREFNODE
commandwill
conditionsis dangerous
ovenvritewhat may be a valid fnode in the fnodefile.
While the backupand restorefnodesleatureis a usefulaid in attemptingto recoverdata
your system,
on a volume,this capabilityis limitedin scope.If you are troubleshooting
you maywant to backup the fnodeson the systemdisk beforetakinganyactionthat may
risk the disk'sintegrity.You may alsodecideto backup the fnodeson a routinebasis
(beforeor duringeachsystemshutdown,for instance)so that the R?SAVEfile is always
and
wherea volumeis accessed
relativelycurrcnt. However,undernormalcircumstances,
practical.
The
modifiedfrequently,backingup the fnodesaftereachmodificationis not
mostpracticalsolutionis to backup the fnodefile oncea dayusingthe BACKUP option
of the SHUTDOWN command.
Disk Verification
J-J
B A C K I N G L I P A N I ) R E S T O R I N GF N O I ) E S
protectionfrom the loss
Note that this featureis not intencled
to proviclecomprehensive
with damagediRMX Il volumelabelsor fnodefiles. Rather,it offersa
of dataassociated
tool that,whenproperlyapplied,canbe usefulin maintainingvolumeintegrityin certain
protectionagainstlossof datausethe HumanInterface
situations.For comprehensive
BACKUPcommand.
ANDRESTORE
3.2 USINGFNODEBACKUP
T o u s e t h e f n o d e b a c k u pa n d r e s t o r ef e a t u r e ,y o u m u s t u s e V e r s i o n L l ( o r l a t e r ) o f t h e
I I u m a n I n t e r f a c eF O R M A T c o m n u r n da n r lt h e V e r s i o n2 . 0 ( o r l a t e r ) o f t h e D i s k
V e r i f i c a t i o nU t i l i t y . U s e d t o g e t h er , t h e s ev e r s i o n so f t h e F O R M A T c o m m a n da n d t h e
D i s k V e r i f i c a t i o nU t i l i t y e n a b l ey o u t o
.
f o r m a t a v o l u m et o c r e : ì t et h e b a c k u pf i l e ( R ? S A V E )
.
b a c k u p t h e f n o r i e so f a n y f i ì c sw r i t t e n t o t h e v o l u m e
.
e x a m i n et h e c o n t r ì n t so f t h c h l c k u p f i ì e ( R ' I S A V E , )
.
restore damagedfnodcs
.
r e s t o r et h e v o l u n i el a b e l
.
edit fnodes or savefnodcs
'l
his section describeshou, to perlìrrm each of thcse operations. A brief overview of the
o p e n r t i o ni s f o l l o w e db y o n c o r n r o r ee x a m p l e so f a t y p i c a li m p l e m e n t a t i o n .l n t h e
e x u m p l e sb, l u e o r h o l d e dt e x t i n d i c a t e sa n e n t r yy o u m a k e f r o m y o u r t e r m i n a l . S t a n d a r d
t y p e ( t h i s i s s t a n d a r dt y p e ) i n d i c a t e ss y s t e mo u r p u rr o y o u r r e r m i n a l .
3.2.1 Creatingthe R?SAVEFnodeBackupFile
Ilyou intendto buckupthevolumelrrbelantlthe liodeson a volumc',
you mustfirstcreate
the RISAVE backupfile on the innermost
tracksof thevolume.To do so,you must
invokeVersion2.0oî the HumanInterface
FORMAT command,
specifying
the
RESERVEoption.NOTE THAT THE FORMAT COMMAND OVERWRITESALL
OF THE DATA CURRE,NTLYON THE DISK. Thereftrre,makea backupcopyof any
îilesyouwishto saveusingthe HumanlnterfaceBACKUPcommand.
Oncethe volumehasbeenformtttecì,the R?SAVEfile will contaìna copyof the fnode
file inclutlingthe allocatedliodes (R?SPACE,MAP,
R?FNODEMAP,erc.). Therefore,
you neednot backup the lìode file immediatelyafter formattingthe volume.
PROCEI)URE
Fromthe Iluman Interface,
invokethe FORMAT command,
specifying
the RESERVE
Darameter.
3-,1
Disk Verification
BACKING UP AND RESTORINGFNODES
EXAMPLE
Assumethat you havebootedyour systemfrom a flexibledisketteto format the system
disk. The commandlisted below formats the disk and createsthe R?SAVE backuofile.
The initialized fnode fiìe is cooied into R?SAVE.
-attachdevlce
carbo as :nydlsk: