\section{More fun and games}

This section covers some finer points of \szadb\ use.
You may put them aside when just starting first experiments
with the debugger.
But probably one day you will find some of that information very
useful.

\subsection{Advanced steps}

It was already mentioned that all stepping commands may have also
attached \szadb\ requests.  As a matter of fact there is even one
default, for \name{:f}.  To get a similar effect for other steps
just type what you want to be executed after a given command on
the \szadb\ input line. For example
\begin{exmpl}
	{\tt :s ="this string printed by :s command"n}
\end{exmpl}
You will notice that this form of \name{:step} does not
move you ahead in the program.
This gives an opportunity to set and modify requests in advance,
without an immediate execution.
It also saves your nerves if you are not a very good typist.
To really step by one instruction forward hit \key{Return} and
observe what will happen.
As noted before \name{:j} is a variant of \name{:n} and setting
request for it will really change what is attached to \name{:n}.

The example above is not tremendously useful,
but tracking values of a chosen registers can be.
Or anything else that you need and that will fit on the command line.
This condition is much less limiting than it appears
when used in conjunction with function keys.

There are two points to remember.
There is no syntax check while you are setting requests.
Watch what you are typing if you do not want to see only error
messages.
And there is nothing to prevent a direct or indirect recursion.
Since a depth of \szadb\ stack is limited and \key{\carret C} does
not always work it is better to avoid such constructs.

If you came to a conclusion that the only way to
change requests attached to a stepping command is to
overtype them with something else then you are correct.
Moreover an empty string is not a good replacement 
since it causes an execution.
Luckily there is some other way to turn a noise off.
Try typing \verb|::s-| and similar commands for \name{:n} and
\name{:f}.  Switched off requests are not gone, unless later redefined.
They can be brought back by a similar command as above in which 
\verb|-| was replaced with \verb|+|.
The default request for \name{:f} is special.
It cannot be overtyped or turned on by \verb|::f+|.
To bring it back use \verb|::f`| instead.

There is one more way of request switching.  If you will type,
for example, \verb|::n_|, then whatever was attached to  \name{:s}
will be performed also for \name{:n}, instead of a ``native'' command.
This gives an opportunity to create, say, a quite complicated
request for \name{:n} and most of the time execute a simpler
request for \name{:s}.
When an original request for \name{:n} is
needed it is enough to type \verb|::n+| to get it back.
The same mechanism works for \name{:f}, temporarily redirecting
its requests ``down'' to the first active one.
There is no similar switching going the other way.
To gain a better understanding try all of this after defining
various requests for each of stepping commands and examine
effects with the \verb|$b| command after every switch.

It is also possible to make user breakpoint silent or not. For example
\begin{exmpl}
	{\tt main:b ="entering main"}
\end{exmpl}
{\tt main::b-} and {\tt main::b+} turns the action off and on.

\subsection{How to use function keys}


Function keys can be defined, only once per debugging session, by reading
their definitions from a file. The name of the file can be passed on the
command line with \name{-k} {\sl filename}. The file may be as simple as this
\readexample{kdefs.exm}
Note that an uppercase F, which starts key definition, has to
be in the first column and it has to be immediately followed
by a valid key number.  Shifed functions keys have numbers
between 11 and 20.  A definition of \key{F2} is continued on the
next line since a terminating newline is escaped with a \verb|\|
character.  Otherwise this continuation line would be simply
ignored.  \szadb\ also does not pay any attention to the second
definition of \key{F1}.  To see a list of all function keys defined
type \verb|$k|.

Defined function keys can be used in two ways.  Just hitting
a function key will insert into the current input line as many
characters from a corresponding string as it will fit.
The resulting input text can be edited.
In order to execute a full definition use \verb|$k| followed by a key
number --- always in decimal.
For example, a request \verb|$k2| will print twice
the message, which was just defined in the function key file.

Note that there no way to specify that a function key should execute
immediately instead of waiting for a \key{return}. Also is there no default
function key file name 
like --- \name{adb.key} --- so you'll have to specify the 
\name{-k}~{\sl file\/}
option on the command line each time or use a command alias.
Note also that requests of a form \verb|$k|{\sl $<$number$>$\/} do not
autorepeat.

It is clear that strings of commands attached to function keys
can be longer than a lenght of the input line.  Actually around
2K will be accepted.  This is hopefuly longer than any \szadb\
script you ever want to write.  Especially if you take into
account that one script can call another.  Warnings against
recursion apply as well.

Such long scripts can be, of course, attached to breakpoints
or stepping commands.  They give also, previously mentioned,
opportunity to fill all available space on a base page with
command line arguments.  Just define one of function keys as
\begin{exmpl}
	{\tt :c <text to put on a base page>}
\end{exmpl}
and execute at the beggining of your session.  Coupled with
a possibility of directly modifying the memory this allows 
for a preparation of scripts which will emulate any extended arguments
scheme, even if \szadb\ directly does not support directly any
of these.

\subsection{Other symbol table formats}

This debugger was designed as a companion for Sozobon~C and therefore
it understands its symbol table format, which was inherited from
Alcyon compiler.  Starting with version 2.0 of Sozobon~C compiler
a new format --- ``SozobonX'' --- was introduced and which allows for
an unlimited length of symbol names  (there is an internal compiler
limit of 80 characters, but it can be raised if you really need
to do that).  From 2.1mj szadb recognizes this format as well.
The version for which this document was written also supports MWC ---
currently the official Atari development compiler.
It will cooperate also  with the ST version of GNU compiler gcc.
If you happen to have an older version of gcc loader it may
be necessary for you to get your hands dirty in a source code.
Even better idea would be to update your compiler.  The current
gcc loader can optionally produce symbol tables in ``GST format''
where symbols can be up to twenty two characters long.
A support for this format exists in versions of szadb 1.3 and up.


\subsubsection{Mark Williams C support}

Symbols created by MWC are outwardly different from those produced
by Sozobon C in that that names can be longer  --- up to
sixteen characters --- and an underscore character is appended instead of
beeing prepended.
When \szadb\ will detect an MWC produced object it will apply its
conventions.
That means that if you type \name{main} it will first try
to find a symbol \name{main}.
If this fails it will search for \verb|main_| next  (not for \verb|_main|).
If a symbol name has a leading underscore, or more
than one trailing, you have to type them yourself.

The debugger is trying to guess by itself which compiler produced the
current executable.  If it guesses wrong you may always override its
choice by dropping a hint on the command line.  It consists of an
\name{-os} flag for the Sozobon format and \name{-om} for MWC.
Remember that if you work in an assembler the guessing code can always
be fooled.  The flags always provide a way to set things straight.

When writing this guessing code I had no official description
of the format used by MWC.  All necessary information was inferred
from an examination of MWC produced binaries.
The code  worked so far on everything
I tried, but it may happen to be wrong for your version.
Since \szadb\ comes complete with source you can
modify it accordingly and recompile
(look for all places where a global variable \name{swidth} is modified).

\subsubsection{How to work with gcc}

(Some of an information in this section is likely to be of a historical
value only.  On the other hand maybe there are still some stray copies
of an old gcc loader still in use.  Who knows?)

A default form of executables created by this compiler is with a symbol
table attached. You need to use \name{-s} flag if you really do not want
it produced.  A default format for TOS version of this compiler is
basically the same as for Sozobon C or Alcyon.  If you happen to
be an owner of an old version there is 
one subtle difference.  A bit which carries an information
that a symbol is global one, known as \verb|S_EXT| in \szadb\ parlance,
is not set.  This makes the debugger blind to a symbol presence.

Here are instructions how to modify an old version of a
file \name{ld.c} which contains sources
for gcc linker. In a function \verb|write_atari_sym(p, str)| for TOS version
add the following
\begin{exmpl}
	\verb? if (p->n_type & N_EXT)?\\
	\makebox[1.5cm]{}\verb? sym.a_type |= A_GLOBL;?
\end{exmpl}
just before a line which reads
\begin{exmpl}
	\verb? sym.a_value = p->n_value;?
\end{exmpl}
Recompile and reinstall linker and from this moment on \szadb\
recognizes gcc produced symbols.

Even better idea would be to upgrade your compiler to a newer version.
The modification described above will be already present, but there is
more.
Currently gcc, upon a presence of -G flag, may produce symbol tables
with names up to twenty two characters long.  Versions 1.3 and up of \szadb\
will correctly recognize such symbols making for much nicer debugging
(even if this will require more typing from time to time).  Internally
this is a version of Sozobon format.  Use \name{-os} flag in case
of confusion.

If for some reasons you cannot upgrade, 
you do not have linker sources or you cannot recompile them ---
because you do not have enough memory, for example --- not everyting is
lost.  It is quite feasible to disable \verb|S_EXT| check in \name{setsym()}
(look in the file \name{adb1.c}).  
You will not notice any change for Sozobon C created executables.
All symbols occuring in their symbol tables are actually always global.
This is not quite true for gcc and some new, sometimes strange, symbols
will appear but usually this will not create any problems.
In order to have only globals in a gcc produced symbol table
pass \name{-x} flag either to gcc or to its linker.

\subsubsection{Command line interpretation}

As mentioned before \szadb\ supports only ``vanilla'' command line
without any extension schemes.  Other compilers, like gcc,
may expect something different and there could be some disagreements
about an interpretation of a command line.  Usually this can be
fixed quite easily.  Here is a file, named \name{fixargs.adb},
which can be used with a command line following this pattern
\begin{exmpl}
	\verb? szadb.ttp -k fixargs.adb <program> [argument, ...]?
\end{exmpl}
where \verb?<program>?  was compiled by gcc.
\readexample{fixargs.adb}
This file defines some function keys.  The fact that commands
associated with keys \key{F14} and \key{F15} do not exist,
even if they are referenced in a line for \key{F1}, is not
harmful in any way.
You may
define these keys later for your advantage.  After \szadb\ started
hit \key{F1} followed by \key{Return}.  This will cause,
among others, an execution of a command attached to \key{F11},
i.e \key{F1--shifted}. This command will set a breakpoint at
a start of real program with a fixup command attached.
In turn, this will modify your stack causing your program to
see proper arguments.  Requests in a form of \verb?<sp,10/x?
are added only for reassurance and to show what really happens.

The example above assumes that a symbol \name{getitime} is defined
in your program.  Replace with something which is really present
or you will see some error messages.  They are not fatal.
All of this is not going to work if \name{main} is not present
in your symbol table.  This is not really likely for a program
which has a symbol table and was compiled from C sources, but
may happen for other languages.  Modify accordingly.


\subsubsection{Other compilers}

If you own a compiler which produces symbolic information in an
unsupported format you can modify \szadb\ yourself to support it.  For
a model of how to do this look for \name{setsym()} and
\name{mwsetsym()} in the file \name{adb1.c}.  Both of them call
\name{addsym()} which performs an actual insertion of a new symbol and
its value into a linked list of supported symbols.  A current version
of \name{addsym()} will handle symbol names of any length but internally they
will be chopped off to something not longer than the current value of
the global variable \name{swidth}.  Ensure that this value is set properly
for your needs.

The mechanism above can be easily extended to allow reading some
symbols and their values from a user suplied text file.  Some may find
it very handy.  The current version of \szadb\ does not support this
feature.  It is possible to roll your own if you really need it.


\subsubsection{Screens of not a standard ST size}

Starting with a version $1.4$ \szadb\ does not have standard ST
screen parameters embedded into its code.  Instead it reads all
necessary information from line-A variables and reserves all needed
buffers accordingly.  In particular it follows that \szadb\ will
run correctly in all six TT resolutions.  It may also work with
different overscan utilities, provided screen geometry variables
in a machine were updated properly.  Note that fonts used are
resolution dependent but fixed for a given resolution.  This means
that putting monochrome ST into 50 line mode will not give nice
results without code modifications (see \verb|w_init()| in
\name{window.c}).

A special support is provided for Moniterm monitors.  Because
of limitations of a Moniterm driver you will need also a standard
ST monitor connected in parallel.  In such setup your program
screen will be displayed on Moniterm and \szadb\ will print its
information to a side monitor; no screen flipping with \key{\carret W}
is needed or possible.

Since the debugger tries to limit use of a dynamic memory allocations
the code which reserves \szadb\ work screen and necessary buffers
does that in a ``false'' program space and is located in \name{start.s}.
Should you decide to modify it for any reasons look for comments
which attempt to describe what really happens.

Note: despite of the fact that \szadb\ can be used on TT the 
version $2.1$ is still ST debugger in that sense that it does not support
yet any of 68020/30 specific codes.  This should be fine for most
programs in the nearest future.  An expansion will be easy and
straightforward provided you will have necessary reference handy.

\subsection{Customization}

Some possible customizations were already mentioned.
The other obvious one is a version of  \szadb\ without on-line help.
If you feel brave enough remove the definition of 
the compile time constant \name{HELP} from the \name{makefile}.
A size of the executables will undoubtely go down.

In order to create a version in some other language edit 
a file \name{lang.h}.
It contains all messages which \szadb\ may display.

You can adjust to your taste some other points.  For example,
what are default requests attached to stepping
commands and what is their status (look in \name{stepping.c} for
\name{bpstat()}, \name{findcmds()}, \verb|bpt_list[]|).
Which characters are used for requests switching
(see \name{getrequs()} in \name{pcs.c}).
Some features, like support for functions keys or other symbol
table formats, can be taken out easily without affecting the
whole design.

If you try to recreate \szadb\ with another compiler you should note
that essential parts of this program were written in assembler
and may have to be translated to something your tools can accept.
Here is another point to watch for.
A variable \verb|_BLKSIZ| sets size of \name{Malloc}'ed blocks.
If a library you use supports something similar modify
accordingly.
There are also some constructs in C code,
like a static initialization of a union member (\verb|bpt_list|
in \name{stepping.c}) and an array of size 0 in a definition
of \name{struct symbol} in \name{adb.h}, which 
are accepted by Szozobon C but can give
a hiccup to some other compilers.
These points can be modified without undue strain.
Otherwise the code should be pretty portable, although it is
ST specific by its very nature.

\subsection{Running on a verge}

You may find yourself in a situation when your program wants all
memory it can get and together with the debugger does not exactly
fits into available space.
There are still some things which can be done.

Keep in mind that \szadb\ grabs all memory it needs before a program
to debug is loaded and it does not make any claims later.
These requirements can be minimized. 
Function key definitions if non-existent will not use memory at all,
discounting the supporting code.  
This code by itself is mostly contained in a file \name{fkeydefs.c}
and it is easy to remove.
The flag \name{-nc}, for {\tt no commands},  gives some memory for a price
of missing breakpoint requests.
A more substantial memory chunk can be released with 
\name{-nb}, for {\tt no buffering} on transcript, flag.
You still can open a transcript file but all output will be direct.
Beware of GEMDOS when using transcripts without buffering.

If this does not help then there is a time to trim some fat from
\szadb\ itself. You will have to recompile it leaving some features
out.  On-line help is probably the first candidate.

All this effort can be wasted if you will forget about one thing.
Due to an infamous design bug in TOS a Malloc system call can
be invoked only a small fixed number of times. When this pool is
exhausted you will get ``out of memory condition'' even if memory
is still plentiful.
Therefore all allocation functions, from smart libraries,
request a memory from the system in bigger pieces and later
try to satisfy all requests chopping from an already owned resource.
The name of the game for \szadb\ is to use for all its needs
only one chunk of a system memory which is just big enough, so
not too much of an unused memory will be left.
The whole symbol table of a de\-bug\-ged program must fit there and
all \szadb\ requests for a space for in\-ter\-nal structures have to
be statisfied.
To adjust sizes properly
you may want to change a constant \name{CHUNK} which is defined
at the top of a file \name{adb.c}.

If everything else fail you may still try to change a value of
a global variable \verb|__STKSIZ| from \name{start.s} but this
would be probably the last stand.

\subsection{Writing to memory}

It can be done.
This is left as an exercise to the reader.
Check your documentation.
