/*++

Copyright(c) 1992-2000  Microsoft Corporation

Module Name:

    protocol.c

Abstract:

    Ndis Intermediate Miniport driver sample. This is a passthru driver.

Author:

Environment:


Revision History:


--*/


#include "precomp.h"
#pragma hdrstop

#define MAX_PACKET_POOL_SIZE 0x0000FFFF
#define MIN_PACKET_POOL_SIZE 0x000000FF

VOID
PtBindAdapter(
    OUT PNDIS_STATUS            Status,
    IN  NDIS_HANDLE             BindContext,
    IN  PNDIS_STRING            DeviceName,
    IN  PVOID                   SystemSpecific1,
    IN  PVOID                   SystemSpecific2
    )
/*++

Routine Description:

    Called by NDIS to bind to a miniport below.

Arguments:

    Status            - Return status of bind here.
    BindContext        - Can be passed to NdisCompleteBindAdapter if this call is pended.
    DeviceName         - Device name to bind to. This is passed to NdisOpenAdapter.
    SystemSpecific1    - Can be passed to NdisOpenProtocolConfiguration to read per-binding information
    SystemSpecific2    - Unused

Return Value:

    NDIS_STATUS_PENDING    if this call is pended. In this case call NdisCompleteBindAdapter
    to complete.
    Anything else          Completes this call synchronously

--*/
{
    NDIS_HANDLE                     ConfigHandle = NULL;
    PNDIS_CONFIGURATION_PARAMETER   Param;
    NDIS_STRING                     DeviceStr = NDIS_STRING_CONST("UpperBindings");
    PADAPT                          pAdapt = NULL;
    NDIS_STATUS                     Sts;
    UINT                            MediumIndex;
    ULONG                           TotalSize;
    BOOLEAN                         LockAllocated = FALSE;


    UNREFERENCED_PARAMETER(BindContext);
    UNREFERENCED_PARAMETER(SystemSpecific2);
    
    DBGPRINT(("==> Protocol BindAdapter\n"));

    do
    {
        //
        // Access the configuration section for our binding-specific
        // parameters.
        //
        NdisOpenProtocolConfiguration(Status,
                                       &ConfigHandle,
                                       SystemSpecific1);

        if (*Status != NDIS_STATUS_SUCCESS)
        {
            break;
        }

        //
        // Read the "UpperBindings" reserved key that contains a list
        // of device names representing our miniport instances corresponding
        // to this lower binding. Since this is a 1:1 IM driver, this key
        // contains exactly one name.
        //
        // If we want to implement a N:1 mux driver (N adapter instances
        // over a single lower binding), then UpperBindings will be a
        // MULTI_SZ containing a list of device names - we would loop through
        // this list, calling NdisIMInitializeDeviceInstanceEx once for
        // each name in it.
        //
        NdisReadConfiguration(Status,
                              &Param,
                              ConfigHandle,
                              &DeviceStr,
                              NdisParameterString);
        if (*Status != NDIS_STATUS_SUCCESS)
        {
            break;
        }

        //
        // Allocate memory for the Adapter structure. This represents both the
        // protocol context as well as the adapter structure when the miniport
        // is initialized.
        //
        // In addition to the base structure, allocate space for the device
        // instance string.
        //
        TotalSize = sizeof(ADAPT) + Param->ParameterData.StringData.MaximumLength;

		
// BEGIN_PTUSERIO   在這個(gè)函數(shù)中，我們要初始化設(shè)備名稱

		// 為下層適配器名稱申請(qǐng)空間
		TotalSize += DeviceName->MaximumLength;

// END_PTUSERIO

        NdisAllocateMemoryWithTag(&pAdapt, TotalSize, TAG);

        if (pAdapt == NULL)
        {
            *Status = NDIS_STATUS_RESOURCES;
            break;
        }

        //
        // Initialize the adapter structure. We copy in the IM device
        // name as well, because we may need to use it in a call to
        // NdisIMCancelInitializeDeviceInstance. The string returned
        // by NdisReadConfiguration is active (i.e. available) only
        // for the duration of this call to our BindAdapter handler.
        //
        NdisZeroMemory(pAdapt, TotalSize);
        pAdapt->DeviceName.MaximumLength = Param->ParameterData.StringData.MaximumLength;
        pAdapt->DeviceName.Length = Param->ParameterData.StringData.Length;
        pAdapt->DeviceName.Buffer = (PWCHAR)((ULONG_PTR)pAdapt + sizeof(ADAPT));
        NdisMoveMemory(pAdapt->DeviceName.Buffer,
                       Param->ParameterData.StringData.Buffer,
                       Param->ParameterData.StringData.MaximumLength);

// BEGIN_PTUSERIO			在這里移動(dòng)設(shè)備名稱

		// 構(gòu)造下層設(shè)備名稱字符串
		pAdapt->LowerDeviceName.MaximumLength = DeviceName->MaximumLength;
		pAdapt->LowerDeviceName.Length = DeviceName->Length;

		// 你看上面的pAdapt->DeviceName.Buffer指向結(jié)構(gòu)的末尾，我們的pAdapt->LowerDeviceName.Buffer再向后面添加
		// 讓緩沖區(qū)指向結(jié)構(gòu)的最后（要在上面的pAdapt->DeviceName.Buffer之后）
		pAdapt->LowerDeviceName.Buffer = (PWCHAR)((ULONG_PTR)pAdapt + sizeof(ADAPT) + pAdapt->DeviceName.MaximumLength);

		// 移動(dòng)內(nèi)存
		NdisMoveMemory(pAdapt->LowerDeviceName.Buffer, DeviceName->Buffer, DeviceName->MaximumLength);


// BEGIN_PTEX_FILTER
        //
        // 初始化此適配器上的過(guò)濾相關(guān)數(shù)據(jù)
        //
        FltOnInitAdapter(pAdapt);
// END_PTEX_FILTER
				
		// 添加協(xié)議對(duì)適配器的引用
		PtRefAdapter(pAdapt);


// END_PTUSERIO


        NdisInitializeEvent(&pAdapt->Event);
        NdisAllocateSpinLock(&pAdapt->Lock);
        LockAllocated = TRUE;

        //
        // Allocate a packet pool for sends. We need this to pass sends down.
        // We cannot use the same packet descriptor that came down to our send
        // handler (see also NDIS 5.1 packet stacking).
        //
        NdisAllocatePacketPoolEx(Status,
                                   &pAdapt->SendPacketPoolHandle,
                                   MIN_PACKET_POOL_SIZE,
                                   MAX_PACKET_POOL_SIZE - MIN_PACKET_POOL_SIZE,
                                   sizeof(SEND_RSVD));

        if (*Status != NDIS_STATUS_SUCCESS)
        {
            break;
        }

        //
        // Allocate a packet pool for receives. We need this to indicate receives.
        // Same consideration as sends (see also NDIS 5.1 packet stacking).
        //
        NdisAllocatePacketPoolEx(Status,
                                   &pAdapt->RecvPacketPoolHandle,
                                   MIN_PACKET_POOL_SIZE,
                                   MAX_PACKET_POOL_SIZE - MIN_PACKET_POOL_SIZE,
                                   PROTOCOL_RESERVED_SIZE_IN_PACKET);

        if (*Status != NDIS_STATUS_SUCCESS)
        {
            break;
        }

        //
        // Now open the adapter below and complete the initialization
        //
        NdisOpenAdapter(Status,
                          &Sts,
                          &pAdapt->BindingHandle,
                          &MediumIndex,
                          MediumArray,
                          sizeof(MediumArray)/sizeof(NDIS_MEDIUM),
                          ProtHandle,
                          pAdapt,
                          DeviceName,
                          0,
                          NULL);

        if (*Status == NDIS_STATUS_PENDING)
        {
            NdisWaitEvent(&pAdapt->Event, 0);
            *Status = pAdapt->Status;
        }

        if (*Status != NDIS_STATUS_SUCCESS)
        {
            break;
        }

        pAdapt->Medium = MediumArray[MediumIndex];

        //
        // Now ask NDIS to initialize our miniport (upper) edge.
        // Set the flag below to synchronize with a possible call
        // to our protocol Unbind handler that may come in before
        // our miniport initialization happens.
        //
        pAdapt->MiniportInitPending = TRUE;
        NdisInitializeEvent(&pAdapt->MiniportInitEvent);

        *Status = NdisIMInitializeDeviceInstanceEx(DriverHandle,
                                           &pAdapt->DeviceName,
                                           pAdapt);

        if (*Status != NDIS_STATUS_SUCCESS)
        {
            DBGPRINT(("BindAdapter: Adapt %p, IMInitializeDeviceInstance error %x\n",
                pAdapt, *Status));
            break;
        }

    } while(FALSE);

    //
    // Close the configuration handle now - see comments above with
    // the call to NdisIMInitializeDeviceInstanceEx.
    //
    if (ConfigHandle != NULL)
    {
        NdisCloseConfiguration(ConfigHandle);
    }

    if (*Status != NDIS_STATUS_SUCCESS)
    {
        if (pAdapt != NULL)
        {
            if (pAdapt->BindingHandle != NULL)
            {
                NDIS_STATUS    LocalStatus;

                //
                // Close the binding we opened above.
                //

                NdisResetEvent(&pAdapt->Event);
                
                NdisCloseAdapter(&LocalStatus, pAdapt->BindingHandle);
                pAdapt->BindingHandle = NULL;

                if (LocalStatus == NDIS_STATUS_PENDING)
                {
                     NdisWaitEvent(&pAdapt->Event, 0);
                     LocalStatus = pAdapt->Status;
                }
            }
 
// BEGIN_PTUSERIO	
				
			// 移除協(xié)議對(duì)適配器的引用
			PtDerefAdapter(pAdapt);

// END_PTUSERIO

            pAdapt = NULL;
        }
    }


    DBGPRINT(("<== Protocol BindAdapter: pAdapt %p, Status %x\n", pAdapt, *Status));
}


