Routine Description:

    Called from BulkUsb_ProcessPnPIrp(), the dispatch routine for IRP_MJ_PNP.
    Initializes a given instance of the device on the USB.
    USB client drivers such as us set up URBs (USB Request Packets) to send requests
    to the host controller driver (HCD). The URB structure defines a format for all
    possible commands that can be sent to a USB device.
    Here, we request the device descriptor and store it, and configure the device.


Arguments:

    DeviceObject - pointer to the FDO (Functional Device Object)

Return Value:

    NT status code

--*/
{
    PDEVICE_EXTENSION deviceExtension;
    NTSTATUS ntStatus;
    PUSB_DEVICE_DESCRIPTOR deviceDescriptor = NULL;
    PURB urb;
    ULONG siz;

    BULKUSB_KdPrint( DBGLVL_DEFAULT,("enter BulkUsb_StartDevice\n"));

    deviceExtension = DeviceObject->DeviceExtension;

    urb = BULKUSB_ExAllocatePool(NonPagedPool,
                         sizeof(struct _URB_CONTROL_DESCRIPTOR_REQUEST));

    BULKUSB_KdPrintCond( DBGLVL_HIGH,!urb, ("BulkUsb_StartDevice() FAILED BULKUSB_ExAllocatePool() for URB\n"));

    if (urb) {

        siz = sizeof(USB_DEVICE_DESCRIPTOR);

        deviceDescriptor = BULKUSB_ExAllocatePool(NonPagedPool,
                                          siz);

        BULKUSB_KdPrintCond( DBGLVL_HIGH, !deviceDescriptor, ("BulkUsb_StartDevice() FAILED BULKUSB_ExAllocatePool() for deviceDescriptor\n"));

        if (deviceDescriptor) {

            UsbBuildGetDescriptorRequest(urb,
                                         (USHORT) sizeof (struct _URB_CONTROL_DESCRIPTOR_REQUEST),
                                         USB_DEVICE_DESCRIPTOR_TYPE,
                                         0,
                                         0,
                                         deviceDescriptor,
                                         NULL,
                                         siz,
                                         NULL);


            ntStatus = BulkUsb_CallUSBD(DeviceObject, urb);

            BULKUSB_KdPrintCond( DBGLVL_DEFAULT, !NT_SUCCESS(ntStatus), ("BulkUsb_StartDevice() FAILED BulkUsb_CallUSBD(DeviceObject, urb)\n"));

            if (NT_SUCCESS(ntStatus)) {
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("Device Descriptor = %x, len %x\n",
                                deviceDescriptor,
                                urb->UrbControlDescriptorRequest.TransferBufferLength));

                BULKUSB_KdPrint( DBGLVL_MEDIUM,("I82930 Device Descriptor:\n"));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("-------------------------\n"));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("bLength %d\n", deviceDescriptor->bLength));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("bDescriptorType 0x%x\n", deviceDescriptor->bDescriptorType));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("bcdUSB 0x%x\n", deviceDescriptor->bcdUSB));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("bDeviceClass 0x%x\n", deviceDescriptor->bDeviceClass));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("bDeviceSubClass 0x%x\n", deviceDescriptor->bDeviceSubClass));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("bDeviceProtocol 0x%x\n", deviceDescriptor->bDeviceProtocol));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("bMaxPacketSize0 0x%x\n", deviceDescriptor->bMaxPacketSize0));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("idVendor 0x%x\n", deviceDescriptor->idVendor));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("idProduct 0x%x\n", deviceDescriptor->idProduct));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("bcdDevice 0x%x\n", deviceDescriptor->bcdDevice));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("iManufacturer 0x%x\n", deviceDescriptor->iManufacturer));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("iProduct 0x%x\n", deviceDescriptor->iProduct));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("iSerialNumber 0x%x\n", deviceDescriptor->iSerialNumber));
                BULKUSB_KdPrint( DBGLVL_MEDIUM,("bNumConfigurations 0x%x\n", deviceDescriptor->bNumConfigurations));
            }
        } else {
			// if we got here we failed to allocate deviceDescriptor
            ntStatus = STATUS_INSUFFICIENT_RESOURCES;
        }

        if (NT_SUCCESS(ntStatus)) {
            deviceExtension->UsbDeviceDescriptor = deviceDescriptor;
        } else if (deviceDescriptor) {
            BULKUSB_ExFreePool(deviceDescriptor);
        }

        BULKUSB_ExFreePool(urb);

    } else {
		// if we got here we failed to allocate the urb
        ntStatus = STATUS_INSUFFICIENT_RESOURCES;
    }

    if (NT_SUCCESS(ntStatus)) {
        ntStatus = BulkUsb_ConfigureDevice(DeviceObject);

        BULKUSB_KdPrintCond( DBGLVL_MEDIUM,!NT_SUCCESS(ntStatus),("BulkUsb_StartDevice BulkUsb_ConfigureDevice() FAILURE (%x)\n", ntStatus));
    }


    if (NT_SUCCESS(ntStatus)) {
        deviceExtension->DeviceStarted = TRUE;
    }
    BULKUSB_KdPrint( DBGLVL_DEFAULT, ("exit BulkUsb_StartDevice (%x)\n", ntStatus));

    return ntStatus;
}


NTSTATUS
BulkUsb_RemoveDevice(
    IN  PDEVICE_OBJECT DeviceObject
    )
