ZiLOG Z80-RIO User manual

t_ .'
~
Zilog
Operating System User's Mannal

03-0072-01
Revision A
September 1978
Copyright © 1978 by Zilog, Inc. All rights reserved. No
part of this publication may be reproduced, stored in a
retrieval system, or transmitted,
in any form or by any
means, electronic, mechanical, photocopying, recording, or
otherwise, without the prior written permission
of Zilog.
Zilog assumes no responsibility for the use
of any circuitry
other than circuitry embodied in a Zilog product.
No other
circuit patent licenses are implied.

zaO-RIO
Operating System User's Manual
September 1978

TABLE OF CONTENTS
CHAPTER 1 - INTRODUCTION AND OVERVIEW •
1.1 INTRODUCTION ••
1.2 SYSTEM OVERVIEW
1
1
1.2.1
1.2.2
1.2.3
Hardware Configuration • • • • • •
File Systems • • • • • • • . . • •
System Initialization •••.•••
3
3
3
6
7
1.2.4
1.2.5
Commands • • .• .•..•••
I/O • • • . • • • • • . • • • • • . 7
CHAPTER 2 - RIO EXECUTIVE
2.1 SYSTEM INITIALIZATION
2.2
2.3
2.4
2.5
2.6
FILE NAME CONVENTIONS
MEMORY MANAGEMENT
2.3.1
MEMMGR
COMMAND STRING INTERPRETATION
ERROR HANDLING
PROGRAM EXECUTION OF COMMANDS
CHAPTER 3 - 1/0 STRUCTURE •
3.1
OVERVIEW . •
3.2
I/O REQUESTS - SYSTEM CALLS
3.3
THE 'ASSIGN' I/O REQUEST •••
- i -
9
9
· 10
. • • . 12
• . 13
· 13
• • . 15
· 15
· 16
· 16
· 17
• 19

3.4
STANDARD RIO I/O DEVICES
3.4.1
3.4.2
3.4.3
3.4.4
3.4.5
3.4.6
3.4.7
ZDOS . • • •
DFS
NULL . • • •
CON . • • • .
PCON
FLOPPY • • •
DISK • • • •
CHAPTER 4 - PROGRAM INTERFACE
4.1 PROGRAM LOCATION
4.2
PARAMETER STRING ADDRESS
4.3
PROGRAM STACK SPACE
• • •
21
. . . . . . . . . 21
. . . . . 21
. . . . . . . 21
• • • • • 22
• 27
• • • • • • • 27
• • 27
• • 28
• • • • • 28
· 29
• • • 29
4.4 PROGRAM TERMINATION - ERROR HANDLING ••. 29
4.5 SYSTEM CALLS -SYSTEM ENTRY POINT •. 30
4.6
4.7
4.8
INTERRUPT STATUS • •
I/O UNIT UTILIZATION • •
PROGRAM EXAMPLES
CHAPTER 5 - RIO COMMANDS
5.1
5.2
5.3
5.4
5.5
5.6
5.7
5.8
ACTIVATE
ALLOCATE
BRIEF .
CAT •
CLOSE •
COMPARE
COpy
COPY.DISK •
- i i -
. ... . .
• • 31
. • • • 31
.. • 32
• • 33
· • 35
· • 37
• • 39
• • 40
• 44
• • 45
• • 47
• • • 49

5.9 COPYSD 51
5.10
DATE
53
5.11
DEACTIVATE
54
5.12 DEALLOCATE
55
5.13
DEBUG
56
5.14
DEFINE
60
5.15
DELETE
63
5.16 DISK. FORMAT
67
5.17 DISK. REPAIR
70
5.18
DISK. STATUS
72
5.19 DISPLAY 74
5.20
DO
75
5.21
DUMP
79
5.22
ECHO
80
5.23
ERROR
81
5.24
ERRORS
82
5.25
EXTRACT
83
5.26
FORCE
84
5.27
FORMAT 85
5.28
HELP
88
5.29
IMAGE
89
5.30
INITIALIZE
90
5.31
LADT
91
- iii

