view release on metacpan or  search on metacpan

lib/CPU/Z80/Disassembler.pm  view on Meta::CPAN

		chomp($block_comment);
		$self->_block_comments->[$addr] ||= "";
		$self->_block_comments->[$addr] .= "$block_comment\n";
	}
}

#------------------------------------------------------------------------------

=head2 line_comments

Appends each of the given line comments to the instrutions starting at 
the given address, one comment per instruction.

=cut

#------------------------------------------------------------------------------
sub line_comments {
	my($self, $addr, @line_comments) = @_;
	
	for (@line_comments) {
		my $instr = $self->instr->[$addr];
		croak("Cannot set comment of unknown instruction at ".format_hex4($addr))
			unless $instr;
		my $old_comment = $instr->comment // "";
		$old_comment .= "\n" if $old_comment;
		$instr->comment($old_comment . $_);
		$addr += $instr->size;
	}
}

#------------------------------------------------------------------------------

=head2 relative_arg

Shows the instruction argument (NN or N) relative to a given label name.
Label name can be '$' for a value relative to the instruction pointer.

=cut

#------------------------------------------------------------------------------

=head2 create_control_file

  $dis->create_control_file($ctl_file, $bin_file, $addr, $arch);

Creates a new control file for the given input binary file, starting at the given address
and for the given architecture. 

The address defaults to zero, and the architecture to undefined. The architecture may be
implemented in the future, for example to define system variable equates for the given
architecture.

It is an error to overwrite a control file.

The Control File is the input file for a disassembly run in an interactive disassembly
session, and the outout is the <bin_file>.asm. After each run, the user studies the output
.asm file, and includes new commands in the control file to add information to the 
.asm file on the next run.

This function creates a template control file that contains just the hex dump of the 
binary file and the decoded assembly instruction at each address, e.g.

  0000                         :F <bin_file>
  0000 D3FD       out ($FD),a
  0002 01FF7F     ld bc,$7FFF
  0005 C3CB03     jp $03CB

The control file commands start with a ':' and refer to the hexadecimal address at the 
start of the line. 

Some commands operate on a range of addresses and accept the inclusive range limits separated
by a single '-'.

A line starting with a blank uses the same address as the previous command.

A semicolon starts a comment in the control file.

  0000      :;        define next address as 0x0000
            :<cmd>  ; <cmd> at the same address 0x0000
  0000-001F :B      ; define a range address of bytes

The dump between the address and the ':' is ignored and is helpfull as a guide while adding 
information to the control file.

=head2 load_control_file

  $dis->load_control_file($ctl_file);

Load the control file created by <create_control_file> and subsequently edited by the user
and create a new .asm disassembly file.

=head1 Control File commands

=head2 Include

Include another control file at the current location.

  #include vars.ctl

=head2 File

Load a binary file at the given address.

  0000 :F zx81.rom

=head2 Code

Define the start of a code routine, with an optional label. The code is not known to be
stack-safe, i.e. not to have data bytes following the call instruction. The disassembler
stops disassembly when it cannot determine if the bytes after a call instruction are 
data or code.

  0000 :C START

=head2 Procedure

Define the start of a procedure with a possible list of arguments following the call
instruction.

The signature is a list of {'B','W','C'}+, identifing each of the following items
after the call instruction (Byte, Word or Code). In the following example the call