.bp 1 .op .cs 5 .mt 5 .mb 6 .pl 66 .ll 65 .po 10 .hm 2 .fm 2 .he .ft 5-% .pc 1 .ce .sh Section 5 .qs .sp .ce .sh CP/M 2 System Interface .qs .tc 5 CP/M 2 System Interface .sp 2 .he CP/M Operating System Manual 5.1 Introduction .tc 5.1 Introduction 5.1 Introduction .pp 5 This chapter describes CP/M (release 2) system organization including the structure of memory and system entry points. This section provides the information you need to write programs that operate under CP/M and that use the peripheral and disk I/O facilities of the system. .pp CP/M is logically divided into four parts, called the Basic Input/Output System (BIOS), the Basic Disk Operating System (BDOS), the Console Command Processor (CCP), and the Transient Program Area (TPA). The BIOS is a hardware-dependent module that defines the exact low level interface with a particular computer system that is necessary for peripheral device I/O. Although a standard BIOS is supplied by Digital Research, explicit instructions are provided for field reconfiguration of the BIOS to match nearly any hardware environment, see Section 6. .pp The BIOS and BDOS are logically combined into a single module with a common entry point and referred to as the FDOS. The CCP is a distinct program that uses the FDOS to provide a human-oriented interface with the information that is cataloged on the back-up storage device. The TPA is an area of memory, not used by the FDOS and CCP, where various nonresident operating system commands and user programs are executed. The lower portion of memory is reserved for system information and is detailed in later sections. Memory organization of the CP/M system is shown in Figure 5-1. .sp 3 .nf High Memory FDOS (BDOS+BIOS) FBASE: CCP CBASE: TPA TBASE: System Parameters BOOT: .sp 2 .ce .sh Figure 5-1. CP/M Memory Organization .qs .fi .sp 2 .pp The exact memory addresses corresponding to BOOT, TBASE, CBASE, and FBASE vary from version to version and are described fully in Section 6. All standard CP/M versions assume BOOT=0000H, which is the base of random access memory. The machine code found at location BOOT performs a system warm start, which loads and initializes the programs and variables necessary to return control to the CCP. Thus, transient programs need only jump to location BOOT to return control to CP/M at the command level. Further, the standard versions assume TBASE=BOOT+0100H, which is normally location 0100H. The principal entry point to the FDOS is at location BOOT+0005H (normally 0005H) where a jump to FBASE is found. The address field at BOOT+0006H (normally 0006H) contains the value of FBASE and can be used to determine the size of available memory, assuming that the CCP is being overlaid by a transient program. .pp Transient programs are loaded into the TPA and executed as follows. The operator communicates with the CCP by typing command lines following each prompt. Each command line takes one of the following forms: .sp .nf .in 8 command command file1 command file1 file2 .fi .in 0 .sp where command is either a built-in function, such as DIR or TYPE, or the name of a transient command or program. If the command is a built-in function of CP/M, it is executed immediately. Otherwise, the CCP searches the currently addressed disk for a file by the name .sp .ti 8 command.COM .pp If the file is found, it is assumed to be a memory image of a program that executes in the TPA and thus implicity originates at TBASE in memory. The CCP loads the COM file from the disk into memory starting at TBASE and can extend up to CBASE. .pp If the command is followed by one or two file specifications, the CCP prepares one or two File Control Block (FCB) names in the system parameter area. These optional FCBs are in the form necessary to access files through the FDOS and are described in Section 5.2. .pp The transient program receives control from the CCP and begins execution, using the I/O facilities of the FDOS. The transient program is called from the CCP. Thus, it can simply return to the CCP upon completion of its processing, or can jump to BOOT to pass control back to CP/M. In the first case, the transient program must not use memory above CBASE, while in the latter case, memory up through FBASE-1 can be used. .pp The transient program can use the CP/M I/O facilities to communicate with the operator's console and peripheral devices, including the disk subsystem. The I/O system is accessed by passing a function number and an information address to CP/M through the FDOS entry point at BOOT+0005H. In the case of a disk read, for example, the transient program sends the number corresponding to a disk read, along with the address of an FCB to the CP/M FDOS. The FDOS, in turn, performs the operation and returns with either a disk read completion indication or an error number indicating that the disk read was unsuccessful. .sp 2 .tc 5.2 Operating System Call Conventions .he CP/M Operating System Manual 5.2 Call Conventions .sh 5.2 Operating System Call Conventions .qs .pp This section provides detailed information for performing direct operating system calls from user programs. Many of the functions listed below, however, are accessed more simply through the I/O macro library provided with the MAC macro assembler and listed in the Digital Research manual entitled, \c .ul Programmer's Utilities Guide for the CP/M Family of Operating Systems. .qu .pp CP/M facilities that are available for access by transient programs fall into two general categories: simple device I/O and disk file I/O. The simple device operations are .sp .nf .in 5 .ti -2 o read a console character .ti -2 o write a console character .ti -2 o read a sequential character .ti -2 o write a sequential character .ti -2 o get or set I/O status .ti -2 o print console buffer .ti -2 o interrogate console ready .sp The following FDOS operations perform disk I/O: .sp .ti -2 o disk system reset .ti -2 o drive selection .ti -2 o file creation .ti -2 o file close .ti -2 o directory search .ti -2 o file delete .ti -2 o file rename .ti -2 o random or sequential read .ti -2 o random or sequential write .ti -2 o interrogate available disks .ti -2 o interrogate selected disk .ti -2 o set DMA address .ti -2 o set/reset file indicators. .fi .in 0 .pp As mentioned above, access to the FDOS functions is accomplished by passing a function number and information address through the primary point at location BOOT+0005H. In general, the function number is passed in register C with the information address in the double byte pair DE. Single byte values are returned in register A, with double byte values returned in HL, a zero value is returned when the function number is out of range. For reasons of compatibility, register A = L and register B = H upon return in all cases. Note that the register passing conventions of CP/M agree with those of the Intel PL/M systems programming language. CP/M functions and their numbers are listed below. .bp .nf .in 5 O System Reset 19 Delete File 1 Console Input 20 Read Sequential 2 Console Output 21 Write Sequential 3 Reader Input 22 Make File 4 Punch Output 23 Rename File 5 List Output 24 Return Login Vector 6 Direct Console I/O 25 Return Current Disk 7 Get I/O Byte 26 Set DMA Address 8 Set I/O Byte 27 Get Addr(Alloc) 9 Print String 28 Write Protect Disk 10 Read Console Buffer 29 Get R/0 Vector 11 Get Console Status 30 Set File Attributes 12 Return Version Number 31 Get Addr(Disk Parms) 13 Reset Disk System 32 Set/Get User Code 14 Select Disk 33 Read Random 15 Open File 34 Write Random 16 Close File 35 Compute File Size 17 Search for First 36 Set Random Record 18 Search for Next 37 Reset Drive 40 Write Random with Zero Fill .fi .in 0 .sp .pp Functions 28 and 32 should be avoided in application programs to maintain upward compatibility with CP/M. .pp Upon entry to a transient program, the CCP leaves the stack pointer set to an eight-level stack area with the CCP return address pushed onto the stack, leaving seven levels before overflow occurs. Although this stack is usually not used by a transient program (most transients return to the CCP through a jump to location 0000H) it is large enough to make CP/M system calls because the FDOS switches to a local stack at system entry. For example, the assembly-language program segment below reads characters continuously until an asterisk is encountered, at which time control returns to the CCP, assuming a standard CP/M system with BOOT = 0000H. .sp 2 .nf .in 8 BDOS EQU 0005H ;STANDARD CP/M ENTRY CONIN EQU 1 ;CONSOLE INPUT FUNCTION ; ORG 0100H ;BASE OF TPA NEXTC: MVI C,CONIN ;READ NEXT CHARACTER CALL BDOS ;RETURN CHARACTER IN CPI '*' ;END OF PROCESSING? JNZ NEXTC ;LOOP IF NOT RET ;RETURN TO CCP END .fi .in 0 .sp .pp CP/M implements a named file structure on each disk, providing a logical organization that allows any particular file to contain any number of records from completely empty to the full capacity of the drive. Each drive is logically distinct with a disk directory and file data area. The disk filenames are in three parts: the drive select code, the filename (consisting of one to eight nonblank characters), and the filetype (consisting of zero to three nonblank characters). The filetype names the generic category of a particular file, while the filename distinguishes individual files in each category. The filetypes listed in Table 5-1 name a few generic categories that have been established, although they are somewhat arbitrary. .sp 2 .sh Table 5-1. CP/M Filetypes .qs .sp .nf Filetype Meaning .sp .in 30 .ti -11 ASM Assembler Source .ti -11 PRN Printer Listing .ti -11 HEX Hex Machine Code .ti -11 BAS Basic Source File .ti -11 INT Intermediate Code .ti -11 COM Command File .ti -11 PLI PL/I Source File .ti -11 REL Relocatable Module .ti -11 TEX TEX Formatter Source .ti -11 BAK ED Source Backup .ti -11 SYM SID Symbol File .ti -11 $$$ Temporary File .fi .in 0 .sp .pp Source files are treated as a sequence of ASCII characters, where each line of the source file is followed by a carriage return, and line-feed sequence (0DH followed by 0AH). Thus, one 128-byte CP/M record can contain several lines of source text. The end of an ASCII file is denoted by a CTRL-Z character (1AH) or a real end-of-file returned by the CP/M read operation. CTRL-Z characters embedded within machine code files (for example, COM files) are ignored and the end-of-file condition returned by CP/M is used to terminate read operations. .pp Files in CP/M can be thought of as a sequence of up to 65536 records of 128 bytes each, numbered from 0 through 65535, thus allowing a maximum of 8 megabytes per file. Note, however, that although the records may be considered logically contiguous, they may not be physically contiguous in the disk data area. Internally, all files are divided into 16K byte segments called logical extents, so that counters are easily maintained as 8-bit values. The division into extents is discussed in the paragraphs that follow: however, they are not particularly significant for the programmer, because each extent is automatically accessed in both sequential and random access modes. .pp In the file operations starting with Function 15, DE usually addresses a FCB. Transient programs often use the default FCB area reserved by CP/M at location BOOT+005CH (normally 005CH) for simple file operations. The basic unit of file information is a 128-byte record used for all file operations. Thus, a default location for disk I/O is provided by CP/M at location BOOT+0080H (normally 0080H) which is the initial default DMA address. See Function 26. .pp All directory operations take place in a reserved area that does not affect write buffers as was the case in release 1, with the exception of Search First and Search Next, where compatibility is required. .pp The FCB data area consists of a sequence of 33 bytes for sequential access and a series of 36 bytes in the case when the file is accessed randomly. The default FCB, normally located at 005CH, can be used for random access files, because the three bytes starting at BOOT+007DH are available for this purpose. Figure 5-2 shows the FCB format with the following fields. .sp 3 .nf dr f1 f2 / / f8 t1 t2 t3 ex s1 s2 rc d0 / / dn cr r0 r1 r2 00 01 02 ... 08 09 10 11 12 13 14 15 16 ... 31 32 33 34 35 .fi .sp 2 .sh Figure 5-2. File Control Block Format .sp 3 The following table lists and describes each of the fields in the File Control Block figure. .sp 2 .sh Table 5-2. File Control Block Fields .nf .sp Field Definition .sp dr drive code (0-16) 0 = use default drive for file 1 = auto disk select drive A, 2 = auto disk select drive B, . . . 16= auto disk select drive P. .sp f1...f8 contain the filename in ASCII upper-case, with high bit = 0 .sp t1, t2, t3 contain the filetype in ASCII upper-case, with high bit = 0 t1', t2', and t3' denote the bit of these positions, t1' = 1 =>Read-Only file, t2' = 1 =>SYS file, no DIR list .sp ex contains the current extent number, normally set to 00 by the user, but in range 0-31 during file I/O .bp .sh Table 5-2. (continued) .qs .sp Field Definition .sp s1 reserved for internal system use .sp s2 reserved for internal system use, set to zero on call to OPEN, MAKE, SEARCH .sp rc record count for extent ex; takes on values from 0-127 .sp d0...dn filled in by CP/M; reserved for system use .sp cr current record to read or write in a sequential file operation; normally set to zero by user .sp r0, r1, r2 optional random record number in the range 0-65535, with overflow to r2, r0, r1 constitute a 16-bit value with low byte r0, and high byte r1 .fi .sp .pp Each file being accessed through CP/M must have a corresponding FCB, which provides the name and allocation information for all subsequent file operations. When accessing files, it is the programmer's responsibility to fill the lower 16 bytes of the FCB and initialize the cr field. Normally, bytes 1 through 11 are set to the ASCII character values for the filename and filetype, while all other fields are zero. .pp FCBs are stored in a directory area of the disk, and are brought into central memory before the programmer proceeds with file operations (see the OPEN and MAKE functions). The memory copy of the FCB is updated as file operations take place and later recorded permanently on disk at the termination of the file operation, (see the CLOSE command). .pp The CCP constructs the first 16 bytes of two optional FCBs for a transient by scanning the remainder of the line following the transient name, denoted by file1 and file2 in the prototype command line described above, with unspecified fields set to ASCII blanks. The first FCB is constructed at location BOOT+005CH and can be used as is for subsequent file operations. The second FCB occupies the d0...dn portion of the first FCB and must be moved to another area of memory before use. If, for example, the following command line is typed: .sp .ti 8 PROGNAME B:X.ZOT Y.ZAP .bp the file PROGNAME.COM is loaded into the TPA, and the default FCB at BOOT+005CH is initialized to drive code 2, filename X, and filetype ZOT. The second drive code takes the default value 0, which is placed at BOOT-006CH, with the filename Y placed into location BOOT+006DH and filetype ZAP located 8 bytes later at BOOT+0075H. All remaining fields through cr are set to zero. Note again that it is the programmer's responsibility to move this second filename and filetype to another area, usually a separate file control block, before opening the file that begins at BOOT+005CH, because the open operation overwrites the second name and type. .pp If no filenames are specified in the original command, the fields beginning at BOOT+005DH and BOOT+006DH contain blanks. In all cases, the CCP translates lower-case alphabetics to upper-case to be consistent with the CP/M file naming conventions. .pp As an added convenience, the default buffer area at location BOOT+0080H is initialized to the command line tail typed by the operator following the program name. The first position contains the number of characters, with the characters themselves following the character count. Given the above command line, the area beginning at BOOT+0080H is initialized as follows: .sp 2 .nf .in 5 BOOT+0080H: .sp +00 +01 +02 +03 +04 +05 +06 +07 +08 +09 +A +B +C +D +E E '' 'B' ':' 'X' '.' 'Z' 'O' 'T' '' 'Y' '.' 'Z' 'A' 'P' .fi .in 0 .sp 2 where the characters are translated to upper-case ASCII with uninitialized memory following the last valid character. Again, it is the responsibility of the programmer to extract the information from this buffer before any file operations are performed, unless the default DMA address is explicitly changed. .pp Individual functions are described in detail in the pages that follow. .bp .sp 4 .nf FUNCTION 0: SYSTEM RESET .sp Entry Parameters: Register C: 00H .fi .sp 2 .pp The System Reset function returns control to the CP/M operating system at the CCP level. The CCP reinitializes the disk subsystem by selecting and logging-in disk drive A. This function has exactly the same effect as a jump to location BOOT. .sp 6 .nf FUNCTION 1: CONSOLE INPUT .sp Entry Parameters: Register C: 01H .sp Returned Value: Register A: ASCII Character .fi .sp 2 .pp The Console Input function reads the next console character to register A. Graphic characters, along with carriage return, line-feed, and back space (CTRL-H) are echoed to the console. Tab characters, CTRL-I, move the cursor to the next tab stop. A check is made for start/stop scroll, CTRL-S, and start/stop printer echo, CTRL-P. The FDOS does not return to the calling program until a character has been typed, thus suspending execution if a character is not ready. .bp .sp 4 .nf FUNCTION 2: CONSOLE OUTPUT .sp Entry Parameters Register C: 02H Register E: ASCII Character .fi .sp 2 .pp The ASCII character from register E is sent to the console device. As in Function 1, tabs are expanded and checks are made for start/stop scroll and printer echo. .sp 6 .nf FUNCTION 3: READER INPUT .sp Entry Parameters: Register C: 03H .sp Returned Value: Register A: ASCII Character .fi .sp 2 .pp The Reader Input function reads the next character from the logical reader into register A. See the IOBYTE definition in Chapter 6. Control does not return until the character has been read. .bp .sp 4 .nf FUNCTION 4: PUNCH OUTPUT .sp Entry Parameters: Register C: 04H register E: ASCII Character .fi .sp 2 .pp The Punch Output function sends the character from register E to the logical punch device. .sp 6 .nf FUNCTION 5: LIST OUTPUT .sp Entry Parameters: Register C: 05H Register E: ASCII Character .fi .sp 2 .pp The List Output function sends the ASCII character in register E to the logical listing device. .bp .sp 4 .nf FUNCTION 6: DIRECT CONSOLE I/O .sp Entry Parameters: Register C: 06H Register E: 0FFH (input) or char (output) .sp Returned Value: Register A: char or status .fi .sp 2 .pp Direct Console I/O is supported under CP/M for those specialized applications where basic console input and output are required. Use of this function should, in general, be avoided since it bypasses all of the CP/M normal control character functions (for example, CTRL-S and CTRL-P). Programs that perform direct I/O through the BIOS under previous releases of CP/M, however, should be changed to use direct I/O under BDOS so that they can be fully supported under future releases of MP/M \ and CP/M. .pp Upon entry to Function 6, register E either contains hexadecimal FF, denoting a console input request, or an ASCII character. If the input value is FF, Function 6 returns A = 00 if no character is ready, otherwise A contains the next console input character. .pp If the input value in E is not FF, Function 6 assumes that E contains a valid ASCII character that is sent to the console. .pp Function 6 must not be used in conjunction with other console I/O functions. .sp 6 .nf FUNCTION 7: GET I/O BYTE .sp Entry Parameters: Register C: 07H .sp Returned Value: Register A: I/O Byte Value .fi .sp 2 .pp The Get I/O Byte function returns the current value of IOBYTE in register A. See Chapter 6 for IOBYTE definition. .bp .sp 4 .nf FUNCTION 8: SET I/O BYTE .sp Entry Parameters: Register C: 08H Register E: I/O Byte Value .fi .sp 2 .pp The SET I/O Byte function changes the IOBYTE value to that given in register E. .sp 6 .nf FUNCTION 9: PRINT STRING .sp Entry Parameters: Register C: 09H Registers DE: String Address .fi .sp 2 .pp The Print String function sends the character string stored in memory at the location given by DE to the console device, until a $ is encountered in the string. Tabs are expanded as in Function 2, and checks are made for start/stop scroll and printer echo. .nx fiveb.tex