home *** CD-ROM | disk | FTP | other *** search
/ RISC DISC 2 / RISC_DISC_2.iso / pd_share / program / tools / decaof / Doc / Text < prev   
Encoding:
Text File  |  1995-02-17  |  5.8 KB  |  168 lines
  1. [[ Note: This text-only version of the manual was produced by hand from
  2.    the Impression version. It is therefore likely that there are lots of
  3.    infelicities in the formatting; in particular, font changes have been
  4.    lost. If a sentence doesn’t seem to make any sense, see whether it’s
  5.    any better if you pretend some of the words in it are in italics. :-) ]]
  6.  
  7. User manual for decAOF
  8. ======================
  9.  
  10.  
  11. Legal rubbish
  12. -------------
  13.  
  14. This program is not public domain; it is mine. The same applies to this
  15. documentation. You don’t have to pay for it, and you may distribute it
  16. freely. You may not, however, (1) distribute modified copies, or (2) make
  17. money from it in any way. You may, of course, modify your own copy. If you
  18. think your modifications are improvements, get in touch with me and tell me
  19. more...
  20.  
  21.  
  22. About this program
  23. ------------------
  24.  
  25. This program (called decaof) reads an AOF file (i.e., an object file) and
  26. displays its contents interactively. It disassembles machine code, and
  27. inserts labels at addresses corresponding to symbols defined in the file. It
  28. displays everything in tasteful colours. It is economical in space, and runs
  29. quickly. It hasn’t crashed my machine for years.
  30.  
  31.  
  32. Just what is an object file, anyway?
  33. ------------------------------------
  34.  
  35. It’s a file containing machine code and data, but with some blanks still to
  36. be filled in, and with some information on how to fill in the blanks on other
  37. such files. Typically the blanks are addresses of functions, variables etc.
  38. It’s rather like an assembly-language program with all the labels still
  39. there, except that the actual assembly has been done.
  40.  
  41. Slightly less vaguely: an object file contains
  42.  • a number of areas, each containing code or data or both;
  43.  • a symbol table, giving the names of symbols used or defined in the areas;
  44.  • information on relocations to be done within the areas.
  45. Relocation is the process of filling in the blanks. The relocation
  46. instructions say things like “Add the value of symbol so-and-so to the word
  47. at location such-and-such”.
  48.  
  49.  
  50. Why do I need your program?
  51. ---------------------------
  52.  
  53. The AOF format is slightly hairy, and it’s not much fun staring at a hex dump
  54. of an object file trying to work out what relocations happen where. Perhaps
  55. more importantly, it’s very much easier to understand code when you know what
  56. function is where, and can see at a glance whether that mysterious BL
  57. instruction is calling printf or delete_all_my_files or solve_equations. And
  58. it’s useful to be able to move at a moment’s notice to a particular function.
  59.  
  60.  
  61. How do I use your program? --------------------------
  62.  
  63. Type decaof <filename>; you will be given some not-very-exciting information
  64. from the file header, and prompted for what to do next. At this point you
  65. enter commands and the computer acts on them; there follows a list of
  66. available commands.
  67.  
  68. The Address command
  69.  
  70. Address <address> | <symbol>
  71. Change the current address to the given location within the current area. If
  72. you give the address numerically, it should be in hexadecimal; otherwise, you
  73. may use the name of any symbol in the current area.
  74.  
  75. The Area command
  76.  
  77. Area <number> | <name>
  78. Change the current area to the one specified. Areas are numbered from 1 upwards.
  79.  
  80. The Areas command
  81.  
  82. Areas
  83. Display a list of all the areas in the object file, with their names, sizes
  84. and numbers of relocations.
  85.  
  86. The Symbol command
  87.  
  88. Symbol <prefix>
  89. Display all the symbols (in all areas, not just the current area) whose names
  90. begin with the specified prefix, together with their addresses where known.
  91.  
  92. The Symbols command
  93.  
  94. Symbols <area> | * | external | absolute
  95. Display all the symbols in a given area, or all symbols in the entire file,
  96. or all external symbols, or all absolute symbols.
  97.  
  98. The Goto command
  99.  
  100. Goto <address> | <symbol>
  101. Do the same as the Address command, and then display the rest of the contents
  102. of the current area until it’s finished or the user presses Escape.
  103.  
  104. The Page command
  105.  
  106. Page <address> | <symbol>
  107. Do the same as the Address command, and then display one screenful of area
  108. contents.
  109.  
  110. The Quit command
  111.  
  112. Quit
  113. Quit.
  114.  
  115. The Help command
  116.  
  117. Help
  118. Display a list of the available commands.
  119.  
  120. Calling the operating system
  121.  
  122. *<command>
  123. Pass the command to the operating system. Caution: if this loads in a
  124. program, it may well overwrite the code for decaof, and goodness only knows
  125. what will happen when it tries to return.
  126.  
  127.  
  128. Problems
  129. --------
  130.  
  131. • It would be nice if it were possible to write all the information decaof
  132. can produce to a file, for future use. I have a program that does that (an
  133. earlier version of decaof, in fact), but it doesn’t do all the nice
  134. interactive things that decaof does.
  135.  
  136. • decaof displays things in pretty colours. To do this, it assumes that the
  137. palette is set up as for the desktop. Running it in other circumstances (say,
  138. immediately after a mode change) may result in its trying to use flashing
  139. colours and things. Ugh.
  140.  
  141. • Because white-on-black text is less straining to the eyes than
  142. black-on-white, decaof changes the background colour. If for some reason you
  143. depend on having a white background, I suppose this might be a problem.  (I
  144. only mean that it does the equivalent of COLOUR 135; it doesn’t change the
  145. palette or anything.)
  146.  
  147. • I think I have observed problems when running decaof together with things
  148. that intercept OS_ReadLine, such as the LineEditor module. I don’t use that
  149. myself; if you have problems, let me know and I’ll see what I can do.
  150.  
  151.  
  152. Feedback
  153. --------
  154.  
  155. Here are an e-mail address and a snail-mail address for me. Both are valid as
  156. of February 1995, and both should work for quite a while yet. I should be
  157. glad of any comments you have about this program, whether positive or
  158. negative. Negative comments will be appreciated more if accompanied by
  159. practical suggestions for improvements.
  160.  
  161. e-mail: gjm11@pmms.cam.ac.uk
  162.  
  163. snail-mail:    Gareth McCaughan
  164.         Trinity College
  165.         Cambridge CB2 1TQ
  166.         England
  167.  
  168.