readme

A Zilog Z80 simulator, debugger and profiler tailored for ZX Spectrum development (but generic enoug

LICENSE
-------

This program is licensed under the GNU General Public Licence (GPL), version
2 or, at your choice, any following version. You should find a copy of the
GPL inside the file 'LICENSE' in this directory.


SYNTAX
------

The syntax for the Z80Sim program is:

	z80sim [<options>] <binaryfile>

<binaryfile> contains a raw Z80 program, which is loaded at location 0x0000
by default.

<options> can be one or more of the following:
  --trace              shows the state of the processor after each
                       instruction executed
  --symbols <file.sym> uses a .sym file as generated by SDCC
                       (???CHECK) to learn about global symbols
                       used in the program
  --dbg <file.dbg>     uses a .dbg file as generated by MakeDBG to
                       be able to refer to C source code lines


INTRODUCTION
------------

Z80Sim is a program that attempts to simulate the behaviour of the Zilog Z80
processor, as documented by Zilog. It is able to load a binary program
specified by the user into memory that is mapped onto the 64Kb address space
of the Z80, and while it executes the program, it can give some information
that is hopefully useful for the user to improve the program. This
information can include:

- The internal state of the simulated processor after each instruction
executed, including the registers AF, BC, DE, HL and the equivalents in the
second bank, IX, IY, PC, SP, (!!!TODO) I, R, IFF1, IFF2
- Each instruction executed in its mnemonic (assembly) form, with direct
addresses shown as literals instead of plain numbers if a symbols map is
present
- Instructions that changed neither the internal state of the processor
(except for the program counter and the R register) nor the main memory, to
help locale programming errors

Additional information is provided for programs that include special
instructions that serve as Z80Sim directives; specifically, the instruction
RST 0x08 gets trapped by Z80Sim, which then performs various actions
depending on the value it finds in register A. A library of C functions is
provided that contains wrappers to these functionalities.
The information Z80Sim can show this way includes:

- ASCII characters that the program instructs Z80Sim to print; a C functions
for printing strings is provided
- Accesses to memory that has been defined illegal by the program; the
addresses or ranges of addresses that Z80Sim considers illegal can be changed
by the program during execution, or (!!!TODO) guessed by Z80Sim if a debug
information file is loaded
- (!!!TODO) An outlined view of function entries and exits; the directives
needed by this features can be added to the code automatically by the SDCC C
compiler
- (!!!TODO) Statistic views of the profile of program execution, with data
about time spent in each function, number of times each function has been
called, and percentage by which each functions contributed to the total
execution time

Moreover, Z80Sim can interrupt the execution of a program when specific
events are detected, namely:
- (!!!TODO) When a function is entered or exited (if the relevant directives
are present in the code)
- (!!!TODO) When an instruction that was not documented by Zilog is executed
- (!!!TODO) When an instruction that does not change the state is executed
- When an instruction accessing memory that has been declared illegal is
executed
- When a Z80 register reaches a value specified by the user
- When the value in a memory location specified by the user changes or
reaches a specific value

Such an interruption is called a 'trap'. After a trap, the integrated
debugger is invoked.

The Z80 can communicate with the external world by means of the address/data
buses ("memory" and "port" accesses) and the interrupt request (IRQ) and
non-maskable interrupt (NMI) pins.
(!!!TODO) Z80Sim can send information from these places to TCP/IP sockets,
and receive information from TCP/IP sockets to put in these places. This
allows one to write programs that communicate with Z80Sim via TCP/IP and
which, together with Z80Sim, form an emulation of a complete computing
system, such as the ZX Spectrum line of computers.


THE DEBUGGER
------------

The debugger is entered when a trap occurs or when the user explicitly
requests interruption by raising a SIGINT (usually with CTRL+C).
Here we'll concentrate on traps caused by a change in the value of a register
or memory location.
The debugger command 'watch <expression>' can be used  to specify such a
condition, which is called a "watchpoint". Whenever the value of <expression>
changes, a trap is raised.

The syntax of <expression> is mostly a subset of C expression syntax. The
following operators are available:

 - '(' and ')' modify the precedence of evaluation
 - '*' dereferences the memory location on its right ('*0x8000' is the value
   at address 0x8000)
 - '+' adds its two operands together
 - '-' subtracts the right-side operand from the left-side operand
 - '&' returns the bitwise And of its two operands
 - '|' returns the bitwise Or of its two operands
 - '^' returns the bitwise Exclusive Or of its two operands
 - '~' returns the binary complement of the operand on its right
 - '>>' returns the left-side operand shifted to the right by <n> binary
   positions, where <n> is the value of the right-side operand; the padding
   bits inserted on the left are not set
 - '<<' returns the left-side operand shifted to the left by <n> binary
 positions, where <n> is the value of the right-side operand; the padding bits
 inserted on the right are not set
 - '==' returns 1 if its two operands evaluate to the same value, 0 otherwise
 - '!=' behaves like '==' with the return values exchanged
 - '<' and '<=' return 1 if the left-side operand is  smaller than (or equal
   to, in the case of '<=') the right-side operand
 - '>' and '>=' return 1 if the left-side operand is greater than (or equal
   to, in the case of '>=') the right-side operand
 - '.l' and '.b' return the lowest 8 bits of the operand on its left; so
   '*<address>.b' is equivalent to '(*<address>)&0x00ff)'
 - '.h' returns the highest 8 bits of the operand on its left; so
   '<register>.h' is equivalent to '(<register>&0xff00)>>8'

The values manipulated by the operators above are 16-bit unsigned values
(i.e. Z80 pointers or register pairs). A value can be specified in one of the
following ways:

 - an integer in its (decimal, hexadecimal or octal) literal representation,
   with hexadecimal values prefixed with '0x' and octals with '0'; values
   greater than 0xffff wrap around
 - a register specification: '$PC', '$SP', '$AF', '$BC', '$DE', '$HL', '$IX'
   or '$IY'; the value returned corresponds to the contents of the register
   at the time of evaluation
 - an exported (???CHECK) global symbol, such as 'MyGlobalVariable'; if
   'MyGlobalVariable' is stored at the memory address <n>, the notation is
   equivalent to '*<n>', while '&MyGlobalVariable' is equivalent to '<n>
   Other values result in a parsing error.

Some examples of valid expressions:
 - ($PC==&MisbehavingFunction) traps as soon as the function
   MisbehavingFunction() is entered
 - ($SP<StackFrameLowest | $SP>StackFrameHighest) traps when the stack pointer
   exceeds the bounds specified by the variables StackFrameLowest and
   StackFrameHighest
 - (*$SP==0xDEAD) traps when the value on top of the stack becomes 0xDEAD
 - (*$PC.l==0x00) traps when a NOP (0x00) is executed
 - ($AF.h&0x01) traps when the Carry flag (???CHECK) changes value

The debugger command 'eval <expression>' only returns the current walue of
<expression> without setting a watchpoint.

The syntax for other commands available in the debugger can be obtained by
typing the command 'help' (!!!TODO).

MEMORY PROTECTION
-----------------
When program execution begins, every memory byte is flagged as freely
readable and writable by the program.
Memory can later be protected from reading, writing or both by the program or
inside the debugger (!!!TODO), on a byte per byte basis.

The following functions are used to (un)protect memory from a C program:
  _SimReadProtect(void* Start, unsigned int Span);
  _SimWriteProtect(void* Start, unsigned int Span);
  _SimUnprotect(void* Start, unsigned int Span);
These functions protect or unprotect 'Span' memory bytes starting at address
'Start'.

The following macros are also defined:
  _SimReadProtectVar(lvalue)
  _SimWriteProtectVar(lvalue)
  _SimUnprotectVar(lvalue)
So, for example, writing
  _SimWriteProtectVar(MyVariable);
is equivalent to
  _SimWriteProtect(&MyVariable, sizeof(MyVariable));

When an attempt to read/write from/to a read/write protected memory location
is made, a trap is raised.