w11 - /man/cat1/dasm-11.0

DASM-11(1)                   Retro Project Manual                   DASM-11(1)


NAME
       dasm-11 - simple dis-assembler for PDP-11 binary code

SYNOPSIS
       dasm-11 [OPTION]...  FILE
       dasm-11 --help

DESCRIPTION
       dasm-11  is  a  simple disassembler for PDP-11 binary code.  It reads a
       core dump in lsm-11(5) format from FILE.  If FILE is '-' the core  dump
       is  read  from  stdin.   If FILE ends on '.gz' it is expanded with gun-
       zip(1) on-the-fly.  The disassembled code is written in MACRO-11 format
       to  stdout,  followed by a symbol table, a cross-reference table, and a
       statistics summary.


   Basic operation
       In very simplified terms, dasm-11 tries to tag each memory word as  ei-
       ther 'code', 'word', 'byte', or 'asciz' and represent it accordingly in
       MACRO-11 format. Sequences of zero 'word' or 'byte' locations are  rep-
       resented with a .blkw or .blkb  directive, respectively.

       The  MACRO-11  output  is always an exact replica of the input and con-
       tains an equivalent representation of all memory locations  defined  in
       the input file.

       In  the most basic operation mode, dasm-11 is used with the --start op-
       tion to specify one or several start addresses.  dasm-11 tags these ad-
       dresses  as  'code'  and  follows all possible code execution paths and
       tags all instructions as 'code'. All memory locations accessed  via  an
       absolute  or  PC  relative address mode are tagged 'byte' or 'word' de-
       pending on the instruction.

       Without code start address via --start, dasm-11 can't do any code  tag-
       ging, and without any tagging, the output is simply a list of .word di-
       rectives, effectively a 1-to-1 dump of the input file.

   Guided operation
       The basic operation with just a few code  start  addresses  has  severe
       functional limitations
         - code reached indirectly, e.g. via dispatch tables, is not detected
         - strings are not detected and dumped as .word lists
         - parameters following 'jsr r5' and trap instructions aren't handled

       Beyond  that,  the  output  is  not very human-friendly, all labels are
       auto-generated with type letter and a 3-4 digit number,  the  immediate
       values  are  numeric,  and the whole output is flat without any annota-
       tion.

       All this is addressed in guided operation.  Additional  information  is
       provided to dasm-11 with 'diassembler steering' file, specified via the
       --das option. The steering file allows
         - to declare the data type for an address:  code,  string,  but  also
           rad50 or float, pointers to and arrays of any of those types.
         - to  declare argument lists for routines (e.g. called with 'jsr r5')
           and trap instructions
         - to declare symbolic names for literal values
         - to define a telling label name for an address
         - to add code annotation, full line or after statement comments
         - to define interrupt vectors

OPTIONS
       -I path
              adds path to the das file  include  search  path.   The  default
              search   path   is  '.'   plus  $RETROBASE/tools/dasm-11/lib  if
              RETROBASE is defined. Each -I adds path after '.'.   -I  can  be
              given multiple times und must have a single path name.

       --das=fnam
              if  specified  fnam  will be read as steering file.  If no --das
              option is given, dasm-11 tries to locate and  load  the  default
              steering  file.  A  '.gz'  and  a '.dmp' suffix is stripped from
              FILE, a '.das' suffix is added, and if that  file  exists,  it's
              loaded.

       --dmode=mode
              default mode of untagged data. Valid values of mode are
              word   represent  untagged  data  with .word directives (the de-
                     fault)
              asciz  interpret untagged data as zero-terminated ASCII and rep-
                     resent  it  with  .asciz  directives.  Useful for finding
                     strings.
              code   interpret untagged data as code. Can be helpful to detect
                     code sequences.

       --start=nn[,...]
              list of code start addresses. nn is interpreted as octal number.
              Either a single value of a comma-separated list of values can be
              specified.   Each address is used as starting point of code tag-
              ging.  When dasm-11 is used  without  a  steering  file  and  no
              --start  option  is  given, no code tagging will be done and the
              output is simply a list of .word directives.

       -help  print full help text and exit.

OPTIONS FOR DEBUG
       --draw  dump raw data.

       --dtag  dump tagged data.

       --tctag trace code tagging.

       --ttlc  trace typlabcref calls.

SEE ALSO
       asm-11(1), lsm-11(5)


AUTHOR
       Walter F.J. Mueller <W.F.J.Mueller@gsi.de>


Retro Project                     2022-08-25                        DASM-11(1)