# Aliados documentation.

(C) 2004-2005 Julián Albo.

Use and distribution allowed under the terms of the GPL license.

Last revision date: 17-may-2005

Current Aliados version: 0.2.0 (unfinished).

## Index.

- Introduction.
- 1 - Command line usage.
- 2 - Built in commands.
  - 2.1 - CP/M commands.
    - 2.1.1 - DIR
    - 2.1.2 - ERA
    - 2.1.3 - USER
  - 2.2 - Aliados commands.
    - 2.2.1 - EXIT
    - 2.2.2 - DEBUG
    - 2.2.3 - LOAD
    - 2.2.4 - GO
    - 2.2,5 - POKE
- 3 - Integrated debugger commands.
  - 3.1 - Generalities.
  - 3.2 - D. Display.
  - 3.3 - F. Fill.
  - 3.4 - G. Go.
  - 3.5 - L. List.
  - 3.6 - M. Move.
  - 3.7 - P. Passpoint.
  - 3.8 - Q. Quit.
  - 3.9 - S. Set.
  - 3.10 - T. Trace.
  - 3.11 - U. Untrace.
- Epilogue.

## Introduction.

Aliados is a CP/M emulator for Linux an other unix. It emulates CP/M itself, not a machine running a version of CP/M. Uses a emulated Z80 CPU and captures all BDOS and BIOS calls to execute natively. The disk drives are assigned to directories and all files with names that meet CP/M filenames conventions are seen as CP/M files.

The emulation is not complete yet, but is very usable and can run many programs, some CP/M Plus native utilities included. Devices supported are the console and the list device, the last can be directed to the print spooler or to a file.

The console is an approximated emulation of the Amstrad PCW series, that uses VT52 control codes, unless options for raw mode are specified (see options).

## 1 - Command line usage.

Aliados is invoked from command line a:

    	aliados [options] [ program [arguments] ]

If program is specified, is readed from the native filesystem, not the CP/M disks. Arguments are concatenated separated with a space and passed as command line arguments to the program, without converting it to upper case. If no program is specified, the interactive mode is entereed, using aliados own command processor.

If no option specify another thing, Disc drive A: is assigned to the current directory, and is set as default and temporary drive.

### Options.

--
  End of options. The following arguments will be considered program and arguments, even if begins with '-'.
-c
  Same as --command.
-d
  Debug mode. Same as -s and -z together.
-s
  Debug system mode. Debug information is showed about the CP/M functions called.
-v
  Same as --version.
-z
  Debug Z80 mode. A dissassembly of each Z80 instruction is showed before executing it.
--argdisk
  If specified, all arguments are examined and if they have a directory part, a disk letter is assigned to each directory and the argument is passed with the directory part replaced by the correspondindg disk letter and ':'. Argumentes that ends with / are passed as disks. The drives are assigned from P: to A:, skipping disks already assigned with other options.
--autodisk
  Searches the current directory for directories with names diskA, diskB... and assigns the corresponding disk letter to each of them.
--command
  Takes one argument. The argument is executed as command line, interpreted as if were introduced in interactive mode.
--defdisk
  Takes one arguments, a drive letter, wich will be setted as default drive.
--disk
  Takes two arguments, drive letter and directory. The drive letter can be upper or lower case, and can be followed by ':'.
--prefix
  Specifies a one letter prefix for the bultin aliados commands. Allows the use of extern commands with the same name.
--tpaend
  Set the upper address of the transient program area. Useful to test programs for use in CP/M machines with less memory available.
--printer
  Direct list device to the file specified. If this option is not present, list output is directed to the spooler.
--raw
  Same as --rawin and --rawout used togheter.
--rawin
  Raw input mode. No terminal emulation on input is done, the input is passed unchanged to CP/M.
--rawout
  Raw output mode. No terminal emulation on output is done, CP/M output is passed unchanged to the standart output.
--wskeys
  Assign to the arrow keys the control codes used in Wordstar and other word processor for cursor movement. No effect in raw input mode.

## 2 - Built in commands.

### 2.1 - CP/M commands.

Some of the CP/M permanent command are supported, but without all his options.

#### 2.1.1 - DIR

