Amiga Elysian Archive/AmigaElysianArchive.iso/prog/utils/execdis.lha/instructions

Text File | 1989-04-27 | 15KB | 420 lines

Copyright (c) 1989 Markus Wandel

Version 1.0

Release notes, February 3, 1989


INTRODUCTION
------------

Here is a complete disassembly of the Amiga operating system
kernel.  This means everything in the ROM component "exec.library".
As this happens to include ROM-Wack and the ROM resident printf
routine, they are disassembled and commented too.  When I say
complete, I mean it.  All code is explained (explained to death
in places), all data tables are formatted nicely, and even the
pad bytes which the linker inserted between object modules are
shown.

I originally did this disassembly in the middle of 1988.  I felt
that I had to, since I wanted to write a device driver for a hard
disk project (which still hasn't come to anything), and felt that
there was insufficient information available to do this properly.
So I started tentatively snooping around SendIO() and related
functions, and spent about 60 hours snooping...

After the disassembly was done, it slowly came to me that I
couldn't legally give it to anyone, because after all, mixed in
with all my comments was a copy of Commdore-Amiga's proprietary
code.  Yet, numerous people wanted a copy.

After much thought and experimentation, this method of making the
disassembly available to the general public was developed.  The
comments are distributed, but the disassembly is not.  Instead,
you get a "script" file, containing the comments and instructions
on how to recreate the disassembly, using code which is disassembled
right out of your ROM.  Thus, I can distribute what I have written
and everybody can add what they already have, to get the whole
thing.  It implies, of course, that without the right version of
the ROM (or kickstart disk), this whole file will be worthless to
you.

There is a catch.  After you have run the enclosed programs and
recreated the disassembly, YOU MAY NOT REDISTRIBUTE IT.  You may
redistribute this archive (a Zoo file) in UNMODIFIED form only.
Just as buying a disk copier does not entitle you to redistribute
copies of all the software it allows you to back up, this method
of creating this disassembly does not entitle you to redistribute
the result.


CONTENTS OF THIS ARCHIVE
------------------------

Upon taking apart the Zoo file, you should have ended up with the
following files:

        pipe.device     - a public domain PIPE: handler
        mountlist

        dis             - a public domain disassembler (modified)

        start           - an EXECUTE script

        convert         - the program which does all the work

        dis.data        - the file which will be processed to
                          create the disassembly.

        instructions    - you are reading them

What to do with these files is explained in the next two sections.


WHAT YOU NEED
-------------

To create the disassembly, you need the following:

1. An UNMODIFIED version 1.2 ROM or kickstart disk.  Don't use
   a disk which has NoKlickStart or any other patch installed on
   it.  Don't use 1.3.  I did this disassembly before 1.3 came
   out, and I just didn't have the energy to change it to fit
   1.3 (the exec appears to have been changed slightly).

2. The "run" and "execute" commands in your c: directory.

3. Disk space:  A bit over 600 kilobytes, preferably on two
   separate disks.  One will hold the files from this archive,
   the other will hold the output file.  If you put both on the
   same disk, you will get a lot of disk thrashing.  People
   with 1 megabyte or more of memory can use the RAM: disk.
   People with two drives can use those.  People with only 512K
   and one floppy drive have no choice, just start with a blank
   disk and try not to listen to your drive being worn out.

4. A bit of space in your devs: directory to install the
   supplied PIPE: handler.


HOW TO RECREATE THE DISASSEMBLY
-------------------------------

NOTE:  A user using a heavily enhanced system (ARP, WShell, ARexx,
       ConMan, etc) has told me that the procedure below does not
       work on his setup.  See the next section for additional
       information if it also does not work for you.

1.  Have two sections of disk space, of approximately 300 and
    350 kilobytes.  Into the smaller section, put the following
    files:

        dis
        start
        convert
        dis.data
        run
        execute

    Get "run" and "execute" from your c: directory.  People who
    have hard disks or enough floppy drives or RAM to keep their
    c: directory online don't have to do this.

    At this point, if your system is anything like mine, you
    will have the above files on a floppy and either another
    floppy, or a RAM: disk, or a hard disk, with enough space
    to receive the output file.

2.  Install the PIPE: device.  1.3 workbench users can skip this,
    since they already have one.  1.2 users do the following:

    (a) copy the file "pipe.device" into the DEVS: directory

    (b) edit your devs:mountlist file to include the segment
        from the "mountlist" file in this archive.

    Note:  Only the included PIPE: device and the PIPE: device
    from 1.3 have been tested with this.  Other PIPE: devices
    (if any exist) may not work.

3.  Boot up your computer with a virgin 1.2 kickstart disk, or
    make sure it has 1.2 ROMs in it.  If you have a 1.3 ROM machine,
    find someone who still uses 1.2.

4.  Type "mount pipe:".  If you are about to remove your workbench
    disk, also type "dir pipe:", which will cause the handler to
    be loaded (you won't get a directory).

5.  Go to the directory where you put the files in step 1.
    Have room available for the output file (about 327 kilobytes).
    As explained earlier, don't make this the same disk as the
    input file or you will get a lot of unnecessary head movement.

6.  Type "execute start".  At this point, you should hear the
    drive gronk away for a while as two programs are loaded at
    the same time.  Eventually, you will get a prompt:

    Output filename?

7.  Type in the name, including disk and path if necessary, of
    your desired output file.  For example:

    Output filename? ram:exec.disassembly

    If you don't want an output file, just press RETURN at this
    point and the program will run without creating one.

8.  Wait as roughly 135 pages of disassembly scroll by.  If you
    (and I!) haven't screwed up anything, it will run all the way
    to the end (this will take a few minutes) and finish properly.
    If something goes wrong, such as that a file got corrupted,
    or you are using the wrong version of the ROM, things may
    abort with an error message.  Let's hope not.

9.  That's it.  Enjoy!  And remember, if you like this, don't
    upload the completed disassembly to a BBS.  Upload this Zoo
    file instead.  Don't convert it to an ARC file, don't throw
    away the Zoo file and then try to piece it back together to
    pass on.  If a BBS absolutely insists that only ARC files
    be uploaded to it (some do), put the Zoo file inside an ARC
    file and upload that.  I'm not kidding.  I think the sooner
    ARC dies out on the Amiga, the better for all of us.


WHAT TO DO IF IT DOESN'T WORK
-----------------------------

The "start" script looks as follows:

        run dis <pipe:todis >pipe:fromdis
        convert

It appears that this will not work properly on some systems which
have certain enhancements added to them.  On a system running ARP
(a 1.3 beta version), ConMan, ARexx, and WShell, executing the
above script did not start the disassembler running as it should
have.  I was not able to investigate, but the user reported that
the disassembly recreation process worked fine if the following
changes were made:

1.  Start up two CLI (shell) windows.

2.  Run the disassembler in the first CLI window:

      dis <pipe:todis >pipe:fromdis

3.  Run the conversion program in the other CLI window:

      convert

In essence, this takes the RUN and EXECUTE commands out of the
procedure.  I don't know what's wrong; it works fine on my system
with the original AmigaDOS commands and the Matt Dillon shell.


WHAT TO DO IF IT STILL DOESN'T WORK
-----------------------------------

If nothing else works, do what I did to verify the archive prior
to release:

- Boot with an original Kickstart 1.2, followed by an original
  Workbench 1.2.  Use CTRL-D to get a CLI right away.

- If you don't have two drives, you may want to copy all the
  necessary commands from C: to RAM: and assign C: there.

- Insert the disk where the files from the archive are, and get
  the PIPE: handler up and running as follows:

      assign devs: {where the pipe.device is}
      mount pipe:
      dir pipe:    (ignore the error)
      assign devs: sys:devs

- Get things rolling (make sure you have a big enough destination
  directory; with 1 meg you can use RAM:)

      execute start


HOW IT WORKS
------------

Let me start by explaining the big "dis.data" file.

This file contains all the comments from my original disassembly
file, plus commands which tell the program "convert" how to
reinsert the disassembled code and data tables.  The commands
have the following syntax:

<width> is a positive or negative number.  Positive means,
left justified within a column <width> spaces wide, negative
means right justified.

<width> can always be omitted, in which case no padding is
added.

@a=<hex address>

This sets the "current address" to the given value.  The next
byte disassembled or otherwise displayed will come from this
location.

@a?<hex address>

This checks that the current address is as expected.  I use this
periodically to make sure that things are still "on track", i.e.
the right instructions are being mated up with the comments.

@<width>b

Display a byte.

@<width>w

Display a word (4 hex digits).

@<width>l

Display a longword (8 hex digits)

@<width>x

Display an address (longword with only 6 digits shown).

@<width>d

Disassemble an instruction.

@<width>p

Display the current address as 6 hex digits.

@<width>,<length>s

Display a string.  It will be shown as a series of characters
in double quotes.  Nonprintable characters are shown in hex,
except for CR and LF, which are shown as such.

The "dis.data" file is read by the "convert" program and
converted to the final output.  To do this, the "convert"
program utilizes the services of a separate disassembler.

The disassembler is run with both the input and the output
redirected.  It takes its input from a pipe named "pipe:todis"
and writes its output to a pipe named "pipe:fromdis".  The
convert program is at the other end of both pipes.

The "start" script first uses "run" to launch the disassembler
in the background.  Then it runs the convert program in the
foreground.  The convert program opens its ends of both the
pipes.  When it is finished using the disassembler, it will
send a "quit" command to the disassembler, empty both pipes,
and exit.  This will cause the disassembler to cease running
in the background, and the pipes to be deleted, returning
everything to its original state.


CAVEATS
-------

The "dis" program has bugs.  The original version I used had
two nasty bugs and a couple of minor ones.  This version has
been improved:  The two nasty bugs it currently has are not
the same ones as the original ones.

The bugs I currently know of are the following:

1. A lot of instructions involving the status register (SR)
   or the condition codes (CCR) are disassembled incorrectly.

2. Instructions which have a direct byte operand which happens
   to be an ASCII character (such as move.b #'a',D0) are
   truncated after the "#".

3. "stop #$xxxx" is shown only as "stop".

Originally, these bugs caused me little grief:  I just patched
up the disassembly where I saw a problem.  But this time, the
disassembler actually has to recreate the code!.  Rather than
fixing the disassembler, I cheated and inserted correct versions
of all the problem instructions into the data file.  These also
include some 68020 and 68881 instructions (not many) which this
disassembler knows nothing about.

As a result, the "dis.data" file is not *quite* free of
Commodore-Amiga's proprietary code.  It includes about 200
bytes or so of readable disassembly.  But they are not
contiguous bytes, so they won't do anyone any good.

Why did I use this buggy disassembler in the first place?  I
had access to another disassembler, which was extremely well
written, had seen industrial strength debugging and testing,
and could disassemble 68020 and 68881 instructions.
Unfortunately, its output didn't look nearly as readable as
that of "dis".  I used it extensively to track down the
places where "dis" had screwed up, and to fill in the few
instructions specific to the 68020/68881.


CREDITS
-------

The "dis" program was written by Greg Lee, and later modified by
Willi Kusche.  I have changed it in the following ways:

    (a) The input can now come from a pipe, or a file, without
        crashing the program.

    (b) An input "end of file" condition causes the disassembler
        to exit.

    (c) No prompts are printed.

The program is still useable interactively though, just load it
by typing "dis" and type "?" to get a command summary.

The PIPE: handler was written by Matt Dillon.  It's pretty hard
to do anything on the Amiga and not use a program by Matt Dillon.

I should express my gratitude to all Amiga PD authors, and the
above in particular, for making this possible.  While I went to
much trouble to be able to release this file, I wouldn't have
gone as far as writing a disassembler or a PIPE: handler, so if
these hadn't been available, you wouldn't be seeing this.

Both these programs are declared to be public domain in their
respective release notes.  If you want to use them for anything
else, I suggest you scour the Fred Fish disks for the complete
versions, with source code and documentation.  Sorry, I forgot the
numbers of the disks, but start at the top and work your way
down in order to get the newest versions.

The files "instructions" and "dis.data" are by me, and are
copyrighted.  You may pass them on to other people, but only
as part of the unmodified Zoo file as described earlier.

The program "convert" was written by me and placed in the public
domain.  If you want to use it for a disassembly distribution
project similar to this one, please do!

The output file you get will contain material which is copyrighted
by me, and material which is copyrighted by Commdore-Amiga.  It
is explicitly NOT redistributable.

Finally, if you want to reach me for comments, this is my address
and phone number.  Well, it's my home address; I'm currently
attending university and my address varies.  Mail sent there
will reach me, and phone calls there will result in a phone
number where you can reach me.

    Markus Wandel
    R.R. #1
    Bruce Mines, Ont.
    P0R 1C0
    Canada

    [phone]