** Introduction

This attempts to document the ReactOS irq handling. As of v0.0.8 this has 
changed to be more nt like, I will attempt to summarize the new
implementation for those unavailable with nt device driver writing. Note,
ReactOS doesn't have an exact implementation but the omissions are, except
where noted, not user visible.

** Steps in grabbing an irq vector

* Call HalConnectInterrupt

PROTOTYPE:

ULONG HalGetInterruptVector(INTERFACE_TYPE InterfaceType,
                            ULONG BusNumber,
			    ULONG BusInterruptLevel,
			    ULONG BusInterruptVector,
			    OUT PKIRQL Irql,
			    OUT PKAFFINITY Affinity)

PURPOSE: 

Translates a bus dependant interrupt vector to a system vector

ARGUMENTS:

      InterfaceType = Type of bus to which the device to receive interrupts 
                      from is connected to. Currently only 'Internal' is
		      recognized
      BusNumber = Number of the bus the device is connected to 
                  (currently ignored)
      BusInterruptLevel = Bus specific interrupt level (currently ignored)
      BusInterruptVector = Bus specific vector. Currently this is the same
                           as the normal vector (09 is the keyboard vector
                           for example)
      Irql = On return contains the DIRQL for the vector
      Affinity = On return contains the affinity mask for the vector
                 (currently unimplemented)
		 
RETURNS:
     The system mapped vector
			    
* Call IoConnectInterrupt

PROTOTYPE:

NTSTATUS IoConnectInterrupt(OUT PKINTERRUPT* InterruptObject,
                            PKSERVICE_ROUTINE ServiceRoutine,
			    PVOID ServiceContext,
			    PKSPIN_LOCK SpinLock,
			    ULONG Vector,
			    KIRQL Irql,
			    KIRQL SynchronizeIrql,
			    KINTERRUPT_MODE InterruptMode,
			    BOOLEAN ShareVector,
			    KAFFINITY ProcessorEnableMask,
			    BOOLEAN FloatingSave)

PURPOSE:   

Connect a service routine to an interrupt vector

ARGUMENTS:

         InterruptObject = Points to an object describes the interrupt on
	                   return
	 ServiceRoutine = Function to be called when the device interrupts
	 ServiceContext = Parameters to be passed to the service routine
	 SpinLock = Should be NULL
	 Vector = System mapped vector returned from HalGetInterruptVector
	 Irql = DIRQL returned from HalGetInterruptVector
	 SynchronizeIrql = Should be the same as Irql
	 InterruptMode = Device interrupt type (currently ignored)
	 ShareVector = True if the interrupt vector can shared
	 ProcessorEnableMask = Currently ignored
	 FloatingSave = Should be false
	 
RETURNS: Status

* Sample code for snarfing an interrupt vector


      void grab_my_irq()
      {
            ULONG MappedIrq;
	    KIRQL Dirql;
	    KAFFINITY Affinity;
	    PKINTERRUPT IrqObject;
	    
	    MappedIrq = HalGetInterruptVector(Internal,
	                                      0,
					      0,
					      MY_VECTOR,
					      &Dirql,
					      &Affinity);
            IoConnectInterrupt(&IrqObject,
	                       my_irq_service_routine,
			       my_context,
			       NULL,
			       MappedIrq,
			       Dirql,
			       Dirql,
			       0, 
			       FALSE,    // Not sharable
			       Affinity, 
			       FALSE);
      }
      
** Designing an interrupt service routine

An interrupt service routine should have the following prototype

      BOOLEAN my_irq_service_routine(PKINTERRUPT Interrupt, 
                                     PVOID ServiceContext);
				     
ARGUMENTS:
         
	 Interrupt = The same as the object returned from the 
	             IoConnectInterrupt
	 ServiceContext = A user defined parameters 
	                  (passed to IoConnectInterrupt)
			  
RETURNS:

         True if it handled the interrupt, false if it should be passed onto
	 other devices sharing the same vector
	 
NOTES:

         While an isr is executing all devices of a lower or equal priority
	 can't interrupt. For this reason it is important that an isr 
	 should complete in a short an interval as possible. The set of 
	 routines an isr can call is also restricted.