Wideusb USB Devices Driver

Introduction

Often the best way to write a USB device driver will be to start withan existing one and modify it as necessary. The information given hereis intended primarily as an outline rather than as a complete guide.

You safely remove the USB device from the USB port. You reconnect the same USB device or a different USB device to the same USB port on the hub. In this scenario, the computer does not detect the USB device. Note This issue affects USB 2.0 hubs and USB 2.0 components in USB 3.0 hubs. This issue occurs because the USB port is disabled. To access a USB device, start by creating a skeleton app based on the WinUSB template included in the integrated environment of Windows Driver Kit (WDK) (with Debugging Tools for Windows) and Microsoft Visual Studio.You can use the template as a starting point. Plug in your device to the host system. Open Device Manager and locate the device. Select and hold (or right-click) the device and select Update driver software. From the context menu. In the wizard, select Browse my computer for driver software. No power to the USB device. Ensure that your USB device, such as a camera or USB mouse, has adequate battery power. If you have checked that neither of the above are the cause of your USB problems, the next thing to do is restart your computer. Do not skip this step as it is very often successful in fixing USB Drivers problems. When you plug the device into your USB, Windows will look for the associated driver, if it cannot find this driver then you will be prompted to insert the driver disc that came with your device. Common USB Device errors are ‘ usb port not working ‘, ‘device descriptor request failed error’ or ‘bugcodeusbdriver’ issues.

Note: At the time of writing only one USB device driver has beenimplemented. Hence it is possible, perhaps probable, that someportability issues have not yet been addressed. One issueinvolves the different types of transfer, for example the initialtarget hardware had no support for isochronous or interrupt transfers,so additional functionality may be needed to switch between transfertypes. Another issue would be hardware where a given endpoint number,say endpoint 1, could be used for either receiving or transmittingdata, but not both because a single fifo is used. Issues like thesewill have to be resolved as and when additional USB device drivers arewritten.

The Control Endpoint

A USB device driver should provide a single usbs_control_endpointdata structure for every USB device. Typical peripherals will haveonly one USB port so there will be just one such data structure in theentire system, but theoretically it is possible to have multiple USBdevices. These may all involve the same chip, in which case a singledevice driver should support multiple device instances, or they mayinvolve different chips. The name or names of these data structuresare determined by the device driver, but appropriate care should betaken to avoid name clashes.

A USB device cannot be used unless the control endpoint data structureexists. However, the presence of USB hardware in the target processoror board does not guarantee that the application will necessarily wantto use that hardware. To avoid unwanted code or data overheads, thedevice driver can provide a configuration option to determine whetheror not the endpoint 0 data structure is actually provided. A defaultvalue of CYGINT_IO_USB_SLAVE_CLIENTS ensures thatthe USB driver will be enabled automatically if higher-level code doesrequire USB support, while leaving ultimate control to the user.

The USB device driver is responsible for filling in thestart_fn,poll_fn andinterrupt_vector fields. Usually this canbe achieved by static initialization. The driver is also largelyresponsible for maintaining the statefield. The control_buffer array should beused to hold the first packet of a control message. Thebuffer and other fields related to datatransfers will be managed jointly by higher-level code andthe device driver. The remaining fields are generally filled in byhigher-level code, although the driver should initialize them to NULLvalues.

Hardware permitting, the USB device should be inactive until thestart_fn is invoked, for example bytristating the appropriate pins. This prevents the host frominteracting with the peripheral before all other parts of the systemhave initialized. It is expected that thestart_fn will only be invoked once, shortlyafter power-up.

Where possible the device driver should detect state changes, such aswhen the connection between host and peripheral is established, andreport these to higher-levelcode via the state_change_fn callback, ifany. The state change to and from configured state cannot easily behandled by the device driver itself, instead higher-level code such asthe common USB slave package will take care of this.

