windows-xp/Source/XPSP1/NT/net/ndis/samples/coisdn/interupt.c

/*
�����������������������������������������������������������������������������

    (C) Copyright 1999
        All rights reserved.

�����������������������������������������������������������������������������

  Portions of this software are:

    (C) Copyright 1995 TriplePoint, Inc. -- http://www.TriplePoint.com
        License to use this software is granted under the same terms 
        outlined in the Microsoft Windows Device Driver Development Kit.

    (C) Copyright 1992 Microsoft Corp. -- http://www.Microsoft.com
        License to use this software is granted under the terms outlined in
        the Microsoft Windows Device Driver Development Kit.

�����������������������������������������������������������������������������

@doc INTERNAL Interrupt Interrupt_c

@module Interrupt.c |

    This module implements the Miniport interrupt processing routines and
    asynchronous processing routines.  
    
    The sample driver does not support physical hardware, so there is no need
    for the typical interrupt handler routines.  However, the driver does
    have an asynchronous event handler which is contained in this module.

@comm

    This module is very dependent on the hardware/firmware interface and should 
    be looked at whenever changes to these interfaces occur.

@head3 Contents |
@index class,mfunc,func,msg,mdata,struct,enum | Interupt_c

@end
�����������������������������������������������������������������������������
*/

#define  __FILEID__             INTERRUPT_OBJECT_TYPE
// Unique file ID for error logging

#include "Miniport.h"                   // Defines all the miniport objects

#if defined(NDIS_LCODE)
#   pragma NDIS_LCODE   // Windows 9x wants this code locked down!
#   pragma NDIS_LDATA
#endif


/* @doc EXTERNAL INTERNAL Interupt Interupt_c MiniportCheckForHang
�����������������������������������������������������������������������������

@func

    <f MiniportCheckForHang> reports the state of the network interface card.

@comm

    The NDIS library calls <f MiniportCheckForHang> once every two seconds to
    check the state of the network interface card.  If this function returns
    TRUE, the NDIS library then attempts to reset the NIC by calling
    <f MiniportReset>.  <f MiniportCheckForHang> should do nothing more than
    check the internal state of the NIC and return TRUE if it detects that
    the NIC is not operating correctly.

    Interrupts can be in any state when MiniportCheckForHang is called.

    <f Note>:
    If your hardware/firmware is flakey you can request that the NDIS
    wrapper call your MiniportReset routine by returning TRUE from this
    routine.  For well behaved hardware/firmware you should always return
    FALSE from this routine.

@rdesc

    <f MiniportCheckForHang> returns FALSE if the NIC is working properly.<nl>
    Otherwise, a TRUE return value indicates that the NIC needs to be reset.

*/

BOOLEAN MiniportCheckForHang(
    IN PMINIPORT_ADAPTER_OBJECT pAdapter                    // @parm
    // A pointer to the <t MINIPORT_ADAPTER_OBJECT> instance.
    )
{
    DBG_FUNC("MiniportCheckForHang")
    // If your hardware can lockup, then you can return TRUE here.
    // If you return TRUE, your MiniportReset routine will be called.
    return (FALSE);
}


#if defined(CARD_REQUEST_ISR)
#if (CARD_REQUEST_ISR == FALSE)

/* @doc EXTERNAL INTERNAL Interupt Interupt_c MiniportDisableInterrupt
�����������������������������������������������������������������������������

@func

    <f MiniportDisableInterrupt> disables the NIC from generating interrupts.

@comm

    Typically, this function disables interrupts by writing a mask value
    specific to the network interface card.

    If the NIC does not support enabling and disabling interrupts, the
    miniport driver must register a miniport interrupt service routine with
    the NDIS library.  Within the interrupt service routine, the miniport
    driver must acknowledge and save the interrupt information.

    In some cases, the NIC must be in a certain state for
    <f MiniportDisableInterrupt> to execute correctly. In these cases, the
    miniport driver must encapsulate within a function all portions of the
    driver which violate the required state and which can be called when
    interrupts are enabled.  Then the miniport driver must call the
    encapsulated code through the NdisMSynchronizeWithInterrupt function.
    For example, on some network interface cards, the I/O ports are paged
    and must be set to page 0 for the deferred processing routine to run
    correctly.  With this kind of NIC, the DPC must be synchronized with
    interrupts.

    Interrupts can be in any state when <f MiniportDisableInterrupt> is
    called.

*/

void MiniportDisableInterrupt(
    IN PMINIPORT_ADAPTER_OBJECT pAdapter                    // @parm
    // A pointer to the <t MINIPORT_ADAPTER_OBJECT> instance.
    )
{
    DBG_FUNC("MiniportDisableInterrupt")
    DBG_ERROR(pAdapter,("This should not be called!\n"));
}


