
                              !DisAssem 3.25
                             ================
                             ARM Disassembler

   This program is Public Domain. You are free to copy it and give it to anyone,
 as long as you don't make any profit, and as long as I'm fully credited (by
 including this file). You may NOT sell it, but PublicDomain-libraries may
 charge a nominal fee to cover the cost of disc, postage etc.

   If you have comments, improvements or if you simply want the latest version
 of !DisAssem, please contact me, my address can be found at the end of this
 file. Send me a disc (preferably with some PD-software on), and I'll return it
 with the latest version of !DisAssem plus some other PD-stuff by me.


   !DisAssem version 3.25     20 June 1994
 -------------------------------------------------------------------------
   The !DisAssem-directory contains the following files:

        !Boot               -
        !Help               - this file
        !Run                -
        !RunImage           -
        !Sprites            -
        !Sprites22          - MODE20 sprites
        CheckRun            -
        Docs.Keys           - read it!
        Docs.KeyWindow      - to be used with Richard Hallas' !KeyWindow
        Docs.Tutorial       - a brief intro to generating BASIC source code
        Resources.!Intro    -
        Resources.DisAssem  - DisAssem 1.25
        Resources.Intro     -
        Resources.Messages  -
        Resources.Options   -
        Resources.Sprites   -
        Resources.Sprites22 - MODE20 version of Resources.Sprites
        Resources.Templates -
        Resources.Ups       -
        Resources.XSprites  -

 -------------------------------------------------------------------------

About DisAssem
--------------
    DisAssem is a multitasking ARM disassembler. Multiple files can be loaded,
 and multiple views can be opened on each file.

This version (3.25)
-------------------
    Did a bit of work on the OLE support, but it's still not quite right.
    The icons now slab to grey, as recommended by the Style Guide.

Installing the program
----------------------
    Copy the application-directory and all the files within it to a suitable
 directory.

'Problems' or 'What DisAssem can't do'
--------------------------------------
    The known bugs and missing things are explained below together with
 whatever feature it concerns. Especially the last part of the explanation of
 automatic marking is important to be familiar with.
    One major problems is that sometimes, upon loading a file, DisAssem
 crashes with an Address Exception. Usually it works allright if you restart
 and reload the file...

Files
-----
    !DisAssem will load and disassemble any type of file, but usually only
 filetypes FFA, FF8 and FFC (Module/Absolut/Utility) will make any sense.
   Most large applications, including !Paint, !Edit, !Draw, !PipeDream etc.,
 are squeezed, and therefore appear garbled. These need to be unsqueezed before
 disassembling.

Load
----
    To load a file, drag its icon to the !DisAssem-icon on the iconbar.

Grab
----
    DisAssem can grab a part of memory or a module from the RMA (Relocatable
 Modules Area). Grabbing is controlled from the Grab window, which can be found
 in the iconbar menu.
    Modules in the RMA can be disassembled without copying them into the
 disassembler's own workspace. This is an easy and memory saving way of
 examining a module, but it's not without sideeffects: If the module is
 reloaded or RMKill'ed/RMReinit'ed, the new startaddress is likely to be
 different from the address DisAssem assumes.
   If the option 'Grab modules workspace' is selected, DisAssem will grab the
 first 2048 bytes starting from the position pointed to by the private word of
 the selected module (usually the workspace pointer).

Save
----
    The disassembled code can be saved as either text, BASIC or as a textfile
 in a format that can be read by AAsm. The marks, if any, can also be saved
 and reloaded.

The assembler
-------------
    The assembler appears when you press F1, and will already contain the
 instruction found at the cursor. You can then alter this and press RETURN
 or click on OK to assemble the instruction and write it back to the file.
 Please note, to assemble a SWI you need to enclose the SWI name in "".

BASIC
-----
    Although DisAssem tries hard to convert the source to BASIC assembler, it
 can't do the job 100% without help from you. Here are a few hints:
    * If you are disassembling a module, be sure to perform a 'Process header
      & tables' (see below).
    * Use EQUD as much as possible.
    * Always, ALWAYS give the code a 'Convert 'Undefined instruction''- and
      'Convert Coprocessor instructions'-treatment (see below).
    * After having used the scanner, look thru the code before saving it.
      If you find any code that hasn't been found by the scanner, push it
      onto the scanner stack, and rescan.
    Usually, you can assume that if the BASIC program runs without generating
 errors, then the produced code is similar to the sourcecode.

