CP/M v2.2 and 3.1 for the PCW16 - version 1.02          John Elliott, July 2022
===============================================================================

Legal bits
==========
  If you are just going to use CP/M, the licensing issues need not concern 
you; but if you want to give or sell it to anyone, you will need to consult 
the detailed section entitled "COPYING" at the end of this document. 

Overview
========

  Unlike previous PCWs, the PCW16 was not supplied with CP/M. This program
provides a CP/M environment.

What will run:                   What won't run:
--------------                   ---------------
BASIC and BASIC programs         Any graphical programs
Programs written for CP/M 2      Programs that try to control the PCW's 
Programs written for CP/M 3      hardware directly (eg: DISCKIT)


Installation
============

  CP/M for the PCW16 is supplied as two disc images: 
PCW720.RAW and PCW1440.RAW. PCW720.RAW is designed to be written to a 720k
floppy disc, PCW1440.RAW to a 1.4Mb floppy disc. They are otherwise identical.

  To run it on a real PCW16, write one or other disc image to a floppy disc,
using a command such as 'dd' under Linux, or 'rawrite' 
<http://www.chrysocome.net/rawwrite> under Windows.

  To run it in the XANNE emulator, use the menu to insert PCW720.RAW or 
PCW1440.RAW into drive A:. If you are launching XANNE from a command line,
use a command similar to 'xanne -A pcw1440.raw'

Running CP/M
============

  With the PCW16 screen displaying the Desktop, press TASK and F7 together. 
Insert the "program" disc, and click "Disc" on screen. The list of programs
below will include "CPM for the PCW16"; highlight it and press the green key.
Shortly, a prompt will appear asking you to make sure your CP/M start-of-day
disc is in the drive. The disc already loaded will behave as a start-of-day
disc, so just leave it in the drive and press the green key again. You will 
next see the CP/M sign-on message, followed by a number of other messages 
describing what facilities are available.

  When you have finished using CP/M, type DESK to return to the Desktop.
 
Switching to CP/M 2
===================

  The disc image supplied has two startup files, for CP/M 2.2 and CP/M 3.
The active startup file has a name ending in .EML, the inactive one in .LBR.

  So, to switch from CP/M 3 to CP/M 2, make sure the CPM2 file is the one
that ends in .EML:

A>REN A10CPM3.LBR=A10CPM3.EML
A>REN A10CPM2.EML=A10CPM2.LBR

  If there is no valid .EML file on a start-of-day disc, CP/M will start 
with a bare-bones copy of CP/M 2.2 -- see "Features" below.

Supplied programs
=================

  The standard CP/M 3 tools have been supplied, from the 1998 Caldera
release of CP/M. These have been updated since the original release of CP/M
for Year 2000 compliance and other bug fixes.

  The standard tools for CP/M 2 (STAT, DDT, LOAD etc) are not included, but
since CP/M is now open source they should be readily obtainable should you
require them.

  The following programs are also present; they correspond to some of the 
extended utilities supplied with official CP/M releases for other Amstrad 
computers.

* DESK    .COM - Return to the Rosanne desktop.
* CRTFONT .COM - Load/save screen fonts.
* LOADKEYS.COM - Load/save keyboard layouts. 
* DU55    .COM - Disc format/copy/verify program, use instead of DISCKIT.
                 Note: DU55 requires CP/M 3 or ZPM3.
* DU55    .DOC - Instructions for DU55.
* DU55CON .COM - Format editor for DU55.
* LANGUAGE.COM - Select the national character set.
* SET24X80.COM - Switch to the 24x80 screen, or back to the 30x80 screen.
* SETLST  .COM - Send a sequence of characters to the printer.
* SETSIO  .COM - Set up the serial port.
* PALETTE .COM - Set up the screen colours.
* CALLANNE.COM - An example of how to call Rosanne from CP/M, with source.
* QT16-01C.LBR - Trevor Gowen's QTERM overlay - supports serial communications
                 up to 4800 baud. You will need a copy of QTERM to use this
                 overlay.
* XLOGSEA .COM - XLOGIN is a utility for older PCWs and Spectrum +3s, allowing
                 them to use discs in the PCW16's "720k boot/root" format.
                 Run XLOGSEA.COM on an older PCW, and it will create several
                 files; you should read the one called XLOGIN.DOC. 

