What the logpanes are
The logpanes contain a record of debuggee events and (if you wish) instructions carried out by the debuggee.
The 3 levels in the main log; the sequential log
The main log presents the logpane information in cascaded form. There are 3 levels to the main log:-
1. Top level: logpane showing main events and user input
2. Event/message logpanes showing events and messages
3. Instruction logpanes showing execution of instructions and resulting register changes.
The sequential log shows events and messages in order of occurrence. This can be watched in real time so you can see what messages are generated by actions of the debuggee.
Size and position of the top level of the main log
To enlarge the top level of the main log temporarily to view its contents click on the down button below the words "Log Pane". Alternatively you can do this by pressing the space bar if the main window has the focus. You can make the main log appear in a separate window by clicking on and dragging the rebar to the left of the words "Log Pane". To restore it to the main window use the "view" menu item. You can move the main log to the bottom of the main window by using the "view" menu item. To restore the number and position of the panes to the default use the "view, panes as default" menu item.
How debug action affects what is logged
F5/F6 action (single-step) and F7 action (run/trap/hook/full log) cause a full log record to be made. F8 action (run/hook/part log) causes a log to be made of events and messages but not instructions and register changes. F9 action (run in the background) only logs exceptions.
List of loggable things
Here is a list of things which appear in the main log with explanations as required:-
Top level logpane:-
"Running to starting address" (this is the first entry shown when the debuggee is loading)
"Starting address reached" (this appears once the debuggee has reached its starting address)
User's key input (showing key name and shift state)
Mouse input (button down and wheel movement)
Breakpoint reached (showing type of breakpoint, code address or procedure, or message name)
Strings sent to the debugger using the API OutputDebugString
Messages to any window
Windows about to be created
Windows about to be activated
Windows about to be moved or sized
Windows about to be minimized or maximized
Window focus about to be changed
Windows about to be destroyed
A Dll (or exe) being loaded in the debuggee address space
A Dll (or exe) being unloaded in the debuggee address space
A new thread starting
A thread terminating
A thread becoming idle (no further messages waiting to be dealt with by the thread)
Strings sent to the debugger using the API OutputDebugString
Instructions which have been executed
Message calling thread and receiving thread (if a message preceded the instructions)
A return from a CALL instruction
"Now at .." (if there has been some interruption in the instruction sequence, for example an F6 jump over when single-stepping)
A new thread starting
A thread terminating
Strings sent to the debugger using the API OutputDebugString
All entries shown in the top level logpane and event/message logpane, but in sequence.
Viewing an event/message logpane
Move the cursor to a "plus" button on the main logpane. It will turn red. Click on it while it is red. This will cause the event/message logpane relating to the entry in the main logpane to appear. If there is no "plus" button next to an entry in the main logpane, it's because the event/message logpane is empty for that entry. This may be because no events or messages have occurred yet after the entry occurred, or it may be because the there is little being logged because you are using F9 action (run in the background), or because you are running to a breakpoint and the breakpoint has not yet been reached. To change the event/message logpane you wish to view, click on another "plus" button. To remove the event/message logpane click again on the button which will now show a "minus".
Viewing an instruction logpane
Move the cursor to a "plus" button on the event/message logpane which is showing. It will turn red. Click on it. This will cause the instruction logpane relating to the entry in the event/message logpane to appear. If there is no "plus" button next to an entry in the event/message logpane, it's because the instruction logpane is empty for that entry. There may be several reasons for this. It may be that you have pressed F8 (run/hook/part log) which does not log instructions. Or it may be that you are using F5/F6 (single-step) or F7 (full log) but the message went to a window procedure in shared memory: if so, the instructions would not be logged. Or it may be that you were using single-step message break but you pressed F6 to ignore the message concerned. To change the instruction logpane you wish to view click on another "plus" button. To remove the event/message logpane click again on the button which will now show a "minus".
Moving the event/message/instruction logpanes
The only way this can be done is by moving the parent window. In the case of an integrated logpane, move GoBug's main window. In the case of a separate logpane, move that.
Viewing the changes in register values
Move the cursor to a "R" button on the instruction logpane which is showing. The registers and flags will appear with any changes shown in a different colour. If the instruction in the log is an MMX or floating point instruction (using the FPU) the appropriate registers will appear. At present the log does not also display the contents of the XMM registers.
Using the keyboard in the log
Instead of using the mouse to perform actions in the log you can use the following keys:-
TAB - if logpane is integral to the main window move focus to main logpane
CrtlTAB - if logpane is separate move focus to log pane from other panes and windows
TAB - move focus between open logpanes (forward)
ShftTAB - move focus between open logpanes (reverse)
UpArrow and DnArrow - move focus rectangle up and down the items in the logpane which currently has the focus
CrtlUpArrow and CrtlDnArrow - move focus rectangle to the first or last line
RtArrow - open the logpane if the "plus" button is red, or view the register values if the "R" button is red
LeftArrow - close the logpane currently being viewed or close the register value pane if it is showing
PgUp and PgDn - scroll up and down the logpane if there is a scrollbar there
CrtlPgUp and CrtlPgDn - fast scroll up and down the logpane if there is a scrollbar there
Ignoring some messages
When in F7 mode the log could be filled up with mouse movement, HITTEST, SETCURSOR and similar messages which would usually be of little interest. Such messages are filtered out by default but you can change which messages are ignored by clicking on the menu item "settings, log settings", and the tab "ignores". Note that the POWERBROADCAST message is only sent to battery powered machines. Any messages ignored by the log will also be ignored by the single-step message break.
Log text colours and font
Log entries relating to the main thread appear in the main log text colour. Log entries relating to other threads have a colour which is related to the sequence in which the thread was made. You can see this sequence in the property sheet which appears when you click on the menu item "settings, log settings" and the tab "text". The starting point for the colour sequence changes to suit the main text colour. You can change the sequence by clicking the "shift" buttons. You can also change the main text colour and font using this property sheet.
Suspension of log and debuggee during view
Opening the sub-logpanes stops any further log records being made. The log icon changes to a snowflake to indicate this. If the debuggee is running in the background it will not be affected by this because there is normally no log activity anyway. But if the you are logging messages (F8 action) or instructions (F7 action) suspension of the log in effect suspends the debuggee. The log will also be suspended during a dump or print of the contents of the log. Also when viewing the sequential log you can freeze the log by using the checkbox in the sequential log pane.
Unless you are single-stepping, if a window of the debuggee lies behind the sub-logpane on the screen, removing the window will cause debuggee activity. This is because the system will cause the parts of the debuggee windows which are then uncovered by the removal of the sub-logpane to paint. This will, of course, change the contents of the log if you are using F7 or F8 action. In practice this should not be a problem, but you can avoid this by minimising the debuggee first, before looking at the sub-logpane.
Memory used by the log
To alter the amount of memory used by the log click on the menu item "Settings, log settings" and then on the "memory" tab. You can allow GoBug to choose the amount of memory to use. In this case it is most likely that GoBug will take a maximum of 640K (after checking the memory capacity of the machine). This is not taken up all at once, but in 4K steps. In most short debug sessions only a part of this memory will actually be used. 640K of memory will permit logging of about 30,720 lines of events, messages, and instructions with register changes. This memory will be used up more quickly if you use F7, which records all instructions and register changes. Using breakpoints to get quickly to the code in which you are interested will keep the log compact, because nothing is logged when running to a breakpoint. If you wish to restrict the amount of memory used by the log you can set this manually.
Looping away of records when memory used
You may see the following in the log: "part of the record looped away". This means that the log memory is full and to make space for later records, earlier records had to be abandoned. This is not normally a problem but you can reduce the amount of log memory used up by running to the code area in which you are interested using breakpoints. This is because nothing is logged when running to a breakpoint.
Emptying the log
You can clear the whole of memory used by the log by using the menu item "settings, clear log". This also restores back to the system any memory which was in use by the log.
"Execution ..." and "Executing in ...'START' .."
If instructions have been executed which are not in response to a message, the words "Executing in ..." may appear in the main or event/message logpanes. An example would be on single-stepping after start up when the debuggee has not yet reached the message loop, when "Executing in ..'START' .." will appear. It might also appear if a function causes messages and then instructions return to the function after those messages have been dealt with. In console applications (which do not have messages) you will see this entry a lot more.
GetMessage, DispatchMessage and queued messages
Queued messages returned in GetMessage will not necessarily be sent on to the window procedure by the message loop. Or they may be changed before they are sent on (for example by TranslateMessage). Queued messages within the message loop are logged, and if they arrive at the window procedure they are logged again. The sequence of events shown by the log for queued messages is:
1. Queued message logged when GetMessage returns
2. If F5/6 (single-stepping) or F7 (full log) the instructions executed within message loop are logged, and finally
3. If the message arrives at the window procedure it is logged again (the source is shown in the log as "queued").
Message showing no instructions
Typically if you have used F8 action (Run/hook/log part) then all messages other than those ignored will appear in the event/message logpane, but no instructions will be logged. Also if you have been single-stepping with the single-step message break "on" and have then pressed F6 (ignore), no instructions will be logged either. However if you press F5 on a single-step message break the instructions will be logged. F7 will log all instructions within the window procedure other than those executed in shared memory or within the code of an API .
Resolution of messages of the same value
A number of messages in Windows have the same value. This does not matter because they are identifiable as destined for, or coming from, windows of a certain type. For example the messages TB_ENABLEBUTTON and TTM_ACTIVATE both have the value 401h. In fact there are 11 messages with this value. With such messages GoBug finds out what sort of window is involved and logs the name of the correct message accordingly.
The logging of command and notify messages
Four messages, WM_COMMAND, WM_NOTIFY, WM_DEVICECHANGE and WM_POWERBROADCAST are carriers for other messages. The log displays the other message first and concludes by giving the carrier in parenthesis.
The logging of API calls
Expect to see additional instructions in the log which do not appear in the codepane around API calls. This is because a call to an imported function is not made directly, execution being routed to another part of the executable file where the true address of the imported function has been placed by the system when the program loaded. The precise method of re-routing used and position of the true address of the imported function varies from linker to linker, but this is how an API call may typically appear if you used F7 action (run/hook/trap/log full):-
Because GoBug works in a slightly different way when jumping over the call using F6 action, the intermediate instruction just prior to the call would not appear.
Recursion within the window procedure
You may see that the instructions for a particular message suddenly end during a particular message as in this example which occurred during WM_NCACTIVATE:-
Here what has happened is that the system has sent another message from within the API DefWindowProc. In fact the message is WM_GETTEXT, so that the system can draw the title of the window. If we now look at the instruction log for WM_GETTEXT, we can see that the last instruction for WM_GETTEXT is, in fact the RET coming out of the window procedure, but then execution appears to come out of the window procedure a second time. This is because the original call to DefWindowProc (during the NCACTIVATE message) has now returned:-
The sequential log
This is a separate representation of certain parts of the log information. The sequential logpane shows events and messages in a single pane and in order of occurrence. You can create the sequential log by using the menu item "view, sequential log". In this log you can see in real time what events and messages are caused by debuggee actions. To help you to observe these, it is possible to make the sequential log appear always on top of the debuggee, using the menu item "view, sequential log (always on top)", or the checkbox in the sequential logpane itself. It is also easier to follow the actual order of messages from the sequential log, something which is often important. Less information appears in the sequential log than in the main log, but you can always use the main log as well to get the full information you need.
To avoid updating of the sequential log whilst viewing it, check the "freeze log" checkbox. The log icon changes to a snowflake to show this. Don't forget to uncheck the box when you want the log to proceed.
Dumping the logpanes
Ensure that the logpane you want to dump is visible and go to the menu item "file, dump". Click on the appropriate logpane which will appear in the menu item. Alternatively right click on the pane and choose "dump the pane". If the log also contains register values, these can also be dumped. Choose a file name for the dumped file (GoBug will suggest a name). Choose a path for the file to be written (GoBug will remember this for the next time you debug this particular exe). Choose the type of file to make (use ANSI unless you want to make a Unicode file because you are using non-Roman characters). Change the starting point and size of the dump. The file which is created on this dump is plain text with carriage returns and line feeds but no tabs. It is usually best to view the dumped file with an editor set to a fixed width font (as opposed to a proportionally spaced font).
Printing the logpanes
Ensure that the logpane you want to print is visible and go to the menu item "file, print". Click on the appropriate logpane which will appear in the menu item. Alternatively right click on the pane and choose "print the pane". If the log also contains register values, these can also be printed. Change the starting point and size of the print. You can change the font used for printing by using the "settings, fonts, when printing" menu item.