/* @doc EXTERNAL INTERNAL Interupt Interupt_c MiniportEnableInterrupt
�����������������������������������������������������������������������������

@func

    <f MiniportEnableInterrupt> enables the NIC to generate interrupts.

@comm

    Typically, this function enables interrupts by writing a mask value
    specific to the network interface card.

    If the NIC does not support enabling and disabling interrupts, the
    miniport driver must register a miniport interrupt service routine with
    the NDIS library. Within the interrupt service routine, the miniport
    driver must acknowledge and save the interrupt information.

    Interrupts can be in any state when <f MiniportEnableInterrupt> is called.

*/

void MiniportEnableInterrupt(
    IN PMINIPORT_ADAPTER_OBJECT pAdapter                    // @parm
    // A pointer to the <t MINIPORT_ADAPTER_OBJECT> instance.
    )
{
    DBG_FUNC("MiniportEnableInterrupt")
    DBG_ERROR(pAdapter,("This should not be called!\n"));
}

#else // !(CARD_REQUEST_ISR == FALSE)

/* @doc EXTERNAL INTERNAL Interupt Interupt_c MiniportISR
�����������������������������������������������������������������������������

@func

    <f MiniportISR> is the miniport driver's interrupt service routine. This
    function runs at a high priority in response to an interrupt. The driver
    should do as little work as possible in this function. It should set
    <p InterruptRecognized> to TRUE if it recognizes the interrupt as
    belonging to its network interface card, or FALSE otherwise. It should
    return FALSE as soon as possible if the interrupt is not generated by
    its NIC. It should set <f QueueMiniportHandleInterrupt> to TRUE if a
    call to <f MiniportHandleInterrupt> at a lower priority is required to
    complete the handling of the interrupt.

    <f Note>: <f MiniportISR> must not call any support functions in the NDIS
    interface library or the transport driver.

@comm

    <f MiniportISR> is called in the following cases:<nl>

    o   The NIC generates an interrupt when there is an outstanding call to
        <f MiniportInitialize>.

    o   The miniport driver supports sharing its interrupt line with another
        NIC.

    o   The miniport driver specifies that this function must be called for
        every interrupt.

    <f Note>: A deferred processing routine is not queued if the miniport
    driver is currently executing <f MiniportHalt> or <f MiniportInitialize>.

*/

void MiniportISR(
    OUT PBOOLEAN                InterruptRecognized,        // @parm
    // If the miniport driver is sharing an interrupt line and it detects
    // that the interrupt came from its NIC, <f MiniportISR> should set
    // this parameter to TRUE.

    OUT PBOOLEAN                QueueMiniportHandleInterrupt, // @parm
    // If the miniport driver is sharing an interrupt line and if
    // <f MiniportHandleInterrupt> must be called to complete handling of
    // the interrupt, <f MiniportISR> should set this parameter to TRUE.

    IN PMINIPORT_ADAPTER_OBJECT pAdapter                    // @parm
    // A pointer to the <t MINIPORT_ADAPTER_OBJECT> instance.
    )
{
    DBG_FUNC("MiniportISR")

    ULONG                       InterruptStatus;

    // TODO: Get the interrupt status from your card.
    if ((InterruptStatus = pAdapter->TODO) == 0)
    {
        *InterruptRecognized =
        *QueueMiniportHandleInterrupt = FALSE;
    }
    else
    {
        pAdapter->pCard->InterruptStatus = InterruptStatus;
        *InterruptRecognized =
        *QueueMiniportHandleInterrupt = TRUE;
    }
}

#endif // (CARD_REQUEST_ISR == FALSE)
#endif // defined(CARD_REQUEST_ISR)

/* @doc EXTERNAL INTERNAL Interupt Interupt_c MiniportHandleInterrupt
�����������������������������������������������������������������������������

@func

    <f MiniportHandleInterrupt> is called by the deferred processing routine
    in the NDIS library to process an interrupt.

@comm

    During a call to <f MiniportHandleInterrupt>, the miniport driver should
    handle all outstanding interrupts and start any new operations.

    Interrupts are disabled during a call to <f MiniportHandleInterrupt>.

*/

void MiniportHandleInterrupt(
    IN PMINIPORT_ADAPTER_OBJECT pAdapter                    // @parm
    // A pointer to the <t MINIPORT_ADAPTER_OBJECT> instance.
    )
{
    DBG_FUNC("MiniportHandleInterrupt")

    PBCHANNEL_OBJECT            pBChannel;
    // A Pointer to one of our <t BCHANNEL_OBJECT>'s.

    ULONG                       BChannelIndex;
    // Index into the pBChannelArray.

    /*
    // Process NIC interrupt.
    */
    CardInterruptHandler(pAdapter->pCard);

    /*
    // Walk through all the links to see if there is any post-proccessing
    // that needs to be done.
    */
    for (BChannelIndex = 0; BChannelIndex < pAdapter->NumBChannels; ++BChannelIndex)
    {
        pBChannel = GET_BCHANNEL_FROM_INDEX(pAdapter, BChannelIndex);

        if (pBChannel->IsOpen)
        {
            /*
            // Indicate a receive complete if it's needed.
            */
            if (pBChannel->NeedReceiveCompleteIndication)
            {
                pBChannel->NeedReceiveCompleteIndication = FALSE;

                /*
                // Indicate receive complete to the NDIS wrapper.
                */
                DBG_RXC(pAdapter, pBChannel->ObjectID);
                NdisMCoReceiveComplete(pAdapter->MiniportAdapterHandle);
            }
        }
    }

    /*
    // Indicate a status complete if it's needed.
    */
    if (pAdapter->NeedStatusCompleteIndication)
    {
        pAdapter->NeedStatusCompleteIndication = FALSE;
        NdisMIndicateStatusComplete(pAdapter->MiniportAdapterHandle);
    }
}