/*++

Routine Description:

	Called from BulkUsb_ProcessPnPIrp() to
    clean up our device instance's allocated buffers; free symbolic links

Arguments:

    DeviceObject - pointer to the FDO

Return Value:

    NT status code from free symbolic link operation

--*/
{
    PDEVICE_EXTENSION deviceExtension;
    NTSTATUS ntStatus = STATUS_SUCCESS;
    UNICODE_STRING deviceLinkUnicodeString;

    BULKUSB_KdPrint( DBGLVL_DEFAULT,("enter BulkUsb_RemoveDevice\n"));

    deviceExtension = DeviceObject->DeviceExtension;

    RtlInitUnicodeString (&deviceLinkUnicodeString,
                          deviceExtension->DeviceLinkNameBuffer);

    // remove the GUID-based symbolic link
    ntStatus = IoSetDeviceInterfaceState(&deviceLinkUnicodeString, FALSE);
    BULKUSB_ASSERT( NT_SUCCESS( ntStatus ) );

    //
    // Free device descriptor structure
    //

    if (deviceExtension->UsbDeviceDescriptor) {
        BULKUSB_ExFreePool(deviceExtension->UsbDeviceDescriptor);
    }

    //
    // Free up the UsbInterface structure
    //
    if (deviceExtension->UsbInterface) {
        BULKUSB_ExFreePool(deviceExtension->UsbInterface);
    }

	// free up the USB config discriptor
    if (deviceExtension->UsbConfigurationDescriptor) {
        BULKUSB_ExFreePool(deviceExtension->UsbConfigurationDescriptor);
    }


    // free the pending irp list
    if ( deviceExtension->PendingIoIrps ) {
             BULKUSB_ExFreePool(deviceExtension->PendingIoIrps );

    }

	BULKUSB_ASSERT( gExAllocCount == 0 );
    BULKUSB_KdPrint( DBGLVL_HIGH,("exit BulkUsb_RemoveDevice() gExAllocCount = dec %d\n", gExAllocCount ));

    BULKUSB_KdPrint( DBGLVL_DEFAULT,("exit BulkUsb_RemoveDevice() status = 0x%x\n", ntStatus ));

    return ntStatus;
}




NTSTATUS
BulkUsb_StopDevice(
    IN  PDEVICE_OBJECT DeviceObject
    )
/*++

Routine Description:

    Stops a given instance of a 82930 device on the USB.
    We basically just tell USB this device is now 'unconfigured'

Arguments:

    DeviceObject - pointer to the device object for this instance of a 82930

Return Value:

    NT status code

--*/
{
    PDEVICE_EXTENSION deviceExtension;
    NTSTATUS ntStatus = STATUS_SUCCESS;
    PURB urb;
    ULONG siz;

    BULKUSB_KdPrint( DBGLVL_DEFAULT,("enter BulkUsb_StopDevice\n"));

    deviceExtension = DeviceObject->DeviceExtension;

    //
    // Send the select configuration urb with a NULL pointer for the configuration
    // handle. This closes the configuration and puts the device in the 'unconfigured'
    // state.
    //

    siz = sizeof(struct _URB_SELECT_CONFIGURATION);

    urb = BULKUSB_ExAllocatePool(NonPagedPool,
                         siz);

    if (urb) {
        UsbBuildSelectConfigurationRequest(urb,
                                          (USHORT) siz,
                                          NULL);

        ntStatus = BulkUsb_CallUSBD(DeviceObject, urb);

        BULKUSB_KdPrintCond( DBGLVL_DEFAULT,!NT_SUCCESS(ntStatus),("BulkUsb_StopDevice() FAILURE Configuration Closed status = %x usb status = %x.\n", ntStatus, urb->UrbHeader.Status));

        BULKUSB_ExFreePool(urb);
    } else {
        ntStatus = STATUS_INSUFFICIENT_RESOURCES;
    }


    if (NT_SUCCESS(ntStatus)) {
        deviceExtension->DeviceStarted = FALSE;
    }

    deviceExtension->StopDeviceRequested = FALSE;

    BULKUSB_KdPrint( DBGLVL_DEFAULT,("exit BulkUsb_StopDevice() (%x)\n", ntStatus));

    return ntStatus;
}



NTSTATUS
BulkUsb_IrpCompletionRoutine(
    IN PDEVICE_OBJECT DeviceObject,
    IN PIRP Irp,
    IN PVOID Context
    )
/*++

Routine Description:

    Used as a  general purpose completion routine so it can signal an event,
    passed as the Context, when the next lower driver is done with the input Irp.
	This routine is used by both PnP and Power Management logic.

    Even though this routine does nothing but set an event, it must be defined and
    prototyped as a completetion routine for use as such


Arguments:

    DeviceObject - Pointer to the device object for the class device.

    Irp - Irp completed.

    Context - Driver defined context, in this case a pointer to an event.

Return Value:

    The function value is the final status from the operation.

--*/
{
    PKEVENT event = Context;

    // Set the input event
    KeSetEvent(event,
               1,       // Priority increment  for waiting thread.
               FALSE);  // Flag this call is not immediately followed by wait.

    // This routine must return STATUS_MORE_PROCESSING_REQUIRED because we have not yet called
    // IoFreeIrp() on this IRP.
    return STATUS_MORE_PROCESSING_REQUIRED;

}