Re: [PATCH] Docs: usb: update struct usb_driver, __init and __exit
From: Jonathan Corbet <corbet@lwn.net>
Date: 2021-10-19 21:17:55
Also in:
linux-usb, lkml
Philipp Hortmann [off-list ref] writes:
update struct usb_driver from usb-skeleton.c. update __init and __exit functions that are moved from usb-skeleton.c to common used multi-stage macros. Signed-off-by: Philipp Hortmann <redacted> --- .../driver-api/usb/writing_usb_driver.rst | 51 +++++++------------ 1 file changed, 19 insertions(+), 32 deletions(-)
Adding linux-usb: this seems like a reasonable change (though see below), but the USB folks should have a chance to look it over too.
quoted hunk ↗ jump to hunk
diff --git a/Documentation/driver-api/usb/writing_usb_driver.rst b/Documentation/driver-api/usb/writing_usb_driver.rst index 2176297e5765..1064adf79ccb 100644 --- a/Documentation/driver-api/usb/writing_usb_driver.rst +++ b/Documentation/driver-api/usb/writing_usb_driver.rst@@ -54,12 +54,15 @@ information is passed to the USB subsystem in the :c:type:`usb_driver` structure. The skeleton driver declares a :c:type:`usb_driver` as:: static struct usb_driver skel_driver = { - .name = "skeleton", - .probe = skel_probe, - .disconnect = skel_disconnect, - .fops = &skel_fops, - .minor = USB_SKEL_MINOR_BASE, - .id_table = skel_table, + .name = "skeleton", + .probe = skel_probe, + .disconnect = skel_disconnect, + .suspend = skel_suspend, + .resume = skel_resume, + .pre_reset = skel_pre_reset, + .post_reset = skel_post_reset, + .id_table = skel_table, + .supports_autosuspend = 1, };@@ -81,36 +84,20 @@ this user-space interaction. The skeleton driver needs this kind of interface, so it provides a minor starting number and a pointer to its :c:type:`file_operations` functions. -The USB driver is then registered with a call to :c:func:`usb_register`, -usually in the driver's init function, as shown here:: - - static int __init usb_skel_init(void) - { - int result; - - /* register this driver with the USB subsystem */ - result = usb_register(&skel_driver); - if (result < 0) { - err("usb_register failed for the "__FILE__ "driver." - "Error number %d", result); - return -1; - } - - return 0; - } - module_init(usb_skel_init); - +The USB driver is then registered with a call to :c:func:`usb_register`
We shouldn't be using :c:func: anymore; just say usb_register() and the right things will happen. Definitely worth fixing while you are in the neighborhood.
+which is usually in the driver's init function. Since this functionality +is usable with many USB drivers, it is hidden behind multi-stage macros. +While the first macros are USB specific the later macros are used in different +subsystems. This removes a lot of boilerplate code. When the driver is unloaded from the system, it needs to deregister itself with the USB subsystem. This is done with the :c:func:`usb_deregister` -function:: +which is also hidden behind multi-stage macros.
If you're making this change, take out "the" (as well as :c:func:).
- static void __exit usb_skel_exit(void)
- {
- /* deregister this driver with the USB subsystem */
- usb_deregister(&skel_driver);
- }
- module_exit(usb_skel_exit);
+The init and exit functions are included in the macro :
+module_usb_driver(skel_driver);
+which is in the first stage replaced by:
+module_driver(__usb_driver, usb_register, usb_deregister)This will not render the way you want; consider using literal blocks here. Thanks, jon