
                                  DisAssem tutorial
                                =====================

    This is a brief tutorial showing you how to generate a BASIC program
    that contains the source code for a ARM code program/file.

    Step 1:
        Start !DisAssem by double clicking on its icon in a filer window.

    Step 2:
        Load a file (module/application or utility) by dragging it to the
        DisAssem icon on the iconbar. The rest of the process is easiest to
        explain if I know which file you are working with, so I suggest you
        load the DisAssem utility module version 1.24 (located inside
        !DisAssem in the Modules directory).

    Step 3:
        When you've loaded the module a window appears showing the code.
        The border is hilighted, showing that that window owns the caret.
        DisAssem can be configured to process a large part of the module
        upon loading, but as I can't be sure your copy is configure to that,
        we'll go through the process here.
        Click MENU while the pointer is inside the window. Select the menu
        item 'Miscellaneous-Process module-Process header & tables'. This
        will set labels at strategic places in the module and will mark off
        the header as EQUD.

    Step 4:
        Click MENU inside the window and select the option
        'Mark-Automatic marking'. This will open a window allowing you to
        let the disassembler set mark/labels at all addresses referenced
        by B <address>/BL <address>/ADR Rx,<address>/LDR Rx,<address> etc.
        Simply click SELECT on 'OK' and the rest is done automatically.

    Step 5:
        Once again, click MENU inside the window and select the options
        'Data-Convert-Undefined instructions',
        'Data-Convert-Coprocessor instructions' and finally select the
        menuoption 'Scanner'.

    Step 6:
        The new window is the scanner. This allows you to scan thru the code,
        marking off those instructions that are code.
        First of all, you should deselect the 'Report suspecious instructions'
        options. If it is ON, the scanner reports back to the user whenever it
        meets an instruction like ADD PC,PC,Rx,LSL#2 (and others). This is
        very useful as it helps you to find branch tables, but we'll do it
        manually this time.
        You will see the string 0000::000000E8  SWIHandling  appearing in the
        top left corner of the scanner window. This means that the scanner is
        sure that there is some code starting at &000000E8.
        If you double click SELECT on the address in the scanner window
        you will see the code window scroll to reveal that address.
        You also will see the word SWIHandling is shown to the left of the
        code (if not press Ctrl-Shift-F3), which indicates that this is
        where the module handles the SWIs it provides.

    Step 7:
        Scroll down another 4 lines/instructions (using the cursor arrows),
        and the cursor will be positioned over this instruction:
        000000F8          ADD     PC,PC,R11,LSL #2
        This is the start of a BRANCH-table, and the 13 Branch instructions
        appearing immediately after that are the entries in the table.

    Step 8:
        Move the cursor (the black bar) down to the first of these Branch
        instructions and press F10 (F10=Stack cursor position; INSERT does
        the same job). This will put the address &00000100 on to the scanner
        stack. Repeat this with the 12 following Branch instructions.

    Step 9:
        You now have 14 entries in the scanner window. In conjuction, the
        14 entries point to everywhere in the module where there is code
        directly accessible from outside the module.
        The next thing to do is to select the option 'Scan all' in the
        scanner window.

    Step 10:
        After a short break the scanner list is cleared and the window with
        the code is redrawn, now showing a series of '' to the left of the
        instructions. This indicates that these instructions have been passed
        by the scanner, and therefore can be considered code.
        If you scroll down to &00002174 (press Shift F4, enter &2174 in the
        writeable icon to the right of 'Goto address' and then press RETURN)
        you will find approx. 100 bytes of data that is used when saving the
        code as BASIC, and you will see that the scanner, as it should, has
        recognized that part of the module as data.

    Step 11:
        We're not finished yet. You now have to transfer the result from the
        scanner to the list of instructions that the disassembler should
        treat as EQUD/data.
        This is done using the menu options 'Data-Convert-Scanner marked-
        Either EQUD or scanner'. Select this (or press Ctrl E) and you will
        see that all the instructions not marked with a '' are shown
        as EQUD &xxxxxxxx.
                
    Step 12:
        Finally press F3, select 'Save as BASIC' and drag the BASIC icon to
        a directory viewer.
        The file can then be loaded into an editor, or you can run it which
        will create a module that is similar to the original DisAssem module.


    The whole process can be summarized to:
     *  Process the module's header and tables.
     *  Set marks/labels where you think it is needed, or let the
        disassembler do it.
     *  Set EQUD mark where you think it is needed.
     *  Scan the code (after having added any extra entry points to the
        scanner list).
     *  Transfer the scanner result to the EQUD list.
     *  Save and run.
