execution

Documentation

Overview

Package execution tracks the result of instruction execution on the CPU. The Result type stores detailed information about each instruction encountered during a program's execution on the CPU. A Result can then be used to produce output for disassemblers and debuggers with the help of the disassembly package.

The Result.IsValid() function can be used to check whether results are consistent with the instruction definition. The CPU package doesn't call this function because it would introduce unwanted performance penalties, but it's probably okay to use in a debugging context.

Index

• type Result
  • func (r Result) IsValid() error
  • func (r *Result) Reset()
  • func (r *Result) String() string

Types

type Result

type Result struct {
	// a reference to the instruction definition
	Defn *instructions.Definition

	// the number of bytes read during instruction decode. if this value is
	// less than Defn.Bytes then the instruction has not yet been fully decoded
	ByteCount int

	// the address at which the instruction began
	Address uint16

	// instruction data is the actual instruction data. so, for example, in the
	// case of branch instruction, instruction data is the offset value.
	InstructionData uint16

	// the actual number of cycles taken by the instruction - usually the same
	// as Defn.Cycles but in the case of PageFaults and branches, this value
	// may be different
	Cycles int

	// whether an extra cycle was required because of 8 bit adder overflow
	PageFault bool

	// whether a known buggy code path (in the emulated CPU) was triggered
	CPUBug string

	// error string. will be a memory access error
	Error string

	// whether branch instruction test passed (ie. branched) or not. testing of
	// this field should be used in conjunction with Defn.IsBranch()
	BranchSuccess bool

	// whether this data has been finalised - some fields in this struct will
	// be undefined if Final is false
	Final bool
}

Result records the state/result of each instruction executed on the CPU. Including the address it was read from, a reference to the instruction definition, and other execution details.

The Result type is updated every cycle during the execution of the emulated CPU. As the execution continues, more information is acquired and detail added to the Result.

The Final field indicates whether the last cycle of the instruction has been executed. An instance of Result with a Final value of false can still be used but with the caveat that the information is incomplete. Note that a Defn of nil means the opcode hasn't even been decoded.

func (Result) IsValid

func (r Result) IsValid() error

IsValid checks whether the instance of Result contains information consistent with the instruction definition.

func (*Result) Reset

func (r *Result) Reset()

Reset nullifies all members of the Result instance.

func (*Result) String

func (r *Result) String() string

very rough disassembly. it should not be used in preference to the disassembly package if at all possible. none-the-less it is useful for development purposes.