如何提交 URB

發行項
03/28/2025

本主題描述將初始化的 URB 提交至 USB 驅動程式堆疊以處理特定要求所需的步驟。

用戶端驅動程式透過 I/O 要求封包（IRP）來與裝置通訊，使用的 I/O 控制程式代碼（IOCTL）請求類型為 IRP_MJ_INTERNAL_DEVICE_CONTROL，傳送至裝置。針對裝置特定要求，例如選取組態要求，要求會在與 IRP 相關聯的 USB 要求區塊（URB）中描述。將 URB 與 IRP 產生關聯，並將要求傳送至 USB 驅動程式堆疊的過程被稱為 URB 提交。若要提交 URB，用戶端驅動程式必須使用 IOCTL_INTERNAL_USB_SUBMIT_URB 作為裝置控制程式代碼。 IOCTL 是其中一個「內部」控制代碼，可提供用戶端驅動程序用來管理其裝置的 I/O 介面，以及裝置所連接的埠。使用者模式應用程式無法存取這些內部 I/O 介面。如需核心模式驅動程式的更多控制程式碼，請參閱 Kernel-Mode USB 用戶端驅動程式的 IOCTL。

先決條件

將要求傳送至通用序列總線（USB）驅動程式堆疊之前，用戶端驅動程式必須根據要求類型配置 URB 結構和格式。如需詳細資訊，請參閱配置和建置 URL 和最佳做法：使用 URL。

操作說明

呼叫 IoAllocateIrp 例程，為 URB 配置 IRP。您必須提供接收 IRP 之裝置物件的堆疊大小。您在先前呼叫 ioAttachDeviceToDeviceStack 例程時收到該裝置物件的指標。堆疊大小會儲存在 DEVICE_OBJECT 結構的 StackSize 成員中。
呼叫 ioGetNextIrpStackLocation ，以取得 IRP 第一個堆棧位置的指標（IO_STACK_LOCATION）。
將 IO_STACK_LOCATION 結構的 MajorFunction 成員設定為 IRP_MJ_INTERNAL_DEVICE_CONTROL。
將 Parameters.DeviceIoControl.IoControlCode 成員設置為 IOCTL_INTERNAL_USB_SUBMIT_URB，該成員屬於 IO_STACK_LOCATION 結構。
將 Parameters.Others.Argument1IO_STACK_LOCATION 結構的成員設定為初始化 URB 結構的位址。若要將 IRP 與 URB 建立關聯，只有在 URB 是由 USBD_UrbAllocate、USBD_SelectConfigUrbAllocateAndBuild或 USBD_SelectInterfaceUrbAllocateAndBuild所分配時，您才能呼叫 USBD_AssignUrbToIoStackLocation。
呼叫 IoSetCompletionRoutineEx來設定完成例程。

如果您以異步方式提交 URB，請將指標傳遞至呼叫端實作完成例程及其內容。呼叫端會在其完成例程中釋放 IRP。

如果您要同步提交 IRP，請實作完成例程，並在呼叫 ioSetCompletionRoutineEx中傳遞該例程的指標。呼叫也需要 Context 參數中的初始化 KEVENT 物件。在您的完成例程中，將事件設定為訊號狀態。
呼叫 IoCallDriver，將填入的 IRP 轉送至裝置堆疊中的下一個下層裝置物件。針對同步呼叫，在呼叫 IoCallDriver之後，先呼叫 KeWaitForSingleObject 等候事件物件，以取得事件通知。
當 IRP 完成時，檢查 IRP IoStatus.Status 成員，並評估結果。如果 IoStatus.Status 是STATUS_SUCCESS，要求就會成功。

USB 同步提交

下列範例示範如何同步提交 URB。

// The SubmitUrbSync routine submits an URB synchronously.
//
// Parameters:
//      DeviceExtension: Pointer to the caller's device extension. The
//                       device extension must have a pointer to
//                       the next lower device object in the device stacks.  
//
//      Irp: Pointer to an IRP allocated by the caller.
//
//      Urb: Pointer to an URB that is allocated by  USBD_UrbAllocate,
//           USBD_IsochUrbAllocate, USBD_SelectConfigUrbAllocateAndBuild,
//           or USBD_SelectInterfaceUrbAllocateAndBuild.

//      CompletionRoutine: Completion routine.
//
// Return Value:
//
//      NTSTATUS  

NTSTATUS SubmitUrbSync( PDEVICE_EXTENSION DeviceExtension,
                       PIRP Irp,
                       PURB Urb,  
                       PIO_COMPLETION_ROUTINE SyncCompletionRoutine)  

