Version 1.09 (2007/03/02)

Preparing your software for debugging

DeskDebug can only examine programs compiled or linked with debugging information of the filetype 'DebImage' (&FD3). These images are created by enabling the debug option in whatever software you use to create executable images. Some common development tools are:

If you use ObjASM:

If you use CC:

If you use C++:

And when you link your project:

 

Opening your debugging project

1. Click twice on the 'DeskDebug' icon in the directory viewer. This loads and starts the debugger 'DeskDebug'. The 'DeskDebug' program icon appears on the iconbar. The icon of the debuggee on the icon bar is greyed out, when the debuggee stands still after a break-point or single-step.
   
2. Click twice on the icon of the program to be examined in the directory viewer.
   The 'DeskDebug' Control window opens, and the examination (debugging session) begins.
3. Click the Menu button over the control window to open the control menu.

 

Getting started

• On the entry 'Displays' move the mouse pointer to the right to open the Displays submenu.
• By clicking the entries in this submenu you toggle the related display windows on and off.
• Activate the display 'Source listing' in each case.
  If you wrote the debugee in the Assembly language, then activate additionally the displays 'Symbol table', 'ARM registers' and maybe 'FPU registers'.
  If you wrote the debugee in the 'C' high level language, then activate the displays 'Variable list' and maybe 'Procedures list' too.
• By clicking the button 'Single step' in the control window you can single-step through your program. You can press the key [F5] too to do this. The executation location is indicated in the disssembler and source listing windows, if they are open. The line, where the executation now stands, is marked with a star and has another colour.
• If you wrote the debugee in the 'C' high level language, then activate the option 'Source Step', so that the single step are done by source statements. Otherwise the single steps are done by ARM instructions.
• If you activate the option 'Step over Procedures', then all procedures and functions are executed in real time; otherwise they can be single-stepped through too. If you already are in a procedure or function, then you can execute it in realtime until to its end by adjust-clicking the button 'Continue'.
• With the buttons 'No null events', 'No pointer events' and 'No messages' you can prevent the debugee from receiving null events, pointer entry / leave events and wimp messages.
• By clicking the button 'Continue' you run the debugee in real time until to the next break point. You can press the key [F6] too to do this.

You have different possibilities to set and remove break points.

• In the disassembler and source listing windows you can simply adjust-click on a line, and a breakpoint is set or removed at the related location. If a breakpoint is set, then the line is marked with an 'at' (@) sign at its begin and has another colour.
• In the symbol table and procedure list windows you can set and remove breakpoints too by adjust-clicking the concerning line. A breakpoint is then set on the location described by the symbol value or in the related procedure.
• Switch on the display 'Breakpoints' to show the breakpoint list. Adjust-click on a breakpoint line removes the related breakpoint and it's line.
• The menu on the breakpoint window gives further possibilities to set and remove breakpoints.
• In the window 'Set breakpoint' you can type in a breakpoint address and set the breakpoint.

By clicking the button 'Quit' on the control window you terminate the debugee at any time. In some cases you must click this button twice. You can press the key [F2] too.

When an error occurs in the debugee, then the error window opens. It shows you the program name, the error number, the address, where the error occured, and the full original error message. After an error you can not continue the program anymore, but only terminate it.

 

Program windows and menus

To start the debugger, double click on its icon on the directory viewer.

To start the program to be examined (the debuggee), double click on its icon on the directory viewer, or drag the icon to the 'DeskDebug' icon on the icon bar. If an executable file in the application directory has the type 'DebImage', the obey file '!Run' will be read, and then the executable file will be started, so that the debug session begins. Alternatively you can double click or drag to 'DeskDebug' the '!Run' file or any other obey file in the application directory. If in the same directory is an executable file with the type 'DebImage', then the obey file will be read, and the executable file will be executed.

 

Control window

When the debuggee is started, then the 'DeskDebug Control' window is opened. In this window you find the following buttons:

Icon	Action	Key shortcut	Notes
Single step	Click with {Select}: Makes a single-step in the debuggee. If 'Step over Procedures' is ticked: Procedures and functions are executed in real-time, otherwise they are single-stepped.	F5	This button is greyed out, when the debuggee has called 'Wimp_Poll' and is waiting for a wimp event and after an error.
	Click with {Adjust}: Makes a single-step in the debuggee. If 'Step over Procedures' is ticked: Procedures and functions are single-stepped, otherwise they are executed in real-time.	Ctrl+F5
