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


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


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



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


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.


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


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


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


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.


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.


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.


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:


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


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


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


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.


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.




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


Copyright 2008 David Cantrell <>

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


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