/ 
CPU-Z80-Disassembler-0.07
River stage zero No dependents
++
 / CPU::Z80::Disassembler::Instruction
Author image Paulo Custodio
and 1 contributors

NAME

CPU::Z80::Disassembler::Instruction - One Z80 disassembled instruction

SYNOPSIS

  use CPU::Z80::Disassembler::Instruction;
  $instr = CPU::Z80::Disassembler::Instruction->disassemble(
                    $memory, $addr, $limit_addr);
  $instr = CPU::Z80::Disassembler::Instruction->defb($memory, $addr, $count);
  $instr = CPU::Z80::Disassembler::Instruction->defb2($memory, $addr, $count);
  $instr = CPU::Z80::Disassembler::Instruction->defw($memory, $addr, $count);
  $instr = CPU::Z80::Disassembler::Instruction->defm($memory, $addr, $length);
  $instr = CPU::Z80::Disassembler::Instruction->defmz($memory, $addr);
  $instr = CPU::Z80::Disassembler::Instruction->defm7($memory, $addr);
  $instr = CPU::Z80::Disassembler::Instruction->org($memory, $addr);
  
  $instr->addr; $instr->next_addr;
  $instr->bytes; $instr->opcode; $instr->N; $instr->NN; $instr->DIS; $instr->STR;
  $instr->comment;
  print $instr->dump;
  print $instr->asm;            
  print $instr->as_string, "\n";

DESCRIPTION

This module represents one disassembled instruction. The object is constructed by one of the factory methods, and has attributes to ease the interpretation of the instruction.

CONSTRUCTORS

disassemble

Factory method to create a new object by disassembling the given CPU::Z80::Disassembler::Memory object at the given address.

The $limit_addr argument, if defined, tells the disassembler to select the longest possible instruction, that does not use the byte at $limit_add. The default is to select the shortest possible instruction.

For example, the sequence of bytes 62 6B is decoded as ld h,d if $limit_addr is undef.

If $limit_addr is defined with any value different from $addr + 1, where the second byte is stored, then the same sequence of bytes is decoded as ld hl,de.

To decode standard Z80 instructions, do not pass the $limit_addr argument.

To decode extended Z80 instructions, pass the address of the next label after $addr, or 0x10000 to get always the longest instruction.

If the instruction at the given address is an invalid opcode, or if there are no loaded bytes at the given address, the instrution object is not constructed and the factory returns undef.

defb

Factory method to create a new object by disassembling a defb instruction at the given address, reading one or $count byte(s) from memory.

defb2

Same as defb but shows binary data.

defw

Factory method to create a new object by disassembling a defw instruction at the given address, reading one or $count word(s) from memory.

defm

Factory method to create a new object by disassembling a defm instruction at the given address, reading $length character(s) from memory.

defmz

Factory method to create a new object by disassembling a defmz instruction at the given address, reading character(s) from memory until a zero terminator is found.

defm7

Factory method to create a new object by disassembling a defm7 instruction at the given address, reading character(s) from memory until a character with bit 7 set is found.

org

Factory method to create a new ORG instruction.

ATTRIBUTES

memory

Point to the memory object from where this instruction was disassembled.

addr

Address of the instruction.

size

Size of the instruction, in bytes.

next_addr

Returns the address that follows this instruction.

next_code

Returns the list with the next possible addresses where the code flow can continue.

For an instruction that does not branch, this is the same as next_addr.

For a decision-branch instruction, these are the next_addr and the NN.

For an instruction that breaks the flow (e.g. ret), this is an empty list.

A call or rst instruction is considered as breaking the flow, because the called routine might manipulate the return pointer in the stack, and the bytes after the call or rst instruction can be data bytes.

bytes

Reference to a list of the instruction bytes. The bytes are retrieved from the CPU::Z80::Disassembler::Memory object.

opcode

Canonical assembly instruction, e.g. 'ld a,(NN)'. The possible argument types are N, NN, DIS and STR. There is one method to get/set each of the argument types.

N

8-bit data used by the instruction.

N2

8-bit data used by the instruction, to be shown in base 2.

NN

16-bit data used by the instruction.

DIS

Offset for index register.

STR

String for defm* instructions.

comment

Comment to be written after a '; ' at the end of the line.

format

Returs the hash of special formating functions for each type of argument. These functions, if defined, are called instead of the ones in the CPU::Z80::Disassembler::Format module to format each type of argument.

For example, to format the 8-bit argument of an instruction as decimal:

  $instr->format->{N} = sub { my $v = shift; return "$v" };

PREDICATES

is_code

Return TRUE if the instruction is a Z80 assembly opcode, FALSE if it is one of the data definition or org instructions.

is_call

Return TRUE if the instruction is a call instruction, i.e. call or rst.

is_branch

Return TRUE if the instruction may branch to another address, the address is stored in the NN attribute. This is either a jump or a call instruction.

is_break_flow

Return TRUE if the instruction breaks the flow at this point and jumps to some other part of the code. A call instruction is considered as breaking the flow, see next_code above.

FUNCTIONS

as_string

Returns the disassembled instruction opcode and arguments.

dump

Returns the disassembly dump ready to print, containing address, bytes and instruction, followed by newline.

asm

Returns the disassembly asm line ready to print, containing instruction and comments, followed by newline.

AUTHOR, BUGS, FEEDBACK, LICENSE AND COPYRIGHT

See CPU::Z80::Disassembler.