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: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: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: is a positive or negative number. Positive means, left justified within a column spaces wide, negative means right justified. can always be omitted, in which case no padding is added. @a= This sets the "current address" to the given value. The next byte disassembled or otherwise displayed will come from this location. @a? 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. @b Display a byte. @w Display a word (4 hex digits). @l Display a longword (8 hex digits) @x Display an address (longword with only 6 digits shown). @d Disassemble an instruction. @p Display the current address as 6 hex digits. @,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 (705) 785-3383