The CIA resource provides access to the timers and timer interrupt bits of
the 8520 complex interface adapter (cia) a and b chips.   this resource is
intended for use by high performance timing applications such as MIDI time
stamping and SMPTE time coding.

Four functions allow you to interact with the CIA hardware.

                           CIA Resource Functions
                           ----------------------
     ableicr()             enable or disable interrupt control
                           Register interrupts.  Can also return the
                           current or previous enabled interrupt mask.

     addicrvector()        allocate one of the cia timers by assigning
                           an interrupt handler to an interrupt bit
                           and enabling the interrupt of one of the
                           timers. If the timer you request is not
                           available, a pointer to the interrupt
                           structure that owns it will be returned.

     remicrvector()        remove an interrupt handler from an
                           interrupt bit and disable the interrupt.

     seticr()              cause or clear one or more interrupts, or
                           return the current or previous interrupt
                           status.

Each CIA chip has two interval timers within it - Timer A and Timer
B - that may be available. The CIA chips operate at different interrupt
levels with the CIA-A timers at interrupt level 2 and the CIA-B timers at
interrupt level 6.

   Choose A Timer Wisely.
   ----------------------
   The timer you use should be based solely on interrupt level and
   availability. If the timer you request is not available, try for
   another.  Whatever you do, do not base your decision on what you
   think the timer is used for by the system.

You allocate a timer by calling addicrvector(). this is the only way you
should access a timer.   If the function returns zero, you have
successfully allocated that timer.  If it is unavailable, the owner
interrupt will be returned.

   /* allocate CIA-A Timer A */
   inta = AddICRVector (CIAResource, CIAICRB_TA, &tint);

   if (inta)  /* if allocate was not successful */
       printf("Error: Could not allocate timer\n");
   else
       {
       ...ready for timing
       }

The timer is deallocated by calling remicrvector().  this is the only way
you should deallocate a timer.

   RemICRVector(CIAResource, CIAICRB_TA, &tint);

Your application should not make any assumptions regarding which interval
timers (if any) are available for use; other tasks or critical operating
system routines may be using the interval timers. In fact, in the latest
version of the operating system, the timer device may dynamically allocate
one of the interval timers.

   Time Is Of The Essence!
   -----------------------
   There are a limited number of free CIA interval timers.  Applications
   which use the interval timers may not be able to run at the same time
   if all interval timers are in use.  As a general rule, you should use
   the timer device for most interval timing.

You read from and write to the CIA interrupt control registers using
seticr() and ableicr().  seticr() is useful for sampling which cia
interrupts (if any) are active.  It can also be used to clear and generate
interrupts.  ableicr() is used to disable and enable a particular cia
interrupt.  Additional information about these functions can be found in
the Amiga ROM Kernel Reference Manual: Includes and Autodocs.

Things to keep in mind:

   1. Never directly read from or write to the CIA interrupt control
      registers.  Always use seticr() and ableicr().

   2. Your interrupt routine will be called with a pointer to your data
      area in register A1, and a pointer to the code being called in
      register A5. No other registers are set up for you.  You must observe
      the standard convention of preserving all registers except D0-D1 and
      A0-A1.

   3. Never turn off all level 2 or level 6 interrupts.  The proper way to
      disable interrupts for an interval timer that you've successfully
      allocated is via the ableicr() function.

   4. Interrupt handling code should be written in assembly code and, if
      possible, should signal a task to do most of the work.

   5. Do not make assumptions about which CIA interval timers (if any) are
      available for use.  The only proper way to own an interval timer is
      via the addicrvector() function.

   6. Do not use seticr(), ableicr() and remicrvector() to affect timers or
      other CIA hardware which your task does not own.

Changes in the CIA resource:

   *  In pre-V36 versions of the operating system, seticr() could return
      FALSE for a particular interrupt just prior to processing the
      interrupt. seticr() now returns true for a particular interrupt until
      sometime after the interrupt has been processed.

   *  Applications which only need to read a CIA interval timer should use
      the readeclock() function of the timer device.  see "timer device"
      chapter of this manual for more information on ReadEClock().

   *  The timer device may dynamically allocate a free CIA interval timer.
      Do not make any assumptions regarding which interval timers are in
      use unless you are taking over the machine completely.

     cia_interval.c 

Additional programming information on the CIA resource can be found in the
include files and the Autodocs for the CIA resource and the 8520 spec.
The includes files and Autodocs are in the Amiga ROM Kernel Reference
Manual: Includes and Autodocs and the 8520 spec is in the Amiga
hardware reference manual.

                         CIA Resource Information
                     -------------------------------
                     INCLUDES        resources/cia.h
                                     resources/cia.i
                                     hardware/cia.h
                                     hardware/cia.i

                     AUTODOCS        cia.doc

                     HARDWARE        8520 specification