Mupen64Plus v2.0 Core Debugger

Mupen64Plus v2.0 API

Mupen64Plus v2.0 Core Debugger API

Most libmupen64plus functions return an m64p_error return code, which is an enumerated type defined in m64p_types.h. Front-end code should check the return value of each call to a libmupen64plus function.

General Debugger Functions

Prototype	m64p_error DebugSetCallbacks(void (*dbg_frontend_init)(void), void (*dbg_frontend_update)(unsigned int pc), void (*dbg_frontend_vi)(void))
Input Parameters	dbg_frontend_init Pointer to function which is called when debugger is initialized. dbg_frontend_update Pointer to function which is called after debugger hits a breakpoint or executes one instruction in stepping mode. dbg_frontend_vi Pointer to function which is called during each vertical interrupt.
Requirements	The Mupen64Plus library must be built with debugger support and must be initialized before calling this function.
Usage	This function is called by the front-end to supply debugger callback function pointers. If debugger is enabled and then later disabled within the GUI, this function may be called with NULL pointers in order to disable the callbacks.

Prototype	m64p_error DebugSetCoreCompare(void (*dbg_core_compare)(unsigned int), void (*dbg_core_data_sync)(int, void *))
Input Parameters	dbg_core_compare Pointer to function which is called after each R4300 instruction, for comparing the operation of one R4300 emulator core against another. dbg_core_data_sync Pointer to function which is used to transfer data from the sending emulator core to the receiving core, such as controller button press or movement data.
Requirements	The Mupen64Plus library must be initialized before calling this function.
Usage	This function is called by the front-end to supply callback function pointers for the Core Comparison feature. This feature is designed to work as follows. The front-end application will set up some channel for communicating data between two separately running instances of mupen64plus. For example, the unix console front-end will use named FIFOs. The front-end will register callback functions for comparing the 2 cores' states via this DebugSetCoreCompare API call. When the dbg_core_compare callback fires, the front-end will use the DebugGetCPUDataPtr function (and DebugMemGetPointer function if desired) to transmit emulator core state data from the 'sending' instance to the 'receiving' instance. The receiving instance may then check the core state data against it's own internal state and report any discrepancies. When the dbg_core_data_sync callback fires, the front-end should transmit a block of data from the sending instance to the receiving instance. This is for the purposes of synchronizing events such as controller inputs or state loading commands, so that the 2 cores may stay synchronized. This feature does not require the M64CAPS_DEBUGGER capability to built into the core, but it does require the M64CAPS_CORE_COMPARE capability.

Prototype	m64p_error DebugSetRunState(m64p_dbg_runstate runstate)
Input Parameters	runstate An m64p_dbg_runstate enumerated type specifying the debugging state of the emulator. M64P_DBG_RUNSTATE_RUNNING continues execution until a breakpoint is hit or a different state is chosen. M64P_DBG_RUNSTATE_STEPPING enters a single step running mode that sends callbacks as each step is performed. M64P_DBG_RUNSTATE_PAUSED pauses execution to allow manual stepping.
Requirements	The Mupen64Plus library must be built with debugger support and must be initialized before calling this function.
Usage	This function sets the run state of the R4300 CPU emulator.

Prototype	int DebugGetState(m64p_dbg_state statenum)
Input Parameters	statenum An m64p_dbg_state enumerated type specifying which debugger state variable to read.
Requirements	The Mupen64Plus library must be built with debugger support and must be initialized before calling this function.
Usage	This function reads and returns a debugger state variable, which are enumerated in m64p_types.h.

Prototype	m64p_error DebugStep(void)
Requirements	The Mupen64Plus library must be built with debugger support and must be initialized, the emulator core must be executing a ROM, and the debugger must be active before calling this function.
Usage	This function signals the debugger to advance one instruction when in the stepping mode.

Prototype	void DebugDecodeOp(unsigned int instruction, char *op, char *args, int pc)
Input Parameters	instruction 32-bit R4300 instruction opcode op Pointer to character array to store decoded instruction mnemonic args Pointer to character array to store instruction arguments pc Program Counter address at which instruction is stored
Requirements	The Mupen64Plus library must be built with debugger support.
Usage	This is a helper function for the debugger front-end. This instruction takes a PC value and an R4300 instruction opcode and writes the disassembled instruction mnemonic and arguments into character buffers. This is intended to be used to display disassembled code.

Memory Functions

Prototype	void * DebugMemGetRecompInfo(m64p_dbg_mem_info recomp_type, unsigned int address, int index)
Input Parameters	recomp_type Type of information to retrieve about a recompiled machine instruction. Must be a M64P_DBG_RECOMP_* type. address Program Counter value (in N64 memory space) of R4300 instruction about which to retrieve the recompiled x86 instructions. index Index of recompiled instruction about which to receive information.
Requirements	The Mupen64Plus library must be built with debugger support and must be initialized before calling this function. This function may not be available on all platforms.
Usage	This function is used by the front-end to retrieve disassembly information about recompiled code. For example, the dynamic recompiler may take a single R4300 instruction and compile it into 10 x86 instructions. This function may then be used to retrieve the disassembled code of the 10 x86 instructions. For recomp_type of M64P_DBG_RECOMP_OPCODE or M64P_DBG_RECOMP_ARGS, a character pointer will be returned which gives the disassembled instruction code. For recomp_type of M64P_DBG_RECOMP_ADDR, a pointer to the recompiled x86 instruction will be given.

