【usb】winusb interface design analysis

Get interfaceHandle

• First get CreateFilethe device operation handle using, DeviceHandle.
• Then use WinUsb_InitializeGet Interface Operation Handle to get the operation handle of the first interface of the device by default.

control transfer

BOOL WinUsb_ControlTransfer(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            WINUSB_SETUP_PACKET     SetupPacket,
  [out]           PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

• InterfaceHandleWinUsb_InitializeIt is the interface operation handle obtained through the above .
• SetupPacketCorresponds to the Setup package in the usb protocol.
• BufferThe buffer to send or receive data into.
• BufferLengthbuffer size.
• LengthTransferredThe length of data actually sent or received.
• OverlappedIt is used for asynchronous transmission. If this field is not set, the interface is a synchronous interface. The function will not return until the transmission is completed. Otherwise, the function returns immediately, and after the transmission is completed, Overlappeda callback notification is made through the mechanism.

Introduction to Overlapped Mechanism

Get endpoint information

Get interface information

BOOL WinUsb_QueryInterfaceSettings(
  [in]  WINUSB_INTERFACE_HANDLE   InterfaceHandle,
  [in]  UCHAR                     AlternateInterfaceNumber,
  [out] PUSB_INTERFACE_DESCRIPTOR UsbAltInterfaceDescriptor
);

• USB_INTERFACE_DESCRIPTORCorresponds to the standard interface descriptor in the USB protocol . Through this parameter, we can know how many endpoints the interface has.

Get endpoint information

BOOL WinUsb_QueryPipe(
  [in]  WINUSB_INTERFACE_HANDLE  InterfaceHandle,
  [in]  UCHAR                    AlternateInterfaceNumber,
  [in]  UCHAR                    PipeIndex,
  [out] PWINUSB_PIPE_INFORMATION PipeInformation
);

typedef struct _WINUSB_PIPE_INFORMATION {
    
    
  USBD_PIPE_TYPE PipeType;
  UCHAR          PipeId;
  USHORT         MaximumPacketSize;
  UCHAR          Interval;
} WINUSB_PIPE_INFORMATION, *PWINUSB_PIPE_INFORMATION;

Once we know how many endpoints there are, we can get endpoint information one by one.

• WINUSB_PIPE_INFORMATIONThrough this parameter, we can know the type of pipe (control transfer/bulk transfer/interrupt transfer/isochronous transfer), and the direction of the pipe (host-to-device or device-to-host).

Perform bulk (bulk) transfers and interrupt (interrupt) transfers

• Through the above endpoint information, we can know what transmission type the endpoint supports and the direction of its data transmission. Then we can perform data transmission based on the information of the endpoint.

BOOL WinUsb_ReadPipe(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            UCHAR                   PipeID,
  [out]           PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

BOOL WinUsb_WritePipe(
  [in]            WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]            UCHAR                   PipeID,
  [in]            PUCHAR                  Buffer,
  [in]            ULONG                   BufferLength,
  [out, optional] PULONG                  LengthTransferred,
  [in, optional]  LPOVERLAPPED            Overlapped
);

• Both interrupt transfer and bulk transfer use the above two interfaces to transfer data. According to the endpoint information, we can know the transmission direction of the pipeline. If the direction is host-to-device, then it is writing, that is, we need to use the WinUsb_WritePipeinterface to write data to the endpoint.
• If the direction is device-to-host, then we can use WinUsb_ReadPipethe interface to read data from the endpoint.
• Like control transfers, these two interfaces provide Overlappedmechanisms to control synchronous or asynchronous transfers.

pipeline strategy

• The so-called pipeline strategy means that the behavior of the endpoint can be controlled according to the needs. For example, set the transmission timeout period. Or when sending a request, if the size of the request packet is exactly an integer multiple of the maximum length that the endpoint can send, do you need to send a zero-length packet, and so on. The interface is as follows:

BOOL WinUsb_SetPipePolicy(
  [in] WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in] UCHAR                   PipeID,
  [in] ULONG                   PolicyType,
  [in] ULONG                   ValueLength,
  [in] PVOID                   Value
);

BOOL WinUsb_GetPipePolicy(
  [in]      WINUSB_INTERFACE_HANDLE InterfaceHandle,
  [in]      UCHAR                   PipeID,
  [in]      ULONG                   PolicyType,
  [in, out] PULONG                  ValueLength,
  [out]     PVOID                   Value
);

Summarize

• For control transmission and isochronous transmission, winusb provides transmission interfaces respectively. WinUsb_ControlTransfer , WinUsb_ReadIsochPipe, WinUsb_WriteIsochPipe.
• For bulk transfer and interrupt transfer, a set of interfaces is uniformly used. WinUsb_ReadPipe, WinUsb_WritePipe.
• The above interfaces all Overlappedcontrol synchronous transmission or asynchronous transmission through mechanisms.
• You can personalize the behavior of the pipeline by modifying the pipeline policy.
• In addition to the above interfaces, winusb also provides various requests, which can be used flexibly. For example, IOCTL_GENERICUSBFN_GET_INTERFACE_DESCRIPTOR_SETall endpoint information of an interface can be obtained.

References

Access a USB device by using WinUSB functions
WinUSB functions for pipeline policy modification