This readme file documents the structure of the source code a bit.
First a short overview how ADis works then a description of each
supplied file and what it does.

Overview

The  disassembly  part  of  ADis is rather easy.  There's a huge table
which  is  indexed  into by the upper 10 bits of the instruction being
disassembled.   This  table  contains the name of the instruction, two
fields  for  the  allowed addressing modes and a pointer to a function
which  handles  the  details  of  addressing  modes etc.  If there are
multiple instructions with the same bit pattern in the upper 10 bits a
chain of opcode entries is used to check the possible instructions one
by one.  The rest of the disassembly part is a collection of functions
which  handle the entries.  This setup is rather easy but allows for a
very fast disassembly.
The  part  of  ADis which should use the disassembler intelligently to
recognize  data  is a bit more complicated.  ADis keeps a symbol table
for named symbols and labels.  It reads the file to be disassembled up
to  three times.  
The  first  time  only  the  relocation  hunks are read to enter named
symbol  into  the  reference  table.   
The   second  pass  is  the  analysis  pass.   It  keeps  a  table  of
disassembled  parts  of  the file and iteratively tries to find a code
thread.    If  it  finds  a  code  thread  that  contains  an  illegal
instruction  it  backs  up  to  the last secure position and marks the
starting address as data.
The  third pass uses the array the second pass has filled to determine
if  the current location in the program should be disassembled as code
or data.


A tour through the source files:

defs.h
This file contains structures and constant definitions used throughout
the  program.   Additionally  it contains 'extern' definitions for all
global variables as well as prototypes.

refs.h
The   file   contains   definitions  for  the  reference  table.   See
ref_table.c for further details.

string_recog.h     
This  file  contains  just  one  array  to  determine  the  type  of a
character,  i.e.   if it is printable or not or if it is another valid
character such as linefeed.  The standard isalpha,...  functions could
not  be  used  because I wanted to be able to recognize german Umlauts
also.

amiga.c
This  file  contains most of the Amiga specific part of ADis.  This is
mainly for disassembling libraries and devices.  The rest of the Amiga
specific code is in hunks.c.

analyze.c
This  is  main 'intelligent' part of ADis.  I'm not particularly proud
of  this  code,  it's  rather  badly  readable.   ADis  first tries to
disassemble  all  parts  of  the program it has some hint that this is
code.   These  are locations that are jumped to.  When this is done it
tries   to  resume  disassembly  at  some  label  that  has  not  been
disassembled  yet.   If this fails too, it merely tries to guess where
to  resume.   In all those cases it might happen, that ADis steps onto
an  illegal instruction which causes backup to the last point of which
ADis is fairly sure.

decode_ea.c              
This  file contains only one routine for the decoding of the lower six
bits which contain the addressing mode used.

disasm_code.c            
This  file  calls  the disassembly routines appropriately depending on
the type of disassembly wanted (quick or 'intelligent').

disasm_data.c
This file disassembles the data and BSS hunks of a file.

fpu_opcodes.c            
This  contains  a  small table for the FPU opcodes.  As nearly all FPU
opcodes  start  with  the same upper 10 bits, seven bits of the second
word are used to index into this table.

globals.c
Contains all global variables.

hunks.c
This  file  reads  a  file in the Amiga load file format and calls the
appropriate routines to disassemble it.  Currently it does not support
the  additional  2.0 hunk types like DREL, because I could not get any
information about these.

jmptab.c                 
This file contains code to disassemble jump tables.  Jump tables are a
major difficulty for every disassembler, ADis recognizes at least part
of the often used jump table structures generated by some compilers.

main.c                   
The  main  program  file.   Handles  argument  parsing  and  calls the
routines that do the work.

mem.c                    
A  very  small  file  only  there  to make memory allocation easier to
handle and to replace.

mmu_opcodes.c            
Similar  to  the  FPU opcodes most of the MMU opcodes do not differ in
the  upper  10 bits.  A table for some bits in the second word is used
to call the appropriate function.

opcode_handler_cpu.c
These  are  the functions called via the opcode table.  Every function
is  called  with  a  pointer  to  the  current opcode entry and 'code'
pointing to the current instruction.  This way many instructions could
be handled in groups.

opcode_handler_fpu.c     
These are the functions for disassembling FPU opcodes.

opcode_handler_mmu.c     
These are the functions for disassembling MMU opcodes.

opcodes.c
This is the main opcode table.

ref_table.c              
This  implements  a  very fast reference table.  It has been tuned for
best performance for finding the next label from the current position,
because this is used by the analyzing pass extensively.

user_defined.c           
Handles used-defined labels given on the command line.

util.c                   
A  few  string  handling  routines.  These could have been replaced by
sprintf's but I wouldn't like to see ADis working with these (it would
take years).


This  is  it.  If you like to modify ADis or use parts of it dive into
the  code  and  have  fun.  I know it's documented very well, but it's
been  some  time  ago that I have written this.  If you have questions
regarding  the source code, do not hesitate to ask me.  Contact me via
e-mail if possible.

My address is:
apel@gypsy.physik.uni-kl.de

Have fun

Martin