Organisation
============

  In this release, all system files are stored in the boot file - this is 
called A10CPM2.EML for CP/M 2, or A10CPM3.EML for CP/M 3.

Features
========

  If there is no .EML file on the start-of-day disc, CP/M will load with a 
very basic specification:

* 56k TPA
* 1 floppy drive, read-only access
* Dumb terminal screen

  If the start-of-day disc does have a suitable .EML file, then the 
specification becomes:

* 56k TPA (61k under CP/M 3)
* 1 floppy drive, read/write access. The drive can be used as A: and B:
* 512k drive M:
* VT-52 compatible screen
* Support for the parallel printer
* Support for the serial port

  For programming information, see the "Technical" section at the end.

New in this release
===================

* After over 23 years, this updated release of PCW16 CP/M has the following 
 updates:
- With the final licence encumbrances removed, genuine copies of Digital 
 Research CP/M 2 and 3 are included, rather than the workalikes previously 
 used. Accordingly, the workalikes are no longer included.
- A bugfix: The boot code needs a little extra initialisation to start up 
 with genuine CP/M 2 rather than the previous clone code.
- There is now no need to copy components from an older PCW.
- The build process has been updated and no longer requires a physical floppy
 disc.

Known Bugs and Features
=======================

  Under CP/M 2, you must be very careful to change discs only at the A>
prompt, and to press STOP when you do.

Missing Features (or, the Wish List). 
None of these is essential for normal use of CP/M.
==================================================

 * Some of the DD_* USERF calls are missing, but they require direct 
  programming of the floppy controller (see below).
 * EXPORT/IMPORT programs to access the Cabinet.
 * Equivalent of the PAPER / DAISY utility on an old PCW.
 * GSX support.
 * Digital Research Logo support.
 * Currently, CP/M is implemented as a Rosanne application; there may be a 
  case for writing it to use only the hardware, so that it can be loaded onto
  a "bare" PCW16. Then again, there may not.
 * Virtual consoles and MP/M support.

Technical information
=====================

  For technical and programming information, see the file USERF.TXT.

VT52 screen driver
==================

  The screen driver accepts all escape codes used on "classic" PCWs.

  It also accepts the following CRTPLUS codes:

* ESC + B <n>              (set border colour)
* ESC + a <n> and ESC - a  (AND with character <n>)
* ESC + b  and    ESC - b  (bold on/off)
* ESC + d  and    ESC - d  (double width on and off)
* ESC + D  and    ESC - D  (doublestrike on/off)
* ESC + f  and    ESC - f  (flashing cursor on/off)
* ESC + g  and    ESC - g  (grey text on/off)
* ESC + h  and    ESC - h  (double height)
* ESC + i  and    ESC - i  (italic text on/off)
* ESC + o <n> and ESC - o  (OR with character <n>)
* ESC + u <n> and ESC - u  (set underline style)
* ESC + x <n> and ESC - x  (XOR with character <n>)

  The ESC x (set 24x80 screen) and ESC y (set 30x80 screen) are done by 
changing the font size. The ESC 3 n (change mode) is done by changing the 
screen resolution, which can be quite alarming if you aren't expecting it.

  The program CRTFONT allows you to switch screen fonts. The syntax is:

CRTFONT <fontfile>             - to load a font for the 30x80 screen
CRTFONT <fontfile> [TALL]      - to load a font for the 24x80 screen
CRTFONT <fontfile> [SAVE]      - to save the current 30x80 font
CRTFONT <fontfile> [TALL,SAVE] - to save the current 24x80 font

  The supplied fonts are based on the "S" font supplied with Slackware Linux,
but using the same character set as a "classic" PCW.

  The program PALETTE lets you change the screen colours. Unless your PCW16
has a colour display (and just how likely is that?) you will be limited to 
three colours - black, white and dark grey.

  The command to use is:

PALETTE background foreground

  where each of "background" and "foreground" is a number. Numbers you should
use are:

   0 - Black
  21 - Dark grey
  63 - White

  The PALETTE command can take more than two numbers; the extra ones get used
as additional "foreground" colours if the screen is in Mode 0 or Mode 1.

