                                   COPYRIGHT

     Copyright (D 1983 Digital Research Inc.  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
     Inc., 60 Garden Court, Box DRI, Monterey, California 93942.

                                  DISCLAIMER

     DIGITAL RESEARCH INC.  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 Inc. reserves the right to
     revise this publication and to make changes from time to time in the
     content hereof without obligation of Digital Research Inc. to notify
     any person of such revision or changes.

                                NOTICE TO USER

     From time to time changes are made in the filenames and in the files
     actually included on the distribution disk.  This manual should not
     be construed as a representation or warranty that such files or
     facilities exist on the distribution disk or as part of the
     materials and programs distributed.  Most distribution disks include
     a "README.DOC" file.  This file explains variations from the manual
     which do constitute modification of the manual and the items
     included therewith.    Be sure to read this file before using the
     software.

                                  TRADEMARKS

     CP/M and Digital Research and its logo are registered trademarks of
     Digital Research Inc.  CP/M Plus, DDT, LINK-80, RMAC, SID, TEX, and
     XREF are trademarks of Digital Research Inc.  Altos is a registered
     trademark of Altos Corporation.  IBM is a registered trademark of
     International Business Machines.  Intel is a registered trademark of
     Intel Corporation.  Microsoft is a registered trademark of Microsoft
     Corporation.  Zilog and Z80 are registered trademarks of Zilog Inc.

     The CP/M Plus (CP/M Version 3) Operating System System Guide was
     prepared using the Digital Research TEX" Text Formatter and printed
     in the United States of America.

                       **********************************
                       * First Edition: January 1983
                       *    Second Edition: July 1983
                       **********************************

                                       Foreworci


              Cp/mg) 3, also marketed as CP/M PlusTm , is a single-console
         operating system for 8-bit machines that use an IntelO 8080, 8085,
         or zilogp Z80OR CPU.       CP/M 3 is upward-compatible with its
         predecessor, CP/M 2, and offers more features and higher performance
         than CP/M 2. This manual describes the steps necessary to create or
         modify a CP/M 3 Basic Input Output System (BIOS) tailored for a
         specific hardware environment.

              The CP/M Plus (CP/M Version 3) Operating System System
         Guide (hereafter cited as CP/M Plus System Guide) assumes you are
         familiar with systems programming in 8080 assembly language and that
         you have access to a CP/M 2 system.     It also assumes you understand
         the target hardware and that you have functioning disk I/O drivers.
         You should be familiar with the accompanying CP/M Plus (CP/M Version
         3) Operating System User's Guide (hereafter cited as CP/M Plus
         User's Guide) describing the operating system utilities.  You should
         also be familiar with the CP/M Plus (CP/M Version 3) Operating
         system Programmer I s Guide (hereaf ter cited as CP/M Plus Programmer I s
         Guide), which desc lbes the system calls use@by the applications
         programmer to interface with the operating system.  The Programmer' s
         Utilities Guide for the CP/M Family of Operating Systems (hereafter
         cited as Programmer's Utilities Guide) documents the assembling and
         debugging utilities.

              Section 1 of this manual is an overview of the component
         modules of the CP/M 3 operating system.         Section 2 provides an
         overview of the functions and data structures necessary to write an
         interface module between CP/M 3 and specific hardware.  Section 3
         contains a detailed description of these functions and data
         structures, followed by instructions to assemble and link the
         distributed modules with your customized modules.             Section 4
         describes the modular organization of the sample CP/M 3 BIOS on your
         distribution diskette.        Section 5 documents the procedure to
         generate and boot your CP/M 3 system.          Section 6 is a sample
         debugging session.

              The appendixes contain tables, and sample BIOS modules you can
         use, or study and modify.       Appendix A discusses removable media
         drives.  Appendix B discusses automatic density support.  Appendix C
         describes how CP/M 3 differs from CP/M 2.         Appendix D shows the
         format of the CPM3.SYS file.

              Appendixes E through H are listings of the assembled source
         code for the four hardware-independent modules of the sample BIOS.
         Appendix E is the kernel module to use when creating a modular BIOS
         in the form of the distributed sample.  Appendix F shows the System
         Control Block.   Appendix G is a table of equates for the baud rate
         and mode byte for character I/O.       Appendix H contains the macro
         definitions you can use to generate some of the CP/M 3 disk data
         structures.  Appendix I lists the assembled source code for the six
         BIOS modules that depend on the Altos@ 8000-15 Computer System
         hardware.  It also contains a sample Submit file to build a BIOS.

                                         iii

         Appendixes J and K are tabular summaries of the public entry
    points and data items in the modules of the sample BIOS.  Finally,
    Appendix L is a tabular summary of the thirty-three functions of the
    CP/M 3 BIOS, complete with entry parameters and returned values.








                                     iv

                                Table of Contents


        1  CP/M 3 Operating System Overview

           1.1   Introduction to CP/M 3     1

           1.2   CP/M 3 System Components     2

           1.3   Communication Between Modules     2

           1.4   Banked and Nonbanked Systems     4

           1.5   Memory Requirements     7

           1.6   Disk Organization    10

           1.7   Hardware Supported     10

                 1.7.1 Hardware Supported by CP/M 3 Banked System .       11
                 1.7.2 Hardware Supported by CP/M 3 Nonbanked System      11

           1.8   Customizing CP/M 3     11

           1.9   Initial Load (Cold Boot) of CP/M 3    12

        2  CP/M  3 BIOS Overview

           2.1   Organization of the BIOS    15

           2.2   System Control Block     17

           2.3   System Initialization    18

           2.4   Character I/O    19

           2.5   Disk I/O     20

           2.6   Memory Selects and Moves    24

           2.7   Clock Support     24

        3  CP/M  3 BIOS Functional Specifications

           3.1   System Control Block    27

           3.2   Character I/O Data Structures    32

           3.3   BIOS Disk Data Structures    34

                 3.3.1 Drive Table     36
                 3.3.2 Disk Parameter Header    36

                                           v

                                Table of Contents
                                   (continued)


               3.3.3 Disk Parameter Block       40
               3.3.4 Buffer Control Block       44
               3.3.5 Data Structure macro Definitions     46
         3.4   BIOS Subroutine Entry Points       49
               3.4.1   System Initialization Functions     51
               3.4.2   Character I/O Functions      54
               3.4.3   Disk I/O Functions        58
               3.4.4   Memory Select and Move Functions     64
               3.4.5   Clock Support Function       67
         3.5   Banking Considerations        67
         3.6   Assembling and Linking Your BIOS       69

     4   CP/M  3 Sample BIOS Modules
         4.1   Functional Summary of BIOS Modules      71
         4.2   Conventions Used in BIOS Modules       73
         4.3   Interactions of Modules        73
               4.3.1 Initial Boot         73
               4.3.2 Character I/O Operation      74
               4.3.3 Disk I/O Operation       74
         4.4   Predefined Variables and Subroutines      75
         4.5   BOOT Module          77
         4.6   Character I/O         78
         4.7   Disk I/O          81
               4.7.1   Disk I/O Structure       81
               4.7.2   Drive Table Module (DRVTBL)      81
               4.7.3   Extended Disk Parameter Headers       (XDPHS)    82
               4.7.4   Subroutine Entry Points      83
               4.7.5   Error Handling and Recovery      84
               4.7.6   Multiple Sector I/O       85
         4.8 MOVE Module          85
         4.9 Linking Modules into the BIOS      86


                                           vi

                              Table of Contents
                                  (continued)

       5 System Generation
           5.1 GENCPM Utility     87
           5.2 Customizing the CPMLDR     98
           5.3 CPMLDR Utility    100
           5.4 Booting CP/M 3    101

       6   Debugging the BIOS    103








                                        vii
                                  Appendixes

      A Removable Media Considerations      107

      B  Auto-density Support       109

      C  Modifying a CP/M 2 BIOS      ill     I
      D  CPM3.SYS File Format       115

      E  Root Module of Relocatable BIOS for CP/M 3    117

      F  Svstein Control Blo,,:k Definition for CP/M 3 BIOS    129

      G  Ea@@ites for Mode Byte Fields: MODEBAUD.LIR    131

      H  Macro Definitions for CP/M 3 BIOS Data Structures: CPM3.L         133

      1  A(.'S 8000-15 BIOS M(,)duies
         I.1   T3oot Loader Module for CP/M 3     137
         I.2   Character IIC) Randler for Z80 Chip-based System   140
         I.3   Drive Table       144
         I.4   Z80 DVIA Single-derisi-ty Disk Handler    144
         1.5   Bank and Move Module for CP/M Linked BIOS    152
         I.6   I/O Port Addresses for Z80 Chip-based System   153
         I.7   Sample Submit File for ASC 8000-15 System    155

      J  Public Entry Points 1.7o-r CP/M 3 Sample BIOS Modules             157

      K  Public Data Items in CP/M 3 Sample BIOS Modules .                 159

      L  CP/M 3 BIOS Function Summary     161


                                       viii
                            Tables, Figures, and Listings



        Tables

            1-1.    CP/M 3 Operating System Memory Requirements       7

            2-1.    CP/M 3 BIOS Jump Vector        16
            2-2.    CP/M 3 BIOS Functions         17
            2-3.    Initialization of Page Zero      18
            2-4.    CP/M 3 Logical Device Characteris@ics      19
            2-5.    BDOS Calls to BIOS in Nonbanked/Banked Systems .              21
            2-6.    Multiple Sector I/O in Nonbanked/Banked Systems.              22
            2-7.    Reading Two Contiguous Sectors      in Banked  System.        23

            3-1.    System Control Block Fields       29
            3-2.    Disk Parameter Header Fields      37
            3-3.    Disk Parameter Block Fields       40
            3-4.    BSH and BLM Values         42
            3-5.    Maximum EXM Values    '    -       42
            3-6.    BLS and Number of Dir;cto;y Entries      43
            3-7.    PSH and PHM Values                                            44
            3-8.    Buffer Control Block @iel@s:                                  45
            3-9.    Functional Organization of BIOS Entry Points     49
            3-10.   CP/M 3 BIOS Function Jump Table Summary      50
            3-11.   I/O Redirection Bit Vectors in SCB      54

            4-1.    CP/M 3 BIOS Module Function Summary      72
            4-2.    Public Symbols in CP/M 3 BIOS       75
            4-3.    Global Variables in BIOSKRNL.ASM       76
            4-4.    Public Utility Subroutines in BIOSKRNL.ASM     76
            4-5.    Public Names in the BIOS Jump Vector      77
            4-6.    BOOT Module Entry Points        78
            4-7.    Mode Bits       79
            4-8.    Baud Rates for seri;l'D;vices       79
            4-9.    Character Device Labels        80
            4-10.   Fields of Each XDPH. @s:       83
            4-11.   Subroutine Entry Poin       84
            4-12.   Move Module Entry Points        86

            5-1.    Sample CP/M 3 System Track      Organization      99

            C-1.    CP/M 3 BIOS Functions       ill

            D-1.    CPM3.SYS File Format       115
            D-2.    Header Record Definition      115

            K-1.    Public Data Items       159

            L-1.    BIOS Function Jump Table Summary     161





                                            ix

                          Tables, Figures, and Listings

                                    (continued)



       Figures

          1.1.    General Memory Organization of CP/M 3       4
          1-2.    Memory  Organization for Banked CP/M 3 System     5
          1-3.    memory  Organization with Bank 1 Enabled      6
          1-4.    Memory  organization in Nonbanked CP/M 3 System        .  .    7
          1-5.    Memory  Organization in Banked CP/M 3       8
          1-6.    Memory  Organization in Nonbanked CP/M 3      9
          1-7.    CP/M 3  System Disk Organization       10

          2-1.    CP/M 3  System Tracks        19

          3.1     Disk Data Structures in a Banked       System     35
          3.2     Disk Parameter Header Format       36
          3-3.    Disk Parameter Block Format       40
          3-4.    ALO and ALl          43
          3-5.    Buffer Control Block Format       44

          4-1.    XDPH Format          82

      Listings

          3-1.    SCB.ASM File          28
          3-2.    Sample Character Device Table       33
          3-3.    Equates for Mode Byte Bit Fields      34

          E-1.    Root Module of Relocatable BIOS for CP/M 3   117

          F-1.    System Control Block Definition for CP/M 3 BIOS.          .  129

          G-1.    Equates for Mode Byte Fields: MODEBAUD.LIB   131

          H-1.    Macro Definitions        133

          I-1.    Boot Loader Module for CP/M 3      137
          i-2.    Character I/O Handler for Z80 Chip-based System.          .  140
          i-3.    Drive Table . . . .    1                                     144
                  Z80 DMA Single-densi y                                    '. 144
          I-4.                            t ;isk'H;n@l;r:
          I-5.    Bank and Move Module for CP/M 3 Linked BIOS . . . .          152
          I-6.    1/0 Port Addresses for Z80 Chip-based System              .  153
          I-7.    Sample Submit File for ACS 8000-15 System. .              .  155

          J-1.    Public Entry Points       157






                                            x

                                      ection I

                     CP/M 3 Operating System Overview




             This section is an overview of the CP/M 3 operating system,
        with a description of the system components and how they relate to
        each other.      The section includes a discussion of memory
        configurations and supported hardware.  The last portion summarizes
        the creation of a customized version of the CP/M 3 Basic Input
        Output System (BIOS).

        1.1 Introduction to CP/M 3

             CP/M 3 provides an environment for program development and
        execution on computer systems that use the Intel 8080, 8085, -or ZBO
        microprocessor chip.    CP/M 3 provides rapid access to data and
        programs through a file structure that supports dynamic allocation
        of space for sequential and random access files.

             CP/M 3 supports a maximum of sixteen logical floppy or hard
        disks with a storage capacity of up to 512 megabytes each.        The
        maximum file size supported is 32 megabytes.  You can configure the
        number of directory entries and block size to satisfy various user
        needs.

             CP/M 3 is supplied in two versions.       One version supports
        nonbank-switched memory; the second version supports hardware with
        bank-switched memory capabilities.     CP/M 3 supplies additional
        facilities for the bank-switched system, including extended command
        line editing, password protection of files, and extended error
        messages.

             The nonbanked system requires 8.5 kilobytes of memory, plus
        space for your customized BIOS.   It can execute in a minimum of 32
        kilobytes of memory.

             The bank-switched system requires a minimum of two memory banks
        with 11 kilobytes of memory in Bank 0 and 1.5 kilobytes in common
        memory, plus space for your customized BIOS.      The bank-switched
        system provides more user memory for application programs.

             CP/M 3 resides in the file CPM3.SYS, which is loaded into
        memory by a system loader during system initialization.  The system
        loader resides on the first two tracks of the system disk.  CPM3.SYS
        contains the distributed BDOS and the customized BIOS.

             The CP/M 3 operating system is distributed on two single-
        density, single-sided, eight-inch floppy disks.  Digital Research
        supplies a sample BIOS that is configured for an Altos 8000-15
        microcomputer system with bank-switched memory and two single-
        density, single-sided, eight-inch floppy disk drives.

     CP/M 3 System Guide                   1.2 CP/M 3 System Components

     1.2 CP/M 3 System Components

          The CP/M 3 operating system consists of the following three
     modules: the Console Command Processor (CCP), the Basic Disk
     Operating System (BDOS), and the Basic Input Output System (BIOS).

          The CCP is a program that provides the basic user interface to
     the facilities of the operating system.  The CCP supplies six built-
     in commands: DTR, DIRS, ERASE, RENAME, TYPE, and USER.  The CCP
     executes in the Transient Program Area (TPA), the region of memory
     where all application programs execute.       The CCP contains the
     Program Loader Module, which loads transient (applications) programs
     from disk into the TPA for execution.

          The BDOS is the logical nucleus and file system of CP/M 3. The
     BDOS provides the interface between the application program and the
     physical input/output routines of the BIOS.

          The BIOS is a hardware-dependent module that interfaces the
     BDOS to a particular hardware environment.  The BIOS performs all
     physical I/O in the system.     The BIOS consists of a number of
     routines that you must configure to support the specific hardware of
     the target computer system.

          The BDOS and the BIOS modules cooperate to provide the CCP and
     othf,r transient programs with hardware-independent access to CP/M 3
     facilities.  Because the BIOS is configured for different hardware
     environments and the BDOS remains constant, you can transfer
     programs that run under CP/M 3 unchanged to systems with different
     hardware configurations.

     1.3 Communication Between t4odules

          The BIOS loads the CCP into the TPA at system cold and warm
     start.  The CCP moves the Program Loader Module to the top of the
     TPA and uses the Program Loader Module to load transient programs.

          The BDOS contains a set of functions that the CCP and
     applications programs call to perform disk and character input and
     output operations.

          The BIOS contains a Jump Table with a set of 33 entry points
     that the BDOS calls to perform hardware-dependent primitive
     functions, such as peripheral device I/O.  For example, CONIN is an
     entry point of the BIOS called by the BDOS to read the next console
     input character.








                                       2

        CP/M 3 System Guide              1.3 Communication Between Modules

             Similarities exist between the BDOS functions and the BIOS
        functions, particularly for simple device I/O.  For example, when a
        transient program makes a console output function call to the BDOS,
        the BDOS makes a console output call to the BIOS.  In the case of
        disk I/O, however, this relationship is more complex.        The BDOS
        might make many BIOS function calls to perform a single BDOS file
        1/0 function.     BDOS disk I/O is in terms of 128-byte logical
        records.  BIOS disk I/O is in terms of physical sectors and tracks.

             The System Control Block (SCB) is a 100-byte, decimal, CP/M 3
        data structure that resides in the BDOS system component.  The BDOS
        and the BIOS communicate through fields in the SCB.           The SCB
        contains BDOS flags and data, CCP flags and data, and other system
        information, such as console characteristics and the current date
        and time.  You can access some of the System Control Block fields
        from the BIOS.

             Note that the SCB contains critical system parameters which
        reflect the current state of the operating system.  If a program
        modif i es these parameters, the operating system can crash.        See
        Section 3 of this manual, and the description of BDOS Function 49 in
        the CP/M Plus Proqrammer's Guide for more information on the System
        Con rol Block.

             Page Zero is a region of memory that acts as an interface
        between transient programs and the operating system.         Page Zero
        contains critical system parameters, including   the entry to the BDOS
        and the entry to the BIOS Warm BOOT routine.  At system start-up,
        the BIOS initializes these two entry points in Page Zero.           Ali
        linkage between transient programs and the BDOS   is restricted to the
        indirect linkage through Page Zero.       Figure  1-1 illustrates the
        general memory organization of CP/M 3.








                                           3

     CP/M 3 System Guide                1.3 Communication Between Modules

        High memory:

                                      BIOS: Basic 1/0 System

        BIOS -base:



        BDOS base:                    BDOS Basic Disk Operating System


                                      LOADER: Program Leader Module
                                              Component of CCP
        LOADER-base.

                TPA                   TPA: Transient Program Area


                                      CCP: Console Command Processor

        0100H@

                                      PAGE ZERO

        OOOOH:

               Figure 1-1.  General Memory Organization of CP/M 3


          Note that all memory regions in CP/M 3 are page aligned,       which
     means that they must begin on a page boundary.  Because a page is
     defined as 256 (100H) bytes, a page boundary always begins at a
     hexadecimal address where the low-order byte of the hex address is
     zero.

     1.4 Banked and Nonbanked Systems

          CP/M 3 is supplied in two versions:        one for hardware that
     supports banked memory, and the other for hardware with a minimum of
     32 kilobytes of memory.         The systems are called banked and
     nonbanked.

          Digital Research supplies System Page Relocatable (. SPR) files
     for both a banked BDOS and a nonbanked BDOS.  A sample banked BIOS
     is supplied for you to use as an example when creating a customized
     BIOS for your set of hardware components.








                                           4

