Usb kernel driver example

To find the physical connector, plug any USB 3. Refresh UsbView to see where your device is located. Before using bcdedit to change boot information you may need to temporarily suspend Windows security features such as BitLocker and Secure Boot on the test PC.

Note that TargetName does not have to be the official name of the target computer; it can be any string that you create as long as it meets these restrictions:. Under Location on the General tab, the bus, device, and function numbers are displayed. Enter this command:. The bus, device, and function numbers must be in decimal format.

In some cases, power transitions can interfere with debugging over USB 3. To avoid these problems, disable selective suspend for the xHCI host controller and its root hub that you are using for debugging. Right click the node, and choose Properties. If there is a Power Management tab, open the tab, and clear the Allow the computer to turn off this device to save power check box. When you have finished using the xHCI host controller for debugging, re-enable selective suspend for the xHCI host controller.

At this point, the USB debug driver gets installed on the host computer. This is why it is important to match the bitness of WinDbg to the bitness of Windows. After the USB debug driver is installed, you can use either the bit or bit version of WinDbg for subsequent debugging sessions. On the host computer, open WinDbg.

On the File menu, choose Kernel Debug. This is valid only for interrupt or isochronous urbs. For low-speed and full-speed devices, the units are frames, which are equivalent to milliseconds.

Valid only for isochronous urbs and specifies the number of isochronous transfer buffers to be handled by this urb. Set by the USB core only for isochronous urbs after their completion. It specifies the number of isochronous transfers that reported any type of error.

Valid only for isochronous urbs. This structure allows a single urb to define a number of isochronous transfers at once. It is also used to collect the transfer status of each individual transfer. The length of the data received into the transfer buffer for this isochronous packet. The status of the individual isochronous transfer of this packet.

The struct urb structure must never be created statically in a driver or within another structure, because that would break the reference counting scheme used by the USB core for urbs.

This function has the prototype:. If you do not want to create an isochronous urb, this variable should be set to 0. If the function is successful in allocating enough space for the urb, a pointer to the urb is returned to the caller. After a urb has been created, it must be properly initialized before it can be used by the USB core. See the next sections for how to initialize different types of urbs. This function only has one argument:. The argument is a pointer to the struct urb you want to release.

After this function is called, the urb structure is gone, and the driver cannot access it any more. The specific endpoint of the USB device to which this urb is to be sent. A pointer to the buffer from which outgoing data is taken or into which incoming data is received.

Note that this can not be a static buffer and must be created with a call to kmalloc. Pointer to the blob that is added to the urb structure for later retrieval by the completion handler function. The interval at which that this urb should be scheduled. See the previous description of the struct urb structure to find the proper units for this value.

Bulk urbs are initialized much like interrupt urbs. However, there is no interval parameter because bulk urbs have no interval value. Most drivers do not use this function, as it is much simpler to use the synchronous API calls as described in Section Isochronous urbs unfortunately do not have an initializer function like the interrupt, control, and bulk urbs do. The following is an example of how to properly initialize this type of urb. It was taken from the konicawc.

The urb parameter is a pointer to the urb that is to be sent to the device. After a urb has been submitted to the USB core successfully, it should never try to access any fields of the urb structure until the complete function is called.

The caller is within a urb completion handler, an interrupt, a bottom half, a tasklet, or a timer callback. The caller is holding a spinlock or rwlock. Note that if a semaphore is being held, this value is not necessary. It should also be used in the error handling path of all storage-type devices. This should be used for all other situations that do not fall into one of the previously mentioned categories.

If the function succeeds, the completion handler of the urb as specified by the complete function pointer is called exactly once when the urb is completed. When this function is called, the USB core is finished with the URB, and control of it is now returned to the device driver. There are only three ways a urb can be finished and have the complete function called:.

The urb is successfully sent to the device, and the device returns the proper acknowledgment. For an OUT urb, the data was successfully sent, and for an IN urb, the requested data was successfully received. If this has happened, the status variable in the urb is set to 0. Some kind of error happened when sending or receiving data from the device.

This is noted by the error value in the status variable in the urb structure. An example of how to test for the different return values within a urb completion call is shown later in this chapter.

The urb parameter for both of these functions is a pointer to the urb that is to be canceled. This function is usually used when the device is disconnected from the system, in the disconnect callback. This function does not wait for the urb to be fully stopped before returning to the caller.

This is useful for stopping the urb while in an interrupt handler or when a spinlock is held, as waiting for a urb to fully stop requires the ability for the USB core to put the calling process to sleep. This list is used by the USB core to decide which driver to give a device to, and by the hotplug scripts to decide which driver to automatically load when a specific device is plugged into the system.

Determines which of the following fields in the structure the device should be matched against. This number is assigned by the USB forum to its members and cannot be made up by anyone else. All vendors that have a vendor ID assigned to them can manage their product IDs however they choose to.

Define the low and high ends of the range of the vendor-assigned product version number. Both of these values are expressed in binary-coded decimal BCD form. These variables, combined with the idVendor and idProduct , are used to define a specific version of a device.

Define the class, subclass, and protocol of the device, respectively. These values specify the behavior for the whole device, including all interfaces on this device. Much like the device-specific values above, these define the class, subclass, and protocol of the individual interface, respectively.