Cursor
------
    The black bar - the cursor - shows the current position in the file.
 Use the up- and down-cursorkeys and the SELECT-button to move it around.
 The last 512 cursor positions are buffered in a stack; scroll thru these
 using Ctrl-F8 and Ctrl-F9. 'Find cursor' or F5 scrolls the window to reveal
 the cursor.
    'Save instruction' will save the instruction at the cursorposition.
    'Export to !ARMcode' will send the instruction to !ARMcode, which will
 enable you to edit it and export it back to DisAssem.
    'Change word' enables you to change the value of the word at the cursor.
    'Alter instructions' uses BASIC syntax.

Process header & tables
-----------------------
     'Process header & tables' will try to mark those parts of the loaded
 module that are data/text instead of code. *-commands/SWI-tables and the
 module-header will be shown as EQUD, and marks will be set at several of
 the entry-points pointed to by the header.
     There is an options available which, when set, will perform this
 operation automatically when a module is loaded/grabbed.

Show software interrupts
------------------------
     Only selectable if the file is a module.
     This will open a window containing all the SWIs provided by the module.
 If the module isn't present in the RMA, only the SWI numbers will be shown.

Show *-commands
---------------
     Only selectable if the file is a module.
     Displays a list of the *-commands provided by the module.

New view
--------
     This will open a window with another view of the file. Different views
 can display different information. You can open a maximum of 5 views on
 each file.

Goto address
------------
     'Goto address' enables you to jump to a specified position. Selecting
 this menuoption (or pressing Shift F4) will open the Goto window.
 If the cursor is placed over a B- or BL-instruction, this window will
 contain the address specified by the instruction, relative to the cursor.   
    The addresses will be updated every quarter of a second if the option
 'Update' is set.
    Clicking on the icon 'Goto' (or pressing F4) will move the cursor to
 the specified position within the file. Clicking on the icon 'Branch by'
 will move the cursor the specified amount of bytes foreward or backward.

Marks
-----
    'Set mark' will set a mark/label (max 11 characters) at the specified
 position in the file. At present there is a limit of approx. 400 marks in
 a file. If the option 'Not if mark already exist' is on, an error occurs
 if you try to set two marks with the same name.
    Goto next/previous/closest mark works from the cursor-position and
 foreward/backward.
    If a mark is set at the cursor position, clicking on the 'Delete' icon
 will delete this mark.
    Renaming a mark is done by positioning the cursor at the mark, pressing
 F6 (open mark window) and entering the new name instead of the old one.
    Marks may be set at non-word-aligned addresses, but this is very likely to
 cause trouble, as the saving and redrawing routines only look for marks at
 word-aligned addresses.
    List marks will list all the marks in the file.

