APDL Public Domain 1

home *** CD-ROM | disk | FTP | other *** search

/ APDL Public Domain 1 / APDL_PD1A.iso / program / debug / wimpdebug / !WimpDebug / Docs / Guide next >

Wrap

Text File | 1991-08-27 | 17.8 KB | 426 lines

|> <WimpDebug$Dir>.Docs.Guide *** WimpDebug Reference Guide *** Last revision: 26. Aug 1991 Documents WimpDebug v1.21 Contents: -CLI commands -SWI interface for high-level languages -ARM code SWI interface -The Aasm and BASIC Assembler macros -General display characteristics -Wimp interface -Display errors -CLI errors ______________________________ CLI commands ________________________________ -- Boot -- The very first 'CLI command' you enter in connection with this module, in one way or another, is the one which loads (and starts up) the module, whether the actual command is "!WimpDebug" or "RMLoad WimpDebug" etc. In all cases, you may append to the 'boot' command the same set of options as to the *WDStartTask command. *WDStartTask [-WindowBg|-WBg <col>] [-WindowFg|-WFg <col>] [-IconBg|-IBg <col>] [-IconFg|-IFg <col>] [-NonvalueBg|-NBg <col>] [-NonvalueFg|-NFg <col>] [-ErrorBg|-EBg <col>] [-ErrorFg|-EFg <col>] [-WindowWidth <width>] [-LeftWidth <lefticonwidth>] [-OpenWindow <0|1>] [-IconNumbers <0|1>] This command (re)starts the WimpDebug task, which provides the display window in the desktop. The following options may be specified: -Colours: You may specify exactly what colours WimpDebug uses in the Display window: the window background and foreground colours, the normal icon colours used, and the icon colours used for indicating non-values and errors. The colours may be specified either with or without qualifiers. If qualifiers are not used, the number(s) given are read and assigned in strict left-to-right order, according to the colour list given in the syntax description. The colour numbers refer to the standard Wimp colours, and may thus be in the range 0-15. -WindowWidth (width> allows you to specify the width of the work area of the display window (in OS units) on the desktop. Note that this may be much wider than what can be seen at once on the screen. -LeftWidth <lefticonwidth> sets the width of the icons in the left column of the Display window. The right column then fills the space left in the window's work area. -OpenWindow <0|1>. This option specifies whether WimpDebug is to open its Display window immediately when it starts up as a task (e.g. upon entering the desktop). The number given is treated as a logical flag, i.e as a zero or non-zero. -IconNumbers <0|1>. If you set this option, the icons in the Display window will be numbered. The number given is treated as a logical flag, i.e as a zero or non-zero. All unspecified parameters retain their previous value. The option settings survive many things, like *RMTidy, but are reset to their default values by "*RMReInit WimpDebug". Examples: "*RMLoad %.WimpDebug -o 1 8 -efg 0" loads the WimpDebug module from the current library and sets these options: the OpenWindow option is enabled, window background colour is set to 8 (dark blue), and the error foreground colour is set to 0 (white). "*WDStart -i 0 -wfg 15 8 2" (re)starts the WimpDebug task after setting these options: icon numbering is disabled, the window background and foreground colours are set to 8 (dark blue) and 15 (cyan) respectively, and the icon background colour is set to 2 (grey). *WDShow <icon> <text> The given text string is displayed in the specified icon as a text constant. The <icon> number is treated as an expression which is evaluated, and the text string is GS_Trans'ed before use. *WDShowEval <icon> <expression> [<base>] The given expression is evaluated, and the result (a 32-bit signed integer) is displayed in the specified icon as a decimal number. Optionally, the number base may be specified explicitly - it may be either 2, 10 or 16. *WDListIcons Lists the contents of the Display window icons. The data are displayed in the same way as in the Display window icons. *WDClear Clears all Display window icons. ________________ SWI interface for high-level languages ____________________ For use of WimpDebug with high-level languages, a set of 'ordinary' SWIs are provided, which are easier to use and almost as comprehensive as the ARM code SWI interface The general form of these calls are: SWI WD_<disptype> (&CFF00-&CFF13) Entry: R0=icon# to use, range 0-31 R1=the value to show or use R2=offset Exit: Unspecified R1 and R2 are added before they are displayed or used otherwise (see the list of examples for how to use this facility). The display types you may choose between are (codes in decimal): Numbers: 0: Hex 1: HexB } Displays the value in the 2: DecS 3: DecSB } specified base. Uses either 4: DecU 5: DecUB } word or byte (LSB) value 6: Bin 7: BinB (Also, if you append an "I" to these codes (or add 8 to the code), they will show the data pointed at by the given value instead of the value itself (i.e. indirected data).) Strings: 16: StringZ (zero terminated) 17: StringCR (zero, CR or LF terminated) 18: StringSP (terminated by SPACE or any ctrl.char) These codes display the string pointed at by the given value. The post-fixes to the SWI names specify how the string is terminated. Others: 19: PC ('display R15', i.e. PC and PSR separately) ______________________ ARM code SWI interface ______________________________ For use with ARM programs, a completely different set of SWIs is avaliable instead of those mentioned above. These SWIs use the SWI number to pass on information such as the icon to use, the register to show etc. - you don't need to use specific registers for holding this information. Thus, these SWIs are completely transparent to the program they are called from. ARM SWIs (as I will call them from now on) are identified by b16-b23 of the SWI number being set, while b0-b15 hold the 'reason code' for the operation to be performed, as well as other information that may be required. Bit 15 of the reason code is used to distinguish between two major classes of operations: 0=display a register, 1=perform housekeeping/special operations. ---- b15=0: (Show register) Reason code composition: 0ooooooiiiiirrrr, where o=display op-code (6-bit value) i=icon# to use (0-31) r=register# to display (0-15) Reason codes (hex): 00: hexadecimal word 01: hexadecimal byte 02: signed decimal word 03: signed decimal byte 04: unsigned decimal word 05: unsigned decimal byte 06: binary word 07: binary byte 08-0F: indirected versions of codes 00-07: the register given is used as a pointer to data in memory, which is fetched and shown. 10: string, zero-terminated 11: string, control-char terminated (i.e. 0, 10 or 13 terminate) 12: string, space or ctrl terminated (i.e. codes<=32 terminate) 13-17: unused 18: Display register as PC+PSR 19-1F: unused 20: Show the register without type specification 21-27: unused 28-37: The same as codes 08-17, except that the word following the debug SWI instruction is treated as an offset literal and added to the value of the specified register before fetching the data to be shown. The offset is a two's complement number. 38-3F: unused ---- b15=1: (perform special operations) Reason code composition: 1oooooxxxxxxxxxx o=reason code (5-bit value) x=reason code parameters/unused (10-bit value) 00: Set display type for icon without modifying the data shown b0-b4=icon# (0-31), b5-b9=display type (00-1F) 01: Set icon to show string constant following SWI, zero-term. b0-b4=icon# (0-31) 02-1F: unused All op-codes in the above list labelled 'unused' are ignored if called. They will be used for future expansion. ______________ The Aasm and BASIC Assembler macro libraries ________________ Hand-calculating the SWI numbers every time you want to use a debug SWI soon becomes tiresome. To aid you in this respect, a couple of macros are supplied which do the hard work of assembling the correct SWI instruction, based on parameters supplied by you. *** The Aasm/ObjAsm library *** The supplied library source is ready for inclusion in your program, using the GET directive. It provides two macros: Show <reg>,<icon>,<disptype>,<offset> ShowStr <icon>,<string> The 'ShowStr' macro assembles an SWI which in effect resembles the *WDShow command in action. It simply displays the given string in the specified icon as a non-value. The 'Show' macro on the other hand is the core macro, which computes SWI numbers for all other functions provided by the ARM debug SWI interface. To achieve the various effects, a number of variations of the basic syntax is used, which the macro definiton recognises and handles. Note though, that the fields specified above never change their meaning. The display types available are similar to those used in the section 'SWI interface for high-level languages' above, i.e. 'Hex', 'DecS', 'DecU' etc. Refer to that section, and the comments at the beginning of the AAsm macro source file, for further information; also have a look at the examples in the Tutorial. "Show <reg>,<icon>,<disptype>" Th is is the basic and most common use of the macro. It will assemble an SWI instruction which instructs WimpDebug to show the contents of the specified register in the specified icon using the display type given. The range of display types accessible by this version of the macro call is those whose op-code is in the range 00h-1Fh. "Show <reg>,<icon>,<disptype>,<offset>" This variant assembles an SWI instruction with an op-code in the range 28h-37h. The given offset value is stored in the word following the debug SWI instruction. When executed, the value is fetched and added to the value in the specified register before being used for other purposes. "Show <reg>,<icon>" This will assemble an SWI instruction with opcode 20h, i.e. it will instruct WimpDebug to show the value in the specified register using the display type already used in the destination icon. "Show ,<icon>,<disptype>" This variant can be used if you want to alter the display type used in an icon without altering the value shown. It assembles an SWI with a 'special operation' op-code #0. The macros perform extensive parameter checking (using the ASSERT directive), to prevent you from using invalid or erroneous parameters, or bad combinations of parameters. Things that are trapped include register and icon values out of range, unknown display types, and invalid parameter combinations, e.g. "Show ,<icon>,<disptype>,<offset>". Note also that if you specify a show operation which includes an <offset> value, indirection is always used, even if it is not explicitly stated in the display type. *** The BASIC Assembler library *** The WimpDebug macros for the BASIC assembler are supplied as a library to be included into the main program, using the LIBRARY command. They consist of user-defined functions which take the required parameters and generate the necessary code corresponding to the required debug action. These are the functions available: FNshow(reg%,icon%,type$) FNshowo(reg%,icon%,type$,offset%) FNsetshowtype(icon%,type$) FNshowtext(icon%,text$) The type specification strings are the same as for the Aasm macros, the only difference being that the BASIC macros have case insensitive type names. The individual macros will now be discussed: -FNshow(reg%,icon%,type$) This is the basic macro for assembling an SWI instruction to show the contents of register reg% in icon icon%, using the display type specified by type$. If type$ is null/empty, the register value will be shown using the type already used in the icon. -FNshowo(reg%,icon%,type$,offset%) A variation of FNshow, which allows you to specify an offset value which is added to the register before it is shown. Indirection is enforced, and you may not leave type$ empty. -FNsetshowtype(icon%,type$) Assembles an instruction which does nothing but modify the show type used in an icon, without altering the value shown. -FNshowtext(icon%,text$) Creates code to show text$ in an icon, i.e. it displays a text constant. Note that all the macros assume that p% is used as the 'pass counter' variable in the assembler - the directive "OPT p%" is used every time the macros assemble something. Change the library file if this does not suit you. _____________________ General display characteristics ______________________ When a WimpDebug SWI is issued, the data shown reflect the state of the computer at the time of issuing the SWI, i.e. indirected data (including strings) are copied from the original memory location to a buffer within WimpDebug. This means that if the monitored value in memory changes later on, the value WimpDebug shows is not affected. Note that when using indirection with number values, the optional 'B' (to indicate byte values) separates between using the equivalent to LDR and LDRB. Thus, without 'B', the operation may only access data at a word aligned address, while 'B' operations may fetch data at any address within the valid addressing range. When displaying strings, WimpDebug will show no more than up to the first 250 characters of it. The format WimpDebug uses for showing the various types of data in the display window is as follows: -Indirected data are always preceeded by the string "-> " to signify that the number shown does not represent the actual value given. -Binary numbers: preceeded by the character "%" to indicate the binary base. In order to prevent unnecessarily long (and unreadable) strings of digits when displaying binary words, WimpDebug will (a) separate each byte in the word by a space, i.e. insert a space for every 8th bit, and (b) only show the significant (non-zero) bytes in the word. So 05A1h will be shown as "%00000101 10100001". -Hexadecimal numbers will be preceeded by the "&" character to indicate the base of the number. -Decimal numbers will be shown spaced, i.e. with a space character inserted for every 3 digits. So 87990 will be shown as "87 990". -Strings will be shown embedded in quotation marks. If the string is longer than the allowed 250 characters, it will be truncated; this is indicated by the string having '...' appended to it after the closing quotemark. Control characters (codes<32) in the string are shown as a hexadecimal number enclosed in square brackets, eg. the char with ASCII code 17h is shown as "[17]". -'R15'-like values will be shown like this: first the value of the PC on its own (b2-25 only), displayed as a hexadecimal word. Then the PSR flags and the interrupt disable bits; these are shown like this: "nZcv-IF" (for example). The PSR bits should be interpreted like this: lower case letters means that the bit/flag is reset, capital letters indicate the bit/flag is set. The interrupt letters are in capitals when the corresponding interrupts are DISABLED (so "iF" means IRQ enabled, FIQ disabled). Finally, the processor mode is shown using a three-letter code: USR, IRQ, FIQ, or SVC. -Non-values are shown with a different icon background colour than ordinary items. The term non-value refers to the fact that WimpDebug is not aware of how the displayed string was obtained, i.e. it was passed the string directly - no binary number to be converted or to use as a string pointer was given. The point in this distinction will become more apparent in (possible) later versions... ___________________________ The WIMP interface _____________________________ Well, there's not much to be said about this, since it's still quite simple and straightforward. WimpDebug puts an icon on the icon bar. The display window will be opened when you click on this icon. The icon bar menu has the usual 'Info' item, along with items for clearing all icons in the window and quitting the WimpDebug task (the module is not removed by this). The current version does not feature a menu or other actions in the display window. ____________________________ Display Errors ________________________________ WimpDebug will return an error message if requested to show something which is in some way illegal or impossible. The message appears in the icon which was intended for the data, and it is marked as an error message by special colours (the default is a red background). These are the errors WimpDebug can give: #0: Address exception You have tried to make WimpDebug show data in memory outside the allowable address range. #1: Data abort exception This error occurs if you try to make WimpDebug access a word in memory at an address which is not word aligned. #2: Unterminated string at end of memory This error occurs if you try to display a string which starts at a valid address but stretches into an invalid address area, without any terminating character to be found, i.e. it's sort of an address exception. #3: Unknown show opcode WimpDebug does not recognise the show operation code passed to it. #4: Show with unspecified type failed You have tried to show some data without specifying a type to use. This fails if the icon previously held a non-value #5: Show type changes may not be applied to non-values You have tried to apply a change of display style to an icon which held a non-value. _________________________________ CLI errors _______________________________ &1E6: Unknown WimpDebug operation. &CFF00: WimpDebug may only be started manually from within the desktop. &CFF01: WindowWidth too small. &CFF02: Left column width out of range. &CFF03: WimpDebug is unable to restore SWI hardware vector. &CFF04: Illegal icon number. &CFF05: Unknown window handle passed to WimpDebug for redraw. &CFF06: Invalid base specification given to *WDShowEval.