CPU emulation

I/O instructions are available, but are dummies; writing to I/O ports has no direct effect, and reading them always returns a null byte. Same is true for all interrupt related instructions (while the I register may be set and read and the EI and DI instructions have the expected side effects, no interrupt will ever occur). Executing a HALT instruction will end program execution (and thereby the execution of tnylpo) and is considered an error situation (see below under Program termination). Well-behaved CP/M applications should never use any of these instructions anyway.

Note that the behaviour of the HALT instruction has changed from earlier versions of tnylpo, where it was simply ignored (resp. acted as if a NMI had been received immediately after entering the halt state). This change allows unused memory areas to be initialized with HALT instructions, which increases the chances of detecting and stopping a runaway application program early.

The R register will be increased as expected; since application programs may use the current value of the R register for the generation of random numbers (the Randomize procedure of Turbo Pascal seems to do this), the R register is initialized with a random value (otherwise, repeated runs of the same program would always generate the same sequence of random numbers).

At the start of program execution, all unused memory (i.e. the part of the TPA not occupied by the loaded executable as well as the unused parts of the zero page and the BIOS area) are initialized with the byte value 0x76 (the HALT instruction). All registers apart from PC, SP, and R are set to zero, PC is set to 0x100, and SP points to a stack area at the top of the TPA.

File name translation

Command line arguments

All further positional arguments are passed as command line arguments to the CP/M program (i.e. they are converted to upper case and copied to the default DMA area at 0x0080; additionally, the default FCB at 0x005c is initialized according to the second and third positional arguments).

Configuration files

A tnylpo configuration file is a regular text file; empty lines and lines starting with a hash sign (#) or a semicolon (;) are ignored. All other lines have the form

<token> is either a keyword (a sequence of alphanumeric characters starting with a letter), a number (hexadecimal, octal or decimal using the usual Unix convention of being prefixed by 0x, 0, resp. some other digit), a string in double quotes, or a comma.

Configuration options

default drive = <drive letter>
command line option -d <drive letter>

close files = (true | false)
command line option -n

logfile = <path>

loglevel = <level>
command line option -v <level>

console = (full | line)
command line options -s or -b

screen delay = (<number> | key)
command line option -t (<number> | @)

lines = (<number> | current)
columns = (<number> | current)
command line options -l (<number> | @) and -c (<number> | @)

application cursor = (true | false)
command line option -w

exchange delete = (true | false)
command line option -r

[alt] char <number> = <string>
[alt] charset = (ascii | vt52 | latin1 | tnylpo)
unprintable = <string>

(printer | punch | reader) file = <path>
(printer | punch | reader) mode = (text | raw)

colors = ( false | true ) [ , <fg> , <bg> ]
command line options -on, -oy, -oy,<fg>,<bg> and -o<fg>,<bg>

cpu delay = <count> , <nanoseconds>
command line options -yn and -y<count>,<nanoseconds>

dump = none
dump = all
dump = (startup | exit | error | signal) [, ...]
command line options -zn, -za, and -z{s|x|e|i}

Terminal emulation

tnylpo's terminal emulation mimicks the VT52 fairly accurately, but offers a number of extensions, among them the ability to support screen sizes of up to 95 by 95 characters (this limitation is due to the limitations of the VT52 direct cursor positioning command), eight-bit operation, a dynamically switchable alternate character set, insert and delete line commands, and bold, underlined, inverted, and blinking (i.e. everybody's favourite) character rendition. To protect the CP/M application (resp. its user) from the effects of screen resizing, the terminal emulation provides a fixed size screen area (typically 80 columns by 24 lines, but this may be changed by command line or configuration file options) within the actual display (a terminal emulator like xterm(1) or the screen of an actual serial terminal). If the display device/window is larger than this area, there will be blank margins to the right and below the VT52 display area; if it is smaller, parts of the output from the emulator will be invisible to the user, but will (re-)appear as soon as the window is enlarged.

The terminal emulation (like the VT52) does not do an automatic line wrap (i.e. the cursor will not move to the first column of the next line if a character is displayed in the last column of a line) and supports (or at least tolerates) all of the VT52 control sequences:

<bel> (0x07)

gives an accustic (or visual) signal.

<bs> (0x08)

moves the cursor left, but stops at column 1.

<tab> (0x09)

moves the cursor to the next tabulator stop if it is before the last tabulator stop on the current line (tabulator stops are at columns 9, 17, 25, ...); otherwise, it moves the cursor one column to the right (resp. does nothing if the cursor is already in the last column).

<lf> (0x0a)

moves the cursor down one line and scrolls up on bottom line.

