CORE: Implement a generic external monitor framework in Xemu (initially used by MEGA65 emulation only though)

[lgblgblgb]

Mega65 target got "UART monitor" for similar job as a real Mega65 has for. Note, that this feature would be useful for every targets for some form! So the monitor framework should be put into the common directory, also it would be cool to have Windows port, since currently it's UNIX only as it needs UNIX/POSIX related socket interface to be able to work.

[lgblgblgb]

According to my current ideas only ... I think (after chatting on these with Paul as well) the best way would be to keep uart-mon interface fully compatible with the real M65 (ie, VHDL implementation of M65 in the FPGA) as m65dbg (and btw uart-monitor was "invented"!) was written for that, and not for Xemu (Xemu tries only implement this uart-mon interface of the board itself). So then m65dbg is really a dual purpose tool, to be able to support the real hardware, and the emulator too. It also requires to try to keep the features of the interface at the minimum as much as possible and implement advanced features (like disasm) on the level of the m65dbg tool itself (or possibly even in a library - libm65dbg - which can be used then by the m65dbg CLI tool, and maybe other future debugger projects with GUI interfaces, PC-based IDEs, or whatever). This basically means, that only the minimal set of features needed at the emulator (or the board/FPGA/VHDL) side, and implement as many features as possible on the m65dbg side then. Surely it's only an idea now.

I've got a very neat piece of work as pull request #52 which made me think about the plans and older chats with developers on this topic, that's why I write these for now.

[lgblgblgb]

Commit 3a85292
The new wannabe interface working through TCP/IP even on Windows (using Winsock2). Capable of detecting HTTP requests (so the possibility to write a html5/JS interface as well) but with compatibility with the existing protocol. It runs in a thread not to disturb the emulator to maintain the connection, and will use some kind of simple message queue to exchange information between the monitor thread and the main emulator thread. Note, this is only the framework yet, it does nothing currently. Though it echoes back the given statement, and with a web browser, it produces a test HTML page for it.

[lgblgblgb]

#143 was a step to the direction by providing a socketapi which can be used for this really old issue

[lgblgblgb]

Some works on the current monitor (not this feature): #220 by Gurcei.

[lgblgblgb]

Again a new beginning. Commit 7629a37 intends to create a cross-platform tcp/ip, thread based umon server solution based on xemu's socketapi abstraction.

[lgblgblgb]

umon branch for MEGA65-based work, see how it fits in general then.

[lgblgblgb]

@gurcei The plan for breakpoints API in general:

CPU65 emulation core will get an opcode callback mechanism. Rules:

• Macro CPU65_EXECUTION_CALLBACK_SUPPORT must be defined (probably in xemu-target.h)
• The emulator must provide the following functions then:
  • bool cpu65_nmi_debug_callback ( void ) - called before a pending NMI is accepted, if callbacks are enabled
  • bool cpu65_irq_debug_callback ( void ) - called before a pending IRQ is accepted, if callbacks are enabled
  • bool cpu65_execution_debug_callback ( void ) - called each time at opcode fetch (only the opcode itself!), if callbacks are enabled
• These callbacks must return with false if there is no need to stop the CPU or true if stopping is desired (breakpoint, etc?)
• The callbacks can query the cpu65 structure to learn more about the situation, like:
  • cpu65.pc the program counter (unlike memwatch callbacks, the PC is accurate and points to the address the next instruction would be executed - or in case of IRQ and NMI where the execution will continue after the NMI/IRQ is executed - but it's still true that the callbacks are issued before IRQ or NMI is accepted)
  • cpu65.op the fetched opcode (only valid for the cpu65_execution_debug_callback not for the NMI or IRQ - for those cpu65.op contains the previous executed opcode, so beware of this)
    • Note: the opcode is single byte. Prefixed opcodes are not handled, ie, both the prefix bytes and the "real" opcode has its own callback invocation. If it's needed anyway to query prefixed opcode, the cpu65 struct contains a prefix field, which can be decoded, if it's really needed at all. This is how CPU65 core emulation works internally too: when the emulator encounters a "wannabe prefix" (like NOP or NEG) it does not know yet if it will be a prefix or a real NEG or NOP alone, it only turns out later, of course. Thus it's not possible to know "in advance".
  • etc ... (see ROOT/xemu/cpu65.h to learn more on the cpu65 structure)
• The callbacks must be enabled/activated before they start to be called by CPU65 core with setting cpu65.execution_debug_callback to true
• cpu65.execution_debug_callback should be set to false as soon as possible when there is no need for the callbacks, since these mechanisms consumes CPU time from the emulator
• Returning with true from callback is not enough alone to stop the CPU, as it only causes the CPU emulation to abort further CPU emulation for that "round". Thus it's emulator target dependent, but some other emulation main loop setting is needed as well. The exact method is no longer scope of CPU65 core though, but emulator target specific.

With this, the emulation target can choose its own way to implement breakpoint, based on PC or even on a given opcode only (by checking cpu65.op) and so on ...

Really this is kinda easy to implement, in fact, already done (but not committed yet).

TODO:

• Implement emulator target (in our case MEGA65) specific solution for the other part of the requirement to keep the CPU stopped. This will also affect some other parts of the MEGA65 emulator not just the shared CPU65 emulation.
• Rework the uartmon stuff to take advantage the new system

NOTE: some may need to be careful not to confuse the breakpoint API with the "memwatch" API: the breakpoint API we're talking about here only deals with opcode fetches and NMI/IRQ acceptances. The "memwatch" API in the other hand can handle any kind of memory read and write operations to be intercepted. Also the breakpoint API can stop the CPU before the actual opcode, while the memwatch API - unfortunately - can only react when an opcode emulation already in progress, thus it's inconsistent somewhat what phase the opcode emulation we're in ... Because it can happen even many-many times within a single opcode (think about a 32 bit flat addressed 32 bit opcode ..., there is need to query BP for 4 bytes of read, then the target memory, not even counting the opcode and prefix fetches ...).