5.32
5.33
MASTER
r·10VE
5.34 PAUSE.
5.35
5.36
5.37
5.38
5.39
5.40
5.41
5.42
5.43
RELEASE .
RENAME
RESTORE TABS
SAVE TABS .
SET • • •
STATUS
VERBOSE
XEQ • .
EXPRESSION EVALUATION .
CHAPTER 6 -
ZDOS •• • .
6.0 ZDOS OPERATION
INITIALIZE
ASSIGN .•• •
OPEN
• 92
• 93
• . • 98
• • • 99
100
102
103
104
109
III
112
113
6.1
6.2
6.3
6.4
6.5
6.6
6.7
6.8
6.9
CLOSE •
REWIND
. . . . . . . . . . . . . .
114
114
122
123
125
132
134
135
137
139
140
READ BINARY • •
WRITE BINARY
WRITE
CURRENT •
DELETE •• • .
- iv -

6.10
DELETE REMAINING
RECORDS
· · · · ·
142
6.11
ERASE
. . · · · · · · · · · · ·
143
6.12
READ AND DELETE
· · · · · ·
145
6.13 READ
CURRENT
· · · · · · · · ·
147
6.14 READ
PREVIOUS · · · · · · ·
149
6.15 READ DIRECT · · · · · · · · · · · ·
151
6.16 SKIP
FORWARD
· · · · · · · · · · · · ·
153
6.17 SKIP
BACKWARD
· · · · · · · · ·
155
6.18
SKIP TO END
· · · · · · · · · · · ·
157
6.19 RENAME
· · · · · · · ·
158
6.20 UPDATE
. · · · · · · · · · · ·
160
6.21
SET ATTRIBUTES · · · ·
162
6.22 QUERY ATTRIBUTES · · · · · · · · ·
164
CHAPTER
7 -
DFS
· · · · · · · · · · · · ·
166
7.1 ZILOG DISK CONTROLLER
· · · · · · · · ·
166
7.2 DFS
OPERATION · · · · · · · · · · ·
168
7.3 SOFTWARE ORGANIZATION · · · · · · ·
171
7.4 DFS ALLOCATION
· · · · · · · · · · ·
172
7.4.1 Sector
0 Format
· · · · ·
172
7.4.2 DFS
Allocation
Algorithm
173
7.5
THE BARE DISK CONTROLLER • • • • ·
,174
7.6 CONTROLLER BOOTSTRAP OPERATION. • . 177
7.7 SYSTEM BOOTSTRAPPING on the MCZ-1/35 179
- v -

APPENDICES
APPENDIX A -
RIO/ZDOS/DFS Error Codes
APPENDIX B - RIO Command Syntax Summary
APPENDIX C - RIO System Constants
APPENDIX D - Converting Files to RIO Format
APPENDIX E - Altering Default RIO
APPENDIX F - I/O Request Vector Format and
I/O Request Codes
APPENDIX G - Program Examples
APPENDIX H - Internal Command Table Contents
APPENDIX I - RIO Memory Manager
APPENDIX J - Descriptor Record of Procedure Type File
APPENDIX K - ZDOS/DFS Command Summary
- vi -

PREFACE
This manual provides an introduction and user's manual
for the RIO operating system used with Zilog's Micro
(ZDS). Detailed description is provided for system
features, including the bootstrap process, the RIO
Executive, default console drivers, I/O structure,
program interface, and the Zilog Floppy Disk File System,
ZDOS, and the Zilog Hard Disk File System, DFS.
Other pertinent documentation with which the reader may
want to become familiar includes:
zaO-MCZ PROM User's Manual
zaO-ZDS PROM User's Manual
zaO-RIO Relocating Assembler and Linker User's Manual
zaO-RIO Text Editor User's Manual
This manual makes use of the following conventions of
notation:
Optional portions of a modifier are enclosed
in brackets, [].
The symbol for logical or, 'I " is used if either
option can be issued. STATUS [0 I 1 ••• 7] means
the command can be issued as STATUS 0, STATUS 1, .••
STATUS 7, or simply as STATUS.
Parameters which can be repeated zero or more times
are enclosed in parentheses and followed by an
asterisk - e.g., (filename)*.
Parameters which can be repeated as necessary
but must appear at least once are enclosed in
parentheses and followed by a plus sign - e.g.,
(filename)+.
- vii -

