GNU/Linux & USB - Hello World Linux HID device driver

Welcome to a new episode of my series about GNU/Linux and USB. In my previous videos, I already showed you how we can convert this Raspberry Pi Pico to an HID device by using tinyUSB and how to access the USB device from a host from user space by using the HID raw API. So, now it's time to leave the user space and head into kernel space. And in today's video, I will show you how we can write the hello world HID device driver for our tinyUSB device running on this Raspberry Pi Pico. So, let's go. I will develop this on my Raspberry Pi here, but of course, you can also implement this on any other PC. Nevertheless, if it's x86 or ARM architecture, it should work on any GNU/Linux system with USB support. Okay, so first let's take a look at the connected USB devices, and you can see this device here with the vendor ID coffee and the product ID 4004 is our tinyUSB device. Our tinyUSB HID device. And for this device, we want to write the driver. The cool thing about USB is every device is or can be identified over its unique combination of a product and a vendor ID. So, all these combinations are unique for one type of device. And this is what we need in the driver to recognize it.

Okay, so let me navigate into my programming folder and let's create a folder. I will call tinyUSB HID tinyUSB.

And in here, I want to implement my driver. So, the name of the driver should be also HID tinyUSB.c.

And in this file, I will implement my driver. And now, let's go through the steps which are required to write any Linux device driver, nevertheless if it's for an HID device or for a PCI Express device or an I2C device, it doesn't matter. These steps are always the same. So, the first thing we have to do is we have to name the compatible devices which are supported by the driver.

Then, we have to implement a probe and a remove function. The probe function is called when we are adding a compatible device to the system. The remove function is called if you're removing a compatible device from the system.

And at the end, we need to bundle all the information, the compatible devices, the probe, the remove function, some other information like a driver's name and a driver struct, and then we need to register this driver at the operating system. And these are all the steps which are required to write a Linux device driver.

So, now let's take a look how we can implement these steps for our USB HID device.

First thing I need to do is I need to add some includes, and here I will include the kernel header HID.c.

Then, let's declare our TinyUSB HID product vendor ID, which was coffee, and the product ID, which was 4004.

Okay. And now, we need to add all the compatible devices. Therefore, I will use a list from the type struct HID device ID, and I will call this HID or TinyUSB HID IDs. And important, this is a link because a driver can be compatible with more than just with one device. And the first element here, I will create a valid entry with the macro HID_USB_device, TinyUSB vendor ID, TinyUSB product ID.

Okay. And then at the end I always need to add an empty element which tells the Linux kernel, "Okay, now I have reached the end of the list." And then I will use the macro module device table to add our new compatible list to the list of all HID devices. So, for us, we are only building a standalone Linux kernel module, this would not be necessary, but if you're compiling the module together with your kernel, at the end you will get a list which tells the kernel where to find a driver for a device. When the device is detected by the system, the kernel can automatically load the correct driver. And that's what this macro is for.

Okay, so the first step is complete. We have declared all the compatible devices. Next step is to add a probe and a remove function.

So, let's start with the probe function, which I will call tiny USB HID probe.

The probe function has two arguments. The first one is from the type HID device and I will call it H dev, and the second argument is a pointer from the type HID device ID. I will call it IDs. And this pointer points to the compatible device in this compatible device table. So, in our case, we just have one compatible device, so this pointer will always point to this entry here. But if we would have multiple devices, the pointer will point to the corresponding compatible device for which the probe function was called. And the cool thing is here, we could also add some device-specific data, and this data can be retrieved over this pointer. That's the whole reason why we are passing this pointer to this struct here. But I won't use it.

And as a return value, we have an integer because normally in the probe function, we are allocating resources and interrupts which could go wrong. So in case an error occurred, we want to return a negative error code which tells the user space what happened or what went wrong. And when we are returning zero, we're indicating okay, probing was successful.

And all I will do in the probe function is I will print one line to the kernel's log with the function dev_info. The first argument is a pointer to our struct device which is in the staff field of the HID device struct. And the second argument is what we want to print out.

Device is probed. Okay, yep, and that's basically it. Okay, the next thing we need to do is we need to implement the remove function.

