From: Mauro Carvalho Chehab Date: Wed, 5 Apr 2017 13:23:04 +0000 (-0300) Subject: usb/callbacks.txt: convert to ReST and add to driver-api book X-Git-Url: https://git.stricted.de/?a=commitdiff_plain;h=3b38e4f21868d83ed03d5d101c789c4df2b08e8b;p=GitHub%2Fmoto-9609%2Fandroid_kernel_motorola_exynos9610.git usb/callbacks.txt: convert to ReST and add to driver-api book This document describe some USB core functions. Add it to the driver-api book. Signed-off-by: Mauro Carvalho Chehab Acked-by: Greg Kroah-Hartman Signed-off-by: Jonathan Corbet --- diff --git a/Documentation/driver-api/usb/callbacks.rst b/Documentation/driver-api/usb/callbacks.rst new file mode 100644 index 000000000000..93a8d53e27e7 --- /dev/null +++ b/Documentation/driver-api/usb/callbacks.rst @@ -0,0 +1,157 @@ +USB core callbacks +~~~~~~~~~~~~~~~~~~ + +What callbacks will usbcore do? +=============================== + +Usbcore will call into a driver through callbacks defined in the driver +structure and through the completion handler of URBs a driver submits. +Only the former are in the scope of this document. These two kinds of +callbacks are completely independent of each other. Information on the +completion callback can be found in Documentation/usb/URB.txt. + +The callbacks defined in the driver structure are: + +1. Hotplugging callbacks: + + - @probe: + Called to see if the driver is willing to manage a particular + interface on a device. + + - @disconnect: + Called when the interface is no longer accessible, usually + because its device has been (or is being) disconnected or the + driver module is being unloaded. + +2. Odd backdoor through usbfs: + + - @ioctl: + Used for drivers that want to talk to userspace through + the "usbfs" filesystem. This lets devices provide ways to + expose information to user space regardless of where they + do (or don't) show up otherwise in the filesystem. + +3. Power management (PM) callbacks: + + - @suspend: + Called when the device is going to be suspended. + + - @resume: + Called when the device is being resumed. + + - @reset_resume: + Called when the suspended device has been reset instead + of being resumed. + +4. Device level operations: + + - @pre_reset: + Called when the device is about to be reset. + + - @post_reset: + Called after the device has been reset + +The ioctl interface (2) should be used only if you have a very good +reason. Sysfs is preferred these days. The PM callbacks are covered +separately in Documentation/usb/power-management.txt. + +Calling conventions +=================== + +All callbacks are mutually exclusive. There's no need for locking +against other USB callbacks. All callbacks are called from a task +context. You may sleep. However, it is important that all sleeps have a +small fixed upper limit in time. In particular you must not call out to +user space and await results. + +Hotplugging callbacks +===================== + +These callbacks are intended to associate and disassociate a driver with +an interface. A driver's bond to an interface is exclusive. + +The probe() callback +-------------------- + +:: + + int (*probe) (struct usb_interface *intf, + const struct usb_device_id *id); + +Accept or decline an interface. If you accept the device return 0, +otherwise -ENODEV or -ENXIO. Other error codes should be used only if a +genuine error occurred during initialisation which prevented a driver +from accepting a device that would else have been accepted. +You are strongly encouraged to use usbcore's facility, +usb_set_intfdata(), to associate a data structure with an interface, so +that you know which internal state and identity you associate with a +particular interface. The device will not be suspended and you may do IO +to the interface you are called for and endpoint 0 of the device. Device +initialisation that doesn't take too long is a good idea here. + +The disconnect() callback +------------------------- + +:: + + void (*disconnect) (struct usb_interface *intf); + +This callback is a signal to break any connection with an interface. +You are not allowed any IO to a device after returning from this +callback. You also may not do any other operation that may interfere +with another driver bound the interface, eg. a power management +operation. +If you are called due to a physical disconnection, all your URBs will be +killed by usbcore. Note that in this case disconnect will be called some +time after the physical disconnection. Thus your driver must be prepared +to deal with failing IO even prior to the callback. + +Device level callbacks +====================== + +pre_reset +--------- + +:: + + int (*pre_reset)(struct usb_interface *intf); + +A driver or user space is triggering a reset on the device which +contains the interface passed as an argument. Cease IO, wait for all +outstanding URBs to complete, and save any device state you need to +restore. No more URBs may be submitted until the post_reset method +is called. + +If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you +are in atomic context. + +post_reset +---------- + +:: + + int (*post_reset)(struct usb_interface *intf); + +The reset has completed. Restore any saved device state and begin +using the device again. + +If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you +are in atomic context. + +Call sequences +============== + +No callbacks other than probe will be invoked for an interface +that isn't bound to your driver. + +Probe will never be called for an interface bound to a driver. +Hence following a successful probe, disconnect will be called +before there is another probe for the same interface. + +Once your driver is bound to an interface, disconnect can be +called at any time except in between pre_reset and post_reset. +pre_reset is always followed by post_reset, even if the reset +failed or the device has been unplugged. + +suspend is always followed by one of: resume, reset_resume, or +disconnect. diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst index 6fe7611f7332..441c5dacdf27 100644 --- a/Documentation/driver-api/usb/index.rst +++ b/Documentation/driver-api/usb/index.rst @@ -8,6 +8,7 @@ Linux USB API gadget anchors bulk-streams + callbacks writing_usb_driver writing_musb_glue_layer diff --git a/Documentation/usb/callbacks.txt b/Documentation/usb/callbacks.txt deleted file mode 100644 index 9e85846bdb98..000000000000 --- a/Documentation/usb/callbacks.txt +++ /dev/null @@ -1,134 +0,0 @@ -What callbacks will usbcore do? -=============================== - -Usbcore will call into a driver through callbacks defined in the driver -structure and through the completion handler of URBs a driver submits. -Only the former are in the scope of this document. These two kinds of -callbacks are completely independent of each other. Information on the -completion callback can be found in Documentation/usb/URB.txt. - -The callbacks defined in the driver structure are: - -1. Hotplugging callbacks: - - * @probe: Called to see if the driver is willing to manage a particular - * interface on a device. - * @disconnect: Called when the interface is no longer accessible, usually - * because its device has been (or is being) disconnected or the - * driver module is being unloaded. - -2. Odd backdoor through usbfs: - - * @ioctl: Used for drivers that want to talk to userspace through - * the "usbfs" filesystem. This lets devices provide ways to - * expose information to user space regardless of where they - * do (or don't) show up otherwise in the filesystem. - -3. Power management (PM) callbacks: - - * @suspend: Called when the device is going to be suspended. - * @resume: Called when the device is being resumed. - * @reset_resume: Called when the suspended device has been reset instead - * of being resumed. - -4. Device level operations: - - * @pre_reset: Called when the device is about to be reset. - * @post_reset: Called after the device has been reset - -The ioctl interface (2) should be used only if you have a very good -reason. Sysfs is preferred these days. The PM callbacks are covered -separately in Documentation/usb/power-management.txt. - -Calling conventions -=================== - -All callbacks are mutually exclusive. There's no need for locking -against other USB callbacks. All callbacks are called from a task -context. You may sleep. However, it is important that all sleeps have a -small fixed upper limit in time. In particular you must not call out to -user space and await results. - -Hotplugging callbacks -===================== - -These callbacks are intended to associate and disassociate a driver with -an interface. A driver's bond to an interface is exclusive. - -The probe() callback --------------------- - -int (*probe) (struct usb_interface *intf, - const struct usb_device_id *id); - -Accept or decline an interface. If you accept the device return 0, -otherwise -ENODEV or -ENXIO. Other error codes should be used only if a -genuine error occurred during initialisation which prevented a driver -from accepting a device that would else have been accepted. -You are strongly encouraged to use usbcore's facility, -usb_set_intfdata(), to associate a data structure with an interface, so -that you know which internal state and identity you associate with a -particular interface. The device will not be suspended and you may do IO -to the interface you are called for and endpoint 0 of the device. Device -initialisation that doesn't take too long is a good idea here. - -The disconnect() callback -------------------------- - -void (*disconnect) (struct usb_interface *intf); - -This callback is a signal to break any connection with an interface. -You are not allowed any IO to a device after returning from this -callback. You also may not do any other operation that may interfere -with another driver bound the interface, eg. a power management -operation. -If you are called due to a physical disconnection, all your URBs will be -killed by usbcore. Note that in this case disconnect will be called some -time after the physical disconnection. Thus your driver must be prepared -to deal with failing IO even prior to the callback. - -Device level callbacks -====================== - -pre_reset ---------- - -int (*pre_reset)(struct usb_interface *intf); - -A driver or user space is triggering a reset on the device which -contains the interface passed as an argument. Cease IO, wait for all -outstanding URBs to complete, and save any device state you need to -restore. No more URBs may be submitted until the post_reset method -is called. - -If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you -are in atomic context. - -post_reset ----------- - -int (*post_reset)(struct usb_interface *intf); - -The reset has completed. Restore any saved device state and begin -using the device again. - -If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you -are in atomic context. - -Call sequences -============== - -No callbacks other than probe will be invoked for an interface -that isn't bound to your driver. - -Probe will never be called for an interface bound to a driver. -Hence following a successful probe, disconnect will be called -before there is another probe for the same interface. - -Once your driver is bound to an interface, disconnect can be -called at any time except in between pre_reset and post_reset. -pre_reset is always followed by post_reset, even if the reset -failed or the device has been unplugged. - -suspend is always followed by one of: resume, reset_resume, or -disconnect.