All memory addresses and constants referring to
memory allocation are given in hexadecimal. Unless
so specified, other constants are given in
decimal. Hexadecimal constants are also indicated
by an 'H' immediately following the hex digits,
e.g., 4FH.
- viii -

CHAPTER 1
INTRODUCTION AND OVERVIEW
1.1 INTRODUCTION
The zao Operating System with Relocatable Modules and I/O
Management, or RIO, is a general-purpose computing system
designed to facilitate the development and integration of
user's programs into a production environment. RIO is
available on various Zilog hardware configurations
including the zao Micro Computer System (MCZ-l) series and the
zao Development System (ZDS). The zao Development System
provides extensive hardware debugging aids to assist the
engineer/programmer in ZaO-based hardware/software system
design. The user has a choic~ between a modest environment
with a minimum of system support or an enhanced environment
which provides access to an assortment of system support
utilities including the Zilog Floppy Disk File System,
ZDOS, and the Zilog Hard Disk File System, DFS.
In the modest environment, the user has access to 3K
(lK=1024) bytes of dedicated read-only memory which
contains a program debugger with file manipulation
capability, a floppy disk driver which supports up to eight
disk drives, and a basic console driver with provision for
paper tape operation.
In the enhanced environment, the user also has access to
the RIO Executive, ZDOS, DFS, and a collection of disk-resident
software including a text editor, macro assembler, and
linker. The RIO Executive provides standardized I/O
management permitting device independent program
development and utilization of alternate or multiple file
systems. ZDOS provides a versatile floppy disk based file
system with variable record length files; up to 16
concurrently active files; management of user-defined
scratch files which are automatically deallocated after
use; and support of up to eight disk drives for over 2.5
megabytes of on-line storage. The hard disk file system,
- 1 -

DFS, supplies similar features on 10 megabyte high speed
disks. The text editor, macro assembler and linker give
the user full support in program development, minimizing
assembly time with relocatable modules while allowing com-
plex memory overlay structures. In addition, a console
driver is provided which allows user definition of character
delete and line delete symbols, automatic insertion of any
number of line feeds, and automatic echo mode to accommodate a
wide r~nge of console devices.
- 2 -

1.2 SYSTEM OVERVIEW
1.2.1 HARDWARE CONFIGURATION
The RIO Operating System is designed to operate with the 4K
PROM in either the Zilog Micro Computer System (MCZ) or
Development System (ZDS). A minimum configuration of 32K
(lK=1024) of random access memory, one disk drive, and a
console device is required.
The MCZ 1/20 Zilog Micro Computer System is equipped with
two floppy disk drives. The left drive is designated drive
'2' and the right drive is designated drive '0'. The Zilog
Development System (ZDS) also has two drives, but the
designations are 'I' and '0' for left and right, respectively.
The MCZ 1/35 uses hard disk cartridge and fixed platter drives.
The usual configuration consists of one fixed platter and one
c?rtridge drive, designated '0' and 'I', respectively. The
system will support up to 8 drives.
1.2.2 FILE SYSTEMS
For systems using floppy disks, ZDOS controls the organization
and allocation of the sectors on a diskette. While the basic unit
of disk allocation is the sector, the fundamental structure within
ZDOS is the 'file'. A file consists of zero or more sectors
of data which contain logically-related information. Each
file has a set of attributes including a name of from one
to thirty-two characters, a set of (possibly null)
properties, a type, a subtype, and a record length. The
smallest amount of information that can be read from or
written to the disk is the contents of one sector, but more
efficient operation can often be achieved by grouping from
one to thirty-two contiguous sectors (a complete track)
into one unit which is then read or written together. This
unit is called a 'record' and the number of bytes of data
in the record is the record length. A record may consist
of 1, 2, 4, 8, 16 or 32 sectors; therefore the record
length may be 128, 256, 512, 1024, 2048, or 4096 bytes.
On systems with hard disks, the Disk File System (DFS)
provides a similar file structure. The bulk of the DFS
- 3 -