Automatic marking
-----------------
    'Automatic marking' will mark all words that are referenced by

      B<cond>     <address>
      BL<cond>    <address>
      LDR<cond>B  Rx,[PC,#<const>]
      STR<cond>B  Rx,[PC,#<const>]
      LDR<cond>   Rx,[PC,#<const>]
      STR<cond>   Rx,[PC,#<const>]
      ADD<cond>   Rx,PC,#<const>
      SUB<cond>   Rx,PC,#<const>

    Several options are available to control the setting of the marks.
    Amongst other things, you can control if a mark is to be set if <cond>=NV,
 that is, if the B/BL/LDR/STR etc. isn't ever going to be executed.
    'Force word alignment' should always be selected. This ensures that all
 marks are set at word aligned addresses (bit 0 and 1 clear). The sideeffect
 is that eg. ADD Rx,PC,#21 isn't dealt with correctly, as the mark is set at
 PC+20. When you save the sourcecode, the above instruction appears as
 ADR Rx,#xxxxxxxx instead of ADR Rx,<name_of_mark>.

Scanner
-------
    The scanner is controlled from the main menu or from the scanner window.
    The scanner tries to guess which part of the file is code, and which part
 is data. It does this by starting at one or more 'safe' addresses given by
 you, and then scans thru the file until it finds a MOV PC,R14 or another
 instruction indicating the end of a piece of code. During the scanning it
 remembers all B and BL instructions, and these are pushed onto the scanner's
 stack (shown in the scanner window) and the scanner then scans from the
 positions pointed to by these instructions.

    Having done all the scanning required in a file, you should select the
 menu option 'Data-Scanner marked-Either EQUD or scanner' to ensure that
 the saving routines recognize the result of the scanner.

    If the options 'Report suspecious instructions' (in the scanner window)
 is ON, the scanner stops when it meets one of the following instructions:
    ADD PC,PC,Rx,LSL#2, ADD PC,Rx,Ry or ORR PC,Rx,...
    You are then asked whether the scanning should continue or not, thus
 giving you the possibility to add the Branches in a branch-table to the
 scanner's stack.

    To remove an entry from the scanner stack, double click ADJUST on the
 entry to hilight it, then select 'Remove entry'.

EQUD
----
    BASICs assembler uses EQUD to assemble a specific word.
    'Show as EQUD' (or F9) toggles a word between being showed as EQUD or as
 the disassembled instruction. Several ways of converting a block of the file
 from/to EQUD is provided:
        Convert         Whole file
                        From/to last cursor position
                        Foreward to next ASCII 0
                        'Undefined instructions'
                        Instructions where cond=NV
                        Coprocessor instructions
        Clear           Whole file
                        From/to last cursor position
        Toggle          Whole file
                        From/to last cursor position
        Scanner marked  Force scanner result
                        Either EQUD or scanner

                    'Convert' means 'Show as EQUD'
                    'Clear'   means 'Don't show as EQUD'
                    'Toggle'  means .......

Options
-------
    Pressing F2 or selecting the menu option 'Options' will open the option-
 window, allowing you to control how the code is displayed.
    'Save' saves the options as default.

 The final, disassembled word/code is made up of 5 parts:
        Address     the address where the instruction came from
        Hex         the hex value of the word (before disassembly)
        Mark        (only if there's a mark at the address)
        Text        ASCII representation of the word
        Code        the actual disassembled code
    The first four parts can be turned on or off, individually for each view
 of the file, and different types of instructions can be shown in different
 colours.
    Each view of each file can be shown in either black or colour. The colours
 can be changed from file to file, but all views of the same file uses the same
 colours.
    The CODE part of the disassembler's output can be shown in either black or
 the same colour as the rest of the output.
    The rest of the options should be easy to figure out.

Find
----
    Select the option 'Find' or press F7 to open the find window.
    'Find' searches the file for a given SWI/word/mark/instruction or embedded
 string.
    Having entered the search criteria, clicking SELECT on the 'Find' icon
 will search foreward from the start of the file, ADJUST will search backward.
 Clicking on 'Next' or 'Previous' or pressing the 'up' or 'down' cursor key
 will search foreward/backward from the cursor.
    'List' will create a list of the first 1024 occurencies of the search
 string (doesn't work when searching for a mark).
    'Count' counts how many matches there are in the file (doesn't work when
 searching for a mark).
 Use Ctrl-C to copy the word/SWI etc at the cursorposition to the find-window.

  String: Control characters (&00-&19) and other non-printable characters can
 be entered by using the special character / to prefix the hex value of the
 character:
             /xx    translates to   ASCII &xx
             //     translates to   /

  Marks: You can search for a reference to a mark by prefixing the name
 with a '~', eg ~Label1. This searches for any instruction which, when
 disassembled, includes the string 'Label1'. So if you have a mark called
 'ReadMode' and the code includes a call to SWI OS_ReadModeVariable, that
 call will also be considered a match.

  Word: Prefix the value with & or % to use hex or binary notation. In this
 case the character # is treated as a single-digit wildcard, eg. &5#4 will
 find &504, &514, &524 etc., and so will %0101####0100. If the first character
 following the % operator is a *, the binary number will be expanded to full
 32 bits by prefixing it with ### (eg. %*0011 = %###..<23 more>..##0011).
  Likewise if the last char in the binary number is a *, but only one * may
 occur in the string, and then only in either end. The wildcard-parser isn't
 very advanced at present!

Tools
-----
    These are provided to make life easier for however needs them.
    Double clicking in the list of modules loads the module.
    Double clicking in the list of handler addresses loads the first 2048 bytes
 from that address and on.
    Double click in the clipboard list to set the position to read from when
 pasting.
    Double click in a list generated by 'Find', to go to that instruction.

OLE
---
    Note, OLE hasn't been tested yet.
    When the filer first sees DisAssem, the disassembler is set up as an OLE
 server for modules (filetype &FFA). This means that if you have a module
 included in eg. an Impression document, Impression can use DisAssem to
 edit the module.
    DisAssem treats OLE objects a little different from all other files,
 in that it only allows one view of the OLE object, and when you close that
 view, the file is saved and send back to the client (eg. Impression).

 --------------------------------------------------------------------------

  Henrik Bjerregaard Pedersen
  Stengaards Alle 13 B
  DK-2800 Lyngby
  Denmark

  Phone : (+45) 42 88 37 56

  E-mail: hbjphbp@unidhp.uni-c.dk