PILOTDIS(1)                                           PILOTDIS(1)


NAME
       pilotdis - disassemble PalmOS (MC68000) object code

SYNOPSIS
       pilotdis   [-ddd]  [-a file]  [-all[c]]  [-b file]  [-bad]
       [-f file]  [-fdigits digits]  [-i file]  [-isp]  [-j file]
       [-l]   [-lft]   [-n file]   [-ns file]   [-o file]  [-odd]
       [-pc initialpc] [-s length] [-slenp length] [-sp]  file...

DESCRIPTION
       pilotdis is a disassembler for  the Motorola 68000  family
       of cpu devices,  optimized  for PalmOS  object files.  The
       disassembler attempts to discern  between the  instruction
       and data portions of an object code file.

       pilotdis produces output files much like cc(1).  When  the
       -o  option is not used, file arguments that end in .o have
       output filenames with .s substituted for .o; otherwise, .s
       is simply appended.

       The output consists of five columns:

       o      program counter in hexadecimal

       o      file contents with each byte displayed as two char-
              acters in hexadecimal

       o      label (if any)

       o      instruction name

       o      operands (if any)

OPTIONS
       -ddd   Specifies the chip and coprocessors.  Valid  values
              for ddd are currently 000, 008, 010, 020, 030, 851,
              881, and 882.   This  option  may  be  repeated  as
              appropriate.   The default is 000 with no coproces-
              sors.

       -a file
              Specifies that file  contains  lines  of  the  form
              ``aXXX instruction-string''  which  specify accept-
              able A-line opcodes.  XXX is in hexadecimal.

       -all[c]
              Specifies that only one pass should be  made,  out-
              putting  the  instruction  (if  any)  at  each word
              boundary.  If the c is included, -i, -j, -n and -ns
              options  are  also  processed,  and another pass is
              made to ensure consistency between instructions.

       -b file
              Specifies that file contains program counter values
              which  are  taken as locations in data to be output
              on a new line.  The values should be one to a line,
              and  of  a  form  acceptable to strtoul() with base
              equal to 0.  Hex values should be preceeded by 0x.

       -bad   Specifies that lines should be printed to  standard
              error  that  specify  which data caused a potential
              instruction to be made invalid.

       -f file
              Specifies that file  contains  lines  of  the  form
              ``fXXX instruction-string''  which  specify accept-
              able F-line opcodes.  XXX is in hexadecimal.

       -fdigits digits
              Specifies that  mantissas  of  floating-point  con-
              stants  should  be  printed with digits significant
              digits.  The minimum value  of  digits  is  2;  the
              default is 6.

       -g file
              Specifies that file contains A5 offsets  and labels
              for  global  variables.   Normally  the A5 register
              points to  a heap  area used for  global variables.
              The offsets  values  should be  one to a  line in a 
              form acceptable to strtoul() with base  equal to 0.
              The negative  offset should be followed by the name
              of the global variable.

        -i file
              Specifies that file contains program counter values
              which are, if possible, to be taken as locations of
              valid  instructions.  The values should be one to a
              line, and of a form acceptable  to  strtoul()  with
              base equal to 0.   The lines  may  also  contain  a
              label  and/or  a  line  count  'name:count'.   If a
              name is specified  then a label will  be forced  at
              this address.  If the name was 'L' or 'l' the label
              will be in the usual  numeric form 'Lnnn' otherwise
              the supplied name will be used as the label.

       -isp   Specifies  that  the  determination  of  a printing
              character should be  done  by  the  local  system's
              isprint().  By default, only ASCII characters (0x20
              to 0x7e inclusive) are considered printing  charac-
              ters.

       -j file
              Specifies  that  file  contains  A-line  and F-line
              opcodes which are unconditional jumps and therefore
              do  not need to be followed by a valid instruction.
              The values should be one to a line, and of  a  form
              acceptable to strtoul() with base equal to 0.

       -l     Specifies  that  output  should  be  in lower-case.
              (Exception: Label references retain  an  upper-case
              ``L''.)

       -lft   Specifies  that  instructions that ``fall through''
              to a LINK instruction should be  considered  valid.
              By   default,  these  instructions  are  considered
              invalid.

       -n file
              Specifies that file contains program counter values
              which  are  to  be taken as locations of data.  The
              values should be one to  a  line,  and  of  a  form
              acceptable to strtoul() with base equal to 0.   The
              lines  may  also  contain  a label  and/or  a  line
              count 'name:count'.   If a name is specified then a
              label will  be forced at this address.  If the name
              is 'L' or 'l' the label will be in the numeric form
              'Lnnn' otherwise the supplied  name will be used as
              the label.

       -ng
              Specifies that the table of global cross references
              should not be produced.  The global cross reference
              table will only be printed if the '-ng' was not put
              on the  command line,  a full two pass  disassembly
              was used (no '-all') and  references relative to A5
              were found.

       -nl
              Specifies that the  table of label cross references
              should not be produced.  The label  cross reference
              table will only be printed if the '-ng' was not put
              on the  command line,  a full two pass  disassembly
              was used (no '-all').

       -ns file
              Specifies that file contains program counter values
              which  are  to  be  taken  as  locations  at  which
              instructions  do  not  begin.   The  words at these
              locations  may,  however,  be  extension  words  of
              instructions.   The values should be one to a line,
              and of a form acceptable  to  strtoul()  with  base
              equal to 0.

       -o file
              Specifies  the  output  file.   Only one file to be
              disassembled may be given when this option is used.

       -odd   Specifies  that  instructions may begin at odd off-
              sets.  This can be useful when code to be disassem-
              bled  is  not  stripped  out of an object file.  In
              particular, this option is often needed when disas-
              sembling an intact Macintosh resource fork.

       -pc initialpc
              Specifies  that  initialpc  be taken as the program
              counter value for the start  of  the  object  code.
              The default is 0.

       -s length
              Specifies that data contain at least length consec-
              utive printing characters to be output as a string.
              The  minimum  value for length is 2; the default is
              5.

       -slenp length
              Specifies that strings should  print  out  no  more
              than  length characters per output line.  The mini-
              mum value for length is 10; the default is 30.

       -sp    Specifies that register A7 should be output as  SP,
              except in MOVEM instructions.

       -t file
              Specifies that file  contains  lines  of  the  form
              ``XXXX instruction-string''  which  specify accept-
              able trap 15 codes.  XXXX is in hexadecimal.