/* @doc EXTERNAL INTERNAL Interupt Interupt_c MiniportTimer
�����������������������������������������������������������������������������

@func

    <f MiniportTimer> is a required function if a Minipor's NIC does not
    generate interrupts.  Otherwise, one or more <f MiniportTimer> functions
    are optional.

    The driver of a NIC that does not generate interrupts must have a <f
    MiniportTimer> function to poll the state of the NIC. After such a
    Miniport's MiniportInitialize function sets up the driver-allocated timer
    object with NdisMInitializeTimer, a call to NdisMSetPeriodicTimer causes
    the <f MiniportTimer> function associated with the timer object to be run
    repeatedly and automatically at the interval specified by
    MillisecondsPeriod. Such a polling <f MiniportTimer> function monitors the
    state of the NIC to determine when to make indications, when to complete
    pending sends, and so forth. In effect, such a polling <f MiniportTimer>
    function has the same functionality as the MiniportHandleInterrupt
    function in the driver of a NIC that does generate interrupts.

    By contrast, calling NdisMSetTimer causes the <f MiniportTimer> function
    associated with the timer object to be run once when the given
    MillisecondsToDelay expires.  Such a <f MiniportTimer> function usually
    performs some driver-determined action if a particular operation times
    out.

    If either type of <f MiniportTimer> function shares resources with other
    driver functions, the driver should synchronize access to those resources
    with a spin lock.

    A Miniport can have more than one <f MiniportTimer> function at the
    discretion of the driver writer. Each such <f MiniportTimer> function must
    be associated with a driver-allocated and initialized timer object.

    A call to NdisMCancelTimer cancels execution of a nonpolling
    <f MiniportTimer> function, provided that the interval passed in the
    immediately preceding call to NdisMSetTimer has not yet expired. After a
    call to NdisMSetPeriodicTimer, a call to NdisMSetTimer or NdisMCancelTimer
    with the same timer object disables a polling <f MiniportTimer> function:
    either the <f MiniportTimer> function runs once, or it is canceled.

    The MiniportHalt function of any driver with a <f MiniportTimer> function
    should call NdisMCancelTimer to ensure that the <f MiniportTimer> function
    does not attempt to access resources that MiniportHalt has already
    released.

    By default, <f MiniportTimer> runs at IRQL DISPATCH_LEVEL.

*/

void MiniportTimer(
    IN PVOID                    SystemSpecific1,            // @parm
    // UNREFERENCED_PARAMETER

    IN PMINIPORT_ADAPTER_OBJECT pAdapter,                   // @parm
    // A pointer to the <t MINIPORT_ADAPTER_OBJECT> instance.

    IN PVOID                    SystemSpecific2,            // @parm
    // UNREFERENCED_PARAMETER

    IN PVOID                    SystemSpecific3             // @parm
    // UNREFERENCED_PARAMETER
    )
{
    DBG_FUNC("MiniportTimer")

    // DBG_ENTER(pAdapter);

    /*
    // If this is a nested callback, just return, and we'll loop back to
    // the DoItAgain before leaving the outermost callback.
    */
    if (++(pAdapter->NestedEventHandler) > 1)
    {
        DBG_WARNING(pAdapter,("NestedEventHandler=%d > 1\n",
                  pAdapter->NestedEventHandler));
        return;
    }

DoItAgain:
#if defined(SAMPLE_DRIVER)
    /*
    // This sample driver uses timer to simulate interrupts.
    */
    MiniportHandleInterrupt(pAdapter);
#else  // SAMPLE_DRIVER
    // TODO - Add code here to handle timer interrupt events.
#endif // SAMPLE_DRIVER

    /*
    // If we got a nested callback, we have to loop back around.
    */
    if (--(pAdapter->NestedEventHandler) > 0)
    {
        goto DoItAgain;
    }
    else if (pAdapter->NestedEventHandler < 0)
    {
        DBG_ERROR(pAdapter,("NestedEventHandler=%d < 0\n",
                  pAdapter->NestedEventHandler));
    }

    // DBG_LEAVE(pAdapter);

    UNREFERENCED_PARAMETER(SystemSpecific1);
    UNREFERENCED_PARAMETER(SystemSpecific2);
    UNREFERENCED_PARAMETER(SystemSpecific3);
}