arm7tdmi

Documentation

Overview

Package arm7tdmi imlplements the ARM7TDMI instruction set as defined in the ARM7TDMI Instruction Set Reference:

http://www.ecs.csun.edu/~smirzaei/docs/ece425/arm7tdmi_instruction_set_reference.pdf

For this project we only need to emulte the Thumb architecture. The strategy for this was to implement the nineteen opcode formats. As of writing only format 17, software interrupts, remain unimplemented. To this end, the following reference was preferred:

http://bear.ces.cwru.edu/eecs_382/ARM7-TDMI-manual-pt1.pdf

More detailed explanations of Thumb instruction were found in chapter A7.1 of the ARM Architecture Reference Manual. In particular the side-effects of particular instructions were found in the supplied pseudo-code. Where appropriate, the pseudo-code has been included as a comment in the Go source.

https://www.cs.miami.edu/home/burt/learning/Csc521.141/Documents/arm_arm.pdf

Reference for the ARM7TDMI-S, as used in the Harmony cartridge formats. This contains the cycle information for all ARM instructions.

https://developer.arm.com/documentation/ddi0234/b

Specific information about the NXP ARM7TDMI-S used by the Harmony cartridge. This contains good information about the MAM.

https://www.nxp.com/docs/en/user-guide/UM10161.pdf

And the errata, explaining a bug in the MAM that is experienced in the some versions of the Harmony cartridge.

https://www.nxp.com/docs/en/errata/ES_LPC2103.pdf

Index

• Constants
• type ARM
  • func NewARM(mmap memorymodel.Map, prefs *preferences.ARMPreferences, mem SharedMemory, ...) *ARM
  • func (arm *ARM) ClearCaches()
  • func (arm *ARM) CoProcID() string
  • func (arm *ARM) Plumb(mem SharedMemory, hook CartridgeHook)
  • func (arm *ARM) Run(mamcr uint32) (uint32, float32, error)
  • func (arm *ARM) SetDeveloper(dev mapper.CartCoProcDeveloper)
  • func (arm *ARM) SetDisassembler(disasm mapper.CartCoProcDisassembler)
  • func (arm *ARM) Step(vcsClock float32)
  • func (arm *ARM) String() string
• type ARMinterruptReturn
• type BranchTrail
• type CartridgeHook
• type DisasmEntry
  • func Disassemble(opcode uint16) DisasmEntry
  • func (e DisasmEntry) CSV() string
  • func (e DisasmEntry) Key() string
  • func (e DisasmEntry) String() string
• type DisasmSummary
  • func (s DisasmSummary) String() string
• type SharedMemory

Constants

const (
	N cycleType = 'N'
	I cycleType = 'I'
	S cycleType = 'S'
)

const CoProcID = "ARM7TDMI"

CoProcID is the ID returned by the ARM type. This const value can be used for comparison purposes to check if a mapper.CartCoProcBus instance is of the ARM type.

const CycleLimit = 1000000

the maximum number of cycles allowed in a single ARM program execution. no idea if this value is sufficient.

03/02/2022 - raised to accomodate CDFJBoulderDash development

Types

type ARM

type ARM struct {

	// the speed at which the arm is running at and the required stretching for
	// access to flash memory. speed is in MHz. Access latency of Flash memory is
	// 50ns which is 20MHz. Rounding up, this means that the clklen (clk stretching
	// amount) is 4.
	//
	// "The pipelined nature of the ARM7TDMI-S processor bus interface means that
	// there is a distinction between clock cycles and bus cycles. CLKEN can be
	// used to stretch a bus cycle, so that it lasts for many clock cycles. The
	// CLKEN input extends the timing of bus cycles in increments of of complete
	// CLK cycles"
	//
	// Access speed of SRAM is 10ns which is fast enough not to require stretching.
	// MAM also requires no stretching.
	//
	// updated from prefs on every Run() invocation
	Clk float32

	// rather than call the cycle counting functions directly, we assign the
	// functions to these fields. in this way, we can use stubs when executing
	// in immediate mode (when cycle counting isn't necessary)
	//
	// other aspects of cycle counting are not expensive and can remain
	Icycle func()
	Scycle func(bus busAccess, addr uint32)
	Ncycle func(bus busAccess, addr uint32)
	// contains filtered or unexported fields
}

ARM implements the ARM7TDMI-S LPC2103 processor.

func NewARM

func NewARM(mmap memorymodel.Map, prefs *preferences.ARMPreferences, mem SharedMemory, hook CartridgeHook, pathToROM string) *ARM

