NOTE: This is Karl's original README file, which is here for sake of
completeness. Please read the first lines of the CopDis.c source for the
latest news...

                                       seba

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


copdis - copper disassembler  0.0a  6/29/89  (alpha release)


OVERVIEW

Greetings.  The intrepid Amiga hacker, seeking to gain knowledge in the
intricacies of the video coprocessor, or copper, may find use in this
program: a copper list disassembler.

The copper is a source of unspeakable power and it must be studied.

The copper is a programmable processor, capable of executing a very simple
set of instructions that allow it to control much of the Amiga hardware,
including all of the display characteristics and functions, audio functions,
the blitter, serial port and even the floppy disk drives.

The copper has the capability of synchronizing its operations with the
drawing of the display.  Copper programs can use this to do specific
things to specific portions of the screen such as alter color registers,
change display resolutions, etc.  It can also use this capability to
provide a precision timer by which its operations can be precisely ordered,
for example, for using the copper to play music without the intervention
of the 68000 processor.

The copper has a particularly interesting, but little used, capability by
which a currently executing copper program (Copper programs basically must
complete within about 1/60th of a second.) can set up another address for
the copper to begin executing at.  The copper would normally begin executing
at that address at the start of the next video field.  It can be forced to
begin executing it immediately with an additional instruction.

As there are two copper "program counters," it is possible to have a
one-deep subroutine calling capability whereby programs execute running
copper PC 1 and call subroutines by loading their addresses into copper
PC 2 and strobing the location to causes the coppper to start executing
the "subroutine."  At the completion of the subroutine, it strobes the
address that causes the copper to execute using PC 1, which resumes
the caller -- UNTESTED

If that works, a deeper interrupt nesting scheme can be created, if
necessary, involving the copper interrupting the 68000 and getting it
to handle a stack and such.  (kink value == maximum)

USING COPDIS

There are two ways to use copdis.  One is to execute the copdis program.
This goes out and finds various presumably interesting copper lists and
prints them out for you.

The other way to use copdis is to call it directly from your C program.
Simply link copdis.o (after compiling it from copdis.c for the memory
model you're using) in with your program, and call the subroutine 'copdis'
with a pointer to a copper instruction list.  Note that structures such
as "struct cprlist" are not pointers to instruction lists but pointer
to structures that point to instruction lists or point to something that
points to an instruction list.  I think the calls in main are correct,
but I'm not promising *anything.*

BUGS

This program is in a primitive state.  Right now it doesn't take a length
and if it gets passed a bogus address (i.e., not an address of a real
and properly terminated copper list), it can run on and on.  For all I
know, it may even get lost doing OK lists, but I haven't seen that happen,
at least not for a while.  It really ought to do a sanity check on the
size of the list, like stop after an absurd number of instructions go
by, but you can always control-C anyway.

Note also that I'm not a copper expert so any of the information in the
README here could be wrong as well.


Regards, Karl Lehenbauer @ The Hacker's Haven

 Hackercorp
 3918 Panorama
 Missouri City, TX  77459

 (713) 274-5184
 usenet: uunet!sugar!karl
 Internet & BITNET: karl@sugar.hackercorp.com
 BIX: karl (rarely)