software runs in the memory of an intelligent disk con-
,troller; only a small interface routine resides in the
main system memory, thus resulting in a large memory
space saving. DFS files have the same structure as ZDOS
files, except that multiple-sector records are not sup-
ported. The sector (and record) size is 512 bytes.
The properties of a file are defined by the user and may
include any combination of the following:
1) write protected -may not have contents altered;
2) erase protected -may not have contents deleted;
3) locked attributes -may not have its attributes
changed (a file's attributes include its
properties, type, subtype, and other information
included in the file's 'descriptor record'; see
below) ;
4)
random - file is in a format for random
access;
~) secret - file is not normally found in directory
searches (see below).
When a file is created, the user specifies its type,
which must be exactly one of the following:
1) directory - a file directory (see below);
2) procedure - file contains information which
can be loaded into memory and executed
directly;
3) ASCII - file consists of symbols encoded in
the American Standard Code for Information
Interchange format, such as those produced
by the editor or console input device;
4) binary - data of an unspecified format.
In addition to the file type, the user may define a
subtype, which is a value ranging from 0 (default)
to 15. The subtype is useful to differentiate between
files of a certain type. For instance, RIO requires
all I/O device files to be of type procedure, subtype 1.
- 4 -

The file system maintains a special file on each disk which is
named 'DIRECTORY'. In this file are the names of all files
(including itself) on the disk and the location of the
first record of each file. The first record of each file
is one sector long (regardless of the record length of the file)
and is called the 'descriptor record'. All the file attributes
including entry point (where execution may begin), date of
creation, date of last modification, first data record
address, last data record address, record length, and
record count are contained in this record. Each record of
the file contains pointers (disk addresses) to the previous
record and the subsequent record in the file. Note that
records which are logically in order according to file
contents may, in fact, reside in an arbitrary order on the
di~k. This 'linked' structure allows maximum utilization
of the disk. The disk allocation algorithm in ZDOS
~ttempts to localize the disk sectors used for a single
file. Note that the sectors which comprise a single file
record are physically contiguous on the disk and are
therefore always read or written as a single disk access.
ZDOS maintains a bit map to keep track of allocated vs.
unallocated disk sectors. This map resides on three
sectors of the diskette which are preallocated by the diskette
formatting utility and is read into memory by the Initialize
command or automatically by ZDOS when the diskettes are
exchanged. The map is written from memory to the diskette
when a file is closed following an allocation change.
If the diskette is formatted as a 'system' disk, additional
space is preallocated for the system bootstrap routine and
the GET/SAVE command package (see the Debug command,
section 5.13).
Under DFS, the unallocated hard disk sectors are linked
in a free chain. The allocation and deallocation of
sectors is a matter of removing sectors from or adding
sectors to the free chain. System disks contain the
'BOO~STRAP' file contains the file system that is loaded
at eystem initialization.
While files created by the RIO Operating System or PROM
debugger on the Development System or Micro Computer System
are compatible, the bootstrap is not. Thus files may be
interchcnged between systems (procedure files are generally
not transferable) but a system disk will bootstrap
correctly only on the system for which it was designed.
- 5 -