Once the connection between host and peripheral has been established,the peripheral must be ready to accept control messages at all times,and must respond to these within certain time constraints. Forexample, the standard set-address control message must be handledwithin 50ms. The USB specification provides more information on theseconstraints. The device driver is responsible for receiving theinitial packet of a control message. This packet will always be eightbytes and should be stored in thecontrol_buffer field. Certain standardcontrol messages should be detected and handled by the device driveritself. The most important is set-address, but usually the get-status,set-feature and clear-feature requests when applied to haltedendpoints should also be handled by the driver. Other standard controlmessages should first be passed on to thestandard_control_fn callback (if any), andfinally to the default handlerusbs_handle_standard_control provided by thecommon USB slave package. Class, vendor and reserved control messagesshould always be dispatched to the appropriate callback and there isno default handler for these.

Some control messages will involve further data transfer, not just theinitial packet. The device driver must handle this in accordance withthe USB specification and the buffer management strategy. Thedriver is also responsible for keeping track of whether or not thecontrol operation has succeeded and generating an ACK or STALLhandshake.

Usb to usb connectorKinds of usb devices

The polling support is optional and may not be feasible on allhardware. It is only used in certain specialised environments such asRedBoot. A typical implementation of the polling function would justcheck whether or not an interrupt would have occurred and, if so, callthe same code that the interrupt handler would.

Data Endpoints

In addition to the control endpoint data structure, a USB devicedriver should also provide appropriate dataendpoint data structures. Obviously this is only relevant ifthe USB support generally is desired, that is if the control endpoint isprovided. In addition, higher-level code may not require all theendpoints, so it may be useful to provide configuration options thatcontrol the presence of each endpoint. For example, the intendedapplication might only involve a single transmit endpoint and ofcourse control messages, so supporting receive endpoints might wastememory.

Conceptually, data endpoints are much simpler than the controlendpoint. The device driver has to supply two functions, one fordata transfers and another to control the halted condition. Theseimplement the functionality forusbs_start_rx_buffer,usbs_start_tx_buffer,usbs_set_rx_endpoint_halted andusbs_set_tx_endpoint_halted.The device driver is also responsible for maintaining thehalted status.

For data transfers, higher-level code will have filled in thebuffer,buffer_size,complete_fn andcomplete_data fields. The transfer functionshould arrange for the transfer to start, allowing the host to send orreceive packets. Typically this will result in an interrupt at the endof the transfer or after each packet. Once the entire transfer hasbeen completed, the driver's interrupt handling code should invoke thecompletion function. This can happen either in DSR context or threadcontext, depending on the driver's implementation. There are a numberof special cases to consider. If the endpoint is halted when thetransfer is started then the completion function can be invokedimmediately with -EAGAIN. If the transfer cannot becompleted because the connection is broken then the completionfunction should be invoked with -EPIPE. If theendpoint is stalled during the transfer, either because of a standardcontrol message or because higher-level code calls the appropriateset_halted_fn, then again the completionfunction should be invoked with -EAGAIN. Finally,the <usbs_start_rx_endpoint_wait andusbs_start_tx_endpoint_wait functions involvecalling the device driver's data transfer function with a buffer sizeof 0 bytes.

Note: Giving a buffer size of 0 bytes a special meaning is problematicalbecause it prevents transfers of that size. Such transfers are allowedby the USB protocol, consisting of just headers and acknowledgementsand an empty data phase, although rarely useful. A future modificationof the device driver specification will address this issue, althoughcare has to be taken that the functionality remains accessible throughdevtab entries as well as via low-level accesses.

Devtab Entries

For some applications or higher-level packages it may be moreconvenient to use traditional open/read/write I/O calls rather thanthe non-blocking USB I/O calls. To support this the device driver canprovide a devtab entry for each endpoint, for example:

Again care must be taken to avoid name clashes. This can be achievedby having a configuration option to control the base name, with adefault value of e.g. /dev/usbs, and appending anendpoint-specific string. This gives the application developersufficient control to eliminate any name clashes. The common USB slavepackage provides functions usbs_devtab_cwrite andusbs_devtab_cread, which can be used in thefunction tables for transmit and receive endpoints respectively. Theprivate field priv of the devtab entryshould be a pointer to the underlying endpoint data structure.