This value is not used to match against, but it holds information that the driver can use to differentiate the different devices from each other in the probe callback function to the USB driver. As with PCI devices, there are a number of macros that are used to initialize this structure:. This is very commonly used for USB devices that need a specific driver. But for USB drivers, the string usb must be the first value in the macro. Pointer to the module owner of this driver.

Pointer to the name of the driver. It must be unique among all USB drivers in the kernel and is normally set to the same name as the module name of the driver. If this variable is not set, the probe function callback in the USB driver is never called. Pointer to the probe function in the USB driver. This function described in Section If the driver does not want to claim the device, or an error occurs, it should return a negative error value. Pointer to the disconnect function in the USB driver.

Pointer to an ioctl function in the USB driver. If it is present, it is called when a user-space program makes a ioctl call on the usbfs filesystem device entry associated with a USB device attached to this USB driver. In pratice, only the USB hub driver uses this ioctl, as there is no other real need for any other USB driver to use it. Pointer to a suspend function in the USB driver. It is called when the device is to be suspended by the USB core. Pointer to a resume function in the USB driver.

It is called when the device is being resumed by the USB core. This is traditionally done in the module initialization code for the USB driver:. When this call happens, any USB interfaces that were currently bound to this driver are disconnected, and the disconnect function is called for them.

The probe function is called when a device is installed that the USB core thinks this driver should handle; the probe function should perform checks on the information passed to it about the device and decide whether the driver is really appropriate for that device. The disconnect function is called when the driver should no longer control the device for some reason and can do clean-up. Both the probe and disconnect function callbacks are called in the context of the USB hub kernel thread, so it is legal to sleep within them.

However, it is recommended that the majority of work be done when the device is opened by a user if possible, in order to keep the USB probing time to a minimum. This is because the USB core handles the addition and removal of USB devices within a single thread, so any slow device driver can cause the USB device detection time to slow down and become noticeable by the user.

In the probe function callback, the USB driver should initialize any local structures that it might use to manage the USB device.

It should also save any information that it needs about the device to the local structure, as it is usually easier to do so at this time. As an example, USB drivers usually want to detect what the endpoint address and buffer sizes are for the device, as they are needed in order to communicate with the device. This block of code first loops over every endpoint that is present in this interface and assigns a local pointer to the endpoint structure to make it easier to access later:.

If all of these tests are true, the driver knows it found the proper type of endpoint and can save the information about the endpoint that it will later need to communicate over it in a local structure:. Thanks to these two functions, USB drivers do not need to keep a static array of pointers that store the individual device structures for all current devices in the system. The indirect reference to device information allows an unlimited number of devices to be supported by any USB driver.

If the USB driver is not associated with another type of subsystem that handles the user interaction with the device such as input, tty, video, etc. Make sure that the device and driver are in a proper state to handle a user wanting to access the device as soon as this function is called. This structure consists of the following variables:.

The name that sysfs uses to describe the device. A leading pathname, if present, is used only in devfs and is not covered in this book. See Chapter 3 for more information about this structure.

The mode for the devfs file to be created for this driver; unused otherwise. This is the start of the assigned minor range for this driver. All devices associated with this driver are created with unique, increasing minor numbers beginning with this value. If so, this variable is ignored, and all minor numbers for the device are allocated on a first-come, first-served manner. When the USB device is disconnected, all resources associated with the device should be cleaned up, if possible.

This takes the big kernel lock, so that the disconnect callback does not encounter a race condition with the open call when trying to get a pointer to the correct interface data structure. Because the open is called with the big kernel lock taken, if the disconnect also takes that same lock, only one portion of the driver can access and then set the interface data pointer. After the urb is allocated successfully, a DMA buffer should also be created to send the data to the device in the most efficient manner, and the data that is passed to the driver should be copied into that buffer:.

Once the data is properly copied from the user space into the local buffer, the urb must be initialized correctly before it can be submitted to the USB core:. Now that the urb is properly allocated, the data is properly copied, and the urb is properly initialized, it can be submitted to the USB core to be transmitted to the device:. After the urb is successfully transmitted to the USB device or something happens in transmission , the urb callback is called by the USB core.

The first thing the callback function does is check the status of the urb to determine if this urb completed successfully or not. See the list of possible errors for urbs detailed in the section Section Then the callback frees up the allocated buffer that was assigned to this urb to transmit. When a device is plugged into the USB bus that matches the device ID pattern that your driver registered with the USB core, the probe function is called.

The driver now needs to verify that this device is actually accepted or not. If it is accepted, it returns 0. When a device is plugged out or removed, this function will be getting called. As of now, we have finished the basic kinds of stuff. We have completed all the things. It is just simple. Refer to the below example. Is that all? Yes if you use the kernel older than 3. But if you are using the latest Linux kernel which is greater than 3.

This is the helper macro for registering a USB driver. This eliminates a lot of boilerplate. We have written some very basic USB device drivers which will just print the Interface descriptor and Endpoint descriptor while inserting the device.

If you set 0, then it will use the old method. If you set 1 or non-zero value, it will use the new method. This information may help to filter the system log for messages, belonging to the concrete device. Just go through the code below.