³¼COMMODORES¼³
 
³¼GUIDELINES¼³

¹
Like  I  mentioned in the introduction,
these guidelines  are  picked  from the
" ROM  Kernel  Manual:    Includes  and
Autodocs "  from  Addison-Wesley.  I've
picked   some  of  the  most  important
details,  written them in my own words,
and in some cases  commented  them with
examples  from " real life ".  Some  of
these guidelines are very obvious,  and
are  probably  known by everyone, while
others   are   more  " technical "  and
unknown. Here we go:

²Be  sure  that  your  program frees all
allocated  memory  on  exit:  Run  your
program once,  write down the amount of
free  memory,  run  your program again,
and write down the new  amount  of free
memory. If there's any difference, your
program   doesn't   free   it's  memory
correctly.   The reason  why you should
run  your  program once  before testing
this is,  that your program  might  use
some disk-based libraries,  which will,
the  first  time  they're  opened,  use
some memory.¹

Always check, that you get what you ask
for.  This  is  when allocating memory,
opening    screens,   windows,   files,
libraries, devices, resources etc. Just
because  your  program  seems  to  work
correctly,  it  might  be  different on
other machines.

²Clean up after yourself.  That is, free
allocated   memory,   close  libraries,
screens,   windows,  files,  libraries,
devices,  resources  etc.  This must be
done, both upon "normal" exit, and exit
because of an error. Example: You start
by trying to allocate 100 Kb of memory,
this goes well.  Then you try to open a
screen,  but this fails.  In this case, 
remember  to free  the before-mentioned
100 Kb of memory.¹

Remember  that  different  people  have
different  configurations and ROMs.  Do
NOT make assumptions  about free memory
or locations  of  system-structures  or
-code.     Never   call    ROM-routines
directly.  Example:  In  MY  A2000 with
Kickstart 1.3, the exec.library-base is
$676,    and   this   goes   for   most 
1.3-machines, I think. BUT, this should
NOT be assumed in any program, instead,
get  the  base  in address 4,  the only
absolute address in the Amiga!

²When  accessing shared data structures,
remember to  Lock  them,  in  order  to
prevent  other  tasks   from  accessing
these  structures  while  you're  using
them.¹

Beware  of  stack  overflow.   If  your
program  needs a large stack,  remember
to provide the needed stack space.

²When  testing signal bits,  never use a
polling loop.   This will slow down the
multitasking   system,   because   your
program uses all the time to do nothing
but wait.
Example:   You want to test, whether or
not  the  user  clicks  in a gadget. In
this  case,  do  NOT  make  a loop with 
GetMsg, instead, use WaitPort.¹

All  data  for  custom chips must be in
Chip memory ( surprise!). This includes
bitplanes, copper-lists, sound-samples,
trackdisk-buffers, sprites, bobs etc.

²Never  use  software  delay  loops.   A
DBF-loop will use  different amounts of
time  on  different configurations, and
especially    with   different   680x0-
processors.   With  system-programming,
use   the   " Delay "-routine   or  the  
" WaitTOF " ( graphics.library )    for
waiting.  Hardware-coders  should use a
CIA-delay instead. ( See the example in
the Hardware Manual)¹

³About structures:¹
All   non - byte - fields  ( word-  and
longword-fields )  must be word-aligned
(surprise again! ).   For  performance,
longwords  should  be longword-aligned.
Use of the assembler-directive CNOP can
do  this.   All  address  pointers  are
32-bit, even though only 24 bit seem to
be used.  Fields, that seems to contain
irrelevant data, must be initialized to
zero    for    future    compatibility.
Structures  to  be  used  by the custom
chips,   public  data  structures,  and
structures,    that    need   longword-
aligning,  must  NOT  be allocated on a
stack.

²Try to avoid using self-modifying code.
All  680x0-processors  have a pre-fetch
feature,  that is,  the  CPU  loads the
instructions   ahead   of  the  Program 
Counter.  So,  if  your program changes
something  just  ahead  of  the Program
Counter,  the  'old'  contents might be
used, because it's pre-fetched.¹

When  calling   a  system-routine,  the 
library-  or device-base must be in A6.
Even though  it's  possible to CALL the
routine  via e.g. A5  instead,  this is
NOT  supported,   because  the  routine
assumes, that the base is in A6. So, if
the  routine  calls some other routine,
your  Amiga  could be  sent on a little
trip to India!

²Registers A0, A1, D0 and D1 are scratch
registers,  and after calling a system-
routine,    you   must  consider  their 
contents   to   be   lost.   All  other 
registers' contents  will  be preserved
by the system-routines.  Example: I saw
a " Border-Off "-routine,  which worked
perfectly on Kickstart 1.3, but on 2.0,
it crashed. Why? Because, after getting
the pointer to the active window in A0,
the   coder   called   3  routines   in
intuition.library WITHOUT preserving A0
in between. Obviously, the 1.3-routines
didn't change  the contents of A0,  but
the 2.0-routines did.¹


Now,  that's  all  I  have  to say this
time.   Remember,  that if you have any
questions   about   either  system-  or
hardware-programming,  send them to Top
Secret,  and  they'll  be dealt with in
the next Coder's Corner.


²Source:   AMIGA  ROM  Kernel  Reference
Manual:  Includes  and  Autodocs, Third
Edition,  1991  by  Addison-Wesley  and
Commodore-Amiga, Inc.¹

     ³Written by  Estrup of Static Bytes¹