{

    NTSTATUS  ntStatus;  
    KEVENT    kEvent;

    PIO_STACK_LOCATION nextStack;

    // Get the next stack location.
    nextStack = IoGetNextIrpStackLocation(Irp);  

    // Set the major code.
    nextStack->MajorFunction = IRP_MJ_INTERNAL_DEVICE_CONTROL;  

    // Set the IOCTL code for URB submission.
    nextStack->Parameters.DeviceIoControl.IoControlCode = IOCTL_INTERNAL_USB_SUBMIT_URB;  

    // Attach the URB to this IRP.
    // The URB must be allocated by USBD_UrbAllocate, USBD_IsochUrbAllocate,
    // USBD_SelectConfigUrbAllocateAndBuild, or USBD_SelectInterfaceUrbAllocateAndBuild.
    USBD_AssignUrbToIoStackLocation (DeviceExtension->UsbdHandle, nextStack, Urb);

    KeInitializeEvent(&kEvent, NotificationEvent, FALSE);

    ntStatus = IoSetCompletionRoutineEx ( DeviceExtension->NextDeviceObject,  
        Irp,  
        SyncCompletionRoutine,  
        (PVOID) &kEvent,  
        TRUE,
        TRUE,
        TRUE);

    if (!NT_SUCCESS(ntStatus))
    {
        KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "IoSetCompletionRoutineEx failed. \n" ));
        goto Exit;
    }

    ntStatus = IoCallDriver(DeviceExtension->NextDeviceObject, Irp);  

    if (ntStatus == STATUS_PENDING)
    {
        KeWaitForSingleObject ( &kEvent,
            Executive,
            KernelMode,
            FALSE,
            NULL);
    }

    ntStatus = Irp->IoStatus.Status;

Exit:

    if (!NT_SUCCESS(ntStatus))
    {
        // We hit a failure condition,
        // We will free the IRP

        IoFreeIrp(Irp);
        Irp = NULL;
    }


    return ntStatus;
}

// The SyncCompletionRoutine routine is the completion routine
// for the synchronous URB submit request.
//
// Parameters:
//
//      DeviceObject: Pointer to the device object.
//      Irp:          Pointer to an I/O Request Packet.
//      CompletionContext: Context for the completion routine.
//
// Return Value:
//
//      NTSTATUS  

NTSTATUS SyncCompletionRoutine ( PDEVICE_OBJECT DeviceObject,
                                PIRP           Irp,
                                PVOID          Context)
{
    PKEVENT kevent;

    kevent = (PKEVENT) Context;

    if (Irp->PendingReturned == TRUE)
    {
        KeSetEvent(kevent, IO_NO_INCREMENT, FALSE);
    }

    KdPrintEx(( DPFLTR_IHVDRIVER_ID, DPFLTR_INFO_LEVEL, "Request completed. \n" ));


    return STATUS_MORE_PROCESSING_REQUIRED;
}

USB 異步提交

下列範例示範如何以異步方式提交 URB。

// The SubmitUrbASync routine submits an URB asynchronously.
//
// Parameters:
//
// Parameters:
//      DeviceExtension: Pointer to the caller's device extension. The
//                       device extension must have a pointer to
//                       the next lower device object in the device stacks.  
//
//      Irp: Pointer to an IRP allocated by the caller.
//
//      Urb: Pointer to an URB that is allocated by  USBD_UrbAllocate,
//           USBD_IsochUrbAllocate, USBD_SelectConfigUrbAllocateAndBuild,
//           or USBD_SelectInterfaceUrbAllocateAndBuild.

//      CompletionRoutine: Completion routine.
//
//      CompletionContext: Context for the completion routine.
//
//
// Return Value:
//
//      NTSTATUS

NTSTATUS SubmitUrbASync ( PDEVICE_EXTENSION DeviceExtension,
                         PIRP Irp,
                         PURB Urb,  
                         PIO_COMPLETION_ROUTINE CompletionRoutine,  
                         PVOID CompletionContext)  
{
    // Completion routine is required if the URB is submitted asynchronously.
    // The caller's completion routine releases the IRP when it completes.


    NTSTATUS ntStatus = -1;  

    PIO_STACK_LOCATION nextStack = IoGetNextIrpStackLocation(Irp);  

    // Attach the URB to this IRP.
    nextStack->MajorFunction = IRP_MJ_INTERNAL_DEVICE_CONTROL;  

    // Attach the URB to this IRP.
    nextStack->Parameters.DeviceIoControl.IoControlCode = IOCTL_INTERNAL_USB_SUBMIT_URB;  

    // Attach the URB to this IRP.
    (void) USBD_AssignUrbToIoStackLocation (DeviceExtension->UsbdHandle, nextStack, Urb);  

    // Caller's completion routine will free the irp when it completes.
    ntStatus = IoSetCompletionRoutineEx ( DeviceExtension->NextDeviceObject,
        Irp,  
        CompletionRoutine,  
        CompletionContext,  
        TRUE,
        TRUE,
        TRUE);

    if (!NT_SUCCESS(ntStatus))
    {
        goto Exit;
    }

    (void) IoCallDriver(DeviceExtension->NextDeviceObject, Irp);

Exit:
    if (!NT_SUCCESS(ntStatus))
    {
        // We hit a failure condition,
        // We will free the IRP

        IoFreeIrp(Irp);
        Irp = NULL;
    }

    return ntStatus;
}

將要求傳送至USB裝置

共用方式為

如何提交 URB

先決條件

操作說明

USB 同步提交

USB 異步提交

意見反應

其他資源

共用方式為

如何提交 URB

先決條件

操作說明

USB 同步提交

USB 異步提交

相關主題

意見反應

其他資源