Because devtab entries are never accessed directly, only indirectly,they would usually be eliminated by the linker. To avoid this thedevtab entries should normally be defined in a separate source filewhich ends up the special library libextras.arather than in the default library libtarget.a.

Devices

Not all applications or higher-level packages will want to use thedevtab entries and the blocking I/O facilities. It may be appropriatefor the device driver to provide additional configuration options thatcontrol whether or not any or all of the devtab entries should beprovided, to avoid unnecessary memory overheads.

Interrupt Handling

A typical USB device driver will need to service interrupts for all ofthe endpoints and possibly for additional USB events such as enteringor leaving suspended mode. Usually these interrupts need not beserviced directly by the ISR. Instead, they can be left to a DSR. Ifthe peripheral is not able to accept or send another packet just yet,the hardware will generate a NAK and the host will just retry a littlebit later. If high throughput is required then it may be desirable tohandle the bulk transfer protocol largely at ISR level, that is takecare of each packet in the ISR and only activate the DSR once thewhole transfer has completed.

Control messages may involve invoking arbitrary callback functions inhigher-level code. This should normally happen at DSR level. Doing itat ISR level could seriously affect the system's interrupt latency andimpose unacceptable constraints on what operations can be performed bythose callbacks. If the device driver requires a thread anyway then itmay be appropriate to use this thread for invoking the callbacks, butusually it is not worthwhile to add a new thread to the system justfor this; higher-level code is expected to write callbacks thatfunction sensibly at DSR level. Much the same applies to thecompletion functions associated with data transfers. These should alsobe invoked at DSR or thread level.

Support for USB Testing

Optionally a USB device driver can provide support for theUSB test software. This requiresdefining a number of additional data structures, allowing thegeneric test code to work out just what the hardware is capable of andhence what testing can be performed.

The key data structure isusbs_testing_endpoint, defined in cyg/io/usb/usbs.h. In addition somecommonly required constants are provided by the common USB package incyg/io/usb/usb.h. Oneusbs_testing_endpoint structure should bedefined for each supported endpoint. The following fields need to befilled in:

endpoint_type

This specifies the type of endpoint and should be one of USB_ENDPOINT_DESCRIPTOR_ATTR_CONTROL, BULK, ISOCHRONOUS or INTERRUPT.

endpoint_number

This identifies the number that should be used by the host to address this endpoint. For a control endpoint it should be 0. For other types of endpoints it should be between 1 and 15.

endpoint_direction

For control endpoints this field is irrelevant. For other types of endpoint it should be either USB_ENDPOINT_DESCRIPTOR_ENDPOINT_IN or USB_ENDPOINT_DESCRIPTOR_ENDPOINT_OUT. If a given endpoint number can be used for traffic in both directions then there should be two entries in the array, one for each direction.

Wideusb Usb Devices Driver Updater

endpoint

This should be a pointer to the appropriate usbs_control_endpoint, usbs_rx_endpoint or usbs_tx_endpoint structure, allowing the generic testing code to perform low-level I/O.

devtab_entry

If the endpoint also has an entry in the system's device table then this field should give the corresponding string, for example '/dev/usbs1r'. This allows the generic testing code to access the device via higher-level calls like open and read.

min_size

This indicates the smallest transfer size that the hardware can support on this endpoint. Typically this will be one.

Note: Strictly speaking a minimum size of one is not quite right since it is valid for a USB transfer to involve zero bytes, in other words a transfer that involves just headers and acknowledgements and an empty data phase, and that should be tested as well. However current device drivers interpret a transfer size of 0 as special, so that would have to be resolved first.

max_size

Similarly, this specifies the largest transfer size. For control endpoints the USB protocol uses only two bytes to hold the transfer length, so there is an upper bound of 65535 bytes. In practice it is very unlikely that any control transfers would ever need to be this large, and in fact such transfers would take a long time and probably violate timing constraints. For other types of endpoint any of the protocol, the hardware, or the device driver may impose size limits. For example a given device driver might be unable to cope with transfers larger than 65535 bytes. If it should be possible to transfer arbitrary amounts of data then a value of -1 indicates no upper limit, and transfer sizes will be limited by available memory and by the capabilities of the host machine.