VOID
PtOpenAdapterComplete(
    IN  NDIS_HANDLE             ProtocolBindingContext,
    IN  NDIS_STATUS             Status,
    IN  NDIS_STATUS             OpenErrorStatus
    )
/*++

Routine Description:

    Completion routine for NdisOpenAdapter issued from within the PtBindAdapter. Simply
    unblock the caller.

Arguments:

    ProtocolBindingContext    Pointer to the adapter
    Status                    Status of the NdisOpenAdapter call
    OpenErrorStatus            Secondary status(ignored by us).

Return Value:

    None

--*/
{
    PADAPT      pAdapt =(PADAPT)ProtocolBindingContext;
    
    UNREFERENCED_PARAMETER(OpenErrorStatus);
    
    DBGPRINT(("==> PtOpenAdapterComplete: Adapt %p, Status %x\n", pAdapt, Status));
    pAdapt->Status = Status;
    NdisSetEvent(&pAdapt->Event);
}


VOID
PtUnbindAdapter(
    OUT PNDIS_STATUS        Status,
    IN  NDIS_HANDLE            ProtocolBindingContext,
    IN  NDIS_HANDLE            UnbindContext
    )
/*++

Routine Description:

    Called by NDIS when we are required to unbind to the adapter below.
    This functions shares functionality with the miniport's HaltHandler.
    The code should ensure that NdisCloseAdapter and NdisFreeMemory is called
    only once between the two functions

Arguments:

    Status                    Placeholder for return status
    ProtocolBindingContext    Pointer to the adapter structure
    UnbindContext            Context for NdisUnbindComplete() if this pends

Return Value:

    Status for NdisIMDeinitializeDeviceContext

--*/
{
    PADAPT         pAdapt =(PADAPT)ProtocolBindingContext;
    NDIS_STATUS    LocalStatus;

    UNREFERENCED_PARAMETER(UnbindContext);
    
    DBGPRINT(("==> PtUnbindAdapter: Adapt %p\n", pAdapt));

    //
    // Set the flag that the miniport below is unbinding, so the request handlers will
    // fail any request comming later
    // 
    NdisAcquireSpinLock(&pAdapt->Lock);
    pAdapt->UnbindingInProcess = TRUE;
    if (pAdapt->QueuedRequest == TRUE)
    {
        pAdapt->QueuedRequest = FALSE;
        NdisReleaseSpinLock(&pAdapt->Lock);

        PtRequestComplete(pAdapt,
                         &pAdapt->Request,
                         NDIS_STATUS_FAILURE );

    }