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(plusorgif applicable). . 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.
- org
-
an integer, Used in conjunction with
bytes, load the data at the specified offset in bytes
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.
Bug reports should be made on Github or by email.
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.