Keyboard driver
===============
  Keyboard redefinition is possible. Redefinition is done by the LOADKEYS 
command:

LOADKEYS keyfile

where "keyfile" is a series of ASCII lines.
  It is possible to save the current keyboard state with the command:

LOADKEYS keyfile.kmt [SAVE]

 - this saves a "keymap" file that can then be reloaded by LOADKEYS.

  For full details of keyboard functions, see the file KEYBOARD.TXT.

Floppy driver
=============

  The floppy driver can use only CP/M format discs with 9 sectors per track. 
This allows the use of 706k discs from old-style PCWs, high-density discs 
formatted with DU55, and my 702k "DualDOS" format.
  CP/M can be booted from a 706k PCW-format disc or a 1.4Mb disc formatted 
with DU55. 
  As on a PCW "classic", you can use drive B: even when there is only one 
floppy drive; you will be asked to insert the "disc for A:" or the 
"disc for B:". However, since CP/M 2 has a fairly intimate relationship with 
the A: drive, this feature is only really useful under CP/M 3.

SETLST.COM
==========

  SETLST.COM can be used to send a sequence of control codes to the printer.
The command to type is:

  SETLST "string"

  where string is the sequence of characters you want to send. It will be 
interpreted as follows:

  Letters will be converted to lower case.
  A letter after a % sign will remain upper-case.
  A letter after a ^ sign will be converted to a control character.
  %% becomes %
  %^ becomes ^
  %" becomes "
  The sequence ^#<number># becomes the character with the given number.

  So:

    SETLST "^L"      sends Control-L (form feed).
    SETLST "^[D"     sends ESC d  
    SETLST "^[%D"    sends ESC D
    SETLST "^#140#"  sends character 140.
    SETLST "^[%%1"   sends ESC % "1"
    SETLST "^[%%^A"  sends ESC % 1

Serial port
===========

  The serial port driver is based on Trevor Gowen's QTERM overlay. When 
CP/M is first starting, there may be a delay of a few seconds while the 
serial driver tries to detect if there is a communications link in place.

  To set communications parameters, use SETSIO - type SETSIO [HELP] for a
list of the various parameters that can be used. Note that a SETSIO command
line should contain no spaces between options - only commas.

  The three handshake protocols that can be used are:

[PROTOCOL=1] : RTS<>CTS handshake only.
[PROTOCOL=2] : DTR<>DSR handshake only.
[PROTOCOL=3] : RTS--CTS "connect" (CTS checked during Tx), DTR<>DSR handshake.

_______________________________________________________________________________

Acknowledgements:
-----------------

Cliff Lawson and Richard Wildey, for programming information.
Simeon Cran, for letting me use the ZPM3 BDOS.
Trevor Gowen, for the QTERM overlay, the printer FID, and alpha-testing.
Tony Velate, for alpha-testing.

_______________________________________________________________________________

COPYING
=======

  CP/M for the PCW16 is composed of a large number of components with
different distribution conditions. If you intend to distribute it, you may 
have to be careful about what gets included.

DU55
====
  
  DU55 may only be distributed with PCW16 CP/M. No source code is 
provided. There are no other restrictions on the distribution of DU55.

CALLANNE
========

  CALLANNE is freeware and has no restrictions of any kind on distribution.

Digital Research Utilities
==========================
  Files containing Digital Research or Caldera copyright messages are 
covered by the Digital Research licence from DRDOS, Inc -- see COPYING.DRI.

Other .COM files
================

  The other .COM files provided are distributed under the GNU General Public
License, version 2 (see COPYING).

Other system files
==================

  The system files (*.FID, BNKBIOS3.SPR, GENCPM.DAT, ANNELDR.PRG) are 
distributed under the GNU Library General Public License, version 2. This is
so they can be linked with a proprietary CP/M BDOS.

Documentation
=============

  One final point; you should update this documentation if your distribution of
CP/M is packaged differently from the original. There is nothing to stop you 
replacing CP/M with a workaround like ZPM3 or ZSDOS, or supplying separate
CP/M 2 and CP/M 3 startup discs, or omitting one or more drivers from the 
.EML file; but under these circumstances, the documentation should be altered 
to make it clear what has been changed.


