view release on metacpan or  search on metacpan

lib/CPU/Emulator/Z80/Manual.pod  view on Meta::CPAN

=head1 NAME

CPU::Emulator::Z80::Manual

=head1 DESCRIPTION

CPU::Emulator::Z80 implements a Z80 emulator.  See its manpage for
nitty-gritty details about interfacing with it.  This manpage, by
contrast, serves as a HOWTO.

=head1 WHAT ELSE DO I NEED?

First of all, you need perl 5.6.  You will also need a few extra
perl modules.  Those will be automatically installed for you if
you use the CPAN.pm module to install this.

If you want to write your own software that uses this module, then
you will need to know how to program a Z80 processor.  The rest
of this document assumes that you do.

=head1 HOW DO I CREATE A CPU?

    my $cpu = CPU::Emulator::Z80->new();

This will initialise it with 64K of banked memory attached, and
set all registers to zero.  If you want a different memory model,
then pass a CPU::Emulator::Memory object to the constructor
using the 'memory' parameter:

    my $cpu = CPU::Emulator::Z80->new(
        memory => CPU::Emulator::Memory->new(
            size => 0x4000,
            file => 'memory.ram'
        )
    );

Generally, the default is what you want, but note that the default
configuration does *not* backup the CPU's RAM to a file.  Note that
if you define your own memory, it *must* be little-endian.

=head1 HOW DO IT GET A PROGRAM INTO MEMORY

The hard way, which is also most suitable for very small hacks, is
to peek() and poke() the memory directly.  You can get at the memory
using the memory() method.

Alternatively, you can initialise RAM from a file by creating your
own memory object, or from a string by passing a scalar with the
'memory' parameter:

    my $cpu = CPU::Emulator::Z80->new(
        memory => 'blob of impenetrable binary gibberish'
    );

If you are using banked memory then you can bank() a ROM image file.

=head1 HOW DO I RUN A PROGRAM?

After loading a program into memory, use the run() method.  With
no parameters it will run forever, starting wherever the PC points.
Pass a number to it and it will run for that many instructions.

Note that the repeating instructions like LDIR count as several
instructions.  That's because they are really just a non-repeating
instruction, plus a conditional decrement of PC, so the same
instruction gets executed several times.  This is the correct
behaviour.

The astute reader will have noticed that you can single-step your
Z80 programs with run(1), and consequently stop "half way through"
a repeating instruction.

The run() method will also terminate if it executes a STOP instruction.

=head1 WHAT THE HELL IS THE 'STOP' INSTRUCTION?

It's something I added cos it's useful for emulators.  It's a three
byte instruction, the first two bytes being any combination of
0xDD and 0xFD, the third being 0x00.  Strictly speaking this breaks
compatibility with real Z80s, as the two byte prefix is legal but
stupid.  If this is a problem for you please contact me and we can
try to find a work-around.

You can tell the difference between the CPU stopping because it
reached a STOP instruction and for any other reason by using the
stopped() method.

=head1 HOW DO I GET DATA OUT?

The hard way (which, again, is also the most suitable for small hacks)
is to peek() the memory directly.  You can also inspect register
contents:

    print "A register is ".$cpu->register('A')->get();

See also "I/O and Interrupts" below.

=head1 HOW DO I ALTER A RUNNING PROGRAM?