NAME
        AddICRVector -- attach an interrupt handler to a cia bit.

   SYNOPSIS
        interrupt = AddICRVector( Resource, iCRBit, interrupt )
        D0                        A6        D0      A1

        struct interrupt *addicrvector( struct library *, word,
                struct interrupt * );

   FUNCTION
        Assign interrupt processing code to a particular interrupt bit
        of the cia icr.  if the interrupt bit has already been
        assigned, this function will fail, and return a pointer to the
        owner interrupt.  If it succeeds, a null is returned.

        This function will also enable the cia interrupt for the given
        ICR bit.

   INPUTS
        iCRBit          Bit number to set (0..4).
        interrupt       Pointer to interrupt structure.

   RESULT
        interrupt       Zero if successful, otherwise returns a
                            pointer to the current owner interrupt
                            structure.

   NOTE
        A processor interrupt may be generated immediately if this call
        is successful.

        In general, it is probably best to only call this function
        while DISABLED so that the resource to which the interrupt
        handler is being attached may be set to a known state before
        the handler is called. You MUST NOT change the state of the
        resource before attaching your handler to it.

        The cia resources are special in that there is more than one
        of them in the system. Because of this, the C language stubs
        in amiga.lib for the cia resources require an extra parameter
        to specify which cia resource to use. the synopsis for the
        amiga.lib stubs is as follows:

        interrupt = AddICRVector( Resource, iCRBit, interrupt )
        D0                        A6        D0      A1

        struct interrupt *addicrvector( struct library *, word,
                struct interrupt *);

        ***WARNING***

        Never assume that any of the cia hardware is free for use.
        Always use the AddICRVector() function to obtain ownership
        of the cia hardware registers your code will use.

        Note that there are two (2) interval timers per cia.  if
        your application needs one of the interval timers, you
        can try to obtain any one of the four (4) until AddICRVector()
        succeeds.  If all four interval timers are in-use, your
        application should exit cleanly.

        If you just want ownership of a cia hardware timer, or register,
        but do not want interrupts generated, use the AddICRVector()
        function to obtain ownership, and use the ableicr() function
        to turn off (or on) interrupts as needed.

        Note that CIA-B generates level 6 interrupts (which can degrade
        system performance by blocking lower priority interrupts).  As
        usual, interrupt handling code should be optimized for speed.

        Always call remicrvector() when your code exits to release
        ownership of any cia hardware obtained with addicrvector().

   SEE ALSO
        cia.resource/remicrvector(), cia.resource/ableicr()