NOTES
       The output is based on Motorola syntax.

       Immediate  values are sometimes also output in hexadecimal
       after an intervening !.

       The following procedure is used to  filter  out  the  data
       from the instructions:

       o      An  initial  pass is made determining at which file
              offsets potential instructions exist and the  sizes
              of those instructions including operands.

       o      File  offsets  specified  by the user as being data
              are processed.

       o      File offsets specified by the user as not  starting
              instructions are processed.

       o      File   offsets  specified  by  the  user  as  being
              instructions are processed.

       o      Potential  instructions  which  reference  data  as
              instructions  are  changed  to data.  (This step is
              repeated after each of the remaining steps.)

       o      LINK instructions which are referenced by  BSR  and
              JSR  instructions  are  accepted  as final instruc-
              tions.   (A  final  instruction  is  one  that   is
              included in the final output.)

       o      Remaining  LINK  instructions are accepted as final
              instructions.

       o      Branching and jumping instructions  that  reference
              final  instructions and are not potential extension
              words of floating-point instructions  are  accepted
              as final instructions.

       o      Remaining branching and jumping that are not exten-
              sion words of potential floating-point instructions
              and  returning  instructions  are accepted as final
              instructions.

       o      Overlapping instructions are selected by minimizing
              the amount of data.

BUGS
       Since  pilotdis uses  the imperfect procedure given in the
       NOTES, errors may result in the instruction/data  determi-
       nation.  When problems are suspected,  the -bad option can
       be used to determine why instructions get  interpreted  as
       data.   You  can  then use the -i, -ns, and -n options, as
       appropriate.

       The character set used in the object file may  be  neither
       ASCII nor that used by the local system.

       Two  unusual  conditions  checked for should be mentioned.
       Sometimes the decision to designate an  instruction  as  a
       final  instruction  is later contradicted and the instruc-
       tion is changed to  data.   In  general,  the  instruction
       causing  the  contradiction should be regarded as data via
       the -ns option.  Also, sometimes it is reported that there
       is  an  ``overlap''  at a certain offset.  This is because
       pilotdis is unsure if the best selection  of two  possible
       instructions  which  overlap each other was made.  A quick
       inspection of the output at this offset should clear  this
       up.  Messages for these conditions are printed to standard
       error.



                        November 15, 1994                       4


SEE ALSO
       1.     Motorola: M68000 8/16/32 Bit Microprocessors:  Pro-
              grammer's Reference Manual, 5th ed., Prentice-Hall,
              Englewood Cliffs, NJ, 1986.

       2.     Motorola: M68030:  Enhanced  32-Bit  Microprocessor
              User's  Manual,  2nd  ed., Prentice-Hall, Englewood
              Cliffs, NJ, 1989.

       3.     Motorola:  M68851:  Paged  Memory  Management  Unit
              User's  Manual,  2nd  ed., Prentice-Hall, Englewood
              Cliffs, NJ, 1989.

       4.     Motorola: M68881/MC68882: Floating-Point  Coproces-
              sor  User's  Manual, 2nd ed., Prentice-Hall, Engle-
              wood Cliffs, NJ, 1989.

AUTHOR
       Christopher G. Phillips
       Christopher_Phillips@pe.utexas.edu