max_in_padding

This field is needed on some hardware where it is impossible to send packets of a certain size. For example the hardware may be incapable of sending an empty bulk packet to terminate a transfer that is an exact multiple of the 64-byte bulk packet size. Instead the driver has to do some padding and send an extra byte, and the host has to be prepared to receive this extra byte. Such a driver should specify a value of 1 for the padding field. For most drivers this field should be set to 0.

A better solution would be for the device driver to supply a fragment of Tcl code that would adjust the receive buffer size only when necessary, rather than for every transfer. Forcing receive padding on all transfers when only certain transfers will actually be padded reduces the accuracy of certain tests.

alignment

On some hardware data transfers may need to be aligned to certain boundaries, for example a word boundary or a cacheline boundary. Although in theory device drivers could hide such alignment restrictions from higher-level code by having their own buffers and performing appropriate copying, that would be expensive in terms of both memory and cpu cycles. Instead the generic testing code will align any buffers passed to the device driver to the specified boundary. For example, if the driver requires that buffers be aligned to a word boundary then it should specify an alignment value of 4.

The device driver should provide an array of these structuresusbs_testing_endpoints[]. The USB testing codeexamines this array and uses the information to perform appropriatetests. Because different USB devices support different numbers ofendpoints the number of entries in the array is not known in advance,so instead the testing code looks for a special terminatorUSBS_TESTING_ENDPOINTS_TERMINATOR. An examplearray, showing just the control endpoint and the terminator, mightlook like this:

Note: The use of a single array usbs_testing_endpointslimits USB testing to platforms with a single USB device: if therewere multiple devices, each defining their own instance of this array,then there would a collision at link time. In practice this should notbe a major problem since typical USB peripherals only interact with asingle host machine via a single slave port. In addition, even if aperipheral did have multiple slave ports the current USB testing codewould not support this since it would not know which port to use.

PrevHomeNextData EndpointsUpTesting
-->

For certain Universal Serial Bus (USB) devices, such as devices that are accessed by only a single application, you can install WinUSB (Winusb.sys) in the device's kernel-mode stack as the USB device's function driver instead of implementing a driver.

This topic contains these sections:

Automatic installation of WinUSB without an INF file

As an OEM or independent hardware vendor (IHV), you can build your device so that the Winusb.sys gets installed automatically on Windows 8 and later versions of the operating system. Such a device is called a WinUSB device and does not require you to write a custom INF file that references in-box Winusb.inf.

When you connect a WinUSB device, the system reads device information and loads Winusb.sys automatically.

For more information, see WinUSB Device.

Installing WinUSB by specifying the system-provided device class

When you connect your device, you might notice that Windows loads Winusb.sys automatically (if the IHV has defined the device as a WinUSB Device). Otherwise follow these instructions to load the driver:

  1. Plug in your device to the host system.
  2. Open Device Manager and locate the device.
  3. Select and hold (or right-click) the device and select Update driver software... from the context menu.
  4. In the wizard, select Browse my computer for driver software.
  5. Select Let me pick from a list of device drivers on my computer.
  6. From the list of device classes, select Universal Serial Bus devices.
  7. The wizard displays WinUsb Device. Select it to load the driver.

If Universal Serial Bus devices does not appear in the list of device classes, then you need to install the driver by using a custom INF.The preceding procedure does not add a device interface GUID for an app (UWP app or Windows desktop app) to access the device. You must add the GUID manually by following this procedure.

  1. Load the driver as described in the preceding procedure.

  2. Generate a device interface GUID for your device, by using a tool such as guidgen.exe.

  3. Find the registry key for the device under this key:

    HKEY_LOCAL_MACHINESYSTEMCurrentControlSetEnumUSB<VID_vvvv&PID_pppp>

  4. Under the Device Parameters key, add a String registry entry named DeviceInterfaceGUID or a Multi-String entry named DeviceInterfaceGUIDs. Set the value to the GUID you generated in step 2.

  5. Disconnect the device from the system and reconnect it to the same physical port.Note If you change the physical port then you must repeat steps 1 through 4.

