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 immediatly 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 synopsys 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()