<cr> (0x0d)

moves the cursor to the first column of the current line.

<esc> (0x1b)

marks the start of an escape sequence (see below).

All other characters in the ASCII control character range (0x00–0x1f, 0x7f) are ignored. The VT52 escape sequences are:

<esc> ) (0x1b 0x29) and <esc> = (0x1b 0x3d)

switch the keypad to application resp. to regular (numeric) mode (no effect in tnylpo).

<esc> A (0x1b 0x41)

moves the cursor up one line, but stops at the top line.

<esc> B (0x1b 0x42)

moves the cursor down one line, but stops at the bottom line.

<esc> C (0x1b 0x43)

moves the cursor right one column, but stops at the last column.

<esc> D (0x1b 0x44)

moves the cursor left one column, but stops at the first column.

<esc> F (0x1b 0x46) and <esc> G (0x1b 0x47)

display character codes 0x5e–0x7e as graphical resp. as ASCII characters (see below).

<esc> H (0x1b 0x48)

moves the cursor to the left top corner of the display.

<esc> I (0x1b 0x49)

moves the cursor up one line and scrolls down at the first line.

<esc> J (0x1b 0x4a)

clears the display from the current cursor position to the end of the screen.

<esc> K (0x1b 0x4b)

clears the display from the current cursor position to the end of the line.

<esc> Y <line> <column> (0x1b 0x59 0xYY 0xXX)

moves the cursor to the specified position on the display; line and column numbers are given as graphical characters in the range of 0x20 (position 1) to 0x7e (position 95). If the column number is larger than the display width, the horizontal position is not changed; a line number larger than the height of the display moves the cursor to the last line.

<esc> Z (0x1b 0x5a)

identifies the terminal type; the terminal emulation responds by sending the sequence <esc> / K (0x1b 0x2f 0x4b), i.e. it identifies itself as VT52 without hardcopy device.