Writing a custom INF for WinUSB installation

As part of the driver package, you provide an .inf file that installs Winusb.sys as the function driver for the USB device.

The following example .inf file shows WinUSB installation for most USB devices with some modifications, such as changing USB_Install in section names to an appropriate DDInstall value. You should also change the version, manufacturer, and model sections as necessary. For example, provide an appropriate manufacture's name, the name of your signed catalog file, the correct device class, and the vendor identifier (VID) and product identifier (PID) for the device.

Also notice that the setup class is set to 'USBDevice'. Vendors can use the 'USBDevice' setup class for devices that do not belong to another class and are not USB host controllers or hubs.

If you are installing WinUSB as the function driver for one of the functions in a USB composite device, you must provide the hardware ID that is associated with the function, in the INF. You can obtain the hardware ID for the function from the properties of the devnode in Device Manager. The hardware ID string format is 'USBVID_vvvv&PID_pppp'.

The following INF installs WinUSB as the OSR USB FX2 board's function driver on a x64-based system.

Starting in Windows 10, version 1709, the Windows Driver Kit provides InfVerif.exe that you can use to test a driver INF file to make sure there are no syntax issues and the INF file is universal. We recommened that you provide a universal INF. For more information, see Using a Universal INF File.

Only include a ClassInstall32 section in a device INF file to install a new custom device setup class. INF files for devices in an installed class, whether a system-supplied device setup class or a custom class, must not include a ClassInstall32 section.

Except for device-specific values and several issues that are noted in the following list, you can use these sections and directives to install WinUSB for any USB device. These list items describe the Includes and Directives in the preceding .inf file.

  • USB_Install: The Include and Needs directives in the USB_Install section are required for installing WinUSB. You should not modify these directives.

  • USB_Install.Services: The Include directive in the USB_Install.Services section includes the system-supplied .inf for WinUSB (WinUSB.inf). This .inf file is installed by the WinUSB co-installer if it isn't already on the target system. The Needs directive specifies the section within WinUSB.inf that contains information required to install Winusb.sys as the device's function driver. You should not modify these directives.Note Because Windows XP doesn't provide WinUSB.inf, the file must either be copied to Windows XP systems by the co-installer, or you should provide a separate decorated section for Windows XP.

  • USB_Install.HW: This section is the key in the .inf file. It specifies the device interface globally unique identifier (GUID) for your device. The AddReg directive sets the specified interface GUID in a standard registry value. When Winusb.sys is loaded as the device's function driver, it reads the registry value DeviceInterfaceGUIDs key and uses the specified GUID to represent the device interface. You should replace the GUID in this example with one that you create specifically for your device. If the protocols for the device change, create a new device interface GUID.

    Note User-mode software must call SetupDiGetClassDevs to enumerate the registered device interfaces that are associated with one of the device interface classes specified under the DeviceInterfaceGUIDs key. SetupDiGetClassDevs returns the device handle for the device that the user-mode software must then pass to the WinUsb_Initialize routine to obtain a WinUSB handle for the device interface. For more info about these routines, see How to Access a USB Device by Using WinUSB Functions.

The following INF installs WinUSB as the OSR USB FX2 board's function driver on a x64-based system. The example shows INF with WDF coinstallers.

  • USB_Install.CoInstallers: This section, which includes the referenced AddReg and CopyFiles sections, contains data and instructions to install the WinUSB and KMDF co-installers and associate them with the device. Most USB devices can use these sections and directives without modification.

  • The x86-based and x64-based versions of Windows have separate co-installers.

    Note Each co-installer has free and checked versions. Use the free version to install WinUSB on free builds of Windows, including all retail versions. Use the checked version (with the '_chk' suffix) to install WinUSB on checked builds of Windows.

Each time Winusb.sys loads, it registers a device interface that has the device interface classes that are specified in the registry under the DeviceInterfaceGUIDs key.

