[PATCH] Docs: usb: update struct usb_driver, __init and __exit

[PATCH] Docs: usb: update struct usb_driver, __init and __exit

[Philipp Hortmann]

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 <philipp.g.hortmann@gmail.com>
---
 .../driver-api/usb/writing_usb_driver.rst     | 51 +++++++------------
 1 file changed, 19 insertions(+), 32 deletions(-)

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`
+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.
 
-    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)
 
 
 To enable the linux-hotplug system to load the driver automatically when
-- 
2.25.1

Re: [PATCH] Docs: usb: update struct usb_driver, __init and __exit

[Jonathan Corbet]

Philipp Hortmann <philipp.g.hortmann@gmail.com> 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 <philipp.g.hortmann@gmail.com>
> ---
>  .../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.

> 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