CPU::Z80::Assembler - a Z80 assembler
use CPU::Z80::Assembler; $CPU::Z80::Assembler::verbose = 1; our $CPU::Z80::Assembler::fill_byte = 0xFF; $binary = z80asm(q{ ORG 0x1000 LD A, 1 ... }); $binary = z80asm(@lines); $binary = z80asm('#include <file.asm>'); open($fh, $file); $binary = z80asm(sub {<$fh>});
This module provides a single subroutine which implements a Z80 assembler.
By default the 'z80asm' subroutine is exported.
This takes as parameter a list of either text lines to parse, or iterators that return text lines to parse.
The list is passed to the Asm::Preproc that takes care of file includes and handles the %line and #line lines generated by external preprocessors like cpp or nasm. The result of this stage is a CPU::Z80::Assembler::Stream of Asm::Preproc::Line objects.
This stream of lines is passed on to the CPU::Z80::Assembler::Lexer to scan the input and return a CPU::Z80::Assembler::Stream of CPU::Z80::Assembler::Token objects.
The stream of tokens is passed on to CPU:Z80::Assembler::Parser that parses the input and generates the object image in CPU::Z80::Assembler::Program. Assembly macro expansion is handled at this stage by CPU::Z80::Assembler::Macro.
The assembly program is composed by a list of CPU::Z80::Assembler::Segment, each representing one named section of code. Each segment is composed by a list of CPU::Z80::Assembler::Opcode, each representing one assembly instruction.
The output object code is returned as a string.
If the $CPU::Z80::Assembler::verbose variable is set, an output listing is generated by CPU::Z80::Assembler::List on standard output.
Assembly is done in four steps:
input is preprocessed, scanned and split into tokens
tokens are parsed and converted to lists of opcodes
addresses for each opcode are allocated
object code is generated for each opcode, computing all expressions used; the expressions are represented by CPU::Z80::Assembler::Expr.
The z80masm program (installed as part of this module) calls the z80asm() function to assemble an input source file, generate an output binary file, and produce an assembly listing on standard output.
Instructions are separated by new lines or colons ':', and have the following format, in ASCII. Comments start with ';'. Lines starting with '#' are ignored, to handle files generated by pre-processors.
; comment beginning with ; # comment beginning with # as first char on a line [LABEL [:]] INSTRUCTION [: INSTRUCTION ...] [; optional comments] LABEL [:] LABEL = EXPRFESSION [; ...]
See CPU::Z80::Assembler::Lexer for details on the allowed source file tokens.
Numbers can be supplied in either decimal, hexadecimal or binary. Numbers must start with a digit 0 to 9:
159
0xFA21, 0FA21H, $FA21, #FA21
0b12, 12B, %12
A byte of data
A 16-bit word of data, in little-endian order. So the example would actually insert 0x34 followed by 0x12.
A literal string, either single- or double-quoted. Can optionally be followed by a comma-seperated list of bytes. Quoted text can not include the quotes surrounding it or newlines.
Tell the assembler to start building the code at this address. Must be the first instruction and can only appear once. If absent, defaults to 0x0000.
Recursively include another file at the current source file.
Standard Z80 mnemonics as well as the "unofficial" Z80 instructions are supported.
The RST instruction takes as its parameter either the address to jump to or the reset vector number - this is just the address / 8.
This means that, for example, RST 0x28 == RST 5.
The DJNZ and JR instructions take an address as their destination, not an offset. If you need to use an offset, do sums on $. Note that $ is the address of the *current* instruction. The offset needs to be calculated from the address of the *next* instruction, which for these instructions is always $ + 2.
This extra instruction (which assembles to 0xDD 0xDD 0x00) is provided for the convenience of those using the CPU::Emulator::Z80 module.
Labels must start with a letter or underscore, and consist solely of letters, underscores and numbers. They default to having the value of the address they are created at. If you want to assign another value, then you can say:
label = 0x1234
You can use $ to refer to the current address. Mathemagical operations are allowed too - the value is parsed as perl, and you can refer to other labels as their name:
label = $ + 8 otherlabel = label / 2 + 3
Macros are supported. See CPU::Z80::Assembler::Macro for details.
We welcome feedback about our code, including constructive criticism. Bug reports should be made using http://rt.cpan.org/.
CPU::Z80::Assembler::Lexer CPU::Z80::Assembler::Macro CPU::Z80::Assembler::Parser CPU::Emulator::Z80
Copyright (c) 2008-2009, David Cantrell <david@cantrell.org.uk>, Paulo Custodio <pscust@cpan.org>
This software is free-as-in-speech software, and may be used, distributed, and modified under the terms of either the GNU General Public Licence version 2 or the Artistic Licence. It's up to you which one you use. The full text of the licences can be found in the files GPL2.txt and ARTISTIC.txt, respectively.
This software is also free-as-in-mason.
To install CPU::Z80::Assembler, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CPU::Z80::Assembler
CPAN shell
perl -MCPAN -e shell install CPU::Z80::Assembler
For more information on module installation, please visit the detailed CPAN module installation guide.