Feature Request: API for accessing emulator registers within events

[logantgt]

Goal

This issue aims to discuss the design of an API that would allow for access to the data stored in the registers of an emulated processor, and a mechanism to read those registers while the processor is in some desired state (for example, the program counter having reached a desirable piece of code).

Forgive anything that's not especially clear - I know what kind of functionality would be useful to have in this API but I don't know how it should look in the spec!

Applications

A lot of these suggestions are based around the needs of my particular application, and while I think the functionality could be applied to a lot of different scenarios, bare in mind I'm probably not considering every possible use case, and this issue may require more input. For the sake of getting this done I am only proposing a minimal set of features.

Access to register values at certain points in the emulated program makes it possible to extract useful arbitrary data from an emulated application for further processing in an external application. For one example, this is useful in "text hooking" applications where strings (usually in a language foreign to the user) are copied out of memory and sent to a translation service. The current utilities that interact with emulators in this way are overly complicated and often break with simple ABI changes.

Proposals

• A pair of message/answers to ask/receive details about what processors are available to be interacted with through PINE.

For the sake of discussion, a Processor represents a state machine that contains an arbitrary amount of labelled values (typically registers). An emulator should offer access to at least one Processor (ideally the application processor that is associated with executing game code).

The answer should include the name of the processor, the width of its registers as an 8 bit integer, and all the valid register names that can be accessed. PCSX2 could offer an answer like this as a null terminated C string;

 ee:zero,at,v0,v1,a0,a1,a2,a3,t0,t1,t2,t3,t4,t5,t6,t7,s0,s1,s2,s3,s4,s5,s6,s7,t8,t9,k0,k1,gp,sp,fp,ra,pc,hi,lo

where the first byte is the width of the registers (32 dec = SPACE in ascii).

PCSX2 implementation consideration; PS2 registers are seen as 128 bits wide during SIMD operations, pointers are 32 bit, should PINE simply offer the lowest 32 bits of each register?

• A pair of message/answers to request/receive the value of a register inside of a Processor.

This should have a very simple interface, a request might have an argument like ee:a1 to read the value of the A1 register in the PS2's Emotion Engine. Consider the ability to write to registers in the future?

• A set of message/answers to establish, notify, and acknowledge handling of blocking events raised when the program counter of a given processor reaches the address of a given instruction (these could be called "instruction events").

The event API has been mentioned in the draft specification but is not yet implemented.

An "instruction event" should be registered using a known Processor and memory address where desired code is located. Once a registered event is raised, the emulator should pause execution. PINE will notify the client of the raised event, and respond to any read/write requests made by the client. The client program must send a special acknowledgement that the raised event was handled before emulation may resume.

• A pair of message/answers to request/receive an array of bytes from emulator memory, starting at a given address and reading to a certain length. Self explanatory, would make life easier.

[GovanifY]

Hi,

Thanks for opening the issue! Overall feature-wise that seems fine, although here a few points I'd like to bring up, mostly re: implementation.

A pair of message/answers to ask/receive details about what processors are available to be interacted with through PINE.

So, few things with this one. First, do we need a separate command at all compared to, say, a GetSystemVersion or similar, when it comes to the capabilities of the emulator? I'd expect the most common occurence to be an older client with a newer server, in which case it wouldn't matter. It could be helpful for a newer client with an older server though, but at this point wouldn't it make more sense to prompt the user to update the emulator?

In this case, we could probably make away with a versioned protocol (protobuf? JSON?) that the client would know ahead of time when dealing with processors.

I could see a use case for a command to query capabilities if, say, low level tinkering isn't possible at this point in time, but I fail to see any use case of an emulator being unable to do so. Even AOT emulators would have a penalty but be able to do it. What do you think?

A pair of message/answers to request/receive the value of a register inside of a Processor.

Reading/writing to register might have the same penalty in some context, besides that sounds pretty sensible.

A set of message/answers to establish, notify, and acknowledge handling of blocking events raised when the program counter of a given processor reaches the address of a given instruction (these could be called "instruction events").

Three points with this:

• Currently, on the server side, pine is single threaded, having a blocking event would thus lead to blocking every other request until said event is done, which is less than ideal. It's possible to redesign (and honestly necessary), but is probably going to be painful and not as simple as we wish. The way I see it, we will need at least a message handler and the main event processor, on top of additional event threads.
• I disagree re: pausing execution, I think it should be an option, rather than a necessity. Imagine a randomizer, where a client waits for a room to be loaded before updating itself, there's no need for the emulator to stop execution.
• An implementation like this seems akin to stored queries. While this is useful in a limited fashion, this also seems limiting logic wise for the client, and forces the server to implement its own DSL if we want to have a useful debugging handler. I don't really know how to solve this, but it's something to keep in mind.

A pair of message/answers to request/receive an array of bytes from emulator memory, starting at a given address and reading to a certain length. Self explanatory, would make life easier.

Fair. I tried avoiding such a scenario in the first versions of pine because allocations are slow. Given enough safeguards, I believe this could be done safely and was probably a mistake to not allow this from the beginning.