M.J.Karas, 00-00-00
[ Converted Mnemonics to Z80, -PG ]
SLIDING INTO BDOS
THE SMOOTH AND EASY WAY
by: Michael J. Karas
2468 Hansen Court
Simi Valley, CA 93065
What is this thing everybody is talking about called BDOS?
This series will attempt to answer this question in some detail
but first we need a little basis to understand WHY in the first
place. Digital Research CP/M is an operating system for smaller
type micro processor computer systems that is designed to remove
much of the normal computer operation drudgery experienced by the
computer operator. The operating system software embodies a
"system philosophy" that structures and generalizes upon the
operating environment of a piece of electronics hardware. The
environment presented actually allows that piece of quiet,
transistorized machinery to be used at a much higher level. The
full impact of what this operating system provides to a computer
is most probably felt by the typical micro computer hacker that
worked the hard way to get a computer system up and running.
While building, debugging, and integrating the pieces, the
computer was just a whole bunch of parts interfaced together in
an organized manner. However, when the thing is finally a
"computer" how does it get used. The low level process of poking
data into memory from a front panel or even filling, dumping, or
block moving memory data with an EPROM based "monitor program"
hardly makes this computer "useful". The process of putting on
disks and bringing up CP/M lights the torch for computer
usability. In this case the hacker experiences an elated feeling
now "NOW I CAN DO SOMETHING!"
Buried inside of the total operating system presentation is
the concept of generalization brought up in the previous
paragraph. One of the major requirements in order to make a
computer useful is that there has to be applications software
that performs the jobs intended for the computer. Jobs like
accounting, word processing, spread sheet data analysis, or
inventory control. Unfortunately the process of producing
applications software is very, very expensive. A good package may
take anywhere from one to ten man years of development effort to
make. If the process of making an applications package had to be
custom taylored to a specific hardware environment, then there
would not be affordable software available for use upon a given
XYZ computer. Generalization in the operation of a computer
environment solves this problem however. With the understanding
that at a certain level "all microprocessor computer systems are
alike" it is possible, with minimum constraints, to define a set
of logical type operations that make a computer useful.
This logical set of operations, for the Digital Research
CP/M operating system, is defined within the BDOS portion of the
operating system. Here in about 3 1/2 K bytes of tightly written
assembly language is the "generalization converter" that takes
I/O requests for hardware independant applications programs and
turns them into a lower level set of simplistic hardware oriented
functions that are then processed through the BIOS. This
conversion process is beneficial in the light that CP/M Ver 2.2
can be setup to run on a typical brand XYZ computer for about one
half of the effort needed to convert even one of the simplest
application packages had that application been written in a
hardware dependant manner. Conclusion; software developers can
make better, more sophisticated applications available for lower
cost and computer users find a competitive software market place
where there are many times multiple packages available that
perform similar functions.
The thrust of this presentation is to show the prospective
applications programmer how to use most of the generalized set
of "BDOS System Calls" within Digital Researches CP/M Ver 2.2.
The presentation scheme will be to describe all of the functions
and use simple examples. The reader is assumed to be modistly
familiar with 8080 Assembly Language Programming as all of the
examples will be given in machine language. Likewise, in this
environment it is assumed by default that the prospective
programmer is planning to code in assembly language. If a CP/M
compatible high level language is used for programming, such as
Digital Research PL/I-80 or Microsoft BASIC-80, then of course
the program interface at the "System Call" level becomes
transparent to the programmer. Run time subroutines make the high
level coded application get converted through yet another step.
(One major reason applications code in a high level language runs
slower than the equivalent function written in assembly
language).
SUMMARY OF CP/M SYSTEM CALLS
The set of system or "BDOS" I/O entry points available to
the CP/M programmer is complete yet simple. The primary beauty of
the CP/M system is this small world of completeness. Many
programmers familair with other operating systems complain that
the CP/M system is weak, unflexible, and incomplete. However, in
a microprocessor type computer world, the generalization level
defined for the CP/M system allows 85% of all microprocessor type
appliciation jobs to be programmed with relative ease. Also, in
my opinion, 8-bit microprocessor hardware is easily capable of
performing about 90 percent of the typical tasks targeted for
microcomputers. So what is this set of functions? The chart of
Figure 1 summarizes, in function number order, all of the system
operations specific to CP/M Version 2.2 that will be covered in
this presentation. In the subsequent sections that follow the
functions will be grouped into categories so that related
operations may become familiar with reference to one another.
FIGURE 1. DETAILED SUMMARY OF CP/M 2.2 SYSTEM CALLS
Function Entry Value to Return Value from
Number BDOS Passed in BDOS Passed in
DEC HEX Function (DE) or (E) regs (HL) or (A) register
-------------------------------------------------------------------------
0 00 | System Reset | **** | **** |
1 01 | Console Input | **** | (A)=character |
2 02 | Console Output | (E)=character | **** |
3 03 | Reader Input | **** | (A)=character |
4 04 | Punch Output | (E)=character | **** |
5 05 | Printer Output | (E)=character | **** |
6 06 | Direct Console I/O | (E)=0FFH is input| (A)=character |
| | (E)=chr is output| **** |
7 07 | Get IOBYTE | **** | (A)=IOBYTE |
8 08 | Set IOBYTE | (E)=IOBYTE | **** |
9 09 | Display Console String | (DE)=string addr | **** |
10 0A | Input Console String | (DE)=string addr | (A)=# chr input |
11 0B | Get Console Status | **** | (A)=000H idle |
| | | (A)=0FFH ready |
12 0C | Get CP/M Version Number| **** | (HL)=Version # |
13 0D | Reset Disk Subsystem | **** | **** |
14 0E | Select Disk Drive | (E)=disk number | **** |
15 0F | Open a File | (DE)=FCB address | (A)=dir code |
16 10 | Close a File | (DE)=FCB address | (A)=dir code |
17 11 | Search for File | (DE)=FCB address | (A)=dir code |
18 12 | Search for Next | **** | (A)=dir code |
19 13 | Delete File | (DE)=FCB address | (A)=dir code |
20 14 | Read next Record | (DE)=FCB address | (A)=error code |
21 15 | Write next Record | (DE)=FCB address | (A)=error code |
22 16 | Create New File | (DE)=FCB address | (A)=dir code |
23 17 | Rename File | (DE)=FCB address | (A)=dir code |
24 18 | Get Login Vector | **** | (HL)=login vector|
25 19 | Get Logged Disk Number | **** | (A)=logged disk |
26 1A | Set R/W Data Buff Addr | (DE)=buffer addr | **** |
27 1B | Get Allocation Vector | **** | (HL)=alloc vector|
| | | address |
28 1C | Write Protect Disk | (E)=disk number | **** |
29 1D | Get Read Only Vector | **** | (HL)=R/O vector |
30 1E | Set File Attributes | (DE)=FCB address | (A)=dir code |
31 1F | Get Addr of Disk Parms | **** | (HL)=parm addr |
32 20 | Get/Set User Select | (E)=0FFH get | (A)=current user |
33 21 | Read Random Record | (DE)=long FCB adr| (A)=error code |
34 22 | Write Random Record | (DE)=long FCB adr| (A)=error code |
35 23 | Get Size of File | (DE)=long FCB adr| (r0-2=rec cnt) |
36 24 | Set Random Record Num | (DE)=long FCB adr| (r0-2=rec numb) |
37 25 | Reset Drive | (DE)=drive vector| **** |
38 26 | Not used | | |
39 27 | Not used | | |
40 28 | Write Random with | (DE)=long FCB adr| (A)=error code |
-------------------------------------------------------------------------
The technical means required to "use" or interface to the
CP/M system for each function contains a certain common structure
that will be discussed here. The base memory page of a CP/M
system memory map includes, at a specific memory address, a JUMP
instruction to the CP/M BDOS entry point. For most CP/M systems
this is address 00005H. To accomplish BDOS I/O the number of the
function is placed into the (C) register. If the parameter
requires input parameters, then they are passed in the (DE)
register pair or the individual (E) register depending upon
whether the parameter is a word or byte value. Result information
returned by some functions is sent back to the users program in
either the (A) register or the (HL) register pair depending upon
if the value is a byte or word. The following simple program
segment demonstrates the scheme used to output the 26 characters
A-Z to the console screen through the use of function number 2.
BDOS EQU 0005H ; SYSTEM ENTRY
CONOUT EQU 2 ; OUTPUT FUNCTION
ORG 0100H ; TPA BASE
LD B,26 ; PRINT 26 COUNTER
LD C,'A' ; START WITH 'A'
;
LOOP:
PUSH BC ; SAVE COUNTER & LETTER
LD E,C ; LETTER TO (E) FOR OUTPUT
LD C,CONOUT ; BDOS FUNC TO (C)
CALL BDOS ; GO GO OUTPUT
POP BC
INC C ; SEQUENCE TO NEXT CHAR
DEC B ; DECREASE CHR COUNTER
JP NZ,LOOP ; MORE TO DO IF NOT TO ZERO
RET ; IMMEDIATE CCP RETURN
SYSTEM CALLS FOR OPERATOR CONSOLE INPUT AND OUTPUT
Intrinsic to the operation of any computer system,
especially of the CP/M gender, is the operator console. The
device provides the human interface to the machine and as such
the BDOS includes a generalized set of operator communication
functions to perform I/O with the console device. The various
options available will each be presented with a brief example.
INPUT FROM CONSOLE KEYBOARD: Function 1.
This function waits for and reads in a character from the
console device keyboard. The operator typed character is echoed
automatically back to the console display if the character is an
ASCII printable character (020H to 07EH) or it is a carriage
return, line feed, back space, or tab. Note that the BDOS
automatically expands tabs to columns of eight characters. Upon
outputting the character for the echo, a check is made for
console start/stop, CTL-S, and if so the console input routine
does not return to the users program until another arbitrary key
is depressed.
;CONSOLE INPUT EXAMPLE
;
CONIN EQU 001H ; FUNC # 1
BDOS EQU 0005H ; SYSTEM ENTRY
ORG 0100H ; START
LD C,CONIN ; FUNCTION
CALL BDOS ; GO GET CHARACTER
LD (INCHAR),A ; SAVE FOR WHATEVER REASON
RET ; IMMEDIATE CCP RETURN
;
INCHAR:
DEFS 1 ; PLACE TO STORE INPUT CHAR
;
END
OUTPUT TO CONSOLE DISPLAY: Function 2.
The ASCII character in the (E) register is sent to the
console display device. The output may be any byte value but many
times the hardware driver BIOS routines automatically strip off
the upper bit of the byte. Upon output the printer echo flag
within BDOS is checked (CTL-P) and if set the character is also
sent to the printer peripheral device. Note that the BDOS
automatically expands output tabs to columns of eight characters.
Upon outputting the character a check is made for input of
console start/stop, CTL-S, and if so the console output routine
does not return to the users program until another arbitrary key
is depressed.
;CONSOLE OUTPUT EXAMPLE
;
CONOUT EQU 002H ; FUNC # 2
BDOS EQU 0005H ; SYSTEM ENTRY
ORG 0100H ; START
LD A,(OUTCHAR) ; GET CHARACTER TO OUTPUT
LD E,A
LD C,CONOUT ; FUNCTION
CALL BDOS ; GO SEND CHARACTER
RET ; IMMEDIATE CCP RETURN
;
OUTCHAR:
DEFB 'X' ; PLACE TO GET OUTPUT CHAR
;
END
DIRECT USER INTERFACE TO CONSOLE: Function 6.
Some programming applications require that the BDOS not
monitor the input/output character stream as is done with
functions 1 & 2. To allow for these functions the direct I/O
function is supported. The following example shows how it is used
to input values and echo them until an input control-Z character
is typed.
;DIRECT CONSOLE I/O EXAMPLE
;
DIRCIO EQU 006H ; FUNCTION NUMBER
BDOS EQU 0005H ; SYSTEM ENTRY POINT
CTLZ EQU 'Z'-040H ; ASCII CTL-Z CHARACTER
INPUT EQU 0FFH ; DIRECT INPUT FLAG
ORG 0100H ; CONSOLE INPUT
;
LOOP:
LD E,INPUT ; SET FOR INPUT
LD C,DIRCIO ; FUNCTION
CALL BDOS ; GET INPUT OR STATUS
OR A ; IF (A)=0 NO CHAR WAS READY
JP Z,LOOP ; CONTINUE TO WAIT FOR INPUT
CP CTLZ ; IF INPUT WAS CTL Z THEN END
RET Z ; CCP RETURN ON END
LD E,A ; CHARACTER TO (E) FOR OUTPUT
LD C,DIRCIO ; SAME FUNCTION NUMBER AGAIN
CALL BDOS ; GO OUTPUT IT
JP LOOP ; NEXT CHARACTER INPUT LOOP
;
END
PRINTING STRINGS OF CHARACTERS TO THE CONSOLE: Function 9.
Message string sequences of characters to be sent to the
console are quite common in applications programming. Typical
uses may be for user prompt messages, program sign-on messages
etc. The BDOS provides a convenient mechanism to allow the
programmer to output a whole string of characters rather than
having to loop with single character outputs. The string is
intended to be stored in consecutive memory locations and end
with the ASCII '$' character. The (DE) registers are used to
point to the start of the string. The '$' signals the end of the
string to display and is not sent to the console. The output
bytes may be any 8-bit value but many times the hardware driver
BIOS routines automatically strip off the upper bit of the byte.
Upon output of each character the printer echo flag within BDOS
is checked (CTL-P) and if set the character is also sent to the
printer peripheral device. Note that the BDOS automatically
expands output tabs to columns of eight characters. Upon
outputting each character a check is made for input of console
start/stop, CTL-S, and if so the console string output routine
does not return to the users program until another arbitrary key
is depressed.
;CONSOLE STRING PRINT EXAMPLE
;
CONSTR EQU 009H ; FUNC # 9
BDOS EQU 0005H ; SYSTEM ENTRY
CR EQU 0DH ; ASCII CARRIAGE RETURN
LF EQU 0AH ; ASCII LINE FEED
ORG 0100H ; START
LD DE,MESSAGE ; POINT AT STRING TO SEND
LD C,CONSTR ; FUNCTION
CALL BDOS ; GO SEND STRING
RET ; IMMEDIATE CCP RETURN
;
MESSAGE:
DEFB CR,LF,'Hello Operator',CR,LF,'$'
;
END
READING A STRING OF CHARACTERS IN FROM KEYBOARD: Function 10.
The CP/M console command processor (CCP) assumed to be vary
familiar to most CP/M system operators allows buffered command
input with editing features. It turns out that this operation is
a much needed function for getting in strings of text from the
operator console. Use of this function allows standardization of
the command input functions so that the operator can easily learn
the editing key functions. It also removes the pain of writing
the same function over and over again by the applications
programmer. The read string command inputs the edited text to a
buffer pointerd to by the (DE) register pair. The caller
specifies the maximum length desired and the BDOS returns the
actual length of string entered if carriage return is entered
prior to exceeding the maximum input length. The input length is
returned in both the (A) register and as part of the buffer.
Bytes in the string buffer past the end of the entered text are
uninitialized. The example shown below gives an assembly language
view point of the buffer structure and how to program an input
function.
The editing functions supported are the following control
and/or special characters:
rub/del removes and echos the last entered char
ctl-C initiates system reboot if first char
ctl-E echos a CR & LF to console without
putting them into buffer
ctl-H (or back space key) back spaces one char
removing last entered character
ctl-J (or line feed key) terminates line input
ctl-M (or carriage return) terminates input
ctl-R retypes currently entered characters
under current line
ctl-U deletes all of currently entered data
and restarts buffer input on new line
ctl-X deletes all of currently entered data
and restarts buffer input on same line
;CONSOLE INPUT BUFFER EXAMPLE
;
CONBUF EQU 00AH ; STRING INPUT FUNCTION
BDOS EQU 0005H ; SYSTEM ENTRY POINT
LENGTH EQU 32 ; DESIRED MAXIMUM CHARACTERS
ORG 0100H ; START POINT
LD DE,STRING ; POINT AT BUFFER AREA
LD C,CONBUF ; FUNCTION NUMBER
CALL BDOS ; GO GET STRING
RET ; RETURN TO CCP WITHOUT
; ...DOING ANYTHING WITH DATA
;
;
;CONSOLE INPUT BUFFER LAYOUT
;
STRING:
DEFB LENGTH ; MAXIMUM DESIRED INPUT LENGTH
AMOUNT:
DEFS 1 ; BYTE WHERE BDOS RETURNS
; ..ACTUAL BYTE COUNT
STRBF:
DEFS LENGTH ; RESERVED STORAGE FOR UP TO
; "LENGTH" NUMBER OF CHARACTERS
;
END
|
