home *** CD-ROM | disk | FTP | other *** search
/ World of A1200 / World_Of_A1200.iso / programs / develop / adis / adis.doc < prev    next >
Text File  |  1995-02-27  |  15KB  |  329 lines
  1.  
  2.  
  3.  
  4.                    ADis (Advanced Disassembler) User's Guide
  5.                                 Version 1.1
  6.                          $Date: 93/05/16 22:41:50 $
  7.                            written by Martin Apel
  8.                         email: apel@physik.uni-kl.de
  9.  
  10.  
  11. CONTENTS
  12.   1. Introduction
  13.   2. Command line options
  14.   3. Hints and Problems
  15.   4. Reassembly
  16.   5. Theory of operation
  17.   6. Future plans
  18.   7. Miscellaneous
  19.  
  20.  
  21. *************************************************************************
  22.  
  23.  IMPORTANT NOTICE:  This program is copyrighted by Martin Apel, but can
  24.  be freely distributed, providing that the following rules are respected.
  25.  - No change is made to the program nor to the accompanying documentation
  26.  - The package is always distributed in its complete form consisting of 
  27.    the 4 files: "ADis", "ADis.doc", "README" and "libs/ixemul.library".
  28.  - Every form of distribution is allowed and encouraged, but no fee can 
  29.    be charged for this program except for, possibly, the cost of magnetic 
  30.    media and/or disk duplication and shipping.
  31.  - Inclusion in PD software libraries such as Fish Disks is allowed, 
  32.    provided the fees charged for these disks are comparable with those
  33.    charged by Fred Fish.
  34.  - The program cannot be distributed in any commercial product without the 
  35.    written consent of the author.
  36.  
  37.  By copying, distributing and/or using the program you indicate your 
  38.  acceptance of the above rules.
  39.  
  40.  
  41. *************************************************************************
  42.  
  43. 1. INTRODUCTION
  44.  
  45. ADis  is  a 68000+ disassembler which can automatically recognize data
  46. and  strings  put into the code segment.  It also generates only those
  47. labels  that  are really referenced.  The generated file will often be
  48. reassemblable.   In  V1.1 ADis is capable of recognizing all 68020 and
  49. 68881  instructions  even  with the 68020's extended addressing modes.
  50. ADis  will also try to resolve addressing relative to a4, which many C
  51. compilers use in a small memory model.
  52.  
  53. If  you  have  ever  worked  with  a  usual disassembler, you may have
  54. wondered  about all those nasty ORI.B #0,D0 or BVS $4711 instructions.
  55. The  first example is valid, but not very useful.  ADis will recognize
  56. this  and  generate  a  DC.W  0  instead.   The second example is even
  57. illegal, as it branches to an odd address.
  58.  
  59.  
  60. *************************************************************************
  61.  
  62. 2. COMMAND LINE OPTIONS
  63.  
  64. I  will list the possible options for a quick look here.  They will be
  65. explained in detail later.  The following options are available:
  66.  
  67.      -b num                           set buffersize for file buffers in KB
  68.                                       default: 10 KB
  69.      -c2                              enable 68020 instruction disassembly
  70.      -c8                              enable 68881 instruction disassembly
  71.      -ce                              enable extended 68020 addressing modes
  72.                                       (only in conjunction with -c2)
  73.      -fs                              put hunks in a single file
  74.      -fm                              put each hunk in a separate file
  75.      -i                               print addresses where illegal
  76.                                       instructions were found
  77.      -lc hex_address                  disassemble as code
  78.      -ld hex_address                  disassemble as data
  79.      -ml                              disassemble using large memory model
  80.      -ms[base_offset]                 attempt to address code and data 
  81.                                       relative to A4
  82.      -o outfilename                   filename of output file
  83.                                       default: <filename>.dec
  84.      -q                               quick disassembly, no labels
  85.                                       no data recognition in code segments
  86.      -v                               verbose
  87.  
  88. Option -b n:
  89.   You  can  set  the  size of the output buffer to increase the speed of
  90.   writing.  Default is 10 KB.
  91.  
  92. Option -c2:
  93.   This  option  will  enable 68020 opcodes and address register indirect
  94.   with   scaled   index   addressing  modes.   If  not  set,  all  68020
  95.   instructions will be recognized as illegal, and printed as data.
  96.  
  97. Option -c8:
  98.   This option enables 68881 opcodes.  If not set all FPU opcodes will be
  99.   disassembled as data.
  100.  
  101. Option -ce:
  102.   This  option  enables  the  extended 68020 addressing modes.  They are
  103.   disabled  by default, because I have never seen a program generated by
  104.   a  compiler  which really used one of them.  To perform well upon data
  105.   recognition,  the  disassembler  relies heavily upon detecting illegal
  106.   instructions.   By leaving this option disabled, ADis will detect more
  107.   illegals.
  108.  
  109. Option -fs:
  110.   ADis  can either put all hunks into a single output file or generate a
  111.   separate  file  for  each hunk.  The second option comes in handy when
  112.   disassembled files grow so large that they aren't easily processed any
  113.   further  if  everything is put together.  The default is to generate a
  114.   single  file  if  not  more  than  one hunk of each type exists in the
  115.   program  (CODE, DATA, BSS).  This default can be overridden by the -fs
  116.   or  -fm  option.   -fs  forces  ADis to generate a single file even if
  117.   there  are  multiple  hunks  of  the same type.  -fm forces to write a
  118.   separate file for each hunk even if there are only few of them.
  119.  
  120. Option -fm:
  121.   See option -fs.
  122.  
  123. Option -i:
  124.   This option will cause ADis to print its current address every time it
  125.   steps  onto  an illegal instruction.  This will make it easier for you
  126.   to set additional labels to aid ADis.
  127.  
  128. Option -lc hex_address:
  129.   ADis  keeps  a  table  of  all references.  If it doesn't recognize an
  130.   instruction  as code, it will print it as data.  To help ADis with its
  131.   task  to  recognize  code,  you  can  set  a reference at that address
  132.   telling it that this address is meant as code.
  133.  
  134. Option -ld hex_address:
  135.   Generates  a  label  in  ADis' internal tables, which will force it to
  136.   write  a  label out for that address and interpret the bit combination
  137.   at  that address as being data.  However you cannot force something to
  138.   be  disassembled  as data, if it is valid code.  It's simply an aid to
  139.   ADis where to start a new try for disassembly.
  140.  
  141. Option -ml:
  142.   By  default, ADis assumes that the program to be disassembled has been
  143.   compiled  using  a  small  memory  model with A4 as its base register.
  144.   Many  times  this  default  is  very useful, but if either it has been
  145.   compiled  with  the  large  memory  model  or  it  has been hand-coded
  146.   assembler or the like, the -ml option will forbid this default.
  147.  
  148. Option -ms:
  149.   By  default, ADis assumes that the program to be disassembled has been
  150.   compiled  using a small memory model with A4 as its base register.  It
  151.   tries  to  guess  the contents of A4 to generate correct labels.  When
  152.   you  see  many  parts  of the program being disassembled as data, this
  153.   value  is  probably  wrong.   Then you have to look for a "LEA xxx,A4"
  154.   instruction  or  the like and give the value "xxx" as parameter to the
  155.   -ms option.
  156.  
  157. Option -o filename:
  158.   This  option is easy to explain:  It sets the name of the output file.
  159.   Default is <input file>.dec.
  160.  
  161. Option -q:
  162.   Quick  disassembly.   When  this  option  is set, the analysis will be
  163.   skipped and everything inside the code segment will be disassembled as
  164.   code  if  possible.   Illegal  instructions  will  be printed as "DC.W
  165.   hex_val".
  166.  
  167. Option -v:
  168.   Lets ADis display verbose information.  Working on long files ADis may
  169.   produce  no  output for longer time and not access disks, so you might
  170.   think  it  isn't  doing  anything.   With  -v  it displays the current
  171.   address it is working on.
  172.  
  173. Additionally to those command line options the analysis pass can be
  174. terminated by pressing CTRL-D. This will cause the not yet analyzed
  175. part of the program to be disassembled as data.
  176.  
  177. *************************************************************************
  178.  
  179. 3. HINTS AND PROBLEMS
  180.  
  181. Because  ADis  doesn't really understand the code it is disassembling,
  182. it  is  possible that it makes a few mistakes, which in general aren't
  183. very  important,  but  they can be very annoying.  To circumvent this,
  184. there  are  a  few  options  which will modify ADis' behaviour in such
  185. cases.   There  are four problematic areas, in which ADis may generate
  186. strange disassemblies:
  187.   - Code generated by switch statements (PC relative)
  188.   - Code referenced only through jump tables (Relocated references)
  189.   - Different optimizations used by the original assembler the code was
  190.     produced with and the assembler you are using for reassembly.
  191.   - Unterminated code threads
  192.  
  193. 3.1 Code generated by C switch statements (PC relative)
  194.  
  195. ADis  can  recognize  jump tables as such in most cases, but it cannot
  196. compute  the  locations it references, because each compiler generates
  197. different   code  for  jump  tables.   This  might  lead  to  ordinary
  198. statements  disassembled  as  data,  because they are never referenced
  199. directly  by  any  code.  You can change that by looking at the output
  200. and  place a code label at the first address after the jump table with
  201. the  -lc option.  To have these switch statements reassembled properly
  202. you have to modify the output by hand.
  203.  
  204.  
  205. 3.2 Code referenced only through jump tables (Relocated references)
  206.  
  207. When  the  disassembled  program  uses  a  function  pointers and jump
  208. tables,  ADis  will  only generate data references for such locations.
  209. To  force  these to be disassembled as code you can place a code label
  210. at a certain address with the -lc option.
  211.  
  212.  
  213. 3.3 Different optimizations used by the original assembler the code was
  214.     produced with and the assembler you are using for reassembly
  215.  
  216. Most  assemblers  do  not  allow  instructions  to  be  specified very
  217. detailed.   A  "MOVE  $4,A6" instruction (a very common instruction on
  218. the Amiga) might be assembled as an absolute word or long reference to
  219. address  4.  This will change the length of the code generated and all
  220. subsequent  labels to be moved.  If this happens often, it might occur
  221. that  a branch might specifiy a destination outside of its range, i.e.
  222. a branch to an instruction just below 32K away in the original program
  223. might  lead  to  an  instruction more than 32K away in the reassembled
  224. one.   Compilers  do  not  have  this  problem,  because  most of them
  225. generate JMP or JSR instructions which will be optimized to BRA or BSR
  226. by the assembler if possible.
  227. Matter is complicated further, if code length is changed in a C switch
  228. statement.  Then the locations referenced by the offset table will not
  229. fit  anymore.   The  only  solution  to  this is to find the offending
  230. instruction  which  changes the code length and try to specify it more
  231. detailed (dependent on the assembler you use).
  232.  
  233.  
  234. 3.4 Unterminated code threads
  235.  
  236. ADis  assumes  all code threads to be terminated by a RTS, JMP, BRA...
  237. instruction,  i.e.   an  instruction  that unconditionally changes the
  238. control  flow  and  does  not  return.   Some  compilers such as GNU C
  239. generate  special code for the exit statement:  They generate a JSR to
  240. the  exit function, but since this will never return, there is no code
  241. following  the  JSR.   This  will cause ADis to run into the following
  242. locations,  which  might  be data.  Such data often represents illegal
  243. code  and  therefore  the whole thread will be marked as illegal.  The
  244. same occurs for code sequences such as
  245.           BEQ       label1
  246.           BNE       label2
  247. Neither  of  these instructions is an "end instruction" and the thread
  248. is assumed to be continued after that.  In a future version the second
  249. possibility  might  be  recognized as terminating a thread.  Until now
  250. there  is no option to fix the first case; in a future version I might
  251. add an option for generating artificial "end instructions".
  252.  
  253.  
  254. *************************************************************************
  255.  
  256. 4. REASSEMBLY
  257.  
  258. Reassembly  is  somewhat  complicated,  because  I  haven't  found  an
  259. assembler,  which fulfills all requirements.  Some of the available PD
  260. assemblers  such  as  "DAS"  from DICE and "NCode" load the whole file
  261. into  memory,  which  is  impossible for the large files, which may be
  262. generated  by ADis.  Others (e.g.  A68k) will not accept more than one
  263. segment  of  each type in one file.  Still others (e.g.  ASM68k) don't
  264. support  68020  and  68881  opcodes.   When  I  have found a usable PD
  265. assembler  I  will  adapt  ADis  to  directly  generate  code for that
  266. assembler.   For  the  time  being,  the  disassembled  code has to be
  267. modified  to  be understood by different assemblers.  However the only
  268. sections  that  need  to be changed should the NEAR and FAR directives
  269. and maybe cross-references.
  270.  
  271.  
  272. *************************************************************************
  273.  
  274. 5. THEORY OF OPERATION
  275.  
  276. ADis makes three passes through the program.  The first one only reads
  277. the  relocation  and symbol hunks and enters them into a symbol table.
  278. The second pass analyzes the code and stores the type of each location
  279. (code  or  data)  in  a temporary file.  The third pass writes out the
  280. code and data using the temporary file generated in the second pass.
  281.  
  282.  
  283. Analysis
  284.  
  285. The analysis is sort of a backtracking algorithm.  It assumes that the
  286. first  location in the first code segment is executable and traces all
  287. jumps  and  branches from there on recursively.  When stepping onto an
  288. illegal  instruction  it  takes back all decisions that lead there and
  289. flags  the  offending  location as data.  There are several heuristics
  290. which  are used when every code thread has been followed and there are
  291. still  undetermined  parts of the file.  E.g.  it will assume the next
  292. instruction  after  a  RTS  or  JMP  as code, tries to follow it until
  293. either  having  followed all threads again or stepping onto an illegal
  294. instruction.   During  all  this  trial  and error it takes the labels
  295. generated  so  far  as  an orientation where to try disassembling.  By
  296. inserting  labels  "by  hand"  you  can  modify  the  behaviour of the
  297. analysis  pass, but you can also mislead ADis, for instance by placing
  298. a  code  label  at  the second word of a legal instruction.  This will
  299. cause  ADis  to take back all its decisions, because an instruction is
  300. not allowed to cross a label.
  301.  
  302.  
  303. *************************************************************************
  304.  
  305. 6. FUTURE PLANS
  306.  
  307. There  are  several  things  I still want to add to ADis including the
  308. following:
  309.  
  310. - Support for 68030/040 and MMU
  311. - An option for disassembling libraries or devices
  312. - An option to generate artificial "end instructions" (s. 3.4)
  313. - Generate labels for switches (s. 3.1)
  314.  
  315.  
  316. *************************************************************************
  317.  
  318. 7. MISCELLANEOUS
  319.  
  320. Any hints, bugs, praise,... may be addressed to 
  321.                     apel@physik.uni-kl.de
  322. When  reporting bugs, please include the program that was disassembled
  323. incorrectly  or  otherwise revealed a bug in ADis (if possible).  Also
  324. include  the version number of ADis that produced the error.  Requests
  325. for future enhancements are also welcome.
  326.  
  327. -----------
  328. Martin Apel
  329.