The remove function has no return value because in the remove function, we're only freeing resources. There is nothing that can go wrong.

And one argument which is also pointer to our HID device. And in here, let's also just print one line to the kernel's log.

Device is removed. Okay. So now we have implemented the probe and the remove functions and we have our compatible devices. Now we have to bundle this information in the driver struct. Herefore, let's declare a struct from the type variable from the type struct HID driver. And in here, we can bundle the information. So we can give it a name.

We can, we have to pass the pointer to the list with compatible devices. We have to pass a pointer to the probe function.

And we have a pointer, we have to pass a pointer to the remove function.

And this way we are bundling all the driver's data in this driver struct here.

Okay. And now the last step is we need to register the driver. This can be done with the macro module HID driver and we have to pass the driver for which we want to, or which we want to register to it.

Yeah. And now we would be almost done. The last thing is we need to add a license and some additional meta information to this module.

So, the author will be me. And let's also pass a description. Hello world Linux HID device driver for tiny USB HID device.

Okay. Good. And this should be the driver for a hello world HID device driver.

Next thing I need is I need to write a makefile, but here I'm lazy and I will copy one over from my Linux driver tutorials folder.

And I will adapt it so it will compile my tiny USB HID or HID tiny tiny USB device or driver. Okay. So, let's see if I can compile the driver or if I made some mistakes.

Yep, this of course should be a header file, not a C file. HID. So, let's fix this.

Ah. But now we should be able to compile this module. Yep, it's looking good.

So, let me fire up tmux to spawn a second terminal in which we will follow the kernel's log. And then let's load our driver.

So, the driver is loaded and we can see TinyUSB HID device is probed. And now when I go here and when I'm disconnecting the device, we can see the remove function is called. If we're connecting the device again, the probe function will be called again. And now let's unload the module. And if we're unloading the module, the remove function is called again. And this is also interesting, you can see now an HID raw device is created for this device because an HID raw device is only created if for the device there is no corresponding driver, which is the case when we're removing the driver.

Ok.

Uh device is removed. Okay. So now we have implemented the probe and the remove functions and we have our compatible devices. Now we have to bundle this information in the driver struct. Herefore, let's declare a struct from the type uh uh

variable from the type struct HID driver. And in here, we can bundle the information. So we can give it a name.

We can we have to pass the pointer to the list with compatible devices. We can We have to pass a pointer to the probe function.

And we have a pointer We have to pass a pointer to the remove function.

And this way we are bundling all the drivers data in this driver struct here.

Okay. And now the last step is we need to register the driver. This can be done with the macro module HID driver and we have to pass the driver for which we want to or which we want to register to it.

Yeah. And now we would be almost done. The last thing is we need to add a license and some additional meta information to this module.

So, the author will be me. And let's also pass a description. Hello world Linux HID device driver for tiny USB HID device.

Okay. Good. And this should be the driver for a hello world um HID device driver.

Next thing I need is I need to write a make file, but here I'm lazy and I will copy one over from my Linux driver tutorials folder.

And I will adapt it so it will compile my tiny USB HID or HID tiny tiny USB device or driver. Okay. So, let's see if I can compile the driver or if I made some mistakes.

Yep, this of course should be a header file, not a C file. Um HID So, let's fix this.

Ah. But now we should be able to compile this module. Yep, it's looking good.

So, let me fire up tmux to spawn a second terminal in which we will follow the kernel's log. And then let's load our driver.

So, the driver is loaded and we can see Tinus BHID device is probed. And now when I go here and when I'm disconnecting the device, we can see the remove function is called. If we're connecting the device again,

the probe function will be called again. And now let's unload the module. And if we're unloading the module, the remove function is called again. And this is also interesting, you can see now an HID raw device is created for

this device because an HID raw device is only created if for the um device there is no corresponding driver, which is the case when we're removing the driver.

Okay, cool. So, that's how to implement the Hello World HID device driver for Linux. I hope you've enjoyed the video and learned something. In case you want to support my work, you can buy me a coffee on buymeacoffee.com/linuxforlinux.

So, thanks for watching and goodbye.