<esc> [ (0x1b 0x5b) and <esc> \ (0x1b 0x5c)

enter resp. exit "hold screen" mode (see below).

In addition, the terminal emulation in tnylpo supports the following extensions to the VT52 escape sequences:

<esc> E (0x1b 0x45)

clears the display, moves the cursor to the top left corner of the display.

<esc> L (0x1b 0x4c)

inserts a blank line at the cursor position and moves lines below down one line (the last line is lost).

<esc> M (0x1b 0x4d)

deletes the line at the cursor position and moves lines below up one line (an empty line will appear at the bottom of the display).

<esc> N (0x1b 0x4e)

inserts a blank character at the cursor position and moves characters to the right one position to the right (the last character on the line is lost).

<esc> O (0x1b 0x4f)

deletes the character at the cursor position and moves characters to the right one position to the left (a blank character appears in the last column of the line).

<esc> S <color> (0x1b 0x53 0xCC)

sets the background color of subsequent output characters; the color code is described below (Color support).

<esc> T <color> (0x1b 0x54 0xCC)

sets the foreground color of subsequent output characters; the color code is described below (Color support).

<esc> a (0x1b 0x61) and <esc> b (0x1b 0x62)

make the cursor invisible resp. visible.

<esc> c (0x1b 0x63) and <esc> d (0x1b 0x64)

switch to the alternate resp. to the primary character set (see below).

<esc> e (0x1b 0x65) and <esc> f (0x1b 0x66)

switch on resp. off bold characters.

<esc> g (0x1b 0x67) and <esc> h (0x1b 0x68)

switch on resp. off underlined characters.

<esc> i (0x1b 0x69) and <esc> j (0x1b 0x6a)

switch on resp. off inverted characters.

<esc> k (0x1b 0x6a) and <esc> l (0x1b 0x6c)

switch on (arrgh!) resp. off (phew!) blinking characters.

<esc> m (0x1b 0x6d)

switches off bold, underlined, blinking, and inverted characters as well as standout mode (see below); resets the foreground and background colors to their defaults.

<esc> n (0x1b 0x6e) and <esc> o (0x1b 0x6f)

switch the cursor keys to application mode resp. back to regular (VT52) mode: in regular mode, the cursor keys send the sequences <esc> A (up), <esc> B (down), <esc> C (right), and <esc> D (left); in application mode, they send WordStar-compatible commands, namely ^E (0x05, up), ^X (0x18, down), ^D (0x04, right), and ^S (0x13, left).

<esc> p (0x1b 0x70) and <esc> q (0x1b 0x71)

switch on resp. off standout mode; standout mode is the most visible character attribute provided by curses (this is usually inverted video, so using <esc> p and <esc> q is usually equivalent to using <esc> i and <esc> j).

"Hold screen" mode is a feature of the VT52 terminal: it is entered and exited either by the computer sending the relevant control sequence or by the user by pressing the "hold screen" key (in tnylpo, this is the F5 key). In "hold screen" mode, trying to scroll up the screen (by a <lf> on the bottom line of the screen) blocks further output until either "hold screen" mode is exited or the user presses the "scroll page" key (F6 in tnylpo) or the "scroll line" key (F7 in tnylpo), which allow one more screenfull resp. one more line of output.

Displaying graphical characters instead of ASCII characters for the byte range 0x5e–0x7e is another feature of the VT52 terminal which allows access to certain additional shapes like subscripted digits or the ± sign; in tnylpo, graphical mode allows displaying the shapes defined for the character positions 0x00–0x1f and 0x7f, which cannot be displayed directly.

Character sets

Character set definition is done in the configuration file by using the option

which defines <string> (a one-character string literal in double quotes) as representation of code <number> (a number in the range 0–255) in the primary (or alternate, if the line is prefixed by alt) character set. Characters not explicitly defined in this way are taken from a default character set, which may be selected by the option

The possible values correspond to the four built-in character sets ASCII, VT52 (ASCII plus an approximation of the VT52 graphical characters), the ISO 8859-1 (Latin 1) eight-bit character set, which supplements the ASCII code by characters used in Western European languages in positions 0xa0–0xff, and finally a homespun superset of Windows code page 1252 (and thereby a superset of ISO 8859-1 and ASCII), which supports block graphics and the VT100 box drawing characters as graphical character set.

If no character set is specified, tnylpo uses the VT52 character set by default.

By using the command line option -a, a program may be started with the alternate character set selected; the effect is almost identical to the program issuing <esc> c as its very first action. (There is a difference in full screen console mode: During screen initialization, tnylpo passes the blank character from the selected character set to the curses library for use as background character. Since the program itself can select the alternate character set only after this initialization has been done, curses will receive the blank character from the primary character set; with the -a command line option, it will receive the blank character from the alternate character set. This difference is mostly academic, since it is not recommended to redefine the blank character anyway, see below.)

Output characters which are undefined in the currently selected character set are ignored by the terminal emulation; the configuration option

substitutes undefined characters on output by the value of <string> (which must contain a single character).

Function keys

Color support

By default, color support is disabled even on color-capable displays; it must be explicitly enabled either by the configuration option

or by the command line option -oy. Both colors = true and -oy may be followed by two comma-separated color codes, which specify the default foreground resp. background colors of tnylpo's terminal emulation, e.g.

(resp. -oy,6,1) will select yellow characters on a blue background. The default colors may be specified in the configuration file by colors = false, 6, 1 even if color support is disabled (since this may be overridden by -oy). The command line option -o6,1 is a shorthand form of -oy,6,1, and -on may be used to override the configuration file and disable color support. If no default colors have been specified either in the configuration file or on the command line, tnylpo defaults to 7 and 0, i.e. to white text on a black background.

Application programs may select colors by issuing the escape sequences <esc> S <color> and <esc> T <color> to choose the background resp. foreground colors of subsequently displayed characters; <color> is either a single ASCII digit in the range from 0 to 7 (0x31 to 0x37) corresponding to one of the colors supported by tnylpo, or the character = (0x3d), which will select the respective default color. To render e.g. the text Warning! in red, a program may display the character sequence

on the full-screen console. Both foreground and background colors will also be reset to their defaults by the escape sequence <esc> m, which resets all text attributes. On monochrome devices or if color support has been disabled, <esc> S and <esc> T will still be accepted but silently ignored.

Character devices

These files are defined by the configuration options

where <path> is a string in double quotes containing the Unix file path; in case of the output devices (LST: and PUN:), data written by the CP/M program are appended to the contents of the named files; RDR: input will start at the beginning of the reader file. If a CP/M program reads past the end of the reader file, tnylpo will continue to return ^Z (0x1a) bytes as end-of-file indication.

tnylpo's character devices can operate in two modes, depending on the configuration options

In raw mode, bytes are written to the file exactly as they are generated by the CP/M program resp. passed to the CP/M program exactly as they are read from the file (^Z bytes are still returned as EOF indication). In text mode, tnylpo will translate the characters read resp. written using the translation table used by the console. Character set switching by the console (using the escape sequences <esc> c and <esc> d) will affect this translation, but switching to graphical characters (<esc> F and <esc> G) will not. Moreover, tnylpo will convert the line end markers from CP/M (^M^J, 0x0d 0x0a) to Unix (^J, 0x0a) and vice versa in this mode.

Saving a memory image

h

causes the memory contents to be written in Intel Hex format; if this option is absent, a binary file will be written.

b<bytes>

selects a number of bytes (specified as decimal number) starting from address 0x100.

p<pages>

selects a number of pages (units of 256 bytes, specified as decimal number) starting from address 0x100.

r[<low-addr>]-<high-addr>

selects a range of addresses to save (both addresses may be specified as octal, hexadecimal, or decimal numbers using the Unix convention of prefixing them with 0, 0x, or any other digit, respectively); <high-addr> may not be less than <low-addr>, and if <low-addr> is missing, 0x100 will be assumed in its place.

:<filename>

specifies the Unix file to which the memory contents are written; this is mandatory and must be the very last suboption (in fact, everything following the first colon in the argument of the -e command line option is taken as part of the file name).

Individual suboptions resp. suboptions and their parameters may not be separated by whitespace. The three range specifications b, p, and r may not exceed the range of the CP/M memory space (0x0000–0xffff) and are mutually exclusive; if none of them is specified, the whole TPA (starting at address 0x100 and including the last byte before the BDOS area) is saved.

The command line option -e serves as a replacement for the SAVE command of CP/M, which is most often used to save an executable file after applying patches with a debugger (most CP/M debuggers don't provide a command for writing memory contents to a disk file). Invoking tnylpo with the additional option -ep34:new.com is equivalent to issuing the command SAVE 34 NEW.COM immediately after termination of an executable under CP/M.

Supported system calls

BDOS function #49 (Get/Set System Control Block) is only partially implemented: Attempts to write to the SCB are silently ignored, and only the SCB offsets 0x05 (BDOS version number, always 0x22), 0x10–0x11 (program return code), 0x1a (console columns), 0x1c (console lines), 0x37 (output delimiter, always 0x24), 0x3c–0x3d (current DMA address), 0x3e (current disk), 0x44 (current user number), and 0x4a (current multi sector count, always 1) provide meaningful information (all other byte offsets return 0).

BDOS function #102 (Read File Date Stamps and Password Mode) always returns the access and modification timestamps of the underlying Unix file, and function #101 (Return Directory Label Data) correspondingly always returns a value of 0x61.

BDOS function #141 (Delay) delays program execution for the number of system clock ticks passed in register DE; tnylpo defines a tick to last 20 milliseconds, i.e. it emulates a ticker frequency of 50 Hertz.

In addition to the BDOS calls, tnylpo implements all BIOS calls of CP/M 2.2, but all disk related functions are dummies:

No additional BIOS calls from CP/M 3 have been implemented, not even as dummies, i.e. any attempt to call them will result in undefined program behaviour.

Program termination

Furthermore, a CP/M program will be terminated if it performs an action considered illegal by tnylpo, like executing a HALT instruction, trying to write to a read-only file or to a file on a disk configured as read-only, passing invalid arguments to system calls, accessing a disk drive not configured, or requesting an illegal sequence of operations (like trying to read from a disk file which has already been closed).

When the full screen console is active, a program may be terminated by the user pressing the F10 key (see above, "Function keys"); this is equivalent to sending a SIGINT to tnylpo from another terminal/terminal window. Pressing F10 terminates the CP/M program abruptly and should (like sending a signal to tnylpo) only be used as a last resort when dealing with a hung application.

Both program termination due to an illegal action and terminating a program by pressing F10 (or sending tnylpo a signal) are considered irregular forms of program termination.

./.tnylpo.conf

~/.tnylpo.conf

Using configuration informations from a file in the current working directory (./.tnylpo.conf) is convenient in many situations, but poses a potential security risk; mainly for this reason, tnylpo refuses to run if its effective user ID is 0.

Differences between tnylpo and CP/M-80

Direct access to the BDOS and BIOS areas

BDOS and BIOS function emulations are activated by the simulated processor executing a RET instruction fetched from one of the uppermost 19 addresses of the CP/M memory space (0xffed for the BDOS entry, 0xffee to 0xfffe for the 17 BIOS entries of CP/M-80 2.2 and 0xffff for one tnylpo-specific delay routine hiding as 18th BIOS entry); this use of "magic addresses" might confuse debuggers trying to trace system calls.

The BIOS area (starting three bytes before the address stored at 0x0001) is page-aligned and contains the 17(+1)-element BIOS jump vector, the dummy disk structures (see below) and the above mentioned 19 RET instructions. The BDOS area (starting at the address stored at 0x0006) is even shorter, containing only a jump to 0xffed and the table of target addresses for the four fatal BDOS error conditions (non-existing disk, bad sector, read-only disk, and read-only file; these addresses may be modified by an application program, but are completely ignored by tnylpo). Any program expecting the BDOS or the BIOS areas to have the sizes and alignment characteristics of a real CP/M-80 environment will be disappointed.

The OS serial number stored in the six bytes immediately before the BDOS area is always 0x00 0x16 0x00 0xc0 0xff 0xee, a (hopefully inoffensive) dummy indicating BDOS version 2.2.

Direct access to the disk drives

Console Command Processor

File attributes

User areas

I/O byte

FCB structures

Sparse files

File closing

To accommodate such programs, tnylpo provides the -n command line option (and the corresponding close files = false configuration option), which prevent closing the Unix file and removing the file reference from the FCB (effectively making BDOS function #16 a dummy operation). If many files are opened (sequentially or concurrently) by a CP/M program, this may cause tnylpo to run out of files, since the closing of all Unix files is deferred until program termination.

Text file format

On the other hand, text files generated under Unix should be converted to the CP/M line end convention before processing them with programs running on tnylpo (the command set ff=dos might come handy for people using Vim!). The CP/M convention for marking the logical end of text files is honoured automatically, since tnylpo's BDOS emulation pads Unix files to the CP/M record size of 128 bytes with ^Z bytes.

Text file conversion between the Unix and the CP/M formats may be done conveniently using the companion program tnylpo-convert(1).

Performance

The delay routine

To allow CP/M programs to delay execution for a defined (wall clock) time period, tnylpo supplies a delay routine masquerading as 18th BIOS entry: it expects a single parameter, an unsigned 16-bit number in register BC, and waits this many milliseconds before returning to the caller.

The benefit of this routine is at best limited, but most likely nonexistent; since it is an extension, no existing CP/M application (for which tnylpo has been created in the first place) uses it, and even in case somebody would develop new CP/M software, employing tnylpo's delay function would break compatibility with all other CP/M machines or emulators.

As an alternative, tnylpo implements function #141 (Delay) from the MP/M BDOS; while this function is a little more standardized than tnylpo's proprietary extension, it is equally unavailable on real CP/M and most compatible systems and suffers from the additional drawback that it measures time in system timer ticks, which are implementation dependent (tnylpo emulates a tick length of 20 milliseconds, i.e. a 50 Hertz timer).

The name of the program

Character set switching

Character redefinition

Host system locales

File namespace clashes

Color limitiations

Patching a CP/M executable

total 72
drwxr-xr-x   7 tnylpo  users   224 Sep  5 13:04 .
drwxr-xr-x  39 tnylpo  users  1248 Sep  5 13:04 ..
-rw-r--r--   1 tnylpo  users  8192 Sep  5 13:02 asm.com
-rw-r--r--   1 tnylpo  users  4864 Sep  5 13:02 ddt.com
-rw-r--r--   1 tnylpo  users  2091 Sep  4 13:08 patch.asm
-rw-r--r--   1 tnylpo  users  9728 Sep  5 13:02 wm.com
-rw-r--r--   1 tnylpo  users  2688 Sep  5 13:02 wm.hlp

wm.com is the binary to be patched (wm.hlp is an associated data file). asm.com and ddt.com are the standard CP/M absolute assembler and debugger (ASM and DDT) which will be used to prepare resp. apply the patch. patch.asm contains the assembler source file of the patch. Note the size of wm.com, which is 9728 bytes.

First, the patch is assembled, which creates patch.hex, a file in the Intel Hex format.

CP/M ASSEMBLER - VER 2.0
01D8
000H USE FACTOR
END OF ASSEMBLY

Now the debugger is started, which relocates itself to the top of the TPA and loads wm.com into the TPA starting at address 0x100. The option -eb9728:wmnew.com asks tnylpo to save 9728 bytes (the size of wm.com) starting from address 0x100 to the file wmnew.com after the CP/M program (i.e. DDT) has terminated.

DDT VERS 2.2
NEXT  PC
2700 0100

DDT displays two hexadecimal numbers, the first of which is the first free memory address after the loaded program (0x2700 is decimal 9984, i.e. 0x100 plus 9728, the size of wm.com). Now DDT is used to apply the patch: The command i tells DDT the name of the patch file, and the command r reads it into memory (the Intel Hex format provides the necessary address information to apply the changes at the correct locations). Finally, g0 directs DDT to jump to adress 0, which causes it to terminate.

NEXT  PC
2700 0000

As soon as DDT terminates, tnylpo saves the memory contents as directed, creating a patched version of the executable, which can be tested and renamed.

-rw-r--r--   1 tnylpo  users  9728 Sep  5 13:06 wmnew.com