arm

package
v0.23.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: May 29, 2023 License: GPL-3.0, GPL-3.0 Imports: 11 Imported by: 0

Documentation

Overview

Package arm 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

View Source
const (
	N cycleType = 'N'
	I cycleType = 'I'
	S cycleType = 'S'
)
View Source
const DisasmEntryErrorOperator = "error:"

The string that will be in the Operator field in the case of a decoding error

View Source
const (
	NumRegisters
)

register names.

Variables

This section is empty.

Functions

func AddWithCarry

func AddWithCarry(a uint32, b uint32, c uint32) (uint32, bool, bool)

returns result, carry, overflow

func ROR_C

func ROR_C(imm32 uint32, shift uint32) (uint32, bool)

func StaticDisassemble added in v0.22.0

func StaticDisassemble(config StaticDisassembleConfig) error

StaticDisassemble is used to statically disassemble a block of memory. It is assumed that there is a valid instruction at the start of the block

For disassemblies of executed code see the mapper.CartCoProcDisassembler interface

func ThumbExpandImm_C

func ThumbExpandImm_C(imm12 uint32, carry bool) (uint32, bool)

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 architecture.Map, prefs *preferences.ARMPreferences, mem SharedMemory, hook CartridgeHook) *ARM

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

func (*ARM) BreakpointsEnable added in v0.20.0

func (arm *ARM) BreakpointsEnable(enable bool)

BreakpointsEnable turns of breakpoint checking for the duration that disable is true.

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.CartCoProc interface.

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

func (*ARM) ImmediateMode added in v0.22.0

func (arm *ARM) ImmediateMode() bool

ImmediateMode returns whether the most recent execution was in immediate mode or not.

func (*ARM) Interrupt added in v0.20.0

func (arm *ARM) Interrupt()

Interrupt indicates that the ARM execution should cease after the current instruction has been executed. The ARM will then yield with the reson YieldSyncWithVCS.

func (*ARM) Plumb

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

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

The ARMState argument can be nil as a special case. If it is nil then the existing state does not change. For some cartridge mappers this is acceptable and more convenient.

func (*ARM) Registers

func (arm *ARM) Registers() [NumRegisters]uint32

Registers returns a copy of the current values in the ARM registers

func (*ARM) Run

func (arm *ARM) Run() (mapper.YieldReason, float32)

Run will execute an ARM program from the current PC address, unless the previous execution ran to completion (ie. was uninterrupted).

Returns the yield reason, the number of ARM cycles consumed.

func (*ARM) SetByteOrder added in v0.22.0

func (arm *ARM) SetByteOrder(o binary.ByteOrder)

SetByteOrder changes the binary interface used to read memory returned by the SharedMemory interface

func (*ARM) SetDeveloper

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

SetDeveloper implements the mapper.CartCoProc interface.

func (*ARM) SetDisassembler

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

SetDisassembler implements the mapper.CartCoProc interface.

func (*ARM) SetInitialRegisters

func (arm *ARM) SetInitialRegisters(args ...uint32) error

SetInitialRegisters is intended to be called after creation but before the first call to Run().

The optional arguments are used to initialise the registers in order starting with R0. The remaining options will be set to their default values (SP, LR and PC set according to the ResetVectors() via the SharedMemory interface).

Note that you don't need to use this to set the initial values for SP, LR or PC. Those registers are initialised via the ResetVectors() function of the SharedMemory interface. The function will return with an error if those registers are attempted to be initialised.

The emulated ARM will be left in an interrupted state.

func (*ARM) SetRegister added in v0.20.0

func (arm *ARM) SetRegister(reg int, value uint32) bool

SetRegister sets an ARM register to the specified value

func (*ARM) SetRegisters

func (arm *ARM) SetRegisters(registers [NumRegisters]uint32)

SetRegisters sets the live register values to those supplied

func (*ARM) Snapshot

func (arm *ARM) Snapshot() *ARMState

Snapshort makes a copy of the ARM state.

func (*ARM) StackFrame added in v0.20.0

func (arm *ARM) StackFrame() uint32

StackFrame returns the current stack reference for the execution.

func (*ARM) Status

func (arm *ARM) Status() Status

Status returns a copy of the current status register.

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 ARMState

type ARMState struct {
	// contains filtered or unexported fields
}

func (*ARMState) Snapshot

func (s *ARMState) Snapshot() *ARMState

Snapshort makes a copy of the ARMState.

type ARMinterruptReturn

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

ARMInterruptReturn is the return value of the ARMinterrupt type.

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 {
	// the address value. the formatted value is in the Address field
	Addr uint32

	// the opcode for the instruction. in the case of a 32bit instruction, this
	// will be the second word of the opcode
	Opcode uint16

	// instruction is 32bit and the high opcode
	Is32bit  bool
	OpcodeHi uint16

	// formated address for use by disassemblies. more convenient that the Addr
	// field in some contexts
	Address string

	// the operator is the instruction specified by the Opcode field (and
	// OpcodeHi if the instruction is 32bit)
	//
	// the operand is the specific details of the instruction. what registers
	// and what values are used, etc.
	//
	// in the case of an error Operator will contain the DisasmEntryErrorOperator
	// string and the Operand will be the detaled message of the error
	Operator string
	Operand  string

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

	// snapshot of CPU registers at the result of the instruction
	Registers [NumRegisters]uint32

	// basic cycle information
	Cycles         int
	CyclesSequence string

	// cycle details
	MAMCR       int
	BranchTrail BranchTrail
	MergedIS    bool

	// whether this entry was executed in immediate mode. if this field is true
	// then the Cycles and "cycle details" fields will be zero
	ImmediateMode bool
}

DisasmEntry implements the CartCoProcDisasmEntry interface.

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) Size added in v0.22.0

func (e DisasmEntry) Size() int

Size implements the CartCoProcDisasmEntry interface.

func (DisasmEntry) String

func (e DisasmEntry) String() string

String implements the CartCoProcDisasmEntry interface. 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.
	//
	// Note that there is no indication of how the memory will be access. For
	// instance whether it's for a 32bit or an 8bit access. For this reason the
	// implemention can assume that the access is 8bit and that the user of the
	// result will make further boundary checks as appropriate.
	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)

	// Return true is address contains executable instructions.
	IsExecutable(addr uint32) bool
}

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

type StaticDisassembleConfig added in v0.22.0

type StaticDisassembleConfig struct {
	Data      []byte
	Origin    uint32
	ByteOrder binary.ByteOrder
	Callback  func(DisasmEntry)
}

StaticDisassembleConfig is used to set the parameters for a static disassembly

type Status

type Status struct {
	// contains filtered or unexported fields
}

the arm has a 32 bit Status register but we only need the CSPR bits currently.

func (Status) String

func (sr Status) String() string

Directories

Path Synopsis
Package architecture defines the Map type that is used to specify the differences in cartridge and ARM archtectures.
Package architecture defines the Map type that is used to specify the differences in cartridge and ARM archtectures.
Package Callfn facilitates the ARM CALLFN process common to both DPC+ and CDF* cartridge mappers.
Package Callfn facilitates the ARM CALLFN process common to both DPC+ and CDF* cartridge mappers.
Package peripherals implements the optional modules that can make up the ARM processor.
Package peripherals implements the optional modules that can make up the ARM processor.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL