@DATABASE "cia.guide"
@MASTER "Work:Code/doc/cia.doc"
@REMARK created by ADtoHT V1.2 © 1993 Christian Stieber

@NODE Main "cia.resource"
    @{" cia.resource/AbleICR() " LINK "AbleICR"}
    @{" cia.resource/AddICRVector() " LINK "AddICRVector"}
    @{" cia.resource/RemICRVector() " LINK "RemICRVector"}
    @{" cia.resource/SetICR() " LINK "SetICR"}
@ENDNODE

@NODE "AbleICR" "cia.resource/AbleICR()"

   NAME
	AbleICR -- Enable/disable ICR interrupts.

   SYNOPSIS
	oldMask = AbleICR( Resource, mask )
	D0                 A6        D0

	WORD AbleICR( struct @{"Library" LINK "exec/libraries.h/MAIN" 33} *, WORD );

   FUNCTION
	This function provides a means of enabling and disabling 8520
	@{"CIA" LINK "hardware/cia.h/MAIN" 28} interrupt control registers. In addition it returns the
	previous enable mask.

   INPUTS
	mask            A bit mask indicating which interrupts to be
	                    modified. If bit 7 is clear the mask
	                    indicates interrupts to be disabled. If
	                    bit 7 is set, the mask indicates
	                    interrupts to be enabled. Bit positions
	                    are identical to those in 8520 ICR.

   RESULTS
	oldMask         The previous enable mask before the requested
	                    changes. To get the current mask without
	                    making changes, call the function with a
	                    null parameter.

   EXAMPLES
	Get the current mask:
	    mask = AbleICR(0)
	Enable both timer interrupts:
	    AbleICR(0x83)
	Disable serial port interrupt:
	    AbleICR(0x08)

   EXCEPTIONS
	Enabling the mask for a pending interrupt will cause an
	immediate processor interrupt (that is if everything else is
	enabled). You may want to clear the pending interrupts with
	@{"SetICR()" LINK "SetICR" 0} prior to enabling them.

   NOTE
	The @{"CIA" LINK "hardware/cia.h/MAIN" 28} 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" LINK "hardware/cia.h/MAIN" 28} resources require an extra parameter
	to specify which @{"CIA" LINK "hardware/cia.h/MAIN" 28} resource to use. The synopsys for the
	amiga.lib stubs is as follows:

	oldMask = AbleICR( Resource, mask )
	D0                 A6        D0

	WORD AbleICR( struct @{"Library" LINK "exec/libraries.h/MAIN" 33} *, WORD );

   SEE ALSO
	@{"cia.resource/SetICR()" LINK "SetICR" 0}

@ENDNODE

@NODE "AddICRVector" "cia.resource/AddICRVector()"

   NAME
	AddICRVector -- attach an interrupt handler to a @{"CIA" LINK "hardware/cia.h/MAIN" 28} bit.

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

	struct @{"Interrupt" LINK "exec/interrupts.h/MAIN" 21} *AddICRVector( struct @{"Library" LINK "exec/libraries.h/MAIN" 33} *, WORD,
		struct @{"Interrupt" LINK "exec/interrupts.h/MAIN" 21} * );

   FUNCTION
	Assign interrupt processing code to a particular interrupt bit
	of the @{"CIA" LINK "hardware/cia.h/MAIN" 28} 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" LINK "hardware/cia.h/MAIN" 28} 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" LINK "hardware/cia.h/MAIN" 28} 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" LINK "hardware/cia.h/MAIN" 28} resources require an extra parameter
	to specify which @{"CIA" LINK "hardware/cia.h/MAIN" 28} resource to use. The synopsys for the
	amiga.lib stubs is as follows:

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

	struct @{"Interrupt" LINK "exec/interrupts.h/MAIN" 21} *AddICRVector( struct @{"Library" LINK "exec/libraries.h/MAIN" 33} *, WORD,
		struct @{"Interrupt" LINK "exec/interrupts.h/MAIN" 21} *);

	***WARNING***

	Never assume that any of the @{"CIA" LINK "hardware/cia.h/MAIN" 28} hardware is free for use.
	Always use the AddICRVector() function to obtain ownership
	of the @{"CIA" LINK "hardware/cia.h/MAIN" 28} hardware registers your code will use.

	Note that there are two (2) interval timers per @{"CIA" LINK "hardware/cia.h/MAIN" 28}.  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" LINK "hardware/cia.h/MAIN" 28} hardware timer, or register,
	but do not want interrupts generated, use the AddICRVector()
	function to obtain ownership, and use the @{"AbleICR()" LINK "AbleICR" 0} function
	to turn off (or on) interrupts as needed.

	Note that @{"CIA" LINK "hardware/cia.h/MAIN" 28}-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()" LINK "RemICRVector" 0} when your code exits to release
	ownership of any @{"CIA" LINK "hardware/cia.h/MAIN" 28} hardware obtained with AddICRVector().

   SEE ALSO
	@{"cia.resource/RemICRVector()" LINK "RemICRVector" 0}, @{"cia.resource/AbleICR()" LINK "AbleICR" 0}

@ENDNODE

@NODE "RemICRVector" "cia.resource/RemICRVector()"

   NAME
	RemICRVector -- Detach an interrupt handler from a @{"CIA" LINK "hardware/cia.h/MAIN" 28} bit.

   SYNOPSIS
	RemICRVector( Resource, iCRBit, interrupt )
	              A6        D0      A1

	void RemICRVector( struct @{"Library" LINK "exec/libraries.h/MAIN" 33} *, WORD, struct @{"Interrupt" LINK "exec/interrupts.h/MAIN" 21} *);

   FUNCTION
	Disconnect interrupt processing code for a particular
	interrupt bit of the @{"CIA" LINK "hardware/cia.h/MAIN" 28} ICR.

	This function will also disable the @{"CIA" LINK "hardware/cia.h/MAIN" 28} interrupt for the
	given ICR bit.

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

   RESULT

   NOTE
	The @{"CIA" LINK "hardware/cia.h/MAIN" 28} 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" LINK "hardware/cia.h/MAIN" 28} resources require an extra parameter
	to specify which @{"CIA" LINK "hardware/cia.h/MAIN" 28} resource to use. The synopsys for the
	amiga.lib stubs is as follows:

	RemICRVector( Resource, iCRBit, interrupt )
	              A6        D0      A1

	void RemICRVector( struct @{"Library" LINK "exec/libraries.h/MAIN" 33} *, WORD, struct @{"Interrupt" LINK "exec/interrupts.h/MAIN" 21} *);

   SEE ALSO
	@{"cia.resource/AddICRVector()" LINK "AddICRVector" 0}

@ENDNODE

@NODE "SetICR" "cia.resource/SetICR()"

   NAME
	SetICR -- Cause, clear, and sample ICR interrupts.

   SYNOPSIS
	oldMask = SetICR( Resource, mask )
	D0                A6        D0

	WORD SetICR( struct @{"Library" LINK "exec/libraries.h/MAIN" 33} *, WORD );

   FUNCTION
	This function provides a means of reseting, causing, and
	sampling 8520 @{"CIA" LINK "hardware/cia.h/MAIN" 28} interrupt control registers.

   INPUTS
	mask            A bit mask indicating which interrupts to be
	                    effected. If bit 7 is clear the mask
	                    indicates interrupts to be reset.  If bit
	                    7 is set, the mask indicates interrupts to
	                    be caused. Bit positions are identical to
	                    those in 8520 ICR.

   RESULTS
	oldMask         The previous interrupt register status before
	                    making the requested changes.  To sample
	                    current status without making changes,
	                    call the function with a null parameter.

   EXAMPLES
	Get the interrupt mask:
	    mask = SetICR(0)
	Clear serial port interrupt:
	    SetICR(0x08)

   NOTE
	The @{"CIA" LINK "hardware/cia.h/MAIN" 28} 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" LINK "hardware/cia.h/MAIN" 28} resources require an extra parameter
	to specify which @{"CIA" LINK "hardware/cia.h/MAIN" 28} resource to use. The synopsys for the
	amiga.lib stubs is as follows:

	oldMask = SetICR( Resource, mask )
	D0                A6        D0

	WORD SetICR( struct @{"Library" LINK "exec/libraries.h/MAIN" 33} *, WORD );

	***WARNING***

	Never read the contents of the @{"CIA" LINK "hardware/cia.h/MAIN" 28} interrupt control registers
	directly.  Reading the contents of one of the @{"CIA" LINK "hardware/cia.h/MAIN" 28} interrupt
	control registers clears the register.  This can result in
	interrupts being missed by critical operating system code, and
	other applications.

   EXCEPTIONS
	Setting an interrupt bit for an enabled interrupt will cause
	an immediate interrupt.

   SEE ALSO
	@{"cia.resource/AbleICR()" LINK "AbleICR" 0}

@ENDNODE