Continue	Click with {Select}: The debuggee is continued everytime in real time until the next break-point.	F6	This button is greyed out, when the debuggee has called 'Wimp_Poll' and is waiting for a wimp event and after an error.
	Click with {Adjust}: Outside procedures and functions the debuggee is continued in real time until the next break-point. Inside procedures and functions the debuggee is continued until to the return address of the actual procedure or function.	Ctrl+F6
Quit	Click with {Select}: Terminates the debuggee and closes all debugger windows.	F2	'DeskDebug' asks you, whether you really want to terminate the debugging session. The action is taken, if you click 'OK' or press the [Return] key.
	Click with {Adjust}: Terminates the debuggee and re-starts it immediately.	Ctrl+F2	'DeskDebug' asks you, whether you really want to terminate and then re-start the debugging session. The action is taken, if you click 'OK' or press the [Return] key.
Step over Procedures	When ticked, then procedures and functions are executed in real time as opposed to being single-stepped through.	F7	If you click 'Single Step' with {Adjust} or press [F5] with [Ctrl], then this option behaves the other way around.
Source Step	when ticked: single-step by source statement. otherwise: single-step by ARM instruction	F8
No Null Events	When ticked: The debugee can not receive any null events.	F9	This is useful to avoid repeated null events, when the exaninated program allows them, and you want test other things.
No Pointer Events	When ticked: The debugee can not receive any pointer-entering and pointer-leaving events.	F10	This is useful for programs that allow these events. You can suppress them, so that you must not go around the windows of the debugee
No Messages	When ticked: The debugee can not receive any messages.	F11	This is useful, when you want to start another application or open a file, and the debugee must not react on it
Input focus	Gets the input focus into the control window. If listing windows are open, then the input focus is 'moved' through each of them in sequence.	[Ctrl+Tab]	See the explanations in the table Key shortcouts in the row [Ctrl+Tab] too.
State	This field shows the state of the examined program (debuggee).	-	The following states are shown: Running: The program runs in real time or waits for a wimp event. Break-point reached: The program stands still after a break-point. Break on SWI call: e program stands still after a Break on SWI call. Single step...: The program stands still after a single step. Break on error: The program stands still after an error. You can not continue it anymore.

Clicking menu in this window opens the Control menu.

 

Key shortcuts

Key	Action
F2	Terminates the debugee and closes the debugger windows. If additionally [Ctrl] is held down, then it terminates the debuggee and re-starts it immediately. See the description for the control window above too.
F3	Pops up the Save as box, that allows you to save a list. If one of the windows for symbols, procedures or variables has the input focus, then this key acts here too. In this case the appropriate radio button is selected automatically
F4	Opens the Search window explained below. With [Shift] held it continues a search. If one of the windows for the memory dump, symbols, procedures or variables has the input focus, then this key acts here too. In this case the appropriate radio button is selected automatically.
F5	Makes a single step in the debugee.
F6	Continues the debugee in real time until the next break-point.
F7	Toggles the execution of procedures and functions between real-time and step-through.
F8	Toggles single-stepping between ARM instruction and source statement.
F9	Toggles receiving of null events on and off.
F10	Toggles receiving of pointer-entering and pointer-leave events on and off.
F11	Toggles receiving of wimp messages on and off.
Ctrl+Tab	Moves the input focus from the control window in sequence into the following windows: memory dump, disassembler, breakpoints, source listing, source names,symbols, procedures, variables, special and back to the control window; then the input focus is disabled. With [Shift] held down the sequence is the other way around. If the input focus is not in a DeskDebug window, it comes to here with one of these shortcuts, if no application has the input focus, or when the input focus is in an application, that does not understand at least one of these two shortcuts.
	If one of the windows memory dump, disassembler, breakpoints, source listing, source names, symbols, procedures, variables or special has the input focus, then it can be scrolled with the following shortcuts:
Page up / down	Scrolls one window height up or down.
Ctrl Page up / down	Scrolls one line up or down.
Cursor left / right	Scrolls one column left or right.
Ctrl Cursor left / right	Scrolls one window width left or right.
	If one of the windows Search or Save has the input focus, then the following shortcuts are active:
Page up / down	Switches between the five radio buttons, that select, what is saved or searched for.
	With the input focus in the Search window the following two shortcuts are active too:
[Ctrl C]	Toggles the option 'Case sensitive' on and off.
[Ctrl W]	Toggles the option 'Use wildcards' on and off.

 

Control menu

	Display	Leads to the Display submenu explained below.
	Search	Leads to the Search window (available with [F4] too).
	Save	Leads to the Save as box (available with [F3] too).

 

Search Window

Memory	With the five radio buttons on the left of the window you decide which object you want to search for: memory text, source names, symbols, procedures, variables. You can switch between the radiobuttons with [Page up / down] too.
Source names
Symbols
Procedures
Variables
Search string	In the writeable field you can type the string you wish to search for up to 63 chars
Case sensitive	Enables or disables the case sensitivity. You can toggle this with [Ctrl C] too.
Use wildcards	Enables the two little writeable fields at right, where you can type in the wildcards for a single char and for multiple chars. You can toggle this with [Ctrl W] too. The two wildcard chars must be different, and in each field there must be one. The wildcard for multiple chars can only be at the start and/or the end of a search string; for search in memory only at the end of the search string
Cancel	Abandons the search and closes the window.
Search	Performs the search from the start of the list selected above. When you click with {select} then the window closes; with {adjust} it remains open.
Search further	Continues a search from where the previous search has stopped. It searches from the start, if there was no previous search. When you click with {select} then the window closes; with {adjust} it remains open. This option is available with [Shift F4] too

The window can be opened using [F4] from the Memory, Symbols, Procedures and Variables windows with the appropriate search item selected according to the window it was launched from.
Pressing the Return key alone acts same as a click on 'Search'.
Pressing the Return key with [Shift] acts same as a click on 'Search further'.
If you hold down [Ctrl] additionally, then the 'Search' window remains open.

 

Save window

	With the five radio buttons on the top of the window you decide, which of the four lists you want to save: memory dump, symbols, source names, procedures or varibles. You can switch between the radiobuttons with [Page up / down] too.
	The other icons and buttons are to be used along the RISC OS standard
	Drag'n'drop to a directory viewer or another application is possible
	This feature is available with [F3] too. Furthermore it is available from the menus in the symbols, procedures and variables windows. If you invoke the 'Save as' box from one of these menus, the suitable radio button is selected automatically

 

Display submenu

	ARM Registers	When ticked, then the ARM Registers window is opened, when the debuggee stands still after a break-point or single-step
	FPU Registers	When ticked, then the FPU Registers window is opened, when the debuggee stands still after a break-point or single-step
	Wimp event	When ticked, then the Wimp event window is opened
	Context	When ticked, then the Context window is opened
	Memory dump	When ticked, then the Memory Dump window is opened
	Disassembler	When ticked, then the Disassembler listing window is opened
	Breakpoints	When ticked, then the Breakpoints window is opened
	Source listing	When ticked, then the Source Listing window is opened
	Source names	When ticked, then the Source Names window is opened
	Symbols table	When ticked, then the low level Symbols window is opened
	Procedures list	When ticked, then the Procedures list window is opened
	Variables list	When ticked, then the Variables list window is opened

 

ARM Registers Window

The register contents are shown in the fields numbered 0 to 15.
The processor condition flags states are shown in the fields labeled 'N', 'Z', 'C' and 'V'.
If any context is shown, then question marks in the fields mean undefined values.

The toggle size icon shows or hiddens the option that you can find on the bottom zone of this window:
By clicking on one of the two arrows you can select the register, whose contents will be displayed as text. The register number is displayed in the square display, the text corresponding to the contents appears in the long rectangular display. The text can be up to 4 chars long.

 

FPU Registers window

The register contents are shown in the fields numbered 0 to 7.
The FPU flags states are shown in the fields labeled 'IX', 'UF', 'OF', 'DZ' and 'IV'.
If any context is shown, then question marks in the fields mean undefined values.

The toggle size icon shows or hiddens the following options, that you can find on the bottom zone of this window:
With the two radio buttons 'Point' or 'Comma' you can select the delimiter char between the decimal fraction and the integer part.
The option 'Rounding' rounds the number up. The option 'Filling' causes, that the decimal fraction part is filled out with zeroes until the digit amount shown in the 'Frac. digits' field. You can change this digit amount by clicking on the arrows to the right.
These options take effect on any floating point numbers displayed in the variables window too.

 

Memory dump window

It shows the application's memory in the hexadecimal and textual form.

Clicking menu on this window opens the memory dump menu.

 

Disassembler window

Line format: Address, (Label,) Instruction, Operands (Symbols)

Clicking menu in this window opens the disassembler menu

When you select-click on an ARM instruction line, then the source listing window will be 'syncronized' so that you can see the concerning location on both. If the symbol points into a data area, then the concerning location is shown in the Memory dump window.

When you adjust-click on an ARM instruction line, then this causes the same behaviour, but a break-point is set at the concerning location,
if there is currently no break-point already set. If there is a break-point set, then it is removed.

 

Wimp event window

The upper left display shows the Wimp event number.
The upper right display shows the Wimp event name.
The lower left display shows the Wimp Message action number or Toolbox event number.
The lower right display shows the Wimp Message action name or Toolbox event name.

 

Context window

Show only context with relation to source listing	When this option is ticked, then only contexts with relation to a source listing are shown. Otherwise 'low level' contexts are shown too
Update Variables List on Context Change	When this option is ticked, the variables list will be updated on context change
Home	Synchronizes the disassembler and source listings to the beginning of the actual procedure
Out	Moves the Stack Backtrace to the next outer Stack frame and syncronizes the disassembler and source listings to the beginning of the concerning procedure
In	Moves the Stack Backtrace to the next inner Stack frame and syncronizes the disassembler and source listings to the beginning of the concerning procedure
Source	Shows the concerning source file name.
Procedure	Shows the concerning procedure name.
Address	Shows the call location of the actual procedure in the context procedure.
Line	Shows the concerning procedure start line number.
Column	Shows the concerning procedure start column number.

 

Breakpoints window

The breakpoint window contains a list of the all active breakpoints. Breakpoints set by address are listed first, followed by breakpoints on SWIs.

Each line contents the following infos in the order listed below:
Break address, Break option, source filename, source line, procedure name
The letter after each breakpoint address has the following meaning:
F = fixed breakpoint, can be set or cleared only manually.
T = temporary breakpoint, is set and cleared automatically, but can also be cleared manually.

When you select-click on a breakpoint address, then the disassembly and source listing windows are synchronized so, that you can see the relevant location in these two windows.

When you adjust-click, then the breakpoint is removed, and as such it will dissapear from the window.

Each break on SWI line contains firstly the SWI number, then the SWI name

When you select-click a break on SWI line, the disassembler and source listing windows can not be sycronised, because only the SWI numbers, but not their addresses are stored. When you adjust-click a break on SWI line, then the break on SWI is removed, and as such it will disappear from the window

Clicking menu in this window opens the breakpoint menu

 

Source listing window

Clicking menu in this window opens the source listing menu

When you select-click on a source line, then the disassembler window will be 'syncronized' so that you can see the concerning location on both. If the symbol points into a data area, then the concerning location is shown in the Memory dump window.

When you adjust-click on a source instruction line, then this causes the same behaviour, but a break-point is set at the concerning location.
If there is currently no break-point already set. If there is a break-point set, then it is removed.

 

Source names window

It contents the names of all source files.
By clicking on a line the related source listing is shown.

 

Symbols window

The letters after each symbol value have the following meanings:
1st letter: A = absolute, C = code, D = data, N = zero initialised area;
2nd letter: L = local, G = global.

When you select-click on the symbol name, and the symbol value points into a program area, then the disassembler and source listings are 'syncronized' so, that you can see the relevant location on both.

When you adjust-click on a symbol name, and the symbol points into a program area, then the Disassembly and Source listing windows show the concerning location and a break-point is set to the relevant location if there is no break-point set at that location already. If there is already a break-point, then it is removed.

Clicking menu in this window opens the symbol table menu

 

Variables list window

For nested structures, the sub-structures are indented.

Each line beginning near the left margin tells you the following information:

• Type of variable (simple, array, struct)
• Type of number (signed / unsigned, integer / floating point)
• Memory space used: (byte, word)
• Variable name (with a star, if it is a pointer)
  

Inside the "<" and ">":

• memory address or register number
• source line and column number, where the variable appears on the source listing
• memory access class (external, static, register, automatic)
  

After the "=" you see the variable contents.

On indented lines you see between the "<" and ">" only the memory address or register number.

 

Click menu over this window opens the variables list menu

 

Procedures list window

The columns displayed in the procedures window are (from left to right):
procedure name, source listing relative filename, source line number of procedure start, source column number of procedure start, procedure entry address, procedure start address, source line number of procedure end, source column number of procedure end (most often zero), number of return addresses following, return addresses (as many as indicated by the preceding number)

Clicking menu in this window opens the procedures list menu

When you select-Click on the procedure name, then the disassembler and source listings are 'syncronised' so that you can see the relevant location on both.

When you select-click on any procedure address, then the listings are syncronized to show the concerning location.

When you adjust-click on a procedure name or address, then this causes the same behaviour as explained above, but a break-point is set at the relevant location if there is no break-point already set. If there is already a break-point set, then it is removed.

 

Memory dump menu

	Search	Leads to the Search window to search for strings in the memory
	Save	Leads to the Save window to save the memory dump.
	Display address	Leads to the window Show memory location

 

Show memory location window

	None (manual)	Disables the memory dump's auto-moving
	Register	Allows you to select a register number between 0 and 15 with the two arrows to the right of the register display. The 'Memory dump' window will be adjusted so, that the address contained in the selected register will be shown
	Address	Allows you to type in an address from &8000 onwards into the writeable field. You can omit the '&'. The addresses &0 to &F are interpreted as register numbers 0 to 15. The 'Memory dump' window will be adjusted so, that the address in the writeable field will be shown
	Show	Apply the selections. You can press [Return] too, if this window has the input focus.
	Cancel	Leaves the old selections and closes the window

 

Disassembler menu

	Breakpoint	Sets or clears a breakpoint at the address, described by the line, where the mouse pointer was, before the menu opened
	Show location	Leads to the Show program location window
	Options	Leads to the Disassembler options window

 

Show program location window

- In the frame 'current' you find in the display 'selected' the address, that is described by the line, where the mouse pointer was, before the menu opened. In the display 'Execution' you can see the execution address, where the program stands still at the moment.
- In the frame 'target' you can select between 'Execution' and 'Address'.
- If 'Execution' is selected, then the execution location is the target.
- If 'Address' is selected, then you can type an address into the writeable field. If you leave this field empty, then the address described by the
line pointed to by the mouse pointer before the menu opened is used.
- With a click on the button 'Show' or by pressing the return key the Disassembler and Source listing windows are adjusted so, that you can see the desired target in both windows.
- With a click on the button 'Cancel' you throw away the selections.

 

Disassembler options window

In the frame 'ARM instrucion writing' you can select one of the following three choices with the radio buttons:

• Mixed: All the ARM instructions are written with upper and lower case letters, hence: 'Add', 'Sub', 'MovLtS' and so on.
• Upper: All the ARM instructions are written with upper case letters only.
• Lower: All the ARM instructions are written with lower case letters only.

In the frame 'Miscellaneous' you can activate the following options:

• MOV R0,R0 as NOP: If this is enabled, then 'NOP' is shown instead of 'MOV R0,R0'.
• Show ADRL: If this is enabled and the disassembler recognises the relations, then the 'ADRL' pseudo instruction is shown.

In the frame 'Register names' you can activate the following options:

• APCS naming: When enabled, the register names are as follows: 'a1' bis 'a4', 'v1' bis 'v6', 'sl', 'fp', 'ip', 'sp', 'lr' and 'pc'.
  Otherwise the register names are: 'r0' bis 'r12', 'sp', 'lr' and 'pc'.
• Upper case: When enabled, the register names are in upper case letters, otherwise they are in lower case letters.
  

In the frame 'Labels and symbols' is the switchable display for the shown length of labels and symbols with the related down and up arrows.

• If 'Off' is shown, then no labels and symbols, but their values are shown.
• If 'Full' is shown, then the labels and symbols are shown in their full length without any limitation.
• If a number is shown, then the labels and symbols are truncated to the number of chars indicated by the number.

 

Source listing menu

	Breakpoint	Sets or clears a breakpoint at the line number, where the mouse pointer was, before the menu opened
	Show location	Leads to the Show program location window

 

Breakpoints menu

	Set breakpoint	Leads to the Set breakpoint window
	Clear breakpoint	Leads to the Clear breakpoints window
	Set break on SWI	Leads to the Set break on SWI window
	Remove breakpoint on SWI	Leads to the Clear break on SWIs window

 

Set breakpoints window

Type in a breakpoint address. Clicking on 'Set' or pressing the return key sets the breakpoint.

 

Clear breakpoints window

	'Selected only' clears the breakpoint described by the line, where the mouse pointer was before the menu opened.
	Temporary only clears only the temporary breakpoints.
	Fixed ones only clears only the fixed breakpoints.
	All clears all breakpoints.
	The desired action is taken by 'Delete' or cancelled by 'Cancel'.

 

Set breakpoint on SWI window

Enter a SWI name or number to breakpoint on. Clicking on Set or pressing return sets the breakpoint.

 

Clear breakpoint on SWI window

The first option clears the break on SWI described by the line, where the mouse pointer was before the menu opened. The second clears all SWI breakpoints.

 

Symbol table and procedures menu

	Search	Leads to the Search window to search for symbols
	Save	Leads to the Save window to save a symbol table
	Breakpoint	Sets or clears a breakpoint at the address of the symbol described by the line, where the mouse pointer was, before the menu opened
	Show location	If the symbol address is in the program area, then the Disassembler and Source listing windows are adjusted so, that they show that location. If the symbol address is in the data area, then the Memory dump window is adjusted so, that it shows that location

 

Variables menu

	Search	Leads to the Search window to search for variables
	Save	Leads to the Save window to save a symbol variables list.
	Options	Leads to the Variable options window to select variable search options

 

Variable options window

In the box 'Variables search finds:' are four radio buttons.
With two of them you can select, whether main variables or sub-variables are found.
With the two others you can select, whether variable names or type names are found.

In the box 'display limits' are the three switchable displays 'Array elements', 'Struct elements' and 'Nesting level'. With the up and down arrows at the right of each display you can switch between eight values for 'Array elements' and 'Nesting levels' and four values for 'Struct elements'. 'All' means, that all elements and levels are shown.

 

Program icon and icon bar menu

	Click with {Select} before the start of a debug session opens the Parameter window, or after the start of a debug session it brings the windows Control, ARM Registers, FPU Registers, Wimp Events and Kontext to the foreground. Click with {Special} opens always the Source Path window. Click with [Shift] and {Select} re-starts the just examined program. Click with [Shift] and {Adjust} opens the Choices window.
	Info	Shows the 'DeskDebug' program info window.
	Help	Starts the interactive help.
	Display	Leads to the Display submenu explained above.
	Re-start	Starts an already examined application again for another debug session. This option is greyed out while a debug session is aktive.
	Source Path	Opens the Source Path window.
	Parameters	Opens the Parameters window.
	Choices	Opens the Choices window.
	Quit	Terminates the debuggee and the debugger itself. 'DeskDebug' will ask you, whether you really want to terminate the debugging session and the debugger itself. The action is taken, if you click 'OK' or press the [Return] key.

 

Source path window

In the writeable field inside this window you can type in additions to the pathname to the source files (relative pathnames) or whole (absolute) pathnames. Alternatively you can drag the directory with the source files inside to this window. This puts the concerning pathname into the writeable field. Click then on 'Apply' to make the entry valid.
Clicking on 'Cancel' discards the entry, and the old values remain valid. You must set the Source Path, before you start the program to be examined!

If you find out afterwards, that in the 'Source Listing' window are only the line numbers, then click on 'Quit' on the 'Control' window, then change the
Source Path, then start the program to be examined (the debuggee) again. When the field is empty, then the default path is as described in the debug info. DeskDebug will then expect the source file directories, where they were
generated during the assembly or compilation.
^ means 'parent directory'. When you write this in the field, then DeskDebug will expect the source file directories in the directory above that directory mentioned in the debug info.
'^.source' means, that this directory contains a subdirectory named 'source'.
Please note, that DeskDebug reads the 'source path' entry only, when you start the program to be examined. So please set the correct 'source path', before you start the new debugging session.

 

Parameters window

In the writeable field inside this window you can type in the relative or absolute pathname of an executable file with the type 'DebImage' and then add further parameters. Dragging a file into this window puts its pathname into the writable field. You can drag several files, and each pathname will be added to the text in the writable field.
Click then on 'Debug' or hit the return key to start the debug session.
Click on 'Cancel' or hit the esc key to discard the entry and close the window.

 

Choices window

This window offers the possibility, that after the start of DeskDebug the most options are set, as the user likes them.

The frames in the following table contain options, that set the corresponding options in the windows and menus listed to the right accordingly after the start of DeskDebug.

Displays	There is an option for each entry in the submenu with the same name.
Control	The five options correspond to the ones in the Control window.
Disassembler	These options correspont to the 'Disassembler options' window.
Context	These two options correspond to the 'Context' window.
Variable display limits	The three switchable displays correspond to the three same ones in the 'Variable options' window.
Floating point nums	These options correspond to the same ones, that are visible at the bottom of the 'FPU registers' window, when it is toggled to its full size.

The two last frames offer special possibilities:

Misc	Save window's positions	Saves the debugger window's positions with the choices.
	Choices in '!Boot	Decises, whether the choices file is written into the '!Boot' directory or into the application directory.
Load and display	Factory settings	To load and display the factory settings.
	Effective setting	To get and display of a choice done in the mentioned windows in the Choices window.

The two buttons at bottom right edge outside the frames act as follows:
'Cancel' discards the choices just done and resets to the choices saved on disc.
'Set and save' makes the choice active immediately and saves it as a file.

 

Error handling

An error that occured in the debugee is displayed in an persistent window and you will hear a beep.

Single stepping and continuing after an error is not possible.

In most cases you can still look and use all the displays: (Registers, memory, disassembly, source listing, symbol table, procedures list and variable list) after an error. Only a few fatal errors later generate another error, which makes this impossible. In such cases both errors are displayed in wimp error boxes, and the debugee is terminated immediately.

Some examples of how DeskDebug handles errors in the debugee:

Data abort

Instruction fetch abort

Undefined instruction

 

Known issues

• 'DeskDebug' can examine only files with the type 'DebImage', but not with the type 'Absolute'.
• 'DeskDebug' can *not* handle squeezed files! If you try to examine such a file, then an error message will pop up.
• 'DeskDebug' can *not* step through any programs, that run in a TaskWindow. An error message is generated, if you try to examine a program running in a TaskWindow.
• If you want to step through a 'C' program without any debug information, then you must set a break-point at the start of the procedure 'main' by hand. However, the 'Shared C Library' then can not set up its handlers, what can lead to problems.
• Some SWIs and their parameters, the redraw data, the source file index and some other things are stored in the debugger's workspace. The concerning workspace ranges have a fixed size. At moment, there is *no* error handling for the overflow of these workspace ranges. Therefore it may cause problems, when your program has a too big source file, if it calls to many Wimp SWIs beetween two Wimp_Polls and so on.
• When you single-step through a program, then please look on VDU commands! If there are any multi-byte VDU commands, then please set a break-point after the last command parameter write instruction, before the initial VDU command is issued. Then click 'Continue', so that the whole command is executed in real time.
• If you are single-stepping throught the redraw code of the debugee, you should not move any other windows over this window being redrawn or you will 'erase' the window contents as the application cannot respond to redraw its own window.
• Indeed you can not move any windows belonging to the examined program (debuggee), when this stands still on a breakpoint or after a single step.
• When the examined program has a red bar in the 'Task Manager' window, and stands still after a break-point or single-step, then you should click only very shortly on this bar or at the right of this bar. When you hold down the mouse button too long, then the bar becomes green.
• While any menu is open, then you should *not* click with the mouse outside the menu! This closes the menu. To avoid this you can issue the commands 'Single-step' with [F1], 'Continue' with [F2], 'Quit' with [F5], 'Step over Procedures' with [F7] and 'Source Step' with [F8]. For this purpose the 'hot key' flag is set. The input focus in the control window helps too.
• When you click on a menu entry with {Select} or {Adjust}, then the concerning menu is closed, when the next break-point is reached. If you clicked the menu entry with Adjust, then the menu will re-appear anywhere on the screen, when the debugge calls Wimp_CreateMenu again.

 

Technical details