Note If you use the redistributable WinUSB package for Windows XP or Windows Server 2003, make sure that you don't uninstall WinUSB in your uninstall packages. Other USB devices might be using WinUSB, so its binaries must remain in the shared folder.

Usb To Usb Cable Walmart

How to create a driver package that installs Winusb.sys

Usb A Vs Usb B

To use WinUSB as the device's function driver, you create a driver package. The driver package must contain these files:

  • WinUSB co-installer (Winusbcoinstaller.dll)
  • KMDF co-installer (WdfcoinstallerXXX.dll)
  • An .inf file that installs Winusb.sys as the device's function driver. For more information, see Writing an .Inf File for WinUSB Installation.
  • A signed catalog file for the package. This file is required to install WinUSB on x64 versions of Windows starting with Vista.

Note Make sure that the driver package contents meet these requirements:

Usb To Usb Extension Cable

  • The KMDF and WinUSB co-installer files must be obtained from the same version of the Windows Driver Kit (WDK).
  • The co-installer files must be obtained from the latest version of the WDK, so that the driver supports all the latest Windows releases.
  • The contents of the driver package must be digitally signed with a Winqual release signature. For more info about how to create and test signed catalog files, see Kernel-Mode Code Signing Walkthrough on the Windows Dev Center - Hardware site.
  1. Download the Windows Driver Kit (WDK) and install it.

  2. Create a driver package folder on the machine that the USB device is connected to. For example, c:UsbDevice.

  3. Copy the WinUSB co-installer (WinusbcoinstallerX.dll) from the WinDDKBuildNumberredistwinusb folder to the driver package folder.

    The WinUSB co-installer (Winusbcoinstaller.dll) installs WinUSB on the target system, if necessary. The WDK includes three versions of the co-installer depending on the system architecture: x86-based, x64-based, and Itanium-based systems. They are all named WinusbcoinstallerX.dll and are located in the appropriate subdirectory in the WinDDKBuildNumberredistwinusb folder.

  4. Copy the KMDF co-installer (WdfcoinstallerXXX.dll) from the WinDDKBuildNumberredistwdf folder to the driver package folder.

    The KMDF co-installer (WdfcoinstallerXXX.dll) installs the correct version of KMDF on the target system, if necessary. The version of WinUSB co-installer must match the KMDF co-installer because KMDF-based client drivers, such as Winusb.sys, require the corresponding version of the KMDF framework to be installed properly on the system. For example, Winusbcoinstaller2.dll requires KMDF version 1.9, which is installed by Wdfcoinstaller01009.dll. The x86 and x64 versions of WdfcoinstallerXXX.dll are included with the WDK under the WinDDKBuildNumberredistwdf folder. The following table shows the WinUSB co-installer and the associated KMDF co-installer to use on the target system.

    Use this table to determine the WinUSB co-installer and the associated KMDF co-installer.

    WinUSB co-installerKMDF library versionKMDF co-installer
    Winusbcoinstaller.dllRequires KMDF version 1.5 or later

    Wdfcoinstaller01005.dll

    Wdfcoinstaller01007.dll

    Wdfcoinstaller01009.dll

    Winusbcoinstaller2.dllRequires KMDF version 1.9 or laterWdfcoinstaller01009.dll
    Winusbcoinstaller2.dllRequires KMDF version 1.11 or laterWdfCoInstaller01011.dll
  5. Write an .inf file that installs Winusb.sys as the function driver for the USB device.

  6. Create a signed catalog file for the package. This file is required to install WinUSB on x64 versions of Windows.

  7. Attach the USB device to your computer.

  8. Open Device Manager to install the driver. Follow the instructions on the Update Driver Software wizard and choose manual installation. You will need to provide the location of the driver package folder to complete the installation.

Usb to usb cable walmart

Wideusb USB Devices Driver

Related topics

WinUSB Architecture and Modules
Choosing a driver model for developing a USB client driver
How to Access a USB Device by Using WinUSB Functions
WinUSB Power Management
WinUSB Functions for Pipe Policy Modification
WinUSB Functions
WinUSB