As the CP/M command. CP/M Plus options currently not supported.

#### 2.1.2 - ERA

As the CP/M 2.2 command. CP/M Plus options currently not supported,

#### 2.1.3 - USER

Change current user number. Sets the value seen by the programas and by the command processor, but currently has no effect in disk access.

### 2.2 - Aliados commands.

These commands are handled in a special way: if the --prefix option is used they are not recognized without the prefix specified. For example, if --prefix @ is used, EXIT will not be recognized, @EXIT must be used.

#### 2.2.1 - EXIT

EXIT exits the aliados command line session.

#### 2.2.2 DEBUG

DEBUG enters the integrated debugger.

The rest of the command line is parsed as a program name and his arguments, the program is loaded and his parameters established giving all ready to execute in the debugger. The debugger prompt "#" is then showed and debugger commands are accepted.

The debugger commands are described in chapter 3.

#### 2.2.3 LOAD

LOAD loads a program an establishes his parameters preparing it to execution but does not execute it. Is useful in combination with POKE and GO.

#### 2.2.4 GO

GO starts execution of the program currently in memoria. The start address is the beginning of the TPA, 0100 hex, or the start address specified as parameter in hexadecimal or in decimal prefixed by '#'.

#### 2.2.5 POKE

POKE modifies the system memory. Is useful after a LOAD and before a GO to do program modifications and run with him. The syntax is POKE address list_of_items, where address is the hexadecimal addres where the items will be placed and each item on the list can be a string delimited by double quotes or a hexadcimal number in the range 00-FF.

## 3 - Integrated debugger commands.

### 3.1 - Generalities.

All numeric parameters are specified by default in hexadecimal, to use decimal they must prefixed by '#'.

### 3.2 - D Display.

Display memory. The syntax is D[[begin][,end]]. Display the memory from the begin address to the end address, in lines of 16 bytes each. The numeric values of the memory positions are showed, followed by the character interpretation. If begin is no specified the position following the displayed with the las D comand, or 100h is if the first time. If end is not specified 11 complete lines are displayed.

### 3.3 - F Fill.

Fill memory. The syntax is Fstart,end,value. Fills from start to end with the byte value.

### 3.4 - G Go.

Start execution. The syntax is G[start][,list_of_breakpoints]. The excution is started at the start position, or at the current program count if not specified. The list of breakpoints is a comma separated list of memory address, when the excution will end if reched. The breakpoints established in that way are temporaries, to create permanent breakpoints use the P command.

If the excution is terminated by a program exit the debug sesssion ends. If is terminated by reaching a breakpoint, continues.

### 3.5 - L List.

Does a disassmbler listing. The syntax is L[start][,end]. The positions from start to end are listed. If start is not specified begins at the position following the last List command, 100h the first time, or at the current program counter depending on the last commands executed.

### 3.6 - M Move.

Move a block of memory. The syntax is Mfrom,to,destination. The block that starts in from and ends in to (included) is moved to destination. The result is correct even if origin and destination blocks overlaps.

### 3.7 - P Passpoint.

Stablishes a breakpoint. The syntax is P[address[,count]]. If count is not specified 1 is assumed. When the excution (with the G commnad) pass the address the counter is decremented and if it reach 0 execution is stopped and the counter is restored to 1. If count is 0, the breakpoint existent at the address is deleted. If no parameter is specified the current breakpoints are listed.

### 3.8 - Q Quit.

Quits the debugger.

### 3.9 - S Set.

Visualizes and optionally modifies memory. The syntax is Saddress. Beginning in address the byte at that position is showed and the user is prompted. A . as response finishes the S command. An empty line gives the memory untouched and if a hexadecimal number between 0 and FF is given the number is stored in the current position, then the address is incremented and the command continues. With any other response a "?" is showed and the user is prompted again in the same address.

### 3.10 - T Trace.

Trace program instruction. The syntax is T[n]. If n is not specified 1 is assumed. The registers of the CPU and the disassembly of the instruction at the program counter are showed and the instruction executed, as many times as the value of n.

### 3.11 - U Untrace

As the T command, but the CPU state is only showed one time at the beginning.

## Epilogue.

That's all folks!

Send comments and criticisms to: