home *** CD-ROM | disk | FTP | other *** search
/ APDL Public Domain 1 / APDL_PD1A.iso / program / debug / wimpdebug / !WimpDebug / Docs / Tutorial < prev   
Encoding:
Text File  |  1991-08-27  |  11.3 KB  |  296 lines
  1.  
  2.                    *** WimpDebug Introductory Manual ***
  3.  
  4.  
  5.  
  6. ________________________________ In general ________________________________
  7.  
  8.    As you have probably sussed out by now, WimpDebug is a tool for
  9. monitoring what happens inside a Wimp application, i.e. it allows you to
  10. display various status information (variables, register values etc.) from
  11. your program in an easy-to-use fashion.
  12.    The purpose of this manual is to introduce you to the various ways in
  13. which you can use WimpDebug. It will learn you how to utilise the range of
  14. user interfaces in a step-by-step manner, starting at the top level with
  15. easy-to-use *commands and working downwards to the depths of assembler
  16. programming.
  17.    At all levels, the basic principles are very similar. The differences
  18. stem from the various requirements arising from the want of 'comfort' in the
  19. various modes of use.
  20.  
  21.    Start with running the WimpDebug application. This will load the module
  22. and start it up as a task, providing an icon on the icon bar. Click on the
  23. iconbar icon to produce the Display Window. It has 32 text icons, each of
  24. which may hold up to 255 characters of information.
  25.    And now for how to get something in those icons.
  26.  
  27.  
  28.  
  29. _________________________ The CLI/*command interface _______________________
  30.  
  31.    WimpDebug provides a simple way of putting information in the Display
  32. Window icons with *commands. For example, try entering the command
  33.  
  34.     *WDShow 1 Testing.
  35.  
  36. This will display the string "Testing." in icon number 1 in the Display
  37. Window - it's as simple as that! (For the moment, ignore the change of icon
  38. background colour from white to cream.) All WimpDebug interfaces work in a
  39. manner like this: you specify an icon number and what to display. In some
  40. circumstances it is also necessary to specify how to treat the information
  41. you want displayed, e.g. if you give WimpDebug a pointer you must tell it
  42. how to treat it (display the pointer value or the data it points at, etc.).
  43. That's not necessary with the *WDShow command, as the way to display the
  44. string is implicit in the command.
  45.    A variant of *WDShow is *WDShowEval, which takes an expression instead of
  46. a string as an argument and displays the result in an icon. You may specify
  47. a number base if wanted (default is signed decimal).
  48.    The *command interface is most useful if you want to display string
  49. constants (help text etc.) or system variables. Consider the following
  50. examples:
  51.  
  52. *WDShow 4 <File$Path>
  53.   Shows the value of the File$Path system variable in icon 4.
  54.  
  55. *WDShow 0 "Loop counter:"
  56.   Displays the given string in icon 0. You can use this kind of constant
  57. strings as a reminder of what the number displayed in icon 1 or 16
  58. represents.
  59.  
  60. *WDShowEval 18 40*1024*1024
  61.   Shows the result of evaluating the expression in icon 18 - this will be
  62. "41 943 040". Note the use of spacing between the thousands, millions and
  63. billions when showing large numbers.
  64.  
  65. *WDShowEval 5 <sys$year> 2
  66.   Shows the current year as a binary number.
  67.  
  68.    A variety of other *commands are also available. Type "*Help WD." to get
  69. a list of these.
  70.  
  71.  
  72.  
  73. ___________________ The BASIC/high-level SWI interface _____________________
  74.  
  75.    Let's get down to business and use WimpDebug with programs - that's what
  76. it was designed for. Run the following BASIC program:
  77.  
  78.    10 FOR n=0 TO 30
  79.    20 SYS "WD_DecS",n,2^n
  80.    30 NEXT
  81.  
  82.    This illustrates how to use ordinary SYS calls to get WimpDebug display
  83. something in its icons from a high-level language.
  84.    WimpDebug implements a range of SWI calls using the normal way of
  85. implementing these (SWI chunk number + 64 subroutines). The names of these
  86. calls all start with "WD_", which of cource is shorthand for WimpDebug. What
  87. follows the underscore is the display type you want to use for the value
  88. supplied in R1 (in the example above this is "DecS", which is shorthand for
  89. Signed Decimal"). The WRG contains a complete list of the various display
  90. types available - it can be found in the section entitled "SWI calls for
  91. high-level languages".
  92.    While looking in the Reference Guide, have a look at the following
  93. examples - they illustrate quite well the range of possibilities available
  94. with this simple debug SWI interface (all examples are in BASIC):
  95.  
  96.  SYS "WD_DecS",4,a%
  97.    Shows the variable a% as a signed decimal number in icon 4
  98.  
  99.  SYS "WD_HexI",7,p%,4
  100.    Shows the word pointed at by (p%+4) in icon 7
  101.  
  102.  SYS "WD_BinBI",1,buf%,6
  103.    Shows the byte at (buf%+6) as a binary number in icon 1.
  104.  
  105.  SYS "WD_StringZ",16,a$
  106.    Shows a$ in icon 16.
  107.  
  108.  SYS "WD_DecUBI",6,a$,5
  109.    Shows the code of the 6th character in a$ as an unsigned decimal number
  110. in icon 6
  111.  
  112.  SYS "DecU",7,a$
  113.    Shows the address of a$ on the BASIC parameter stack as an unsigned
  114. decimal number in icon 7.
  115.  
  116.  SYS "WD_HexBI",3,RIGHT$(a$)
  117.  SYS "WD_HexBI",3,a$,LEN(a$)-1
  118.    Both show the code of the last character in a$ as a hexadecimal number in
  119. icon 3
  120.  
  121.  SYS "OS_ValidateMemory",a%,b% TO ;f%
  122.  SYS "WD_PC+PSR",2,f%<<26
  123.    Shows the status of the processor flags returned by OS_ValidateMemory in
  124. icon 2. Note that a lot of other (in this case) redundant information is
  125. also shown.
  126.  
  127.  
  128.  
  129. _________________________ ARM code SWI interface ___________________________
  130.  
  131.    Using the previously discussed high-level language debug interface with
  132. ARM code programs works, but it's a tedious business, because you have to
  133. set up registers with specific values, which might interfere with the
  134. program you are writing - you will probably end up writing quite a lot of
  135. code in order to preserve the normal state of affairs, e.g. like this:
  136.  
  137.                 SWI     Wimp_Poll       ; Poll
  138.                 STMFD   SP!,{R0-R2}     ; Show the poll reason code in
  139.                 MOV     R1,R0           ;  icon 4
  140.                 MOV     R0,#4
  141.                 MOV     R2,#0           ; (clear the offset)
  142.                 SWI     WD_DecS
  143.                 LDMFD   SP!,{R0-R2}
  144.                 .
  145.                 (continue poll processing)
  146.                 .
  147.  
  148.    The above example isn't quite realistic, because it assumes that the
  149. SWI "WD_xxx" calls don't corrupt registers, which they do.
  150.  
  151.    With the ARM code SWI interface, you don't have to use registers for
  152. passing on information to WimpDebug. Instead, the information is coded into
  153. the SWI number itself. In addition, the ARM debug SWIs preserve all
  154. registers. These details in combination make the ARM debug SWIs completely
  155. transparent (noninterfering) to the program they are called from.
  156.    The only exception to this is R14_SVC, which is corrupted if the calls
  157. are made when the processor is running in Supervisor mode. The normal
  158. precautions (stacking R14) should be taken to make things work.
  159.  
  160.    If you glance in the WRG in the section on the ARM code SWI interface,
  161. you'll find out that calculating the exact SWI number to use in a given
  162. situation can be rather troublesome. It is much more handy to use macros to
  163. do this job for us.
  164.    In the directory 'Macros', inside the !WimpDebug application directory,
  165. two macro files are provided, ready for use. One is for the Acorn
  166. Stand-alone assembler, the other for the BBC BASIC Assembler.
  167.    Both of them assemble an ARM debug SWI instruction. The SWI number is
  168. computed by considering the parameters you pass on to the macro. In addition
  169. to the obvious possibilities, some more esoteric ones are also possible.
  170.    The two macros will now be discussed separately, as they differ quite a
  171. lot in use.
  172.  
  173.  
  174.                     *** The Aasm/ObjAsm macro ***
  175.  
  176.    The text-file 'Aasm' contains macro definitions ready for inclusion in
  177. your assembler source files - use the GET directive to perform the
  178. inclusion.
  179.    When you have got things set up, with the macro definitions included etc,
  180. using them is a piece of cake. For example, the previous example can now be
  181. rewritten like this:
  182.  
  183.                 SWI     Wimp_Poll       ; Poll
  184.                 Show    0,4,DecS        ; Show poll reason code in icon 4
  185.                 .
  186.                 (continue poll processing)
  187.                 .
  188.  
  189. Rather neat, don't you think? You may insert as many 'Show' instructions in
  190. your program as you wish - they don't have any influence on the execution of
  191. your program (except that they take some time, of course).
  192.  
  193.    As with the high-level SWI calls, you should, at this point, refer to the
  194. WRG. There you'll find a list of the various display methods on offer, as
  195. well as a description of the syntax of the macro parameters. This
  196. information can be found in the sections "ARM code SWI interface" and "The
  197. Aasm and BASIC Assembler macros".
  198.  
  199.    Here are some examples using the Aasm macro:
  200.  
  201.  Show 4,2,HexB
  202.    Displays the least significant byte of R4 (b0-b7) in icon 2 as a
  203. hexadecimal number.
  204.  
  205.  Show 3,16,StringZ
  206.    Displays the zero-terminated string pointed at by R3 in icon 16.
  207.  
  208.  Show 11,10,DecSI
  209.    Displays the word pointed at by R11 in icon 10 as a signed decimal
  210. number.
  211.  
  212.  Show 3,5,BinBI
  213.    Displays the byte pointed at by R3 in icon 5 as a binary number.
  214.  
  215.  Show 0,0,Bin,8
  216.    Displays the word pointed at by (R0+8) in icon 0 as a binary number. Note
  217. that indirection is automatically enabled if you specify an offset.
  218.  
  219.  Show 2,1,DecUB,3
  220.    Displays the byte pointed at by (R2+3) in icon 1 as an unsigned decimal
  221. number.
  222.  
  223.  Show 9,6,DecSB,-11
  224.    Displays the byte pointed at by (R9-11) in icon 6 as a signed decimal
  225. number.
  226.  
  227.  Show 1,3
  228.    Displays the value in R1 in icon 3, using the display type already in use
  229. in that icon.
  230.  
  231.  Show ,4,HexB
  232.    Alters the display type used in icon 4 so that the value shown will have
  233. its LSB displayed as a hexadecimal number.
  234.  
  235.  Show 14,7,PC
  236.    Displays the return address stored in R14 in icon 7, along with
  237. information about the PSR status bits.
  238.  
  239.  ShowStr 4,"Test string."
  240.    Displays the given string in icon 4.
  241.  
  242.  
  243.                    *** The BASIC Assembler macro ***
  244.  
  245.    The BASIC program 'BASIC' in the 'Macros' directory does for the BASIC
  246. assembler what 'Aasm' does for the stand-alone assembler. The functions they
  247. provide are in effect the same, but the implementations are different.
  248.    For example, the 'poll-loop' example given above can be coded with the
  249. BASIC assembler like this:
  250.  
  251. 10 LIBRARY "macros.basic"
  252. 20 DIM code% 100
  253. 30 FOR p%=0 TO 2 STEP 2:P%=code%
  254. 40 [OPT p%
  255. .
  256. 100       SWI    "Wimp_Poll"
  257. 110       FNshow(0,4,"decs")
  258. 120       .
  259. .
  260. 200 ]:NEXT p%
  261.  
  262. The example above also illustrates how to include the library into the main
  263. program, and that the macros expect you to use p% as the assembler pass
  264. control variable, for use in "OPT p%".
  265.  
  266.    The rest of the examples in this section will be the same as those given
  267. for the AAsm macro, only re-coded using the BASIC assembler macro. Refer to
  268. the section above and the WRG when following the examples.
  269.  
  270.  FNshow(4,2,"hexb")
  271.  FNshow(3,16,"stringz")
  272.  FNshow(11,10,"DecSI")
  273.  FNshow(3,5,"binbi")
  274.  FNshowo(0,0,"BIN",8)
  275.  FNshowo(2,1,"DECUB",3)
  276.  FNshowo(9,6,"decsb",-11)
  277.  FNshow(1,3,"")
  278.  FNsetshowtype(4,"hexb")
  279.  FNshow(14,7,"PC")
  280.  FNshowstr(4,"Test string.")
  281.  
  282.  
  283.  
  284. ______________________ Other things you should know ________________________
  285.  
  286.    The WimpDebug module is in fact a completely stand-alone of software - it
  287. doesn't really need the support files provided in the application directory.
  288. If you want to, you may copy the !RunImage file, which holds the module,
  289. into your library and rename it there to 'WimpDebug', or whatever you
  290. prefer. You may then load the module as part of your boot sequence by
  291. RMLoad'ing it. At the same time you may also give parameters - see the WRG
  292. in the section labelled "Booting".
  293. ____________________________________________________________________________
  294.  
  295. © Olav Reinert 1991
  296.