Files
Sepp J Morris 31738079c4 Upload
Digital Research
2020-11-06 18:50:37 +01:00

683 lines
22 KiB
TeX

.Ig
4/20/82
.op
.sp 15
.ce 100
.SH
CP/M-8000
.sp
.sh
Operating System
.sh
.sp
Programmer's Guide
.cs 5
.sp 10
Copyright \ \ January 1983
.sp
Digital Research
P.O. Box 579
160 Central Avenue
Pacific Grove, CA 93950
(408) 649-3896
TWX 910 360 5001
.sp 4
All Rights Reserved
.ce 0
.bp
.po 17
.ll 50
.ce
COPYRIGHT
.sp
Copyright \ \ 1983 by Digital Research. All rights reserved.
No part of this publication may be reproduced, transmitted,
transcribed, stored in a retrieval system, or translated
into any language or computer language, in any form or
by any means, electronic, mechanical, magnetic, optical,
chemical, manual or otherwise, without the prior written
permission of Digital Research, Post Office Box 579, Pacific
Grove, California, 93950.
.sp
This documentation is, however, tutorial in nature. Thus, the reader is
granted permission to include the example programs, either in whole
or in part, in his own programs.
.sp 3
.ce
DISCLAIMER
.sp
Digital Research makes no representations or warranties with
respect to the contents hereof and specifically disclaims
any implied warranties of merchantability or fitness for
any particular purpose. Further, Digital Research reserves the
right to revise this publication and to make changes from
time to time in the content hereof without obligation of
Digital Research to notify any person of such revision or
changes.
.sp 3
.ce
TRADEMARKS
.sp
CP/M and CP/M-86 are registered trademarks of Digital Research.
AS68, CP/M-8000, CP/M-80, CP/M-86, DDT-8000, LD8K, MP/M-80, and MP/M-86 are
trademarks of Digital Research. Zilog is a registered trademark of
Zilog Inc. Unix is a registered trademark of Bell Laboratories.
.sp 3
The\c
.ul
CP/M-8000 Operating System Programmer's Guide
.qu
\was prepared using the Digital Research TEX Text Formatter and printed
in the United States of America.
.sp 2
.ce 3
******************************
* First Edition: May 1983 *
******************************
.bp
.cs 5
.mt 5
.op
.mb 6
.pl 66
.ll 65
.po 10
.pp 5
.hm 2
.fm 2
.ft iii
.ce
.sh
FOREWORD
.sp
.pp
CP/M-8000 is a single-user operating system designed for the
ZILOG \ \ Z8000 or a compatible Z8000 microprocessor. CP/M-8000
requires a minimum of 128K bytes of random access memory (RAM) to
run its base-level system, which contains the CP/M \ \ commands and
the utilities listed below.
.sp
.nf
o CP/M Built-in Commands:
.sp
DIR
.br
DIRS
.br
ERA
.br
REN
.br
SUBMIT
.br
TYPE
.br
USER
.sp
o Standard CP/M Utilities:
.sp
DDT-8000
.br
ED
.br
PIP
.br
STAT
.sp
o Programming Utilities:
.sp
Archive (AR8K)
.br
DUMP
.br
XDUMP
.sp
o Programming Tools
.sp
Assembler (AS8K \ \ )
.br
Linker (LD8K \ \ )
.br
C Compiler*
.br
C Preprocessor*
.sp
* Described in the \c
.ul
C Programming Guide for CP/M-8000.
.qu
.fi
.sp
CP/M-8000 requires a minimum of 128K bytes of RAM
to run the programming tools distributed with CP/M-8000.
.pp
The CP/M-8000 file system is based on and is upwardly compatible
with the CP/M-80 \ \ Version 2.2 and CP/M-86 \ \ Version 1.1 file
systems. However, CP/M-8000 supports a much larger file size
with a maximum of 32 megabytes per file.
.bp
.fm 2
.ft iv
.sp
.pp
CP/M-8000 supports a maximum of 16 disk
drives, with 512 megabytes per drive. CP/M-8000 supports other
peripheral devices that the Basic I/O System
(BIOS) assigns to one of the four logical devices: LIST, CONSOLE,
AUXILIARY INPUT, or AUXILIARY OUTPUT.
.pp
This guide describes the programming interface to CP/M-8000. The first few
sections in this guide discuss the CP/M-8000 architecture, memory models,
executable programs, and file system access functions. Latter sections of
this guide describe programming tools and utilities distributed with your
CP/M-8000 system.
.pp
This guide assumes you are an experienced programmer familiar
with the basic programming concepts of assembly language.
If you are not familiar with the Zilog Z8000 assembly language,
refer to Zilog manuals listed below.
.sp
.in 5
.ti -2
o \c
.ul
======= fill in: Z8000 assembly-language manual =========
.in 0
.pp
Before you can use the facilities in this guide, your CP/M-8000
system must be configured for your hardware environment.
Normally, your system is configured for you by the manufacturer
of your computer or the software distributor. However, if you
have an unusual hardware environment, this may not be the case.
Refer to the \c
.ul
CP/M-8000 Operating System System Guide \c
.qu
for details on how to configure your system for a custom hardware
environment.
.sp 2
.sh
New Functions and Implementation Changes
.qs
.pp
CP/M-8000 has six new Basic Disk Operating System (BDOS) functions
and additional implementation changes in the BDOS functions and
data structures that differ from other CP/M systems.
The new BDOS functions and implementation changes are listed
in Appendix F.
.pp
Table F-4 in Appendix F contains functions and commands supported by other CP/M
systems, but that are not supported by CP/M-8000.
.bp
.ft v
.ce
.sh
Table of Contents
.qs
.sp 3
.nf
.sh
1 Introduction to CP/M-8000
.qs
.sp
1.1 CP/M-8000 System Architecture . . . . . . . . . . . . 1
.sp
1.2 Transient Programs . . . . . . . . . . . . . . . . . 2
.sp
1.3 File System Access . . . . . . . . . . . . . . . . . 2
.sp
1.4 Programming Tools and Commands . . . . . . . . . . . 2
.sp
1.5 CP/M-8000 File Specification . . . . . . . . . . . . . 5
.sp
1.6 Wildcards . . . . . . . . . . . . . . . . . . . . . . 6
.sp
1.7 CP/M-8000 Terminology . . . . . . . . . . . . . . . . 7
.sp 2
.sh
2 The CCP and Transient Programs
.sp
2.1 CCP Built-In and Transient Commands . . . . . . . . . 9
.sp
2.2 Loading A Program In Memory . . . . . . . . . . . . . 10
.sp
2.2.1 Base Page Initialization By The CCP . . . . . 10
2.2.2 Loading Multiple Programs . . . . . . . . . . 10
2.2.3 Base Page Initialization . . . . . . . . . . . 11
.sp
2.3 Exiting Transient Programs . . . . . . . . . . . . . 11
.sp
2.4 Transient Program Execution Model . . . . . . . . . . 12
.sp 2
.sh
3 Command File Format
.qs
========= THIS SECTION NEEDS REVISION FOR X.OUT ==========
.sp
3.1 The Header and Program Segments . . . . . . . . . . . 15
.sp
3.2 The Symbol Table . . . . . . . . . . . . . . . . . . 17
.sp
3.2.1 Printing The Symbol Table . . . . . . . . . . 19
.sp
3.3 Relocation Information . . . . . . . . . . . . . . . 19
.sp
3.3.1 The Format of A Relocation Word . . . . . . . 20
.sp 2
.sh
4 Basic Disk Operating System Functions
.qs
.sp
4.1 BDOS Functions and Parameters . . . . . . . . . . . . 24
.sp
4.1.1 Invoking BDOS Functions . . . . . . . . . . . . 24
4.1.2 Organization Of BDOS Functions . . . . . . . . 25
.bp
.ft vi
.ce 2
.sh
Table of Contents
.sp
.sh
(continued)
.qs
.sp 3
4.2 File Access Functions . . . . . . . . . . . . . . . . 25
.sp
4.2.1 A File Control Block (FCB) . . . . . . . . . . 26
4.2.2 File Processing Errors . . . . . . . . . . . . 28
4.2.3 Open File Function . . . . . . . . . . . . . . 31
4.2.4 Close File Function . . . . . . . . . . . . . 32
4.2.5 Search For First Function . . . . . . . . . . 33
4.2.6 Search For Next Function . . . . . . . . . . . 34
4.2.7 Delete File Function . . . . . . . . . . . . . 35
4.2.8 Read Sequential Function . . . . . . . . . . . 36
4.2.9 Write Sequential Function . . . . . . . . . . 37
4.2.10 Make File Function . . . . . . . . . . . . . . 39
4.2.11 Rename File Function . . . . . . . . . . . . . 40
4.2.12 Set Direct Memory Access (DMA) Address . . . . 41
4.2.13 Set File Attributes Function . . . . . . . . . 42
4.2.14 Read Random Function . . . . . . . . . . . . . 44
4.2.15 Write Random Function . . . . . . . . . . . . 46
4.2.16 Compute File Size Function . . . . . . . . . . 48
4.2.17 Set Random Record Function . . . . . . . . . . 49
4.2.18 Write Random With Zero Fill Function . . . . . 51
.sp
4.3 Drive Functions . . . . . . . . . . . . . . . . . . . 52
.sp
4.3.1 Reset Disk System Function . . . . . . . . . . 53
4.3.2 Select Disk Function . . . . . . . . . . . . . 54
4.3.3 Return Login Vector Function . . . . . . . . . 55
4.3.4 Return Current Disk Function . . . . . . . . . 56
4.3.5 Write Protect Disk Function . . . . . . . . . 57
4.3.6 Get Read-Only Vector Function . . . . . . . . 58
4.3.7 Get Disk Parameters Function . . . . . . . . . 59
4.3.8 Reset Drive Function . . . . . . . . . . . . . 61
4.3.9 Get Disk Free Space Function . . . . . . . . . 62
.sp
4.4 Character I/O Functions . . . . . . . . . . . . . . . 62
.sp
4.4.1 Console I/O Functions . . . . . . . . . . . . 64
Console Input Function . . . . . . . . . . . . 64
Console Output Function . . . . . . . . . . . 65
Direct Console I/O Function . . . . . . . . . 66
Print String Function . . . . . . . . . . . . 68
Read Console Buffer Function . . . . . . . . . 69
Get Console Status Function . . . . . . . . . 71
.sp
.mb 5
.fm 1
4.4.2 Additional Serial I/O Functions . . . . . . . 72
Auxiliary Input Function . . . . . . . . . . . 72
Auxiliary Output Function . . . . . . . . . . 73
List Output Function . . . . . . . . . . . . . 74
.bp
.ft vii
.mb 6
.fm 2
.ce 2
.sh
Table of Contents
.qs
.sp
.sh
(continued)
.qs
.sp 3
4.4.3 I/O Byte Functions . . . . . . . . . . . . . . 74
Get I/O Byte Function . . . . . . . . . . . . 76
Set I/O Byte Function . . . . . . . . . . . . 77
.sp
4.5 System/Program Control Functions . . . . . . . . . . 77
.sp
4.5.1 System Reset Function . . . . . . . . . . . . 78
4.5.2 Return Version Number Function . . . . . . . . 79
4.5.3 Set/Get User Code . . . . . . . . . . . . . . 81
4.5.4 Chain To Program Function . . . . . . . . . . 82
4.5.5 Flush Buffers Function . . . . . . . . . . . . 83
4.5.6 Direct BIOS Call Function . . . . . . . . . . 84
4.5.7 Program Load Function . . . . . . . . . . . . 85
.sp
4.6 Exception Functions . . . . . . . . . . . . . . . . . 87
.sp
4.6.1 Set Exception Vector Function . . . . . . . . 88
4.6.2 Set Supervisor State . . . . . . . . . . . . . 91
4.6.3 Get/Set TPA Limits . . . . . . . . . . . . . . 92
.sp 2
.sh
5 AS8K Assembler
.qs
============= BASE ON MCCLURE'S DOCUMENTATION ==============
.sp
5.1 Assembler Operation . . . . . . . . . . . . . . . . . 95
.sp
5.2 Initializing AS68 . . . . . . . . . . . . . . . . . . 95
.sp
5.3 Invoking the Assembler (AS68) . . . . . . . . . . . . 95
.sp
5.4 Assembly Language Directives . . . . . . . . . . . . 98
.sp
5.5 Sample Commands Invoking AS68 . . . . . . . . . . . . 104
.sp
5.6 Assembly Language Differences . . . . . . . . . . . . 104
.sp
5.7 Assembly Language Extensions . . . . . . . . . . . . 106
.sp
5.8 Error Messages . . . . . . . . . . . . . . . . . . . 107
.sp 2
.sh
6 LD8K Linker
.qs
============= BASE ON MCCLURE'S DOCUMENTATION ==============
.sp
6.1 Linker Operation . . . . . . . . . . . . . . . . . . 109
.sp
6.2 Invoking the Linker (L068) . . . . . . . . . . . . . 109
.sp
6.3 Sample Commands Invoking L068 . . . . . . . . . . . . 112
.sp
6.4 L068 Error Messages . . . . . . . . . . . . . . . . . 112
.bp
.ft viii
.ce 2
.sh
Table of Contents
.sp
.sh
(continued)
.qs
.sp 3
.sh
7 Programming Utilities
.qs
.sp
7.1 Archive Utility . . . . . . . . . . . . . . . . . . . 113
.sp
============= BASE ON MCCLURE'S DOCUMENTATION ==============
7.1.1 AR68 Syntax . . . . . . . . . . . . . . . . . 113
7.1.2 AR68 Operation . . . . . . . . . . . . . . . . 115
7.1.3 AR68 Commands and Options . . . . . . . . . . 115
7.1.4 Errors . . . . . . . . . . . . . . . . . . . . 120
.sp
7.2 DUMP Utility . . . . . . . . . . . . . . . . . . . . 120
.sp
7.2.1 Invoking DUMP . . . . . . . . . . . . . . . . 120
7.2.2 DUMP Output . . . . . . . . . . . . . . . . . 121
7.2.3 DUMP Examples . . . . . . . . . . . . . . . . 122
.sp
7.4 XDUMP Utility . . . . . . . . . . . . . . . . . . . 124
.sp
============== TO BE WRITTEN ==============================
7.4.1 Invoking XDUMP . . . . . . . . . . . . . . . 124
7.4.2 XDUMP Output . . . . . . . . . . . . . . . . 124
7.4.3 XDUMP Examples . . . . . . . . . . . . . . . 125
.sp
.sh
8 DDT-8000
.qs
.sp
8.1 DDT-8000 Operation . . . . . . . . . . . . . . . . . . 129
============== BASE ON THORN'S DOCUMENTATION ==============
.sp
8.1.1 Invoking DDT-8000 . . . . . . . . . . . . . . . 129
8.1.2 DDT-8000 Command Conventions . . . . . . . . . 129
8.1.3 Specifying Address . . . . . . . . . . . . . . 130
8.1.4 Terminating DDT-8000 . . . . . . . . . . . . . 130
8.1.5 DDT-8000 Operation with Interrupts . . . . . . 130
.bp
.ft ix
.ce 2
.sh
Table of Contents
.sp
.sh
(continued)
.qs
.sp 3
8.2 DDT-8000 Commands . . . . . . . . . . . . . . . . . . 131
.sp
8.2.1 The D (Display) Command . . . . . . . . . . . 131
8.2.2 The E (Load for Execution) Command . . . . . . 132
8.2.3 The F (Fill) Command . . . . . . . . . . . . . 132
8.2.4 The G (Go) Command . . . . . . . . . . . . . . 133
8.2.5 The H (Hexadecimal Math) Command . . . . . . . 133
8.2.6 The I (Input Command Tail) Command . . . . . . 133
8.2.7 The L (List) Command . . . . . . . . . . . . . 134
8.2.8 The M (Move) Command . . . . . . . . . . . . . 134
8.2.9 The R (Read) Command . . . . . . . . . . . . . 135
8.2.10 The S (Set) Command . . . . . . . . . . . . . 135
8.2.11 The T (Trace) Command . . . . . . . . . . . . 136
8.2.12 The U (Untrace) Command . . . . . . . . . . . 136
8.2.13 The V (Value) Command . . . . . . . . . . . . 137
8.2.14 The W (Write) Command . . . . . . . . . . . . 137
8.2.15 The X (Examine CPU State) Command . . . . . . 137
.sp
8.3 Assembly Language Syntax for A and L Commands . . . . 139
.bp
.ft x
.ce
.sh
Appendixes
.qs
.sp 3
.sh
A Summary of BIOS Functions \c
.qs
\ . . . . . . . . . . . . . . . . 141
.sp 2
.sh
B Transient Program Load Example\c
.qs
\ . . . . . . . . . . . . . . 143
.sp 2
.sh
C Base Page Format\c
.qs
\ . . . . . . . . . . . . . . . . . . . . . 151
.sp 2
.sh
D Instruction Set Summary \c
.qs
\ . . . . . . . . . . . . . . . . . 153
.sp 2
.sh
E Error Messages\c
.qs
\ . . . . . . . . . . . . . . . . . . . . . . 157
=============== DELETE OR REVISE ===========================
.sp
E.1 AR68 Error Messages . . . . . . . . . . . . . . . . . 157
.sp
E.1.1 Fatal Diagnostic Error Messages . . . . . . . 157
E.1.2 AR68 Internal Logic Error Messages . . . . . . 160
.sp
E.2 AS68 Error Messages . . . . . . . . . . . . . . . . . 161
.sp
E.2.1 AS68 Diagnostic Error Messages . . . . . . . . 161
E.2.2 User-recoverable Fatal Error Messages . . . . 167
E.2.3 AS68 Internal Logic Error Messages . . . . . . 171
.sp
E.3 BDOS Error Messages . . . . . . . . . . . . . . . . . 171
.sp
E.4 BIOS Error Messages . . . . . . . . . . . . . . . . . 175
.sp
E.5 CCP Error Messages . . . . . . . . . . . . . . . . . 176
.sp
E.5.1 Diagnostic Error Messages . . . . . . . . . . 176
E.5.2 CCP Internal Logic Error Messages . . . . . . 179
.sp
E.6 DDT-8000 Error Messages . . . . . . . . . . . . . . . 180
.sp
E.6.1 Diagnostic Error Messages . . . . . . . . . . 180
E.6.2 DDT-8000 Internal Logic Error Messages . . . . 186
.sp
E.7 DUMP Error Messages . . . . . . . . . . . . . . . . . 187
.sp
E.8 LD8K Error Messages . . . . . . . . . . . . . . . . . 187
.sp
E.8.1 Fatal Diagnostic Error Messages . . . . . . . 187
E.8.2 LO68 Internal Logic Error Messages . . . . . . 191
.sp
E.9 XDUMP Error Messages . . . . . . . . . . . . . . . . . 191
.bp
.ft xi
.ce 2
.sh
Appendixes
.sp
.sh
(continued)
.qs
.sh
F New Functions and Implementation Changes\c
.qs
\ . . . . . . . . . 199
.sp
F.1 BDOS Function and Data Structure Changes . . . . . . 199
.sp
F.2 BDOS Functions Not Supported By CP/M-8000 . . . . . . 200
.bp
.ft xii
.ce
.sh
Tables, Figures, and Listings
.qs
================= TO BE REVISED ==========================
.sp 3
.sh
Tables
.qs
.sp
.nf
1-1. Program Modules in the CPM.SYS File . . . . . . . 1
1-2. CP/M-8000 Programmer's Guide Conventions . . . . . 2
1-3. CP/M-8000 Commands (Programmer's Guide) . . . . . 3
1-4. CP/M-8000 Commands (Users Guide) . . . . . . . . . 4
1-5. CP/M-8000 Commands (C Manual) . . . . . . . . . . 5
1-6. Delimiter Characters . . . . . . . . . . . . . . 6
1-7. CP/M-8000 Terminology . . . . . . . . . . . . . . 7
3-1. Values for Symbol Types . . . . . . . . . . . . . 18
3-2. Relocation Word Values (bits 0 through 2) . . . . 20
4-1. CP/M-8000 BDOS Functions . . . . . . . . . . . . . 23
4-2. BDOS Parameter Summary . . . . . . . . . . . . . 24
4-3. File Access Functions . . . . . . . . . . . . . . 26
4-4. Read-Write Error Response Options . . . . . . . . 29
4-5. Disk File Error Response Options . . . . . . . . 30
4-6. Unsuccessful Write Operation Return Codes . . . . 38
4-7. File Attributes . . . . . . . . . . . . . . . . . 43
4-8. Read Random Function Return Codes . . . . . . . . 45
4-9. Write Random Function Return Codes . . . . . . . 47
4-10. Current Position Definitions . . . . . . . . . . 49
4-11. Drive Functions . . . . . . . . . . . . . . . . . 52
4-12. Fields in the DPB and CDPB . . . . . . . . . . . 60
4-13. Character I/O Functions . . . . . . . . . . . . . 62
4-14. Direct Console I/O Function Values . . . . . . . 66
4-15. Line Editing Controls . . . . . . . . . . . . . . 70
4-16. I/O Byte Field Definitions . . . . . . . . . . . 75
4-17. System and Program Control Functions . . . . . . 77
4-18. Version Numbers . . . . . . . . . . . . . . . . . 79
4-19. Program Load Function Return Codes . . . . . . . 85
4-20. Load Parameter Block Options . . . . . . . . . . 86
4-21. Valid Vectors and Exceptions . . . . . . . . . . 90
4-22. TPAB Parameter Field Values, Bits 0 and 1 . . . . 93
5-1. Assembler Option . . . . . . . . . . . . . . . . 96
5-2. Assembly Language Directives . . . . . . . . . . 98
8-1. DDT-68K Command Summary . . . . . . . . . . . . . 106
A-1. Summary of BIOS Functions . . . . . . . . . . . . 117
C-1. Base Page Format: Offsets and Contents . . . . . 127
D-1. Instruction Set Summary . . . . . . . . . . . . . 128
D-2. Variations of Instruction Types . . . . . . . . . 131
E-1. AR68 Fatal Diagnostic Error Messages . . . . . . 157
E-2. AS68 Diagnostic Error Messages . . . . . . . . . 161
E-3. User-recoverable Fatal Error Messages . . . . . . 167
.bp
.ft xiii
.ce 2
.sh
Tables, Figures, and Listings
.sp
.sh
(continued)
.sp 3
.sh
Tables
.qs
E-4. BDOS Error Messages . . . . . . . . . . . . . . . 172
E-5. BIOS Error Messages . . . . . . . . . . . . . . . 175
E-6. CCP Diagnostic Error Messages . . . . . . . . . . 176
E-7. DDT-8000 Diagnostic Error Messages . . . . . . . . 180
E-8. DUMP Error Messages . . . . . . . . . . . . . . . 187
E-9. LO68 Fatal Diagnostic Error Messages . . . . . . 188
E-10. NM68 Error Messages . . . . . . . . . . . . . . . 192
E-11. RELOC Error Messages . . . . . . . . . . . . . . 193
E-12. SENDC68 Diagnostic Error Messages . . . . . . . . 196
E-13. SIZE68 Error Messages . . . . . . . . . . . . . . 197
F-1. New BDOS Functions . . . . . . . . . . . . . . . 199
F-2. BDOS Function Implementation Changes . . . . . . 199
F-3. BDOS Data Structure Implementation Changes . . . 200
F-4. BDOS Functions Not Supported by CP/M-8000 . . . . 200
.sp 2
.sh
Figures
.qs
.sp
2-1. Format of the Command Tail in the DMA Buffer . . 11
2-2. CP/M-8000 Default Memory Model . . . . . . . . . . 13
2-3. CP/M-8000 Memory Model with Inaccessible Memory . 14
3-1. Header for Contiguous Program Segments . . . . . 16
3-2. Header for Noncontiguous Program Segments . . . . 17
3-3. Entry in Symbol Table . . . . . . . . . . . . . . 18
4-1. FCB Format for Rename Function . . . . . . . . . 40
4-2. DPB and CDBP . . . . . . . . . . . . . . . . . . 59
4-3. I/O Byte . . . . . . . . . . . . . . . . . . . . 74
4-4. Command Line Format in the DMA Buffer . . . . . . 82
4-5. BIOS Parameter Block (BPB) . . . . . . . . . . . 84
4-6. Format of the Load Parameter Block (LPB) . . . . 86
4-7. Exception Parameter Block (EPB) . . . . . . . . . 88
4-8. Transient Program Parameter Block . . . . . . . . 92
4-9. Parameter Field in TPAB . . . . . . . . . . . . . 93
.sh
Listings
.qs
.sp
B-1. Transient Program Load Example 1 . . . . . . . . 143
B-2. Transient Program Load Example 2 . . . . . . . . 146
.nx one