Club Amiga de Montreal - CAM/CAM_CD_1.iso/files/454.lha/Exector/exector-doc

Text File | 1990-12-06 | 12.9 KB | 250 lines

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
                                   Exector
                           © 1990 by Doug McLean

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
WHAT IT IS:

    Exector is a program designed to locate and display some of the
system structures that the operating system on the Amiga maintains and
uses (specifically, the Exec structures). If you program on the Amiga and
know what I am talking about, then you will probably be able to put
Exector to good use. If you are learning to program on the Amiga or are
interested in how it works and how it keeps track of everything (like tasks
and memory and devices and a lot more), then Exector could be a valuable
educational aid (along with the appropriate reference and text books). If you
arn't into things like C, Assembler and operating systems at all, then go
download a game or something, Exector will be utterly useless to you. But if
you are interested in this sort of stuff, you will be happy to know that
Exector will display any of the system structures in any of the Exec
header files.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
HOW IT WAS MADE:

    The gadget images were designed in Deluxe Paint III then saved as
brushes. Power Windows 2.0 was used to make the custom screen and windows,
the menu, and actual gadgets, and to generate the C structures for these.
The program was written and compiled with Lattice C 5.04. It was written
on an Amiga 500 with 1 meg of memory and two floppy drives, running
KickStart 1.2. Exector has not been tested with any add on products such as
accelerator/processor cards or memory expansion (but it should work fine if
the manufacturer followed Commodore's rules).

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
COPYRIGHT, UPDATES, AND BUGS:

    Exector, and any associated files and documantation are CopyRight
1990 by Doug McLean. All rights are reserved.

    You are granted permission to distribute and use Exector provided
that you comply with the following terms and conditions:

    [1] You may only distribute Exector in it's original archived
        form, intact, complete, and unmodified. If the program is
        distributed as part of a collection of software on disk,
            it must be either in it's original archived form, or complete
            with all files and documentation in it's own directory.
    [2] Exector may not be sold, and no fee may be charged for the
        program except where the fee is:
        [a] the normal download fee charged by information services and
            some BBSs, and such fee is applied to all downloads,
        [b] a nominal disk copying fee charged by a non-profit users
        group, and Exector is part of a collection of software on
        that disk.
    [3] If you use Exector for non-commercial purposes, you must send
         a $25 registration fee to the author at the address below.
    [4] If you use Exector at all for any commercial purpose, you must
        send a $50 registration fee to the author at the address below.

    The author accepts no responsibility for the performance or lack
thereof of this program.

    Updates, if I decide to update Exector, will be available ONLY to
registered users. I am making no promises to update Exector, but if I do,
upgraded versions will be available ONLY to registered users. Users who
have registered will be able to obtain any upgrades as they are released
either from my BBS or via mail (you will have to supply a disk, envelope,
and postage). Whether I upgrade Exector or not will depend largly on how
may people register.

    As for bugs, at release time I haven't found any, but that doesn't
mean anything. If you find any, please report them to me either via mail
or my BBS. NOTE that it is possible to guru your system with Exector, this
is not the programs fault. Just don't try to look at any of the hardware
i/o registers or the system or current program stack (these stacks can
want change as you look at them, and sometimes the system doesn't like
this).

    Please send registration fees, bug reports, comments, suggestions,
and any old computer hardware that you have lying around to:

Doug McLean Jr.
145 Bedell Ave.
Saint John, N.B.
Canada, E2K 2C3

BBS: The Mad Scientist's BBS  [phone] 12/2400 8/N/1

Note that the BBS is down when I need the computer for something else
(like programming), and I may answer the phone voice.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
USAGE:

run exector

    Sorry, this doesn't run in the backround like I wanted it to. The
linker is giving me problems with this (it never did before), it says
"reference to unmerged data item" and tells me to compile with -b0. That
didn't help, and neither did declaring the item in question (_BackgroundIO)
far. I'll work on it if I do another version, but for now, please start
Exector with the run command.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
A BIT OF INFO:

    The operating system in the Amiga is mostly a group of libraries
that handle the various aspects of the Amiga's operation. Dos handles files
and related things, Intuition handles screens, windows, gadgets, etc, and
Exec handles tasks, memory, interrupts, and a host of related things.
Clearly, the Exec is essential to the Amiga's operation.

    The "root" structure for the Exec is called ExecBase. It contains
pointers to linked lists of tasks, devices, memory, and to other data and
code. It also contains a fair amount of actual data (as opposed to pointers)
within the structure. ExecBase is THE main structure in the Amiga's
operating system, everything starts here. From here you can find other
libraries, tasks, memory, devices, and whatever else the Exec keeps track
of. There are many excellent reference books on this, and several public
domain/shareware/freeware/comercial programs that will help. Of particular
note are are ExecDiss © 1989 by Markus Wandel and Xoper 2.2 © 1989 by
Werner Gunther. ExecDiss will disassemble and comment the part of the
Amiga's ROM that contains the Exec. The comments are plentiful and
informative. Xoper is a system monitor that shows just about everything
the Amiga is doing (or waiting to do, or knows about). It can provide
pointers to many of the structures you may wish to examine with Exector.
Another good place to look for info is in your C or assembler header files,
they are usually heavily commented.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
USING EXECTOR:

    When Exector starts up, after a brief wait you will see the top part
of your ExecBase structure (the system only has one of these, but there are
numerous occurances of the other structures). Above the structure display
are the gadgets. There is one gadget for each type of structure defined
in the Exec header files, as well as a hex dump gadget. When you use one of
these gadgets, you must tell Exector the base address of the structure you
wish to examine. There are two ways to do this:

    [1] Click first on a valid address in the display window, then
        on the appropriate structure gadget. Valid addresses are any
        address on the left of the screen in the address column, or
        any address PRECEEDED BY A * on the right of the screen in
        the value column. YOU are responsible for ensuring that the
        structure you wish to examine is actually present at the
        address you select, the program doesn't check this in any
        way. The address you select will appear in the control
        window next to the hex input string gadget. You may not
        select a null pointer in this way.
    [2] Click first on the structure gadget and then enter a hex
        address in the hex input string gadget. The input must be an
            8 digit hex address (a 32 bit unsigned long). LEADING ZEROS
        MUST BE INCLUDED or your input will not be accepted.

    Using the information in ExecBase, you should be able to find just
about anything the Exec looks after. However, to make things a bit easier,
I have included the ability to list tasks, devices, libraries, message
ports, memory, and resources. These lists are accessed from the menu bar.
Select the list you wish to view, then click on the address associated
with the structure you wish to view, then on the structure type gadget.
Future versions may have expanded support in this area (more info in the
lists and more lists).

    Whenever you view a structure, it's structure type and address are
placed on an internal stack. This stack will hold up to 512 structure/
address pairs. Select the Bk (back) gadget to move back one in the stack.
The structure you were previously looking at will be shown, and the stack
pointer will be lowered. You can back up all the way to ExecBase. Note
that as things change rapidly in the Amiga's memory, this stack may not
always be valid (although I have found that it usually is).

    Another important gadget is the No Exp/Expand gadget. This gadget
is a toggle gadget that selects expanded or normal structures. When set
on Exoand, all embedded structures are expanded and shown in the display
in their correct place within the overall structure that you are viewing.
Since many structures contain a node structure as their first element,
expanded structures make it very easy to follow a list of structures
through memory: get the first structure in the linked list (usually from
a list structure within the ExecBase structure), select expanded structures,
then click on the pointer to the next node and then the structure type gadget
as long as there are nodes to follow. The last node in the list is a dummy
node (identified by a null pointer to it's successor), so when you get here
you will want to hit Bk once to get to the last real node. You can toggle
expanded structures on and off as you please. Structure members that are
part of a sub-structure within the current structure have their names
preceeded by a > in the display. Sorry, I didn't do anything to show
how deep a member might be within sub-structures, just that it is part
of some sub-structure.

    Here is what all the gadgets do:

Structure Type Gadgets: selects structure types (includes Hex gadget).
            See above.
Hex Input Gadget      : allows entry of a 32 bit hex address. Activated by
            and used with structure type gadgets. See above.
Bk                    : The back gadget moves you back one in the internal
            stack. See above.
Icon               : this puts the program to sleep and places a small
            gadget in a small window on your workbench screen.
            Select it to awaken Exector. Your stack is not
            disturbed, as things change often in the Amiga,
            you may wish to select reset after awakening
            Exector.
Reset                 : This clears the stack, and returns you to startup
            conditions (the expand gadget is not affected). It
            is necessary to select this if the internal stack
            fills up, or if you want to start over.
Up and Down Arrows    : These move the display up or down one half screen,
            if the current buffer is longer than one screen.
Again                 : This displays the current structure over again.
            Use it when the structure you are examining changes
            frequently (for example, a running task), or after
            looking at a list from the menu if you want to
            re-display the current structure.
File                  : This will send whatever is in the current display
            buffer to whatever file you choose (ram:exec, prt:,
            etc). The file is opened in append mode. Select
            this gadget, enter the file name in the string
            gadget next to it, then hit return.

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

HINTS, TIPS, AND NOTES:

 - Remember that the Amiga is a multi-tasking system. You can use other
   programs (like Xoper, mentioned way above) to provide pointers to
   structures.
 - You can use Exector to get pointers to code locations (such as
   interrupts or ROM) and dis-assemble the code with a dis-assembler in
   another window.
 - It is easier to view ExecBase non-expanded, and view any sub-structures
   alone rather than as part of ExecBase. Use ExecBase to get to the
   first structure in a list, and display this structure. Now select
   expanded and you can follow the node links to the next structure in
   the list. Remember that the last node in the list is a dummy node, and
   not a structure of the type you are viewing.
 - If you wish to see the text pointed to by a character pointer, select
   the pointer in the value column, then the Hex gadget. Hex and text will
   be displayed. Then use Bk to get back to your structure.
 - When viewing expanded structures, offsets are displayed as an offset
   from the start of the structure which they are directly part, not the
   overall structure. Expand ExecBase and scroll through it to see what I
   mean.
 - You are responsible for ensuring that the structure you expect is at the
   address you specify. To the program, whatever is found in the address
   you specify is just more data, and it will try to display it as the
   structure you specify. Specifying a bad address could cause a guru!