         CP/M 3 System Guide              1.4 Banked and Nonbanked Systems


              The following figure shows the memory organization for a banked
         system.  Bank 0 and common memory are for the operating system.
         Bank 1 is the Transient Program Area, which contains the Page Zero
         region of memory.  You can use additional banks to enhance operating
         system performance.

              In banked CP/M 3 systems, CPMLDR, the system loader, loads part
         of the BDOS into common memory and part of the BDOS into Bank 0.
         CPMLDR loads the BIOS in the same manner.

              Figure 1-2 shows the memory organization for the banked version
         of CP/M 3.



             Top of memory
                                        Hardware-Dependent Buffer Space

                                O.S     Resident Operating System Modules
               Common
              to all banks



             Top of Banked
               Memory          Banked
                                 0 S.


             Bank-Sw tc@)(,d




                                                                  nhh@H



                                Bank 0         Rank 1             Bank N


              Figure 1-2.  Memory organization for Banked CP/M 3 System



              In this figure, the top region of memory is called common
         memory.   Common memory is always enabled and addressable.        The
         operating system is divided into two modules: the resident portion,
         which resides in common memory, and the banked portion, which
         resides just below common memory in Bank 0.

              The shaded areas in Figure 1-2 represent the memory available
         to transient programs.  The clear areas are used by the operating
         system for disk record buffers and directory hash tables.  The clear
         area in the common region above the operating system represents




                                             5
                                                                                AN

    CP/M 3 System Guide              1.4 Banked and Nonbanked Systems

    space that can be allocated for data buffers by GENCPM, the CP/M 3
    system generation utility.  The minimum size of the buffer area is
    determined by the specific hardware requirements of the host
    microcomputer system.

         Bank 0, the system bank, is the bank that is enabled when CP/M
    3 is cold started.  Bank 1 is the transient program bank.

         The transient program bank must be contiguous from location
    zero to the top of banked memory.      Common memory must also be
    contiguous.  The other banks need not begin at location zero or have
    contiguous memory.

         Figure 1-3 shows the CP/M 3 memory organization when the TPA
    bank, Bank 1, is enabled in a bank-switched system.


            Top of memory
                                       Hardware Dependent Buffer Space

                               O.S.    Resident Operating System Modules

                 Common


             Top of Banked
               Memory






              Low Memory
                (OOOOH)
                              Bank 1

          Figure 1-3.  Memory Organization with Bank I Enabled
                              in Banked System


         The operating system switches to Bank 0 or other banks when
    performing operating system functions.       In general, any bank
    switching performed by the operating system  is transparent to the
    calling program.

         The memory organization for the nonbanked version of CP/M 3 is
    much simpler, as shown in Figure 1-4:






                                       6

         CP/M 3 System Guide               1.4 Banked and Nonbanked Systems
                               Top of memory
                                                os.




                                 Low Memory
                                    (OOOOH)



            Figure 1-4.  Memory Organization in Nonbanked CP/M 3 System



              In the nonbanked version of CP/M 3, memory consists of a single
         contiguous region addressable from OOOOH up to a maximum of OFFFFH,
         or 64K-1.   The clear area above the operating system represents
         space that can be allocated for data buffers and directory hash
         tables by the CP/M 3 system generation utility, GENCPM, or directly
         allocated by the BIOS.    The minimum size of the buffer area is
         determined by the specific hardware requirements of the host
         microcomputer system.  Again, the shaded region represents the space
         available for transient programs.


         1.5 Memory Requirements

              Table 1-1 shows typical sizes of the CP/M 3 operating system
         components.


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

                CP/M 3 Version         Nonbanked             Banked
                                                       Common     Bank 0

              BDOS                         8.5K          1.5K      11K

              BIOS (values vary)
              floppy system                1.5K           .75K      2K
              hard system                  2.5K          1.5K       3K


              The CP/M 3 banked system requires a minimum of two banks (Bank
         0 and Bank 1) and can support up to 16 banks of memory. The size of
         the common region is often 16K, but can be as small as 4K.     Common
         memory must be large enough to contain the required buffers and the
         resident (common) portion of the operating system, which means a
         1.5K BDOS and the common part of your customized BIOS.



                                           7

     CP/M 3 System Guide                        1.5 Memory Requirements

          In a banked environment, CP/M 3 maintains a cache of deblocking
     buffers and directory records using a Least Recently Used (LRU)
     buffering scheme.  The LRU buffer is the first to be reused when the
     system runs out of buffer space.  The BDOS maintains separate buffer
     pools for directory and data record caching.

          The RSX modules shown in Figure 1-5 are Resident System
     Extensions (RSX) that are loaded directly below the operating system
     when included in an application or utility program.  The Program
     Loader places the RSX in memory and chains BDOS calls through the
     RSX entry point in the RSX.

          Figure 1-5 shows the memory organization in a typical bank-
     switched CP/M 3 system.



                                LRU DATA BUFFERS
     COMMON MEMORY
                                 RESIDENT BIOS 1K

                               RESIDENT BDOS 1.5K


      ALLOCATION/CHECKSUM        PROGRAM LOADER        LRU DATA BUFFERS
           VECTORS
                                Stacked RSX Modules    HASHED DIRECTORY
         BANKED BIOS 3K                                     TABLES
                                      TPA                (one per drive)
         BANKED BDOS 11K
                                    . . .               COPY OF CCP FOR
          LRU DIRECTORY                                   WARM START
            BUFFERS                   TPA                   (optional)

       HASHED DIRECTORY
            TABL-ES
          (one per drive)        Optional overlays

                               TRANSIENT PROGRAM
                                   PAGE ZERO
              BANK 0                 BANK 1                  BANK 2
             Figure 1-5.  Memory Organization in Banked CP/M 3
        CP/M 3 System Guide                        1.5 Memory Requirements

             The banked system supports a TPA of   60K or more. The banked
        portion of the operating system in Bank 0  requires at least 16K of
        memory.

             In the banked system, the BDOS and the BIOS are separated into
        two parts: a resident portion, and a banked portion.  The resident
        BDOS and BIOS are located in common memory.  The banked BDOS and
        BIOS are located in the operating system bank, referred to as Bank 0
        in this manual.

             The TPA extends from 100H in Bank 1 up to the bottom of the
        resident BDOS in common memory.  The banked BIOS and BDOS reside in
        Bank 0 with the directory buffers.     Typically, all data buffers
        reside in common.  Data buffers  can reside in an alternate bank if
        the system has a DMA controller   capable of transferring arbitrary
        blocks of data from one bank to another.  Hashed directory tables
        (one per drive) can be placed    in any bank except Bank 1 (TPA).
        Hashed directory tables require   4 bytes per directory entry.

             Figure 1-6 shows a typical   nonbanked system configuration.


                                Buffers and Hash Tables

                                BIOS

                                BDOS

                                PROGRAM LOADER



                                Optional overlays

                                TRANSIENT PROGRAM

                                BASE PAGE Oh-100h


                Figure 1-6.  Memory organization in Nonbanked CP/M 3


             The nonbanked CP/M 3 system requires 8.5K of memory plus space
        for the BIOS, buffers, and hash tables, allowing a TPA size of up to
        52K to 54K, depending on the size of the BIOS and the number of hash
        tables and buffers you are using.








                                            9

     CP/M 3 System Guide                          1.6 Disk Organization

     1.6 Disk Organization

          Figure 1-7 illustrates the organization of a CP/M 3 system
     disk.

                    Track M
                                  CP/M 3 Data Region
               Data Tracks
                                  CP/M 3 Directory Region
                    Track N       CCP (Optioral)

               System tracks      CPMLDR

                                  Cold Boot Loader

                    Track 0

               Figure 1-7.  CP/M 3 System Disk Organization


          In Figure 1-7, the first N tracks are the system tracks; the
     remaining tracks, the data tracks, are used by CP/M 3 for file
     storage.  Note that the system tracks are used by CP/M 3 only during
     system cold start and warm start.  All other CP/M 3 disk access is
     directed to the data tracks of the disk.  To maintain compatibility
     with Digital Research products, you should use an eight-inch,
     single-density, IBM' 3740 formatted disk with two system tracks.

     1.7 Hardware Supported

          You can customize the BIOS to match any hardware environment
     with the following general characteristics.








                                         10

        CP/M 3 System Guide                        1.7 Hardware Supported

        1.7.1 Hardware Supported by CP/M 3 Banked System

            oIntel 8080, Intel 8085, or zilog ZBO CPU or equivalent.

            aA minimum of two and up to sixteen banks of memory with the top
             4K-32K in common memory.  Bank 1 must have contiguous memory
             from address OOOOH to the base of common memory.  A reasonable
             configuration consists of two banks of 48K RAM each, with the
             top 16K in common memory.

            oone to sixteen disk drives of up to 512 megabytes capacity
             each.

            aSome form of ASCII console device, usually a CRT.

            oOne to twelve additional character input and or output devices,
             such as printers, communications hardware, and plotters.

        1.7.2 Hardware Supported by CP/M 3 Nonbanked System

            oIntel 8080, Intel 8085, or Zilog Z80 CPU or equivalent.

            oA minimum of 32K and up to 64K contiguous memory addressable
             from location zero.

            oOne to sixteen disk drives of up to 512 megabytes capacity
             each.

            oSome form of ASCII console device, usually a CRT.

            oOne to twelve additional input and or output devices, usually
             including a printer.

             Because most CP/M-compatible software is distributed on eight-
        inch, soft-sectored, single-density floppy disks, it is recommended
        that a CP/M 3 hardware configuration include a minimum of two disk
        drives, at least one of which is a single-density floppy disk drive.

        1.8 Customizing CP/M 3

             Digital Research supplies the BDOS files for a banked and a
        nonbanked version of CP/M 3. A system generation utility, GENCPM,
        is provided with CP/M 3 to create a version of the operating system
        tailored to your hardware.      GENCPM combines the BDOS and your
        customized BIOS files to create a CPM3.SYS file, which is loaded
        into memory at system start-up.  The CPM3.SYS file contains the BDOS
        and BIOS system components and information indicating where these
        modules reside in memory.

      CP/M 3 System Guide                          1.8 Customizing CP/M 3

           Digital Research supplies a CP/M 3 loader file, CPMLDR, which
      you can link with your customized loader BIOS and use to load the
      CPM3.SYS file into memory.      CPMLDR is a small, self-contained
      version of CP/M 3 that supports only console output and sequential
      file input.  Consistent with CP/M 3 organization, it contains two
      modules: an invariant CPMLDR BDOS, and a variant CPMLDR-BIOS, which
      is adapted to match the hos7t microcomputer hardware environment.
      The CPMLDR BIOS module can perform cold start initialization of I/O
      ports and similar functions.  CPMLDR can display a memory map of the
      CP/M 3 system at start-up.  This is a GENCPM option.

           The following steps tell you how to create a new version of
      CP/M 3 tailored to your specific hardware.

           1) Write and assemble a customized BIOS following the
              specif ications described in Section 3.        This software
              module must correspond to the exact physical
              characteristics of the target system, including memory and
              port addresses, peripheral types, and drive
              characteristics.

           2) Use the system generation utility, GENCPM, to create the
              CPM3.SYS file containing the CP/M 3 distributed BDOS and
              your customized BIOS, as described in Section 5.

           3) Write a customized loader BIOS (LDRBIOS) to reside on the
              system tracks as part of CPMLDR.  CPMLDR loads the CPM3.SYS
              file into memory from disk.           Section 5 gives the
              instructions for customizing the LDRBIOS and generating
              CPMLDR.    Link your customized LDRBIOS file with the
              supplied CPMLDR file.

           4) Use the COPYSYS utility to put CPMLDR on the system tracks
              of a disk.

           5) Test and debug your customized version of CP/M 3.

           If you have banked memory, Digital Research recommends that you
      first use your customized BIOS to create a nonbanked version of the
      CP/M 3 operating system.  You can leave your entire BIOS in common
      memory until you have a working system.  Test all your routines in a
      nonbanked version of CP/M 3 before you create a banked version.

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

           CP/M 3 is loaded into memory as follows.           Execution is
      initiated by a four-stage procedure.  The first stage consists of
      loading into memory a small program, called the Cold Boot Loader,
      from the system tracks of the Boot disk.  This load operation is
      typically handled L-y a hardware feature associated with system
      reset.  The Cold Boot Loader is usually 128 or 256 bytes in length.





                                          12

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

              In the second   stage, the Cold Boot Loader loads the      memory
         image of the CP/M 3  system loader program, CPMLDR, from the    system
         tracks of a disk into memory and passes control to it. For a    banked
         system, the Cold Boot Loader loads CPMLDR into Bank 0.         A PROM
         loader can perform stages one and two.

              In the third stage, CPMLDR reads the CPM3.SYS f ile, which
         contains the BDOS and customized BIOS, from the the data area   of the
         disk into the memory addresses assigned by GENCPM.        In a  banked
         system, CPMLDR reads the common part of the BDOS and BIOS into the
         common part of memory, and reads the banked part of the BDOS and
         BIOS into the area of memory below common base in Bank 0. CPMLDR
         then transfers control to the Cold BOCT system initialization
         routine in the BIOS.

              For the f inal stage, the BIOS Cold BOOT routine, BIOS Function
         0, performs any remaining necessary hardware initialization,
         displays the sign-on message, and reads the CCP from the system
         tracks or from a CCP.COM file on disk into location IOOH of the TPA.
         The Cold BOOT routine transfers control to the CCP, which then
         displays the system prompt.

              Section 2 provides an overview of the organization of the
         System Control Block and the data structures and functions in the
         CP/M 3 BIOS.

                                     End of Section 1








                                              13

                                     Section 2

                             CP/M 3 BIOS Overview



              This section describes the organization of the CP/M 3 BIDS and
          the BIDS jump vector.  It provides an overview of the System Control
          Block, followed by a discussion of system initialization procedures,
          character I/O, clock support, disk I/O, and memory selects and
          moves.

          2.1 Organization of the BIOS

              The BIDS is the CP/M 3 module that contains all hardware-
          dependent input and output routines.    To configure CP/M 3 for a
          particular hardware environment, use the sample BIOS supplied with
          this document and adapt it to the specific hardware of the target
          system.

              Alternatively, you can modify an existing CP/M 2.2 BIDS to
          install CP/M 3 on your target machine.  Note that an unmodified CP/M
          2.2 BIDS does not work with the CP/M 3 operating system.         See
          Appendix C for a description of the modifications necessary to
          convert a CP/M 2.2 BIDS to a CP/M 3 BIDS.

               The BIDS is a set of routines that performs system
          initialization, character-oriented I/O to the console and printer
          devices, and physical sector I/O to the disk devices.  The BIDS also
          contains routines that manage block moves and memory selects for
          systems with bank-switched memory.  The BIDS supplies tables that
          define the layout of the disk devices and allocate buffer space
          which the BDOS uses to perform record blocking and deblocking.  The
          BIDS can maintain the system time and date in the System Control
          Block.

               Table 2-1 describes the entry points into the BIDS from the
          Cold Start Loader and the BDOS.  Entry to the BIDS is through a jump
          vector.  The jump vector is a set of 33 jump instructions that pass
          program control to the individual BIDS subroutines.

               You must include all of the entry points in the BIDS jump
          vector in your BIDS.  However, if your system does not support some
          of the functions provided for in the BIDS, you can use empty
          subroutines for those functions.  For example, if your system does
          not support a printer, JMP LIST can reference a subroutine
          consisting of only a RET instruction.  Table 2-1 shows the elements
          of the jump vector.








                                              15

    CP/M 3 System Guide                    2.1 Organization of the BIOS

                     Table  2-1. CP/M 3 BIOS Jump Vector

        No.  Instruction  I               Description

          0  JMP BOOT       Perform cold  start initialization
          1  JMP WBOOT      Perform warm  start initialization
          2  JMP CONST      Check for console input character ready
          3  JMP CONIN      Read Console Character in
          4  JMP CONOUT     Write Console Character out
          5  JMP LIST       Write List Character out
          6  JMP AUXOUT     Write Auxiliary Output Character
          7  JMP AUXIN      Read Auxiliary Input Character
          8  JMP HOME       Move to Track 00 on Selected Disk
          9  JMP SELDSK     Select Disk Drive
        10   JMP SETTRK     Set Track Number
        11   JMP SETSEC     Set Sector Number
        12   JMP SETDMA     Set DMA Address
        13   JMP READ       Read Specified Sector
        14   JMP WRITE      Write Specified Sector
        15   JMP LISTST     Return List Status
        16   JMP SECTRN     Translate Logical to Physical Sector
        17   JMP CONOST     Return Output Status of Console
        18   JMP AUXIST     Return Input Status of Aux. Port
        19   JMP AUXOST     Return Output Status of Aux. Port
        20   JMP DEVTBL     Return Address of Char. I/O Table
        21   JMP DEVINI     Initialize Char. I/O Devices
        22   JMP DRVTBL     Return Address of Disk Drive Table
        23   JMP MULTIO     Set Number of Logically Consecutive
                            sectors to be read or written
        24   JMP FLUSH      Force Physical Buffer Flushing for
                            user-supported deblocking
        25   JMP MOVE       Memory to Memory Move
        26   JMP TIME       Time Set/Get signal
        27   JMP SELMEM     Select Bank of memory
        28   JMP SETBNK     Specify Bank for DMA Operation
        29   JMP XMOVE      Set Bank When a Buffer is in a Bank
                            other than 0 or 1
        30   JMP USERF      Reserved for System Implementor
        31   JMP RESERV1    Reserved for Future Use
        32   JMP RESERV2    Reserved for Future Use


         Each jump address in Table 2-1 corresponds to a particular
    subroutine that performs a specific system operation.  Note that two
    entry points are reserved for future versions of CP/M, and one entry
    point is provided for OEM subroutines, accessed only by direct BIOS
    calls using BDOS Function 50.  Table 2-2 shows the five categories
    of system operations and the function calls that accomplish these
    operations.








                                         16

         CP/M 3 System Guide                  2.1 Organization of the BIOS

                          Table 2-2.  CP/M 3 BIOS Functions

              Operation      Function

              System Initialization

                             BOOT, WBOOT, DEVTBL, DEVINI, DRVTBL


              Character I/O

                             CONST, CONIN, CONOUT, LIST, AUXOUT, AUXIN,
                             LISTST, CONOST, AUXIST, AUXOST

              Disk I/O       HOME, SELDSK, SETTRK, SETSEC, SETDMA,
                             READ, WRITE, SECTRN, MULTIO, FLUSH


              Memory Selects and Moves

                             MOVE, SELMEM, SETBNK, XMOVE


              Clock Support

                             TIME

              You do not need to implement every function in the BIOS jump
         vector.  However, to operate, the BDOS needs the BOOT, WBOOT, CONST,
         CONIN, CONOUT, HOME, SELDSK, SETTRK, SETSEC, SETDMA, READ, WRITE,
         SECTRN, MULTIO, and FLUSH subroutines.  Implement SELMEM and SETBNK
         only in a banked environment.  You can implement MULTIO, FLUSH, and
         TIME as returns with a zero in register A. DEVICE and some other
         utilities use the remaining entry points, but it is not necessary to
         fully implement them in order to debug and develop the system.

         Note: include all routines but make the nonimplemented routines a
         RET instruction.

         2.2 System Control Block

              The System Control Block (SCB) is a data structure located in
         the BDOS.  The SCB is a communications area referenced by the BDOS,
         the CCP, the BIOS, and other system components.  The SCB contains
         system parameters and variables, some of which the BIOS can
         reference.   The fields of the SCB are named, and definitions of
         these names are supplied as public variable and subroutine names in
         the SCB.ASM file contained on the distribution disk.  See Section
         3.1 for a discussion of the System Control Block.




                                            17

     CP/M 3 System Guide                       2.3 System Initialization

     2.3 System Initialization

          When the BOOT and WBOOT routines of the BIOS get control, they
     must initialize two system parameters in Page Zero of memory, as
     shown in Table 2-3.

                    Table 2-3.  Initialization of Page Zero

          Location  I                 Description

             0,1,2   Set to JMP WBOOT (OOOOH: JMP BIOS+3). Location
                     1 and 2 must contain the address of WBOOT in
                     the jump vector.

             5,6,7   Set to JMP BDOS, the primary entry point to
                     CP/M 3 for transient programs.       The current
                     address of the BDOS is maintained in the
                     variable @MXTPA in the System Control Block.
                     (See Section 3.1, "System Control Block," and
                     BIOS Function 1: WBOOT on page 52.)

          The BOOT and WBOOT routine must load the CCP into the TPA in
     Bank I at location 0100H.   The CCP can be loaded in two ways.       If
     there is sufficient space on the system tracks, the CCP can be
     stored on the system tracks and loaded from there.  If you prefer,
     or if there is not sufficient space on the system tracks, the BIOS
     Cold BOOT routine can read the CCP into memory from the file CCP.COM
     on disk.

          If the CCP is in a COM file, use the BOOT and WBOOT routines
     to perform any necessary system initialization, then use the BDOS
     functions to OPEN and READ the CCP.COM file into the TPA.  In bank-
     switched systems, the CCP must be read into the TPA in Bank 1.

          In bank-switched systems, your Cold BOOT routine can place a
     copy of the CCP into a reserved area of an alternate bank after
     loading the CCP into the TPA in Bank 1. Then the Warm BOOT routine
     can copy the CCP into the TPA in Bank 1 from the alternate bank,
     rather than reloading the CCP from disk, thus avoiding all disk
     accesses during warm starts.

          There is a 128-byte buffer in the resident portion of the BDOS
     in a banked system that can be used by BOOT and WBOOT.  The address
     of this buffer is stored in the SCB variable @BNKBF.  BOOT and WBOOT
     can use this buffer when copying the CCP to and from the alternate
     bank.

          The system tracks for CP/M 3 are usually partitioned as shown
     in the following figure;

         CP/M 3 System Guide                      2.3 System Initialization


                    Cold              CPMLDR       I         CCP
                   StEiti Lor                      I


                          Figure 2-1.  CP/M 3 System Tracks


              The cold start procedure is designed so you need to initialize
         the system tracks only once.  This is possible because the system
         tracks contain the system loader and need not change when you change
         the CP/M 3 operating system.  The Cold Start Loader loads CPMLDR
         into a constant memory location that is chosen when the system is
         configured.    However , CPMLDR loads the BDOS and BIOS system
         components into memory as specified in the CPM3.SYS file generated
         by GENCPM, the system generation utility.  Thus, CP/M 3 allows the
         user to configure a new system with GENCPM and then run it without
         having to update the system tracks of the system disk.

         2.4 Character 1/0

              CP/M 3 assumes that all simple character I/O operations are
         performed in 8-bit ASCII, upper- and lowercase, with no parity.  An
         ASCII CRTL-Z (lAH) denotes an end-of-file condition for an input
         device.

              Table 2-4 lists the characteristics of the logical devices.

                   Table 2-4.  CP/M 3 Logical Device Characteristics

                   Device                    Characteristics

              CONIN, CONOUT       T h e interactive console that
                                  communicates with the operator,
                                  accessed by CONST, CONIN, CONOUT, and
                                  CONOUTST.  Typically, the CONSOLE is a
                                  device such as a CRT or teletype,
                                  interfaced serially, but it can also
                                  be a memory-mapped video display and
                                  keyboard.  The console is an input
                                  device and an output device.

               LIST               The system printer, if it exists on
                                  your system.  LIST is usually a hard-
                                  copy device such as a printer or
                                  teletypewriter.

              AUXOUT              The auxiliary character output device,
                                  such as a modem.

               AUXIN              The auxiliary character input device,
                                  such as a modem.




                                              19

    CP/M 3 System Guide                                  2.4 Character I/O

          Note that you can define a single peripheral as the LIST,
    AUXOUT, and AUXIN device simultaneously.              If you assign no
    peripheral device as the LIST, AUXOUT, or AUXIN device, the AUXOUT
    and LIST routines can just return, and the AUXIN routine can return
    with a 1AH (CTRL-Z) in register A to indicate an immediate end-of-
    file.

          CP/M 3 supports character device I/O redirection.  This means
    that you can direct a logical device, such as CONIN or AUXOUT, to
    one or more physical devices.       The DEVICE utility allows you to
    reassign devices and display, and to change the current device
    configurations, as described in the CP/M Plus User's Guide.  The I/O
    redirection facility is optional.  You should not implement it until
    the rest of your BIOS is fully functional.

    2.5 Disk I/O

          The BDOS accomplishes disk I/O by making a sequence of calls to
    the various disk access subroutines in the BIOS.  The subroutines
    set up the disk number to access, the track and sector on a
    particular disk, and the Direct Memory Access (DMA) address and bank
    involved in the I/O operation.            After these parameters are
    established, the BDOS calls the READ or WRITE function to perform
    the actual I/O operation.

          Note that the BDOS can make a single call to SELDSK to select a
    disk drive, follow it with a number of read or write operations to
    the selected disk, and then select another drive for subsequent
    operations.

          CP/M 3 supports multiple sector read or write operations to
    optimize rotational latency on block disk transfers.             You can
    implement the multiple sector I/O facility in the BIOS by using the
    multisector count passed to the MULTIO entry point.  The BDOS calls
    MULTIO to read or write up to 128 sectors.  For every sector number
    1 to n, the BDOS calls SETDMA then calls READ or WRITE.

          Table 2-5 shows the sequence of BIOS calls that the BDOS makes
    to read or write a physical disk sector in a nonbanked and a banked
    system.  Table 2-6 shows the sequence of calls the BDOS makes to the
    BIOS to read or write multiple contiguous physical sectors in a
    nonbanked and banked system.








                                           20

        CP/M 3 System Guide                                   2.5 Disk I/O

         Table 2-5.  BDOS Calls to BIOS in Nonbanked and Banked Systems

                                  Nonbanked BDOS

                Call                         Explanation

             SELDSK          Called only when disk is initially
                             selected or reselected.

             SETTRK          Called for every read or write of a
                             physical sector.

             SETSEC          Called for every read or write of a
                             physical sector.

             SETDMA          Called for every read or write of a
                             physical sector.

             READ, WRITE     Called for every read or write of a
                             physical sector.

                                    Banked EDOS

             SELDSK          Called only when disk is initially
                             selected or reselected.

             SETTRK          Called for every read or write of a
                             physical sector.

             SETSEC          Called for every read or write of a
                             physical sector.

             SETDMA          Called for every read or write of a
                             physical sector.

             SETBNK          Called for every read or write of a
                             physical sector.

             READ, WRITE     Called for every read or write of a
                             physical sector.








                                            21

     CP/M 3 System Guide                                    2.5 Disk I/O

      Table 2-6.  Multiple Sector I/O in Nonbanked and Banked Systems

                               Nonbanked BDOS

             Call                          Explanation

          SELDSK          Called only when disk is initially
                          selected or reselected.

          MULTIO          Called to inform the BIOS that the next n
                          calls to disk READ or disk WRITE require a
                          transfer of n contiguous physical sectors
                          to contiguous memory.

          SETTRK          Called for every read or write of a
                          physical sector.

          SETSEC          Called for every read or write of a
                          physical sector.

          SETDMA          Called for every read or write of a
                          physical sector.

          READ, WRITE     Called for every read or write of a
                          physical sector.

                                 Banked BDOS

          SELDSK          Called only when disk is initially
                          selected or reselected.

          MULTIO          Called to inform the BIOS that the next n
                          calls to disk READ or disk WRITE require a
                          transfer of n contiguous physical sectors
                          to contiguous memory.

          SETTRK          Called for every read or write of a
                          physical sector.

          SETSEC          Called for every read or write of a
                          physical sector.

          SETDMA          Called for every read or write of a
                          physical sector.

          SETBNK          Called for every read or write of a
                          physical sector.

          READ, WRITE     Called for every read or write of a
                          physical sector.








                                          22

         CP/M 3 System Guide                                   2.5 Disk I/O

              Table 2-7 shows the sequence of BDOS calls to read two
         contiguous physical sectors in a banked system.

           Table 2-7.  Reading Two Contiguous Sectors in Banked System

                   Call                    Explanation

                  SELDSK          Called to initially select disk
                  MULTIO          With a value of 2
                  SETTRK          For first sector
                  SETSEC          For first sector
                  SETDMA          For first sector
                  SETBNK
                  READ
                  SETTRK          For second sector
                  SETSEC          For second sector
                  SETDMA          For second sector
                  SETBNK
                  READ


              The CP/M 3 BDOS performs its own blocking and deblocking of
         logical 128-byte records.  Unlike earlier versions of CP/M, the BIOS
         READ and WRITE routines always transfer physical sectors as
         specified in the Disk Parameter Block to or from the DMA buffer.
         The Disk Parameter Header defines one or more physical sector
         buffers which the BDOS uses for logical record blocking and
         deblocking.

              In a banked environment, CP/M 3 maintains a cache of deblocking
         buf fers and directory records using a Least Recently Used (LRU)
         buffering scheme.  The LRU buffer is the first to be reused when the
         system runs out of buffer space.  The BDOS maintains separate buffer
         pools for directory and data record caching.

              The BIOS contains the data structures to control the data and
         directory buffers and the hash tables.  You can either assign these
         buffers and tables yourself in the BIOS, or allow the GENCPM utility
         to generate them automatically.

              Hash tables greatly speed directory searching.  The BDOS can
         use hash tables to determine the location of directory entries and
         therefore reduce the number of disk accesses required to read a
         directory entry.  The hash table allows the BDOS to directly access
         the sector of the directory containing the desired directory entry
         without having to read the directory sequentially.  By eliminating a
         sequential read of the directory records, hashing also increases the
         percentage of time that the desired directory record is in a buffer,
         eliminating the need for any physical disk accesses in these cases.
         Hash tables and directory caches eliminate many of the directory
         accesses required when accessing large files.        However, in a
         nonbanked system, hash tables increase the size of the operating
         system.



                                            23

     CP/M 3 System Guide                                   2.5 Disk I/O

          When the BIOS finds an error condition, the READ and WRITE
     routines should perform several retries before reporting the error
     condition to the BDOS.    Ten retries are typical.     If the BIOS
     returns an error condition to the BDOS, the BDOS reports the error
     to the user in the following form:

             CP/M Error on d: Disk I/O

     The d: represents the drive specification of the relevant drive.

          To provide better diagnostic capabilities for the user, it is
     often desirable to print a more explicit error message from the BIOS
     READ or WRITE routines before the BIOS returns an error code to the
     BDOS.  The BIOS should interrogate the SCB Error Mode Variable to
     determine if it is appropriate to print a message on the console.

     2.6 Memory Selects and Moves

          Four BIOS functions are provided to perform memory management.
     The functions are MOVE, XMOVE, SELMEM, and SETBNK.       The XMOVE,
     SELMEM, and SETBNK memory management routines are applicable to the
     BIOS of banked systems.

          The BDOS uses the BIOS MOVE routine to perform memory-to-memory
     block transfers.    In a banked system, the BDOS calls XMOVE to
     specify the source and destination banks to be used by the MOVE
     routine. If you use memory that is not in the common area for data
     record buffers, you must implement the XMOVE routine.

          The BDOS uses SELMEM when the operating system needs to execute
     code or access data in other than the currently selected bank.

          The BDOS calls the SETBNK routine prior to calling disk READ or
     disk WRITE functions.  The SETBNK routine must save its specified
     bank as the DMA bank.  When the BDOS invokes a disk I/O routine, the
     I/O routine should save the current bank number and select the DMA
     bank prior to the disk READ or WRITE.  After completion of the disk
     READ or WRITE, the disk I/O routine must reselect the current bank.
     Note that when the BDOS calls the disk I/O routines, Bank 0 is in
     context (selected).

     2.7 Clock Support

          If the system  has a real-time clock or is capable of keeping
     time, possibly by  counting interrupts from a counter/timer chip,
     then the BIOS can maintain the time of day in the System Control
     Block and update the time on clock interrupts.  BIOS Function 26 is
     provided for those systems where the clock is unable to generate an
     interrupt.








                                         24

         CP/M 3 System Guide                              2.7 Clock Support

              The time of day is kept as four fields. @DATE is a binary word
         containing the number of days since 31 December 1977.  The bytes
         @HOUR, @MIN, and @SEC in the System Control Block contain the hour,
         minute, and second in Binary Coded Decimal (BCD) format.

                                    End of Section 2








        Al
                                            25
                                      Section 3

                     CP/M 3 BIOS Functional Specifications



              This section contains a detailed description of the CP/M 3
         BIOS    The section first discusses the BIOS data structures and
         their relationships, including the System Control Block, the drive
         table, the Disk Parameter Header, the Disk Parameter Block, the
         Buffer Control Blocks, and the character I/O table.  The overview of
         the data structures is followed by a summary of the functions in the
         BIOS jump vector.  A detailed description of the entry values and
         returned values for each jump instruction in the BIOS jump vector
         follows the summary.  The last part of this section discusses the
         steps to follow when assembling and linking your customized BIOS.

         3.1 The System  Control Block

              The System Control Block (SCB) is a data structure located in
         the BDOS.   The SCB contains flags and data used by the CCP, the
         BDOS, the BIOS,  and other system components. The BIOS can access
         specif ic data   in the System Control Block through the public
         variables defined in the SCB.ASM file, which is supplied on the
         distribution disk.

              Declare the variable names you want to reference in the SCB as
         externals in your BIOS.ASM source file.  Then link your BIOS with
         the SCB.REL module.

              In the SCB.ASM file, the high-order byte of the various SCB
         addresses is defined as OFEH.  The linker marks absolute external
         equates as page relocatable when generating a System Page
         Relocatable (SPR) format file.  GENCPM recognizes page relocatable
         addresses of OFExxH as references to the System Control Block in the
         BDOS.  GENCPM changes these addresses to point to the actual SCB in
         the BDOS when it is relocating the system.

              Do not perform assembly-time arithmetic on any references to
         the external labels of the SCB.  The result of the arithmetic could
         alter the page value to something other than OFEH.

              Listing 3-1 shows the SCB.ASM file.     The listing shows the
         f ield names of the System Control Block.       A @ before a name
         indicates that it is a data item.  A ? preceding a name indicates
         that it is the label of an instruction.   In the listing, r/w means
         Read-Write, and r/o means Read-Only.  The BIOS can modify a Read-
         Write variable, but must not modify a Read-Only variable.  Table 3-1
         describes each item in the System Control Block in detail.








                                            27

    CP/M 3 System Guide                         3.1 System Control Block

             title 'System Control Block Definition for CP/M3 BIOS'

             public @civec, @covec, @aivec, @aovec, @lovec, @bnkbf
             public @crdma, @crdsk, @vinfo, @resel, @fx, @usrcd
             public @mltio, @ermde, @erdsk, @media, @bflgs
             public @date, @hour, @min, @sec, ?erjmp, @mxtpa

    scb$base equ      OFEOOH            ; Base of the SCB

    @CIVEC equ        scb$base+22h      ; Console Input Redirection
                                        ; Vector (word, r/w)
    @COVEC   equ      scb$base+24h      ; Console Output Redirection
                                          Vector (word, r/w)
    @AIVEC   equ      scb$base+26h      ; Auxiliary Input Redirection
                                        ; Vector (word, r/w)
    @AOVEC   equ      scb$base+28h      ; Auxiliary Output Redirection
                                        ; Vector (word, r/w)
    @LOVEC   equ      scb$base+2Ah      ; List Output Redirection
                                        ; Vector (word, r/w)
    @BNKBF   equ      scb$base+35h      ; Address of 128 Byte Buffer
                                        ; for Banked BIOS (word, r/o)
    @CRDMA   equ      scb$base+3Ch      ; Current DMA Address
                                        ; (word, r/o)
    @CRDSK   equ      scb$base+3Eh      ; Current Disk (byte, r/o)
    @VINFO   equ      scb$base+3Fh      ; BDOS Variable "INFO"
                                        ; (word, r/o)
    @RESEL   equ      scb$base+41h      ; FCB Flag (byte, r/o)
    @FX      equ      scb$base+43h      ; BDOS Function for Error
                                        ; Messages (byte, r/o)
    @USRCD   equ      scb$base+44h      ; Current User Code (byte, r/o)
    @MLTIO   equ      scb$base+4Ah      ; Current Multisector Count
                                        ; (byte,r/w)
    @ERMDE   equ      scb$base+4Bh      ; BDOS Error Mode (byte, r/o)
    @ERDSK   equ      scb$base+51h      ; BDOS Error Disk (byte, r/o)
    @MEDIA   equ      scb$base+54h      ; Set by BIOS to indicate
                                        ; open door (byte,r/w)
    @BFLGS   equ      scb$base+57h      ; BDOS Message Size Flag
                                        ; (byte,r/o)
    @DATE    equ      scb$base+58h      ; Date in Days Since 1 Jan 78
                                        ; (word, r/w)
    @HOUR    equ      scb$base+5Ah      ; Hour in BCD (byte, r/w)
    @MIN     equ      scb$base+5Bh      ; Minute in BCD (byte, r/w)
    @SEC     equ      scb$base+5Ch      ; Second in BCD (byte, r/w)
    ?ERJMP   equ      scb$base+5Fh      ; BDOS Error Message Jump
                                        ; (3 bytes, r/w)
    @MXTPA   equ      scb$base+62h      ; Top of User TPA
                                        ; (address at 6,7)(word, r/o)
             end

                           Listing 3-1.  SCB.ASK File







                                          2 8

        CP/M 3 System Guide                       3.1 System Control Block

              The following table describes in detail each of the fields of
        the System Control Block.

                       Table 3-1.  System Control Block Fields

              Field     Meaning

              @CIVEC, @COVEC, @AIVEC, @AOVEC, @LOVEC (Read-Write
              Variable)

                        These fields are the 16 bit I/O redirection
                        vectors for the five logical devices:    console
                        input, console output, auxiliary input,
                        auxiliary output, and the list device. (See
                        Section 3.4.2, "Character I/O Functions.")

              @BNKBF (Read-Only Variable)

                        @BNKBF contains the address of a 128 byte
                        buffer in the resident portion of the BDOS in a
                        banked system.  This buffer is available for
                        use during BOOT and WBOOT only.  You can use it
                        to transfer a copy of the CCP from an image in
                        an alternate bank if the system does not
                        support interbank moves.

              @CRDMA, @FX, @USRCD, @ERDSK (Read-Only Variable)

                        These variables contain the current DMA
                        address, the BDOS function number, the current
                        user code, and the disk code of the drive on
                        which the last error occurred.     They can be
                        displayed when a BDOS error is intercepted by
                        the BIOS.  See ?ERJMP.

              @CRDSK (Read-Only Variable)

                        @CRDSK is the current default drive, set by
                        BDOS Function 14.

              @VINFO, @RESEL (Read-Only Variable)

                        If @RESEL is equal to OFFH then @VINFO contains
                        the address of a valid FCB.  If @RESEL is not
                        equal to OFFH, then @VINFO is undefined.  You
                        can use @VINFO to display the filespec when the
                        BIOS intercepts a BDOS error.







                                            29

    CP/M 3 System Guide                          3.1 System Control Block

                             Table 3-1. (continued)

          Field       Meaning

          @MLTIO    (Read-Write Variable)

                      @MLTIO contains the current multisector count.
                      The BIOS can change the multisector count
                      directly, or through BDOS Function 44.         The
                      value of the multisector count can range from 1
                      to 128.

          @ERMDE (Read-Only Variable)

                      @ERMDE contains the current BDOS error mode.
                      OFFH indicates the BDOS is returning error
                      codes to the application program without
                      displaying any error messages.  OFEH indicates
                      the BDOS is both displaying and returning
                      errors.  Any other value indicates the BDOS is
                      displaying errors without notifying the
                      application program.

          @MEDIA (Read-Write Variable)

                      @MEDIA is global system flag indicating that a
                      drive door has been opened.  The BIOS routine
                      that detects the open drive door sets this flag
                      to OFFH.  The BIOS routine also sets the MEDIA
                      byte in  the Disk Parameter Header associated
                      with the open-door drive to OFFH.

          @BFLGS (Read-Only Variable)

                      The BDOS in CP/M 3 produces two kinds of error
                      messages:   short error messages and extended
                      error messages.  Short error messages display
                      one or two lines of text.  Long error messages
                      display a third line of text containing the
                      filename, filetype, and BDOS Function Number
                      involved in the error.

                      In banked systems, GENCPM sets this flag in the
                      System Control Block to indicate whether the
                      BIOS displays short or extended error messages.
                      Your error message handler should check this
                      byte in the System Control Block.  If the high-
                      order bit, bit 7, is set to 0, the BDOS
                      displays short error messages. if the high-
                      order bit is set to 1, the BDOS displays the
                      extended three-line error messages.





                                           30

       CP/M 3 System Guide                         3.1 System Control Block

                               Table 3-1. (continued)

             Field      Meaning

             @BFLGS (continued)

                        For example, the BDOS displays the following
                        error message if the BIOS returns an error from
                        READ and the BDOS is displaying long error
                        messages.

                             CP/M Error on d: Disk I/O
                             BDOS Function = nn     File = filename.typ

                        In the above error message, Function nn and
                        filename.typ represent BDOS function number and
                        file specification involved, respectively.

             @DATE (Read-Write Variable)

                        The number of days since 31 December 1977,
                        expressed as a 16-bit unsigned integer, low
                        byte first.   A real-time clock interrupt can
                        update the @DATE field to indicate the current
                        date.

             @HOUR, @MIN, @SEC (Read-Write Variable)

                        These 2-digit Binary Coded Decimal (BCD) fields
                        indicate the current hour, minute, and second
                        if updated by a real-time clock interrupt.

             ?ERJMP (Read-Write Code Label)

                        The BDOS calls the error message subroutine
                        through this jump instruction.       Register C
                        contains an error code as follows:

                             1    Permanent Error
                             2    Read Only Disk
                             3    Read Only File
                             4    Select Error
                             7    Password Error
                             8    File Exists
                             9    ? in Filename

                        Error code 1 above results in the BDOS message
                        Disk I/O.






                                            31

     CP/M 3 System Guide                       3.1 System Control Block

                            Table 3-1. (continued)

          Field      Meaning

          ?ERJMP (continued)

                     The ?ERJMP vector allows the BIOS to intercept
                     the BDOS error messages so you can display them
                     in a foreign language.  Note that this vector
                     is not branched to if the application program
                     is expecting return codes on physical errors.
                     Refer to the CP/M Plus Programmer's Guide for
                     more information.

                     ?ERJMP is set to point to the default (English)
                     error message routine contained in the BDOS.
                     The BOOT routine can modify the address at
                     ?ERJMP+L to point to an alternate message
                     routine.  Your error message handler can refer
                     to @FX, @VINFO (if @RESEL is equal to OFFH),
                     @CRDMA, @CRDSK, and @USRCD to print additional
                     error information.  Your error handler should
                     return to the BDOS with a RET instruction after
                     printing the appropriate message.

           @MXTPA (Read-Only Variable)

                     @MXTPA contains the address of the current BDOS
                     entry point.  This is also the address of the
                     top of the TPA.  The BOOT and WBOOT routines of
                     the BIOS must use this address to initialize
                     the BDOS entry JMP instruction at location
                     005H, during system initialization.  Each time
                     a RSX is loaded, @MXTPA is adjusted by the
                     system to reflect the change in the available
                     User Memory (TPA).


      3.2 Character I/O Data Structures

           TheBIOS data structure CHRTBL is a character table describing
      the physical I/O devices.  CHRTBL contains 6-byte physical device
      names and the characteristics of each physical device.         These
      characteristics include a mode byte, and the current baud rate, if
      any, of the device.    The DEVICE utility references the physical
      devices through the names and attributes contained in your CHRTBL.
      DEVICE can also display the physical names and characteristics in
      your CHRTBL.

           The mode byte specifies whether the device is an input or
      output device, whether it has a selectable baud rate, whether it is
      a serial device, and if XON/XOFF protocol is enabled.





                                          32

          CP/M 3 System Guide                3.2 Character I/O Data Structures

               Listing 3-2 shows a sample character device table that the
          DEVICE utility uses to set and display I/O direction.


                   .; sample character device table

          chrtbl   db  'CRT    I               ; console VDT
                   db  mb$in$out+mb$serial+mb$soft$baud
                   db  baud$9600

                   db  'LPT    I               ; system serial printer
                   db  mb$output+mb$serial+mb$soft$baud+mb$xon
                   db  baud$9600

                   db  'TI810 '                ; alternate printer
                   db  mb$output+mb$serial+mb$soft$baud
                   db  baud$9600

                   db  'MODEM '                ; 300 baud modem port
                   db  mb$in$out+mb$serial+mb$soft$baud
                   db  baud$300

                   db  'VAX    I               ; interface to VAX 11/780
                   db  mb$in$out+mb$serial+mb$soft$baud
                   db  baud$9600

                   db  'DIABLO'                 Diablo 630 daisy wheel printer
                   db  mb$output+mb$serial+mb$soft$baud+mb$xon$xoff
                   db  baud$1200

                   db  'CEN    I               ; Centronics type parallel printer
                   db  mb$output
                   db  baud$none

                   db  0                       ; table terminator

                       Listing 3-2.  Sample Character Device Table


               Listing 3-3 shows the equates for the fields contained in the
          sample character device table.  Many systems do not support all of
          these baud rates.








                                                33

      CP/M 3 System Guide              3.2 Character I/O Data Structures

             ; equates for mode byte fields

      mb$input                  equ  0000$000lb ; device may do input
      mb$output                 equ  0000$0010b ; device may do output
      mb$in$out                 equ  mb$input+mb$output ; dev may do both
      mb$soft$baud              equ  0000$0100b   ; software selectable
                                                  ; baud rates
      mb$serial                 equ  0000$1000b   ; device may use protocol
      mb$xon$xoff               equ  0001$0000b   ; XON/XOFF protocol
                                                  ; enabled

               equates for baud rate byte

      baud$none                 equ  0            ; no baud rate
                                                  ; associated with device
      baud$50                   equ  1            ; 50 baud
      baud$75                   equ  2            ; 75 baud
      baud$110                  equ  3            ; 110 baud
      baud$134                  equ  4            ; 134.5 baud
      baud$150                  equ  5            ; 150 baud
      baud$300                  equ  6            ; 300 baud
      baud$600                  equ  7            ; 600 baud
      baud$1200                 equ  8            ; 1200 baud
      baud$1800                 equ  9            ; 1800 baud
      baud$2400                 equ  10           ; 2400 baud
      baud$3600                 equ  11           ; 3600 baud
      baud$4800                 equ  12           ; 4800 baud
      baud$7200                 equ  13           ; 7200 baud
      baud$9600                 equ  14           ; 9600 baud
      baud$19200                equ  15           ; 19.2k baud

                 Listing 3-3. Equates for Mode      Byte Bit Fields


      3.3 BIOS Disk Data Structures

           The BIOS includes tables that describe the particular
      characteristics of the disk subsystem used with CP/M 3.             This
      section describes the elements of these tables.

           In general, each disk drive has an associated Disk Parameter
      Header (DPH) that contains information about the disk drive and
      provides a scratche>ad area for certain BDOS operations.  One of the
      elements of this Disk Parameter Header is a pointer to the Disk
      Parameter Block (DPB), which contains the actual disk description.

           In the banked system, only the Disk Parameter Block must reside
      in common memory.  The DPHS, checksum vectors, allocation vectors,
      Buffer Control Blocks, and Directory Buffers can reside in common
      memory or Bank 0. The hash tables can reside in common memory or
      any bank except Bank 1.        The data buffers can reside in banked
      memory if you implement the XMOVE function.



                                            34

             CP/M 3 System Guide                                                 3.3 BIOS Data Structures

                      Figure 3-1 shows the relationships between the drive table, the
             Disk Parameter Header, and the Data and Directory Buffer Control
             Block fields and their respective data structures and buffers.

                         Drive Table @addresses of DPHS)

               L I I I                           ......      1-1
               0      1     2      3      4                 15
                                                                                  C@ecksum Vector

                                                                                     Allocation Vector


                                                                                                   Hash Table


                      Dis k Parameter Header                  I
                                                                 I DIR DTA
                     XLT                  MF            3V  ALV BCB BCB







                          Buffer Control Block (BCB)                                             BCB

                                            Buf f                                                    Buff
                                            addr                                                     addr


                                 Directory Buffer                       Li                  Data Buffer




                                       BCB                                                      BCB

                                            Buff                                                     Buff rl
                                            addr                                                     add
                                                                                                       I

                L                Directory  Buffer                      Li                  Data Buffer




                           BCB                                                     BCB

                                            Buff                                                     Buff
                                            addr                                                     addr

                                                                        L
                                 Directory  Buffer                                          Data Buffer


                          Figure 3-1. Disk Data Structures in a                             Banked System




                                                                        35

     CP/M 3 System Guide                        3.3 BIOS Data Structures


     3.3.1 Drive Table

          The drive table consists of 16 words containing the addresses
     of the Disk Parameter Headers for each logical drive name, A through
     P, and takes the general form:


             drivetable  dw     dpho
                         dw     dphl
                         dw     dph2


                         @w     dphf


     If a logical drive does not exist in your system, the corresponding
     entry in the drive table must be zero.

          The GENCPM utility accesses the drive table to locate the
     various disk parameter data structures, so that it can determine
     which system configuration to use, and optionally allocate the
     various buffers itself.  You must supply a drive table if you want
     GENCPM to do this allocation.     If certain addresses in the Disk
     Parameter Headers referenced by this drive table are set to OFFFEH,
     GENCPM allocates the appropriate data structures and updates the
     DPH.  You can supply the drive table even if you have performed your
     own memory allocation.  See the BIOS DRVTBL function described in
     Section 3.4.1.

     3.3.2 Disk Parameter Header

          In Figure 3-2, which shows the format of the Disk Parameter
     Header, b refers to bits.


         XLT   -0-  MF DPB         ALV   DIRBCB  DTABCB   HASH HBANK.

         16b   72b  Bb   16bI 16b   16b    16b     16b     16b    8b


                   Figure 3-2.  Disk PiLrameter Header Format



           Table 3-2 describes the fields of the Disk Parameter Header.








                                          36

        CP/M 3 System Guide                       3.3 BIOS Data Structures

                      Table 3-2.   Disk Parameter Header Fields

           Field                           Comments

            XLT       Set the XLT field to the address of the logical to
                      physical sector translation table.  If there is no
                      sector translation and the    logical and physical
                      sector numbers are the same, set XLT to OOOOH. Disk
                      drives with identical sector skew factors can share
                      the same translation table.

                      XLT is the value passed to SECTRN in registers DE.
                      Usually the translation table consists of one byte
                      per physical sector.  Generally, it is advisable to
                      keep the number of physical sectors per logical
                      track to a reasonable value to prevent the
                      translation table from becoming too large.  In the
                      case of disks with multiple heads, you can compute
                      the head number from the track address rather than
                      the sector address.

            -0-       These 72 bits (9 bytes) of zeroes are the scratch
                      area the BDOS uses to maintain various parameters
                      associated with the drive.

            MF        MF is the Media Flag. The BDOS resets MF to zero
                      when the drive is logged in.  The BIOS can set this
                      flag and @MEDIA in the SCB to OFFH if it detects
                      that a drive door has been opened.  If the flag is
                      set to OFFH, the BDOS checks for a media change
                      prior to performing the next BDOS file operation on
                      that dr i.ve. If the BDOS determines that the drive
                      contains a new volume, the BDOS performs a login on
                      that drive, and resets the MF flag to OOH.  Note
                      that the BDOS checks this flag only when a system
                      call is made, and not during an operation.
                      Usually, this flag is used only by systems that
                      support door-open interrupts.

            DPB       Set the DPB f ield to the address of a Disk
                      Parameter Block that describes the characteristics
                      of the disk drive.  Several Disk Parameter Headers
                      can address the same Disk Parameter Block if their
                      drive characteristics are identical.       (The Disk
                      Parameter Block is described in Section 3.3.3.)








                                             37

    CP/M 3 System Guide                          3.3 BIOS Data Structures

                           Table 3-2. (continued)

        Field                           Comments

         csv       CSV is the address of a scratchpad area used to
                   detect changed disks.        This address must be
                   different for each removable media Disk Parameter
                   Header.    There must be one byte for every 4
                   directory entries (or 128 bytes of directory).  In
                   other words, length(CSV) = (DRM/4)+l. (See Table
                   3-3 for an explanation of the DRM field.) If the
                   drive is permanently mounted, set the CKS variable
                   in the DPB to 8000H and set CSV to OOOOH.         This
                   way, no storage is reserved for a checksum vector.
                   The checksum vector may be located in common memory
                   or in Bank 0. Set CSV to OFFFEH for GENCPM to set
                   up the checksum vector.

         ALV       ALV is the address of the scratchpad area called
                   the allocation vector, which the BDOS uses to keep
                   disk storage allocation information.       This area
                   must be unique for each drive.

                   The allocation vector usually requires 2 bits for
                   each block on the drive.        Thus, length(ALV) =
                   (DSM/4) + 2.   (See Table 3-3 for an explanation of
                   the DSM field.) In the nonbanked version of CP/M
                   3, you can optionally specify that GENCPM reserve
                   only one bit in the allocation vector per block on
                   the drive.  In this case, length(ALV) = (DSM/8) +
                   1.                                                             I

                   The GENCPM option to use single-bit allocation
                   vectors is provided in the nonbanked version of
                   CP/M 3 because additional memory is required by the
                   double-bit allocation vector.  This option applies
                   to all drives on the system.

                   With double-bit allocation vectors, CP/M 3
                   automatically frees, at every system warm start,
                   all file blocks that are not permanently recorded
                   in the directory.  Note that file space allocated
                   to a f ile is not permanently recorded in a
                   directory unless the file is closed.  Therefore,
                   the allocation vectors in memory can indicate that
                   space is allocated although directory records
                   indicate that space is free for allocation.  With
                   single-bit allocation vectors, CP/M 3 requires that
                   a drive be      reset before this space can be
                   reclaimed.  Because it increases performance, CP/M
                   3 does not reset disks at system warm start.  Thus,
                   with single-bit allocation vectors, if you do not
                   reset the disk system, DIR and SHOW can report an
                   inaccurate amount of free space.  With single-bit




                                          38

         CP/M 3 System Guide                        3.3 BIOS Data Structures

                               Table 3-2. (continued)

            Field    I                     Comments

             ALV       allocation vectors, the user must type a CTRL-C at
         (continued)   the system prompt to reset the disk system to ensure
                       accurate reporting of free space.        Set ALV to
                       OFFFEH for GENCPM to automatically assign space
                       for the allocation vector, single- or double-bit,
                       during system generation.  In the nonbanked system,
                       GENCPM prompts for the type of allocation vector.
                       In the banked system, the allocation vector is
                       always double-bit and can reside in common memory
                       or Bank 0. When GENCPM automatically assigns space
                       for the allocation vector (ALV = OFFFEH) , it places
                       the allocation vector in Bank 0.

             DIRBCB    Set DIRBCB to the address of a single directory
                       Buffer Control Block (BCB) in an unbanked system.
                       Set DIRBCB to the address of a BCB list head in a
                       banked system.

                       Set DIR13CB to OFFFEH for GENCPM to set up the
                       DIRBCB field.  The BDOS uses directory buffers for
                       all accesses of the disk directory.  Several DPHs
                       can refer to the same directory BCB or BCB list
                       head; or, each DPH can reference an independent BCB
                       or BCB list head.      Section 3.3.4 describes the
                       format of the Buffer Control Block.

             DTABCB    Set DTABCB to the address of a single data BCB in
                       an unbanked system.  Set DTABCB to the address of a
                       data BCB list head in a banked system.

                       Set DTABCB to OFFFEH for GENCPM to set        up the
                       DTABCB field. The BDOS uses data buffers      to hold
                       physical sectors so that it can block and      deblock
                       logical 128-byte records.  If the physical record
                       size of the media associated with a DPH is 128
                       bytes, you can set the DTABCB field of the     DPH to
                       OFFFFH, because in this case, the BDOS does not use
                       a data buffer.

              HASH     HASH contains the address of the optional directory
                       hashing table associated with a DPH.  Set HASH to
                       OFFFFH to disable directory hashing.








                                              39

    CP/M 3 System Guide                        3.3 BIOS Data Structures

                          Table 3-2. (continued)

        Field                         Comments

         HASH     Set RASH to OFFFEH to make directory hashing on the
    (continued)   drive a GENCPM option. Each DPH   using hashing must
                  reference a unique hash table.    If a hash table is
                  supplied, it must be 4*(DRM+l) bytes long, where
                  DRM is one less than the length of the directory.
                  In other words, the hash table    must contain four
                  bytes for each directory entry of the disk.

        HBANK     Set HBANK to the bank number of the hash table.
                  HBANK is not used in unbanked systems and should be
                  set to zero.  The hash tables can be contained in
                  the system bank, common memory, or any alternate
                  bank except Bank 1, because hash tables cannot be
                  located in the Transient Program Area.         GENCPM
                  automatically sets HBANK when HASH is set to
                  OFFFEH.

    3.3.3 Disk Parameter Block

         Figure 3-3 shows the format of the Disk Parameter Block, where
    b refers to bits.


       SPT BSH IBLM IEXM   I DSM I DRM I ALO I ALl I CKS I OFF I PSH I PHM

        16b  8b I 8b I 8b  I 16bI 16b I 8b I Bb  I16b I 16b I 8b I 8b


                   Figure  3-3. Disk Parameter Block Format



         Table 3-3 describes the fields of the Disk Parameter Block.

                   Table 3-3.  Disk Parameter Block Fields

        Field                          Comments

         SPT        Set SPT to the total number of 128-byte logical
                    records per track.

         BSH        Data allocation block shift factor. The value
                    of BSH is determined by the data block
                    allocation size.

         BLM        Block mask. The value of BLM is determined by
                    the data block allocation size.



                                         40

       CP/M 3 System Guide                        3.3 BIOS Data Structures

                            Table 3-3. (continued)

            Field                         Comments

             EXM        Extent mask determined by the data block
                        allocation size and the number of disk blocks.

             DSM        Determines the total storage capacity of the
                        disk drive.   DSM is one less than the total
                        number of blocks on the drive.

             DRM        Total number of directory entries minus one that
                        can be stored on this drive.      The directory
                        requires 32 bytes per entry.

             ALO, ALl   Determine reserved directory blocks. See Figure
                        3-4 for more information.

             CKS        The size of the directory check vector,
                        @DRM/4)+l.  Set bit 15 of CKS to 1 if the drive
                        is permanently mounted.    Set CKS to 8000H to
                        indicate that the drive is permanently mounted
                        and directory checksumming is not required.

                        Note: full directory checksumming is required
                        on removable  media to support the automatic
                        login feature of CP/M 3.

             OFF        The number of reserved tracks at the beginning
                        of the logical disk.  OFF is the track on which
                        the directory starts.

             PSH        Specifies the physical record shift factor.

             PHM        Specifies the physical record mask.

             CP/M allocates disk space in a unit called a block.  Blocks are
        also called allocation units, or clusters. BLS is the number of
        bytes in a block.  The block size can be 1024, 2048, 4096, 8192, or
        16384 (decimal) bytes.

             A large block size decreases the size of the allocation vectors
        but can result in wasted disk space.  A smaller block size increases
        the size of the allocation vectors because there are more blocks on
        the same size disk.

             There is a restriction on the block size.  If the block size is
        1024, there cannot be more than 255 blocks present on a logical
        drive.   In other words, if the disk is larger than 256K, it is
        necessary to use at least 2048 byte blocks.

             The value of BLS is not a field in the Disk Parameter Block;
        rather, it is derived from the values of BSH and BLM as given in
        Table 3-4.




                                            41

        CP/M 3 System Guide                                                   3.3 BIOS Data Structures

                                      Table     3-4. BSH and BLM Values

                                        BLS                   BSH                      BLM

                                      1 , 0 24                  3                          7
                                      2 O 4 8                   4                        15
                                      4, 096                    5                        31
                                      8 , 19 2                  6                       6 3
                                     16,384                     7                      127

                 The block mask, BLM, equals one less than the number of 128-
        byte records in an allocation unit, (BLS/128 - 1), or (2**BSH)-l.

                 The value of the Block Shift Factor, BSH, is determined by the
        data block allocation size.  The Block Shift Factor (BSH) equals the
        logarithm base two of the block size in 128-byte records, or
        LOG2 (BLS/128) , where LOG2 represents the binary logarithm function.

                 The value of EXM depends upon both the BLS and whether the DSM
        value is less than 256 or greater than 255, as shown in Table 3-5.

                                      Table 3-5.  Maximum EXK Values

                                       BLS                         EXM values

                                                          DSM<256                DSM>255

                                      1,024                     0                   N/A
                                      2, 048                    1                      0
                                      4 , 09 6                  3                      1
                                      8 , 19 2                  7                      3
                                    16 , 38 4                  15                      7

                 The value of EXM              is one less than the maximum number of 16K
        extents per FCB.

                 Set EXM to zero if you want media compatibility with an
        extended CP/M 1.4 system.  This only applies to double-density CP/M
        1.4 systems, with disk sizes greater than 256K bytes.                                                   It is
        preferable to copy double-density 1.4 disks to single-density, then
        reformat them and recreate them with the CP/M 3 system, because CP/M
        3 uses directory entries more effectively than CP/M 1.4.

                 DSM is one less than the total number of blocks on the drive.
        DSM must be less than or equal to 7FFFH.  If the disk uses 1024 byte
        blocks (BSH=3, BLM=7), DSM must be less than or equal to OOFFH.  The
        product BLS*(DSM+l) is the total number of bytes the drive holds and
        must be within the capacity of the physical disk.                                            It does not
        include the reserved operating system tracks.







                                                                   42

        CP/M 3 System Guide                         3.3 BIOS Data Structures

              The DRM entry is one less than the total number of 32-byte
        directory entries, and is a 16-bit value.  DRM must be less than or
        equal to (BLS/32 * 16) - 1. DRM determines the values of ALO and
        ALI.  The two fields ALO and ALI can together be considered a string
        of 16 bits, as shown in Figure 3-4.


                             AL(D                       AL 1

                  00 I olTo2i 03t041051061071081091 10I111121131 14E]


                                Figure 3-4.  ALO and ALI


              Position 00 corresponds to the high-order bit of the byte
        labeled ALO, and position 15 corresponds to the low-order bit of the
        byte labeled ALI.  Each bit position reserves a data block for a
        number of directory entries, thus allowing a maximum of 16 data
        blocks to be assigned for directory entries.        Bits are assigned
        starting at 00 and filled to the right until position 15.       ALO and
        ALI overlay the first two bytes of the allocation vector for the
        associated drive.     Table 3-6 shows DRM maximums for the       various
        block sizes.

                  Table  3-6. BLS and Number of Directory Entries

                   BLS          Directory Entries         Maximum DRM

                  1,024       32   * reserved blocks            511
                  2,048       64   * reserved blocks         1,023
                  4,096        128 * reserved blocks         2,047
                  8,192        256 * reserved blocks         4,095
                  16,384       512 * reserved blocks         8,191

              If DRM = 127 (128 directory entries) ,  and BLS = 1024, there are
        32 directory entries per block, requiring 4 reserved blocks.  In
        this case, the 4 high-order bits of ALO are set, resulting -Ln the
        values ALO = OFOH and ALI = OOH.  The maximum directory allocation
        is 16 blocks where the block size is determined by BSH and BLM.

              The OFF field determines the number of tracks that are skipped
        at the beginning of the physical disk.           It can be used as a
        mechanism for skipping reserved operating system tracks, which on
        system disks contain the Cold Boot Loader, CPMLDR, and possibly the
        CCP.    It is also used to partition a large disk into smaller
        segmented sections.





                                              43

      CP/M 3 System Guide                          3.3 BIOS Data Structures

           PSH and PHM determine the physical      sector size of the disk.
      All disk I/O is in terms of the physical     sector size.   Set PSH and
      PSM to zero if the BIOS is blocking and     deblocking instead of the
      BDOS.

           PSH specifies the physical record shift factor, ranging from 0
      to 5, corresponding to physical record sizes of 128, 256, 512, 1K,
      2K, or 4K bytes.     It is equal to the logarithm base two of the
      physical record size divided by 128, or LOG2(sector-size/128).  See
      Table 3-7 for PSH values.

           PHM specifies the physical record mask, ranging from 0 to 31,
      corresponding to physical record sizes of 128, 256, 512, 1K, 2K, or
      4K bytes.  It is equal to one less than the sector size divided by
      128, or, (sector-size/128)-l.  See Table 3-7 for PHM values.

                          Table 3-7.  PSH and PHN Values

                           Sector
                           size         PSH              PHM

                            128           0                0
                            256           1                1
                            512           2                3
                         1, 0 24          3                7
                         2 , 048          4               15
                         4 , 0 96         5               31

      3.3.4 Buffer Control Block

           A Buffer Control Block    (BCB) locates physical record buffers
      for the BDOS.  The BDOS uses   the BCB to manage the physical record
      buffers during processing.  More than one Disk Parameter Header can
      specify the same BCB.      The GENCPM utility can create the Buffer
      Control Block.

           Note that the BANK and LINK fields of the Buffer Control Block
      are present only in the banked system.          Therefore, the Buffer
      Control Block is twelve bytes long in the nonbanked system, and
      fifteen bytes long in the banked system.  Note also that only the
      DRV, BUFFAD, BANK, and LINK fields need to contain initial values.
      In Figure 3-5, which shows the form of the Buffer Control Block, b
      refers to bits.


           DRV   REC#  WFLG     00 TRACK    SECTOR   BUFFAD  BANK    LINK

           8b    24b     8b     8b   16b      16b     16b      8b    16b


                   Figure 3-5.  Buffer Control Block Format


                                                                               h

                                            44

         CP/M 3 System Guide                         3.3 BIOS Data Structures

               Table 3-8 describes the fields of each Buffer Control Block.

                        Table 3-8.  Buffer Control Block Fields

               Field                           Comment

               DRV        Identifies the disk drive associated with the
                          record contained in the buffer located at
                          address BUFFAD.  If you do not use GENCPM to
                          allocate buffers, you must set the DRV field to
                          OFFH.

               REC#       Identifies the record position of the current
                          contents of the buffer located at address
                          BUFFAD.  REC# consists of the absolute sector
                          number of the record where the first record of
                          the directory is zero.

               WFLG       Set by the BDOS to OFFH to indicate that the
                          buffer contains new data that has not yet been
                          written to disk.  When the data is written, the
                          BDOS sets the WFLG to zero to indicate the
                          buffer is no longer dirty.

               00         Scratch byte used by BDOS.

               TRACK      Contains the physical track location of the
                          contents of the buffer.

               SECTOR     Contains  the physical sector location of the
                          contents  of the buffer.

               BUFFAD     Specifies the address of the buffer associated
                          with this BCB.

               BANK       Contains the bank number of the buffer
                          associated with this BCB.  This field is only
                          present in banked systems.

               LINK       Contains the address of the next BCB in a
                          linked list, or zero if this is the last BCB in
                          the linked list.     The LINK field is present
                          only in banked systems.

               The BDOS   distinguishes between two kinds of buffers:        data
          buffers referenced by DTABCB, and directory buffers referenced by
          DIRBCB.  In a banked system, the DIRBCB and DTABCB fields of a Disk
          Parameter Header each contain the address of a BCB list head rather
          than the address of an actual BCB.        A BCB list head is a word
          containing the address of the first BCB in a linked list.            if
          several DPHs reference the same BCB list, they must reference the
          same BCB list head.     Each BCB has a LINK field that contains the
          address of the next BCB in the list, or zero if it is the last BCB.




                                            45

    CP/M 3 System Guide                        3.3 BIOS Data Structures

         In banked systems, the one-byte BANK field indicates the bank
    in which the data buffers are located.  The BANK field of directory
    BCBs must be zero because directory buffers must be located in Bank
    0, usually below the banked BDOS module, or in common memory.  The
    BANK field is for systems that support direct memory-to-memory
    transfers from one bank to another. (See the BIOS XMOVE entry point
    in section 3.4.4.)

         The BCD data structures in a banked system must reside in Bank
    0 or in common memory.   The buffers of data BCBs can be located in
    any bank except Bank I (the Transient Program Area).

         For banked systems that do not support interbank block moves
    through XMOVE, the BANK field must be set to 0 and the data buffers
    must reside in common memory.  The directory buffers can be in Bank
    0 even if the system does not support bank-to-bank moves.

         In the nonbanked system, the DPH, DIRBCB, and DTABCB can point
    to the same BCB if the DPH defines a fixed media device.            For
    devices with removable media, the DPH DIRBCB and the DPH DTABCB must
    reference different BCBS.  In banked systems, the DPH DIRBCB and
    DTABCB must point to separate list heads.

         In general, you can enhance the performance of CP/M 3 by
    allocating more BCBS, but the enhancement reduces the amount of TPA
    memory in nonbanked systems.

         If you set the DPH DIRBCB or the DPH DTABCB fields to OFFFEH,
    the GENCPM utility creates BCBS, allocates physical record buffers,
    and sets these f ields to the address of the BCBS.    This allows you
    to write device drivers without regard to buffer requirements.

    3.3.5 Data Structure Macro Definitions

         Several macro definitions are supplied with CP/M 3 to simplify
    the creation of some of the data structures in the BIOS.         These
    macros are defined in the library file CPM3.LIB on the distribution
    disk.

         To reference these macros in your BIOS, include the following
    statement:

             MACLIB    CPM3








                                     46

         CP/M 3 System Guide                         3.3 BIOS Data Structures

         DTBL Macro

              Use the DTBL macro to generate the drive table, DRVTBL.  It has
         one parameter, a list of the DPHs in your system.          The list is
         enclosed in angle brackets.

              The form of the DTBL macro call is

                  label: DTBL      <DPHA,DPHB,...,DPHP>

         where DPHA is the address of the DPH for drive A, DPHB is the
         address of the DPH for drive B, up to drive P. For example,

                 DRVTBL: DTBL       <ACSHDO,FDSDO,FDSD1>

         This example generates the drive table for a three-drive system.
         The DTBL macro always generates a sixteen-word table, even if you
         supply fewer DPH names.      The unused entries are set to zero to
         indicate the corresponding drives do not exist.

         DPH Macro

              The DPH macro routine generates a Disk Parameter Header (DPH) .
         It requires two parameters: the address of the skew table for this
         drive, and the address of the Disk Parameter Block (DPB) .           Two
         parameters are optional:    the maximum size of the checksum vector,
         and the maximum size of the allocation vector.         If you omit the
         maximum size of the checksum vector and the maximum size of the
         allocation vector from the DPH macro invocation, the corresponding
         fields of the Disk Parameter Header are set to OFFFEH so that GENCPM
         automatically allocates the vectors.

               The form of the DPH macro call is

                   label:  DPH      ?trans,?dpb,[?csize],[?asizel

         where:
                   ?trans  is the address of the translation vector for this
                           drive;
                   ?dpb    is the address of the DPB for this drive;
                   ?csize  is the maximum size in bytes of the checksum
                           vector;
                   ?asize  is the maximum size in bytes of the allocation
                           vector.

               The following example, which includes all four parameters,
         shows a typical DPH macro invocation for a standard single-density
         disk drive:

                   FDSDO: DPH      SKEW6,DPB$SD,16,31







                                               47

     CP/M 3 System Guide                           3.3 BIOS Data Structures

     SKEW Macro

           The SKEW macro generates a skew table and requires the
     following parameters: the number of physical sectors per track, the
     skew factor, and the first sector number on each track (usually 0 or
     1).

           The form of the SKEW macro call is

               label: SKEW       ?secs,?skf,?fsc

     where:
               ?secs is the number of physical sectors per track;
               ?skf    is the sector skew factor;
               ?fsc    is the first sector number on each track.

     The following    macro invocation generates the skew table for a
     standard single-density disk drive.

               SKEW6: SKEW       26,6,1

     DPB Macro

           The DPB macro generates a Disk Parameter Block specifying the
     characteristics of a drive type.  It requires six parameters: the
     physical sector size in bytes, the number of physical sectors per
     track, the total number of tracks on the drive, the size of an
     allocation unit in bytes, the number of directory entries desired,
     and the number of system tracks to reserve at the beginning of the
     drive.  There is an optional seventh parameter that defines the CKS
     field in the DPB.  If this parameter is missing, CKS is calculated
     from the directory entries parameter.

           The form of the DPB macro call is

               label:   DPB    ?psize,?pspt,?trks,?bls,?ndirs,?off[,?ncks]

     where:
               ?psize   is the  physical sector size in bytes;
               ?pspt    is the  number of physical sectors per track;
               ?trks    is the  number of tracks on the drive;
               ?bls     is the  allocation unit size in bytes;
               ?ndirs   is the  number of directory entries;
               ?off     is the  number of tracks to reserve;
               ?ncks    is the  number of checked directory entries.

           The following example shows the parameters for a standard
     single-density disk drive:

               DPB$SD: DPB       128,26,77,1024,64,2





                                            48

        CP/M 3 System Guide                        3.3 BIOS Data Structures

              The DPB macro can be used only when the disk drive is under
        eight megabytes.  DPBs for larger disk drives must be constructed by
        hand.

        3.4 BIOS Subroutine Entry Points

              This section describes the entry parameters, returned values,
        and exact responsibilities of each BIOS entry point in the BIOS jump
        vector.    The routines are arranged by function.      Section 3.4.1
        describes system initialization.        Section 3.4.2 presents the
        character I/O functions, followed by Section 3.4.3, discussing the
        disk I/O functions.  Section 3.4.4 discusses the BIOS memory select
        and move functions.  The last section, 3.4.5, discusses the BIOS
        clock support function.  Table 3-9 shows the BIOS entry points the
        BDOS calls to perform each of the four categories of system
        functions.

              Table 3-9.  Functional Organization of BIOS Entry Points

              Operation      Function

              System Initialization

                             BOOT, WBOOT, DEVTBL, DEVINI, DRVTBL,

              Character I/O

                             CONST, CONIN, CONOUT, LIST, AUXOUT, AUXIN,
                             LISTST, CONOST, AUXIST, AUXOST

              Disk I/O

                             HOME, SELDSK, SETTRK, SETSEC, SETDMA,
                             READ, WRITE, SECTRN, MULTIO, FLUSH

              Memory Selects and Moves

                             MOVE, XMOVE, SELMEM, SETBNK

              Clock Support

                             TIME


              Table 3-10 is a summary showing the CP/M 3 BIOS function
        numbers, jump instruction names, and the entry and return parameters
        of each jump instruction in the table, arranged according to the
        BIOS function number.







                                         49

     CP/M 3 System Guide               3.4 BIOS Subroutine Entry Points

           Table 3-10.  CP/M 3 BIOS Function Jump Table Sunmary

         No.  Function        Input                    Output

          0    BOOT       None                None
          1    WBOOT      None                None
          2    CONST      None                A=OFFH if ready
                                              A=OOH if not ready
          3    CONIN      None                A=Con Char
          4    CONOUT     C=Con Char          None
          5    LIST       C=Char              None
          6    AUXOUT     C=Char              None
          7    AUXIN      None                A=Char
          8    HOME       None                None
          9    SELDSK     C=Drive 0-15        HL=DPH addr
                          E=Init Sel Flag     HL=OOOH if invalid dr.
         10    SETTRK     BC=Track No         None
         11    SETSEC     BC=Sector No        None
         12    SETDMA     BC=.DMA             None
         13    READ       None                A=OOH if no Err
                                              A=01H if Non-recov Err
                                              A=OFFH if media changed
         14    WRITE      C=Deblk Code        A=OOH if no Err
                                              A=01H if Phys Err
                                              A=02H if Dsk is R/O
                                              A=OFFH if media changed
         15    LISTST     None                A=OOH if not ready
                                              A=OFFH if ready
         16    SECTRN     BC=Log Sect No      HL=Phys Sect No
                          DE=Trans Tbl Adr
         17    CONOST     None                A=OOH if not ready
                                              A=OFFH if ready
         18    AUXIST     None                A=OOH if not ready
                                              A=OFFH if ready
         19    AUXOST     None                A=OOH if not ready
                                              A=OFFH if ready
         20    DEVTBL     None                HL=Chrtbl addr
         21    DEVINI     C=Dev No 0-15       None
         22    DRVTBL     None                HL=Drv Tbl addr
                                              HL=OFFFFH
                                              HL=OFFFEH
         23    MULTIO     C=Mult Sec Cnt      None
         24    FLUSH      None                A=OOOH if  no err
                                              A=001H if  phys err
                                              A=002H if  disk R/O
         25    MOVE       HL=Dest Adr         HL & DE point to next
                          DE=Source Adr       bytes following MOVE
                          BC=Count
         26    TIME       C=Get/Set Flag      None
         27    SELMEM     A=Mem Bank          None
         28    SETBNK     A=Mem Bank          None
         29    XMOVE      B=Dest Bank         None
                          C=Source Bank





                                         50

         CP/M 3 System Guide              3.4 BIOS Subroutine Entry Points

                                Table 3-10. (continued)

             No. I Function      Input

             30    USERF      Reserved for System Implementor
             31     RESERV1   Reserved for Future Use
             32     RESERV2   Reserved for Future Use

         3.4.1 System Initialization Functions

              This section defines the BIOS system initialization routines
         BOOT, WBOOT, DEVTBL, DEVINI, and DRVTBL.


                               BIOS Function 0: BOOT

                        Get Control from Cold Start Loader
                                and Initialize System

                               Entry Parameters: None

                               Returned Values:    None

              The BOOT entry point gets control from the Cold Start Loader in
         Bank 0 and is responsible for basic system initialization.        Any
         remaining hardware initialization that is not done by the boot ROMS,
         the Cold Boot Loader, or the LDRBIOS should be performed by the BOOT
         routine.

              The BOOT routine must perform the system initialization
         outlined in Section 2.3, "System Initialization." This includes
         initializing Page Zero jumps and loading the CCP.      BOOT usually
         prints a sign-on message, but this can be omitted.  Control is then
         transferred to the CCP in the TPA at 0100H.

              To initialize Page Zero, the BOOT routine must place a jump at
         location OOOOH to BIOS  base + 3, the BIOS warm start entry point.
         The BOOT routine must also place a jump instruction at location
         0005H to the address contained in the System Control Block variable,
         @MXTPA.

              The BOOT routine must establish its own stack area if it calls
         any BDOS or BIOS routines.  In a banked system, the stack is in Bank
         0 when the Cold BOOT routine is entered.   The stack must be placed
         in common memory.








                                             51

    CP/M 3 System Guide                 System Initialization Functions


                         BIOS Function  1:   WBOOT

                    Get Control When a  Warm Start Occurs

                          Entry Parameters: None

                          Returned Values:    None

         The WBOOT entry point is entered when a warm start occurs.  A
    warm start is performed whenever a user program branches to location
    OOOOH or attempts to return to the CCP.      The WBOOT routine must
    perform the system initialization outlined in BIOS Function 0,
    including initializing Page zero jumps and loading the CCP.

         When your WBOOT routine is complete, it must transfer control
    to the CCP at location 0100H in the TPA.

         Note that the CCP does not reset the disk system at warm start.
    The CCP resets the disk system when a CTRL-C is pressed following
    the system prompt.

         Note also that the BIOS stack must be in common memory to make
    BDOS function calls.  Only the BOOT and WBOOT routines can perform
    BDOS function calls.

         If the WBOOT routine is reading the CCP from a file, it must
    set the multisector I/O count, @MLTIO in the System Control Block,
    to the number of 128-byte records to be read in one operation before
    reading CCP.COM. You can directly set @MLTIO in the SCB, or you can
    call BDOS Function 44 to set the multisector count in the SCS.

         If blocking/deblocking is done in the BIOS instead of in the
    BDOS, the WBOOT routine must discard all pending buffers.


                         BIOS Function 20: DEVTBL

                   Return Address of Character I/O Table

                  Entry Parameters: None

                  Returned Values:    HL=address of Chrtbl
              L

         The DEVTBL and DEVINI entry  points allow you to support device
    assignment with a flexible, yet completely optional system.         it
    replaces the IOBYTE facility of CP/M 2.2. Note that the CHRTBL must
    be in common in banked systems.



                                        52

         CP/M 3 System Guide               System Initialization Functions

                             BIC)S Function 21: DEVINI

                          Initialize Character I/O Device

                     Entry Parameters: C=device number, 0-15

                     Returned Values:   None

             The DEVINI routine initializes the physical character device
         specif ied in register C to the baud rate contained in the
         appropriate entry of the CHRTBL.  It need only be supplied if I/O
         redirection has been implemented and is referenced only by the
         DEVICE utility supplied with CP/M 3.


                             BIOS Function 22: DRVTBL

                        Return Address of Disk Drive Table

           Entry Parameters: None

           Returned Values:    HL=Address of Drive Table of Disk
                                  Parameter Headers (DPH); Hashing can
                                  be utilized if specified by the DPHs
                                  referenced by this DRVTBL.
                               HL=OFFFFH if no Drive Table; GENCPM does
                                  not set up buffers.        Hashing is
                                  supported.
                               HL=OFFFEH if no Drive Table; GENCPM does
                                  not set up buffers.    Hashing is not
                                  supported.

             The first instruction of this subroutine must be an LXI
         H,<address> where <address> is one of the above returned values.
         The GENCPM utility accesses the address in this instruction to
         locate the drive table and the disk parameter data structures to
         determine which system configuration to use.

              If you plan to do your own blocking/deblocking, the first
         instruction of the DRVTBL routine must be the following:

                 lxi     h,OFFFEh

         You must also set the PSH and PSM fields of the associated Disk
         Parameter Block to zero.







                                           53

     CP/M 3 System Guide                         Character I/O Functions

     3.4.2 Character I/O Functions

          This section defines the CP/M 3 character I/O routines CONST,
     CONIN, CONOUT, LIST, AUXOUT, AUXIN, LISTST, CONOST, AUXIST, and
     AUXOST.

          CP/M 3 assumes all simple character I/O operations are
     performed in eight-bit ASCII, upper- and lowercase, with no parity.
     ANASCII CTRL-Z (lAH) denotes an end-of-file condition for an input
     device.

          In CP/M 3, you can direct each of the five logical character
     devices to any combination of up to twelve physical devices. Each
     of the  five logical devices has a 16-bit vector in the System
     Control Block (SCB) . Each bit of the vector represents a physical
     device where bit 15 corresponds to device zero, and bit 4 is device
     eleven.  Bits 0 through 3 are reserved for future system use.

          You can use the public names defined in the supplied SCB.ASM
     file to reference the I/O redirection bit vectors.  The names are
     shown in Table 3-11.

              Table 3-11.  I/O Redirection Bit Vectors in SCB

                       Name      T       Logical Device

                      @CIVEC            Console Input
                      @COVEC            Console Output
                      @AIVEC            Auxiliary Input
                      @AOVEC            Auxiliary Output
                      @LOVEC            List Output

          You should send an output character to all of the devices whose
     corresponding bit is set.  An input character should be read from
     the first ready device whose corresponding bit is set.

          An input status routine should return true if any selected
     device is ready.  An output status routine should return true only
     if all selected devices are ready.








                                         54

       CP/M 3 System Guide                          Character I/O Functions

                            BIOS Function 2: CONST

                  Sample the Status of the Console Input Device

                 Entry Parameters: None

                 Returned value:    A=OFFH if a console character
                                      is ready to read
                                    A=OOH if no console character
                                      is ready to read

             Read the status of the currently assigned console device and
       return OFFH in register A if a character is ready to read, and OOH
       in register A if no console characters are ready.


                             BIOS Function 3:     CONIN

                        Read a Character from the Console

                     Entry Parameters: None

                     Returned Values:    A=Console Character

             Read the next console character into register A with no parity.
       If no console character is ready, wait until a character is
       available'before returning.


                              BIOS Function 4:    CONOUT

                             Output Character to Console

                      Entry Parameters: C=Console Character

                      Returned Values:    None

             Send the character in register C to the console output device.
       The character is in ASCII with no parity.








                                            55

     CP/M 3 System Guide                       Character I/O Functions

                          BIOS Function 5:   LIST

                      Output Character to List Device

                      Entry Parameters: C=Character

                      Returned Values:   None

          Send the character from register C to the listing device.  The
     character is in ASCII with no parity.


                         BIOS Function 6:   AUXOUT

                         Output a Character to the
                          Auxiliary Output Device

                       Entry Parameters: C=Character

                       Returned Values:   None

          Send the character from register C to the currently assigned
     AUXOUT device.  The character is in ASCII with no parity.


                         BIOS Function 7:   AUXIN

                         Read a Character from the
                          Auxiliary Input Device

                       Entry Parameters: None

                        Returned Values:   A=Character

           Read the next character from the currently assigned AUXIN
      device into register A with no parity.   A returned ASCII CTRL-Z
      (lAH) reports an end-of-file.








                                        56

        CP/M 3 System Guide                          Character I/O Functions

                             BIOS Function 15: LISTST

                    Return the Ready Status of the List Device

                 Entry Parameters: None

                 Returned Values:    A=OOOH if list device is not
                                       ready to accept a character
                                     A=OFFH if list device is
                                       ready to accept a character

             The BIOS LISTST function returns the ready status of the @ist
        device.


                             BIOS Function 17: CONOST

                          Return Output Status of Console

                      Entry Parameters: None

                      Returned Values:    A=OFFH if ready
                                          A=OOH if not ready

             The CONOST routine checks the status of the console.  CONOST
        returns an OFFH if the console is ready to display another
        character.  This entry point allows for full polled handshaking
        communications support.


                             BIOS Function 18: AUXIST

                       Return Input Status of Auxiliary Port

                      Entry Parameters:    None

                      Returned Values:     A=OFFH if ready
                                           A=OOOH if not ready

        The AUXIST  routine checks the input status of the auxiliary port.
        This entry point allows full polled handshaking for communications
        support using an auxiliary port.







                                            57

    CP/M 3 System Guide                        Character I/O Functions

                       BIOS Function 19:   AUXOST

                 Return Output Status of Auxiliary Port

                 Entry Parameters: None

                 Returned Values:   A=OFFH if ready
                                    A=OOOH if not ready

         The AUXOST routine checks the output status of the auxiliary
    port.    This routine allows full polled handshaking for
    communications support using an auxiliary port.

    3.4.3 Disk I/O Functions

         This section defines the CP/M 3 BIOS disk I/O routines HOME,
    SELDSK, SETTRK, SETSEC, SETDMA, READ, WRITE, SECTRN, MULTIO, and
    FLUSH.


                         BIOS Function 8:    HOME

                 Select Track 00 of the Specified Drive

                         Entry Parameters: None

                         Returned Values:    None

         Return the disk head of the currently selected disk to the
    track 00 position.  Usually, you can translate the HOME call into a
    call on SETTRK with a parameter of 0.








                                       58

        CP/M 3 System Guide                              Disk I/O Functions

                             BIOS Function 9:   SELDSK

                          Select the Specified Disk Drive

                Entry Parameters: C=Disk Drive (0-15)
                                    E=Initial Select Flag

                Returned Values:    HL=Address of Disk Parameter
                                       Header (DPH) if drive exists
                                    HL=OOOH if drive does not exist

             Select the disk drive specified in register C for further
        operations, where register C contains 0 for drive A, 1 for drive B,
        and so on to 15 for drive P.     On each disk select, SELDSK must
        return in HL the base address of a 25-byte area called the Disk
        Parameter Header.  If there is an attempt to select a nonexistent
        drive, SELDSK returns HL=OOOOH as an error indicator.

             On entry to SELDSK, you can determine if it is the first time
        the specified disk is selected.  Bit 0, the least significant bit in
        register E, is set to 0 if the drive has not been previously
        selected.   This information is of interest in systems that read
        configuration information from the disk to set up a dynamic disk
        definition table.

             When the BDOS calls SELDSK with bit 0 in register E set to 1,
        SELDSK must return the same Disk Parameter Header address as it
        returned on the initial call to the drive.  SELDSK can only return a
        OOOH indicating an unsuccessful select on the initial select call.

             SELDSK must return the address of the Disk Parameter Header on
        each call.  Postpone the actual physical disk select operation until
        a READ or WRITE is performed, unless I/O is required for automatic
        density-sensing.


                             BIOS Function 10: SETTRK

                             Set Specified Track Number

                         Entry Parameters: BC=Track Number

                         Returned Values:   None

             Register BC contains the track number for a subsequent disk
        access on the currently selected drive.  Normally, the track number
        is saved until the next READ or WRITE occurs.




                                           59

    CP/M 3 System Guide                               Disk I/O Functions

                         BIOS Function 11: SETSEC

                        Set Specified Sector Number

                    Entry Parameters: BC=Sector Number

                    Returned Values:    None

         Register BC contains the sector number for the subsequent disk
    access on the currently selected drive.  This number is the value
    returned by SECTRN.    Usually, you delay actual sector selection
    until a READ or WRITE operation occurs.


                         BIOS Function 12: SETDMA

                     Set Address for Subsequent Disk I/O

                     Entry Parameters: BC=Direct Memory
                                            Access Address

                     Returned Values:    None

         Register BC contains the DMA (Direct Memory Access) address for
    the subsequent READ or WRITE operation.  For example, if B = OOH and
    C = 80H when the BDOS calls SETDMA, then the subsequent read
    operation reads its data starting at 80H, or the subsequent write
    operation gets its data from 80H, until the next call to SETDMA
    occurs.








                                        60

       CP/M 3 System Guide                                 Disk I/O Functions

                              BIOS Function 13: READ

                      Read a Sector from the Specified Drive

                Entry Parameters:    None

                Returned Values:     A=OOOH if no errors occurred
                                     A=OOIH if nonrecoverable error
                                       condition occurred
                                     A=OFFH if media has changed

             Assume the BDOS has selected the drive, set the track, set the
       sector, and specified the DMA address.  The READ subroutine attempts
       to read one sector based upon these parameters, then returns one of
       the error codes in register A as described above.

             If the value in register A is 0, then CP/M 3 assumes that the
       disk operation completed properly.  If an error occurs, the BIOS
       should attempt several retries to see if the error is recoverable
       before returning the error code.

             If an error occurs in a system that supports automatic density
       selection, the system should verify the density of the drive.  If
       the density has changed, return a OFFH in the accumulator.  This
       causes the BDOS to terminate the current operation and relog in the
       disk.


                             BIOS Function 14: WRITE

                       Write a Sector to the Specified Disk

              Entry Parameters:    C=Deblocking Codes

              Returned Values:     A=OOOH if no error occurred
                                   A=001H if physical error occurred
                                   A=002H if disk is Read-Only
                                   A=OFFH if media has changed

             Write the data from   the currently selected DMA address    to the
       currently selected drive, track, and sector.         Upon each call to
       WRITE, the BDOS provides the following information in register C:

             0 = deferred write
             1 = nondeferred write
             2 = deferred write to the first sector of a new data block






                                             61

      CP/M 3 System Guide                              Disk I/O Functions

      This information is provided for those BIOS implementations that do
      blocking/deblocking in the BIOS instead of the BDOS.

           As in READ, the BIOS should attempt several retries before
      reporting an error.

           If an error occurs in a system that supports automatic density
      selection, the system should verify the density of the drive.  If
      the density has changed, return a OFFH in the accumulator.  This
      causes the BDOS to terminate the current operation and relog in the
      disk.


                          BIOS Function 16: SECTRN

                Translate Sector Number Given Translate Table

                Entry Parameters: BC=Logical Sector Number
                                    DE=Translate Table Address

                Returned Values:    HL=Physical Sector Number

           SECTRN performs logical  sequential sector address to physical
      sector translation to improve the overall response of CP/M 3.
      Digital Research ships standard CP/M disk with a skew factor of 6,
      where six physical sectors are skipped between each logical read
      operation.  This skew factor allows enough time between sectors for
      most programs on a slow system to process their buffers without
      missing the next sector.       In computer systems that use fast
      processors, memory, and disk subsystems, you can change the skew
      factor to improve overall response.  Typically, most disk systems
      perform well with a skew of every other physical sector.  You should
      maintain support of single-density, IBM 3740 compatible disks using
      a skew factor of 6    in your CP/M 3 system to allow information
      transfer to and from other CP/M users.

           SECTRN receives a logical sector number in BC, and a translate
      table address in DE. The logical sector number is relative to zero.
      The translate table address is obtained from the Disk Parameter
      Block for the currently selected disk.  The sector number is used as
      an index into the translate table, with the resulting physical
      sector number returned in HL.  For standard, single-density, eight-
      inch disk systems, the tables and indexing code are provided in the
      sample BIOS and need not be changed.

           Certain drive types either do not need skewing or perform the
      skewing externally from the system software.  In this case, the skew
      table address in the DPH can be set to zero, and the SECTRN routine
      can check for the zero in DE and return with the physical sector set
      to the logical sector.





                                          62