1.2.3 SYSTEM INITIALIZATION
Where ZDOS is the primary file system, the bootstrapping
of the operating system is from floppy disks. When a
carriage return is entered as the first character after
pressing RESET, or when the OS command is entered while
in the Debug environment, the PROM monitor reads a 128 byte
minibootstrap from track 17, sector 3 of the disk in drive
O. This program initiates a directory search on drive 0 for
the files OS and ZDOS, which are then read into memory.
Execution is started at the entry point of as. This is
one of two instances where a disk formatted as a system
disk must be ready in drive O. The other is when using the
GET or SAVE commands of the PROM Debugger. In all other
cases, while a particular drive search order may be implied,
there is no difference in the utilization of drives.
This process is similar on systems which use DFS as the
primary file system. The file 'BOOTSTRAP' contains the
file system, which the disk controller loads directly
from disk, using the standard disk search sequence of
drive 1, drive 2, ... , drive O. The PROM monitor then may
communicate directly with the controller to load the file
'OS', again using the standard drive search sequence.
When execution of the file as begins, an initialization
procedure is performed that mayor may not involve other
files. A means is provided to read a set of commands from
a file to extend this initialization process. In this way,
a turnkey system can be implemented simply by editing the
external initialization command file. Alternatively, the
file as can be edited directly to execute a user-defined
command sequence at initialization time (see Appendix E). As
part of the initialization process, memory is sized to determine
the current configuration. If the sizing procedur~ determines
the end of memory to be at other than a 4K boundary, a
warning message is issued to indicate possible memory
failure, thus providing a frequent diagnostic of system
memory.
After initialization, OS responds with the message 'RIO REL v.cc
(Where 'v' is the release version and ICC' is the release cycle)
followed by the system prompt character '%'. Any time RIO
is ready to accept command input, this prompt character is
printed.
- 6 -

1.2.4 COMMANDS
Command implementation is in one of two forms: for
'internal' commands, the code which actually implements the
command is a part of the file as and resides in memory
when as
is loaded; 'external' commands are simply procedure-
type files which are loaded into memory for execution. If
a command is external, a search is made of all accessible
directories for a file of the given name. In this context,
the available command set is limited only by the particular
files of procedure type which are on the 'ready' drives at
a given moment. Therefore, user extension, modification,
or replacement of the Zilog supplied software is a matter
of file manipulation. For example, replacement of the file
named as on a system diskette with another file of the
same name results in the automatic bootstrap of a
user-defined software package. The majority of the
standard RIO command set are implemented as external files.
(Internal commands are noted as such in the command
description, Chapter 5).
1.2.5 I/O
The I/O structure of RIO is designed to facilitate program
development independent of physical device characteristics.
To this end all I/O requests are made with reference to a
'logical unit' which may correspond to any of a given set
of 'I/O devices'. In this way device modifications can
occur with minimal impact on existing software.
The software required to control a particular hardware
device or set of devices is termed the 'device handler'
(used interchangeably with 'I/O device', 'I/O driver',
'device driver', or simply 'device'). Before a particular
device can be accessed, its device handler must be loaded
in memory. Initialization procedures may be required, and
it may be desirable for the memory it utilizes to be
protected from concurrent software routines. RIO provides
command level control of these tasks and assumes that once
this is done, the device is ready to handle I/O requests.
This process is referred to as "activating" a device.
The fundamental concept underlying the RIO I/O structure is
that of the 'logical unit' (also referred to as 'unit' or
- 7 -

'I/O unit') which enables I/O activity independent of a
particular device. Units are 'defined' by linking or
mapping a unit to a given device. I/O requests may not be
made on undefined units, although some requests inherently
result in unit definition.
Three units are predefined by RIO to handle console input
(unit 1), console output (unit 2) and high volume printed
output (unit 3). Unit 0 is used by system functions and is
not available to the user. Units 4-20 (in the standard
system) are available for user programming. Units 1, 2,
and 3 have the mnemonics CONIN, CONOUT and SYSLST,
respectively which can be used interchangeably with the
literal unit designations, where applicable.
I/O requests are made with a standard vector format,
containing information such as unit, data transfer address,
data length, completion codes, and an optional supplemental
parameter vector address. I/O requests are made by
providing a pointer to the request vector (see below) and
making a system call.
Note that programs which use the RIO I/O structure can
remain unchanged so long as compatible I/O devices
are provided. For instance, a BASIC system could
immediately utilize a line printer by redefining SYSLST.
No other software changes would be required.
- 8 -