NewARM is the preferred method of initialisation for the ARM type.

func (*ARM) ClearCaches

func (arm *ARM) ClearCaches()

ClearCaches should be used very rarely. It empties the instruction and disassembly caches.

func (*ARM) CoProcID

func (arm *ARM) CoProcID() string

CoProcID implements the mapper.CartCoProcBus interface.

func (*ARM) Plumb

func (arm *ARM) Plumb(mem SharedMemory, hook CartridgeHook)

Plumb should be used to update the shared memory reference. Useful when used in conjunction with the rewind system.

func (*ARM) Run

func (arm *ARM) Run(mamcr uint32) (uint32, float32, error)

Run will continue until the ARM program encounters a switch from THUMB mode to ARM mode. Note that currently, this means the ARM program may run forever.

Returns the MAMCR state, the number of ARM cycles consumed and any errors.

func (*ARM) SetDeveloper

func (arm *ARM) SetDeveloper(dev mapper.CartCoProcDeveloper)

SetDeveloper implements the mapper.CartCoProcBus interface.

func (*ARM) SetDisassembler

func (arm *ARM) SetDisassembler(disasm mapper.CartCoProcDisassembler)

SetDisassembler implements the mapper.CartCoProcBus interface.

func (*ARM) Step

func (arm *ARM) Step(vcsClock float32)

Step moves the ARM on one cycle. Currently, the timer will only step forward when Step() is called and not during the Run() process. This might cause problems in some instances with some ARM programs.

func (*ARM) String

func (arm *ARM) String() string

type ARMinterruptReturn

type ARMinterruptReturn struct {
	InterruptEvent      string
	SaveResult          bool
	SaveRegister        uint32
	SaveValue           uint32
	InterruptServiced   bool
	NumMemAccess        int
	NumAdditionalCycles int
}

type BranchTrail

type BranchTrail int

BranchTrail indicates how the BrainTrail buffer was used for a cycle.

const (
	BranchTrailNotUsed BranchTrail = iota
	BranchTrailUsed
	BranchTrailFlushed
)

List of valid BranchTrail values.

type CartridgeHook

type CartridgeHook interface {
	// Returns false if parent cartridge mapping does not understand the
	// address.
	ARMinterrupt(addr uint32, val1 uint32, val2 uint32) (ARMinterruptReturn, error)
}

CartridgeHook allows the parent cartridge mapping to emulate ARM code in a more direct way. This is primarily because we do not yet emulate full ARM bytecode only Thumb bytecode, and the value of doing so is unclear.

type DisasmEntry

type DisasmEntry struct {
	Location string
	Address  string
	Operator string
	Operand  string

	Opcode uint16

	// total cycles for this instruction
	Cycles int

	// basic notes about the last execution of the entry
	ExecutionNotes string

	// details
	MAMCR          int
	BranchTrail    BranchTrail
	MergedIS       bool
	CyclesSequence string
}

DisasmEntry implements the CartCoProcDisasmEntry interface.

func Disassemble

func Disassemble(opcode uint16) DisasmEntry

Disassemble a single opcode. The assumption being that this is a Thumb encoded instruction.

func (DisasmEntry) CSV

func (e DisasmEntry) CSV() string

CSV implements the CartCoProcDisasmEntry interface. Outputs CSV friendly entries, albeit seprated by semicolons rather than commas.

func (DisasmEntry) Key

func (e DisasmEntry) Key() string

Key implements the CartCoProcDisasmEntry interface.

func (DisasmEntry) String

func (e DisasmEntry) String() string

String returns a very simple representation of the disassembly entry.

type DisasmSummary

type DisasmSummary struct {
	// whether this particular execution was run in immediate mode (ie. no
	// cycle counting)
	ImmediateMode bool

	// count of N, I and S cycles. will be zero if ImmediateMode is true.
	N int
	I int
	S int
}

DisasmSummary implements the CartCoProcDisasmSummary interface.

func (DisasmSummary) String

func (s DisasmSummary) String() string

type SharedMemory

type SharedMemory interface {
	// Return memory block and array offset for the requested address. Memory
	// blocks mays be different for read and write operations.
	MapAddress(addr uint32, write bool) (*[]byte, uint32)

	// Return reset addreses for the Stack Pointer register; the Link Register;
	// and Program Counter
	ResetVectors() (uint32, uint32, uint32)
}

SharedMemory represents the memory passed between the parent cartridge-mapper implementation and the ARM.