head     1.2;
branch   ;
access   ;
symbols  ;
locks    ; strict;
comment  @# @;


1.2
date     93.09.09.18.10.13;  author peter;  state Exp;
branches ;
next     1.1;

1.1
date     93.09.09.16.10.33;  author peter;  state Exp;
branches ;
next     ;


desc
@A little about programming Wack 
@


1.2
log
@Added comment about shift out 
@
text
@CAVEATS:

CODING FOR THE REMOTE MACHINE:

It's tricky to write code that correctly works on remote machines,
because there are two address spaces (host and target).  You have
to be very careful not to confuse them.  Worse, if you only test
using local Wack, your broken functions will work.

If you have a pointer to a structure, that you can display.  To
read a field in it, you can grab the structure:

	struct Foo *address = address of thing on target machine;
	struct Foo foo;

	ReadBlock( address, &foo, sizeof( struct Foo ) );
	display( foo.members );

or you can grab a specific member:

	struct Foo *address = address of thing on target machine;

	value = ReadLong( &address->longmember );

But never do this:

	display( address->longmember );



ERROR HANDLING:

Wack's simplified error handling basically consists of suppressing
output if an error occurs, until you reset.  Normally we reset
before returning the prompt.  This saves a lot of error checking
and works quite well.  It's more expedient than formal, however.




SUGGESTED WACK IMPROVEMENTS:

- Prompt should print a "shift out" or whatever returns console text
  to normal in case a string containing garbage was printed.

- The ReadWord() and related functions should be typed as unsigned,
  not signed.

- Menu commands are not blocked while ARexx is running

- Should rexxhandler really use evaluateSymbol() for rexx commands?
  We have a conflict in return value meaning, so we're cheating.
  We know the ARexx commands return a number, not a string.

- The strings are scattered through the source, and should be gathered.

- Rename PPrintf could really be renamed.

- The ARexx and XWack interfaces are missing a few things.  For example,
  you can't use the disabled-ReadNodeArray().

- Reusing a symbol via BindValue() doesn't cause value2 to be freed if
  it was ACT_COMMAND.

- Not compiled -rr!

- CurrAddr etc. should be ULONG

- Bad rexx commands -> not much error reporting

- Caution:  unlike the other parse commands, parseRemainder() doesn't
  strip quotes.  This is so because parseRemainder() doesn't require
  a spare buffer.



WHAT THE C FILES AND A FEW OTHER FILES DO:

bind.c
- Contains calls to bind each function to its keyword.  Also contains
  help, since help generally changes when bindings change.

copper.c
- Copper list disassembler.  Doesn't know about AGA.

decode.c
- 680x0 disassembler.  Doesn't know about instructions on higher processors.

define.c
- Code to create symbols of different types, search symbols, etc.
  Also contains processLine(), which parses and processes a command
  line.

envoylink.c
- Envoy link functions.  The link functions are called a bit like a
  library, and this module contains the envoy-specific versions of the
  generic link functions.

find.c
- Code to search through memory.

hunks.c
- Retired.

io.c
- Most of the Amiga-specific code for startup, init, input/output, and
  cleanup.

link.c
- Contains the generic link functions that connect in a library-like
  manner to one of the local, Envoy, or SAD link function sets.

locallink.c
- Local link functions.  The link functions are called a bit like a
  library, and this module contains the local-machine versions of the
  generic link functions.

main.c
- Where it all begins.

menus.c
- Code to build the menu strips and execute menu commands.

ops.c
- Basic operations including most simple memory and navigation commands.
  Also contains the code which evaluates a symbol and invokes the right
  function.

parse.c
- Standard Wack parsing functions.  parseToken() basically copies
  successive tokens into presupplied buffers.  parseHexNum() returns
  a hex number.  parseAddress() does the same but returns the current
  address if no argument is found.  parseDecNum() returns a decimal
  number.  parseRemainder() just returns a pointer to the next
  thing in line.

rexxhandler.c
- Builds ARexx symbol table, evaluates ARexx commands, and generally
  does all ARexx stuff (by talking to simplerexx.c).

sadapi.c
- Low-level SAD communication functions that worry about the hardware
  protocol.  Should really be merged into sadlink.c, but it wasn't
  worth the time at the time.  Can also be compiled to produce Randell's
  parallel-port SAD clone which we're using to test the AAA machine.
  The parallel-SAD stuff is not in the public version of Wack.

sadlink.c
- SAD link functions.  The link functions are called a bit like a
  library, and this module contains the SAD-specific versions of the
  generic link functions.  Can also be compiled to produce Randell's
  parallel-port SAD clone which we're using to test the AAA machine.
  The parallel-SAD stuff is not in the public version of Wack.  Depends
  on sadapi.c, and as such this module isn't very knowledgable about
  SAD communication specifics.

sadparapi.c
- Retired.  Same stuff is now a variant compile of sadapi.c.

sadparlink.c
- Retired.  Same stuff is now a variant compile of sadlink.c.

sat.c
- Stub routines for breakpointing/tracing.  There is no code to
  support those operations in this version.

show.c
- Functions to dump most general and exec structures.

showd.c
- Functions to dump DOS structures.

showg.c
- Functions to dump graphics and layers structures.

showi.c
- Functions to dump Intuition structures.

showlock.c
- Functions to dump Semaphores.

simplerexx.c
- Variant of simplerexx tuned to Wack's needs.

special.c
- Contains functions to Walk lists on remote machines.

symbols.c
- Retired.

symload.c
- Contains SegTracker-based symbol sniffing/loading stuff.

validmem.c
- Figure out which regions of memory are touchable or off limits.

wackbase.c
- The "Fake library" stuff used for XWack commands.

special.h
- Macros to generate code to dump a structure or a list of structures.
  Used in the various showX.c files.

wack_lib.sfd
- "Function" definitions for the public library-like functions that
  are part of the XWack protocol.

linklib_lib.sfd
- "Function" definitions for the PRIVATE link functions.
@


1.1
log
@Initial revision
@
text
@d42 3
@