• On a break-point or after a single-step 'DeskDebug' calls Wimp_Poll on the examined task's behalf. Wimp messages concerning the debuggee and Wimp events to it are then queued. Exceptions: The Null_Event and Redraw_Request are not queued, because in these cases queuing would lead into endless loops. The KeyPress_Event is *not* queued, as this is *not* usefull. The window redraws and updates are 'emulated'. Any messages from the Wimp (for example MenuWarning) are *not* queued, as the Wimp sends them repeatedly. The Message_HelpRequest is not queued, as the Help application sends it repeatedly. To distinguish calls to Wimp_Poll on the debuggee's behalf and 'real' calls to Wimp_Poll done by the debuggee itself 'DeskDebug' uses own pre- and post-filters. To allow proper messages queuing and acknowledges it registers an additional post-filter to all tasks too.
• The Wimp SWIs DeleteWindow, OpenWindow, CloseWindow, DragBox, SetExtent, ForceRedraw, ProcessKey, SetCaretPosition, CreateMenu and CreateSubMenu between two calls to Wimp_Poll or Wimp_PollIdle by the debugee are trapped and queued. DeskDebug's pre-filter executes them, when the debuggee calls Wimp_Poll or Wimp_PollIdle. To ensure, that the SWIs GetWindowState, GetWindowInfo and GetWindowOutline everytime get the correct values, additional hidden windows are created, when CreateWindow is executed. The SWIs DeleteWindow, OpenWindow, CloseWindow and SetExtent are executed with these hidden windows too. When the examined program calls Wimp_SendMessage, then this SWI is executed so, that the correct return values are put into the message block, but no message is sent yet. The message itself is copied into a queue, that will be looked, when the examined program calls Wimp_Poll or Wimp_PollIdle, and then the messages are sent.
• To working together with the Toolbox 'DeskDebug' traps the SWIs Filter_RegisterPreFilter and Filter_RegisterPostFilter. It writes their parameters into its own workspace and calls the Toolbox pre- and post-filters from its own pre- and post-filters. 'DeskDebug' handles the 'internal' Toolbox Messages (&44EC0) correctly, so that Toolbox applications run properly.
• As the SWIs 'Wimp_AddMessages' and 'Wimp_RemoveMessages' do not work, when the Toolbox is active, 'DeskDebug' copies the application's messages list, adds its own message numbers to the copy and then provides the pointer to the new message list to the SWI 'Toolbox_Initialise'.
• To working together with the ColourPicker 'DeskDebug' traps the SWIs Filter_RegisterPreFilter and Filter_RegisterPostFilter, while the ColourPicker opens its window. DeskDebug traps the SWIsFilter_DeRegisterPreFilter and Filter_DeRegisterPostFilter, while the ColourPicker closes its window. 'DeskDebug' writes the filter parameters into its own workspace and calls the ColourPicker pre- and post-filters from its own pre- and post-filters.
• The 'low level' and 'take-alive' codes and the desktop user interface are together in the same module, so that I can call all routines with 'BL'. Therefore I did not implement a SWI interface.
• The 'DeskDebug' module provides the two *commands 'DeskDebug_Enter' and 'DeskDebug_Start'. They are only for internal use; you must not use them in your code!
• 'DeskDebug' uses the following internal Wimp Messages: &57580 = Show register window; &57581 = Hide register window; &57582 = Show special window (for output outside the Wimp); &57583 = Tell an error occured in the examined program; &57584 = Pass through an external Wimp Message (for messages queuing); &575A0 = Continue; &575A1 = Single Step. The messages &57580 to &57584 are sent by the 'take-alive-code'; the messages &575A0 and &575A1 are sent by the desktop user interface.
• The whole 'DeskDebug' is carefully hand-written in the good old ARM Assembly language. At moment there are 15500 Assembly Source lines. I am developping 'DeskDebug' since about six years. Many experiments were needed, and often I doubt, whether I would success or not.

 

Credits, Thanks and Acknowledgments

• Firstly I thank to God in the heaven, who gave me such good mental skills, that allow me to develop such a difficult project like this debugger. Often God gaves me good ideas!
• I thank to my parents, who supported me with money in the several past years.
• Thanks to Andreas Feldner, owner of the 'Flying Snail' software house in Germany, who told me the idea to develop this debugger, and that it is possible to multitask while debugging.
• Thanks to Andrew Clower, who gave me the Source code for 'Desktop Hacker', from that I use the Disassembler and some other code sequences in 'DeskDebug'.
• Thanks to Alan Wrigley, the Autor of 'Vigil', another useful debugging tool.
• Many thanks to David Ruck, who helped we with many hints, tips and advices, without them I could not develop this debugger. His patience helped me to overcome many problems.
• Thanks to Martin Wuerthner, who tests DeskDebug with big projects and helps me further.
• Last, but not least, my thanks go to Neil Spellings and Adrian Lees, who test this debugger further, publish and sell it.

Niklaus Weiss 2007