Dave's Free Press

Technology: CPU-Emulator-Memory-1.1004

 

Older stuff

CPU::Emulator::Memory - memory for a CPU emulator


NAME

CPU::Emulator::Memory - memory for a CPU emulator


SYNOPSIS

    my $memory = CPU::Emulator::Memory->new();
    $memory->poke(0xBEEF, ord('s'));
    
    my $value = $memory->peek(0xBEEF); # 115 == ord('s')


DESCRIPTION

This class provides a flat array of values which you can 'peek' and 'poke'.


METHODS

new

The constructor returns an object representing a flat memory space addressable by byte. It takes four optional named parameters:

file
if provided, will provide a disc-based backup of the RAM represented. This file will be read when the object is created (if it exists) and written whenever anything is altered. If no file exists or no filename is provided, then memory is initialised to all zeroes. If the file exists it must be writeable and of the correct size.

endianness
defaults to LITTLE, can be set to BIG. This matters for the peek16 and poke16 methods.

size
the size of the memory to emulate. This defaults to 64K (65536 bytes), or to the length of the string passed to bytes. Note that this does *not* have to be a power of two.

bytes
A string of characters with which to initialise the memory. Note that the length must match the size parameter.

peek, peek8

This method takes a single parameter, an address from 0 the memory size - 1. It returns the value stored at that address, taking account of what secondary memory banks are active. 'peek8' is simply another name for the same function, the suffix indicating that it returns an 8 bit (ie one byte) value.

peek16

As peek and peek8, except it returns a 16 bit value. This is where endianness matters.

poke, poke8

This method takes two parameters, an address and a byte value. The value is written to the address.

It returns 1 if something was written, or 0 if nothing was written.

poke16

This method takes two parameters, an address and a 16-bit value. The value is written to memory as two bytes at the address specified and the following one. This is where endianness matters.

Return values are undefined.


SUBCLASSING

Most useful emulators will need a subclass of this module. For an example, look at the CPU::Emulator::Memory::Banked module bundled with it, which adds some methods of its own, and overrides the peek and poke methods. Note that {peek,poke}{8,16} are *not* overridden but still get all the extra magic, as they are simple wrappers around the peek and poke methods.

You may use the _readRAM and _writeRAM methods for disk-backed RAM, and _read_file may be useful for ROM. These are only useful for subclasses:

_read_file
Takes a filename and the required size, returns the file's contents

_readRAM
Takes a filename and the required size, returns the file's contents and checks that the file is writeable.

_writeRAM
Takes a filename and a chunk of data, writes the data to the file.


BUGS/WARNINGS/LIMITATIONS

It is assumed that the emulated memory will fit in the host's memory.

When memory is disk-backed, the entire memory is written to disk on each poke().

The size of a byte in the emulated memory is the same as that of a char on the host machine. Perl only runs on machines with 8 bit bytes.

If you find any others, please report them using http://rt.cpan.org or by email to <bug-CPU-Emulator-Memory@rt.cpan.org>.


FEEDBACK

I welcome feedback about my code, including constructive criticism and bug reports. The best bug reports include files that I can add to the test suite, which fail with the current code in CVS and will pass once I've fixed the bug.

Feature requests are far more likely to get implemented if you submit a patch yourself.


SOURCE CODE REPOSITORY

git://github.com/DrHyde/perl-modules-CPU-Emulator-Memory.git


THANKS TO

Paulo Custodio for finding and fixing some bugs on Win32, see RT 62375, 62379


AUTHOR, LICENCE and COPYRIGHT

Copyright 2008 David Cantrell <david@cantrell.org.uk>

This module is free-as-in-speech software, and may be used, distributed, and modified under the same terms as Perl itself.


CONSPIRACY

This module is also free-as-in-mason software.