Prototype	int DebugMemGetMemInfo(m64p_dbg_mem_info mem_info_type, unsigned int address)
Input Parameters	mem_info_type Type of information to retrieve about an N64 memory location. Must be a M64P_DBG_MEM_* type. address Memory location (in N64 memory space) about which to retrieve some information.
Requirements	The Mupen64Plus library must be built with debugger support and must be initialized before calling this function.
Usage	This function returns an integer value regarding the memory location address, corresponding to the information requested by mem_info_type, which is a type enumerated in m64p_types.h. For example, if address contains R4300 program code, the front-end may request the number of x86 instructions emitted by the dynamic recompiler by requesting M64P_DBG_MEM_NUM_RECOMPILED.

Prototype	void * DebugMemGetPointer(m64p_dbg_memptr_type mem_ptr_type)
Input Parameters	mem_ptr_type Memory type to which a pointer is requested.
Requirements	The Mupen64Plus library must be initialized before calling this function.
Usage	This function returns a memory pointer (in x86 memory space) to a block of emulated N64 memory. This may be used to retrieve a pointer to a special N64 block (such as the serial, video, or audio registers) or the RDRAM. The m64p_dbg_memptr_type type is enumerated in m64p_types.h

Prototype	unsigned long long DebugMemRead64(unsigned int address) unsigned int DebugMemRead32(unsigned int address) unsigned short DebugMemRead16(unsigned int address) unsigned char DebugMemRead8(unsigned int address)
Input Parameters	address Memory location (in N64 memory space) from which to retrieve a value.
Requirements	The Mupen64Plus library must be built with debugger support and must be initialized before calling this function.
Usage	These functions retrieve a value from the emulated N64 memory. The returned value will be correctly byte-swapped for the host architecture.

Prototype	void DebugMemWrite64(unsigned int address, unsigned long long value) void DebugMemWrite32(unsigned int address, unsigned int value) void DebugMemWrite16(unsigned int address, unsigned short value) void DebugMemWrite8(unsigned int address, unsigned char value)
Input Parameters	address Memory location (in N64 memory space) to which to write a value. value Value to write into emulated memory.
Requirements	The Mupen64Plus library must be built with debugger support and must be initialized before calling this function.
Usage	These functions write a value into the emulated N64 memory. The given value will be correctly byte-swapped before storage.

R4300 CPU Functions

Prototype	void *DebugGetCPUDataPtr(m64p_dbg_cpu_data cpu_data_type)
Input Parameters	cpu_data_type CPU register type to which a pointer is requested.
Requirements	The Mupen64Plus library must be initialized before calling this function.
Usage	This function returns a memory pointer (in x86 memory space) to a specific register in the emulated R4300 CPU. The m64p_dbg_cpu_data type is enumerated in m64p_types.h. It is important to note that when the R4300 CPU core is in the Cached Interpreter or Dynamic Recompiler modes, the address of the PC register is not constant; it will change after each instruction is executed. The pointers to all other registers will never change, as the other registers are global variables.

Breakpoint Functions

Prototype	int DebugBreakpointLookup(unsigned int address, unsigned int size, unsigned int flags)
Input Parameters	address Starting address (in R4300 memory space) to search size Size of address space in bytes to search flags Breakpoint flags
Requirements	The Mupen64Plus library must be built with debugger support and must be initialized before calling this function.
Usage	This function searches through all current breakpoints in the debugger to find one that matches the given input parameters. If a matching breakpoint is found, the index number is returned. If no breakpoints are found, -1 is returned.

Prototype	int DebugBreakpointCommand(m64p_dbg_bkp_command command, unsigned int index, m64p_breakpoint *bkp)
Input Parameters	command Enumerated value specifying the breakpoint command to execute index Purpose varies by command, see table below bkp Pointer to breakpoint for certain commands, see table below
Requirements	The Mupen64Plus library must be built with debugger support and must be initialized before calling this function.
Usage	This function is used to process common breakpoint commands, such as adding, removing, or searching the breakpoints. The meanings of the index and bkp input parameters vary by command, and are given in the table below. The m64p_dbg_bkp_command type is enumerated in m64p_types.h.

Command	Return Value	Function	index Parameter	ptr Parameter
M64P_BKP_CMD_ADD_ADDR	Index of new breakpoint	Add an execution breakpoint at a given R4300 address.	R4300 address	unused
M64P_BKP_CMD_ADD_STRUCT	Index of new breakpoint	Add a custom breakpoint specified in a breakpoint structure.	unused	Pointer to breakpoint struct of new breakpoint
M64P_BKP_CMD_REPLACE	unused	Replace an existing breakpoint with one specified by a breakpoint structure.	Index of breakpoint to replace	Pointer to breakpoint struct of new breakpoint
M64P_BKP_CMD_REMOVE_ADDR	unused	Remove an existing breakpoint	R4300 address of breakpoint to remove	unused
M64P_BKP_CMD_REMOVE_IDX	unused	Remove an existing breakpoint	Index of breakpoint to remove	unused
M64P_BKP_CMD_ENABLE	unused	Enable a specified breakpoint	Index of breakpoint to enable	unused
M64P_BKP_CMD_DISABLE	unused	Disable a specified breakpoint	Index of breakpoint to disable	unused
M64P_BKP_CMD_CHECK	Index of breakpoint if found, otherwise -1	Search for an execution breakpoint at a given address	R4300 address at which to search	unused