MonitorUI

Reason for this page: defining the intended behaviour of the monitor (g)ui to maintain consistency across ports and to prevent needless work :)

General Behaviour

Entering the monitor

• exit fullscreen mode if needed
• if monitor window is not visible, enable it
• transfer focus to the monitor window

Leaving the monitor

• restore fullscreen mode, make emulation window visible
• transfer focus to the emulator window

Single stepping should not close the monitor. There's no need to set the focus back to the emulator window for a single assembly instruction. (This needs some special handling in the monitor code)

Reasons for keeping the monitor open or for closing it

Keeping the monitor open

The console driver is capable of outputting text even when the monitor is not active (ie when the emulation is running). This can be useful because eg trace/watch output shows up immediately.

Additionally developers may want to look at the last monitor output (e.g. a piece of disassembly) while the emulation runs.

Close on exit

Exiting the monitor closes the monitor window, closing the monitor window exits the monitor respectively. The emulation continues and no monitor window clobbers the screen anymore. This is the default behavior, which is also (exclusively) used by most ports.

Proposed Solution

The existing command exit (x) shall close the monitor window and continue the emulation. A close button of the monitor window (if any) shall act in the same way as the command exit.

To be able to keep the monitor window open even when the emulation is re-started, the command go (or g or goto) is to be modified. If go is issued without address, the emulation should continue from the current state. The existing semantic of go <addr> doesn't change.

These two commands (exit, go) allow the user to to do what he wants in any situation.

related: remote monitor

To be clarified: Should exit close the link to a remote monitor?

• when issued from remote? i would say so Gpz 09:38, 14 March 2012 (UTC)

Implementation

keep open on exit

This is optional behavior (SDL can't support it, GTK3 can). It should be enabled if both console_log->console_can_stay_open and KeepMonitorOpen are 1 and the above mentioned "go" command is issued in the monitor. (in all other cases this command should act like exit)

• the monitor window stays open all the time, except for when the user closes the window.
  • This creates the problem that the monitor window might be closed, although console_log->console_can_stay_open and KeepMonitorOpen are 1. This must be handled somehow by switching between buffered and non buffered mode at runtime.
  • ports that do not handle this (yet) may create a window that can not be closed by the user
• entering and exiting the monitor only transfers focus to/from the emulation window respectively

related ui functions

• uimon_window_open
  • opens a the monitor console/window, brings the window to front and transfers focus to it
  • returns console_log
• uimon_window_close
  • closes the monitor window and transfers focus to the main emulator window
• uimon_window_resume
  • in UIs where console_log->console_can_stay_open is 1, transfer focus to the monitor console/window and brings the window to front
  • returns console_log
• uimon_window_suspend
  • transfers focus to the main emulator window, while keeping the window open
  • will only be used if console_log->console_can_stay_open and KeepMonitorOpen are 1, for UIs where console_log->console_can_stay_open is 0 this function is empty

• uimon_in
  • this is probably supposed to return a single line of input of the monitor UI

• uimon_out
  • this is probably supposed to output a line of text to the monitor UI

Status

• KeepMonitorOpen resource is implemented, defaults to 1 and allows reverting to the "old" behaviour by setting it to 0
• single step instructions will not close/leave the monitor at all when stepping 1 instruction only.
• eXit and Go commands are implemented as described above.