diff options
author | Linus Torvalds <torvalds@linux-foundation.org> | 2017-05-02 20:21:17 +0300 |
---|---|---|
committer | Linus Torvalds <torvalds@linux-foundation.org> | 2017-05-02 20:21:17 +0300 |
commit | c58d4055c054fc6dc72f1be8bc71bd6fff209e48 (patch) | |
tree | 56527e28fc65d74d6d5e8397c502ccc87a9ec99b /Documentation/usb/callbacks.txt | |
parent | ceb198bb007b84ead867e87a71ffe715c4412b15 (diff) | |
parent | 9bb0e9cb04c82d6bf0e72f3207307d621083b801 (diff) | |
download | linux-c58d4055c054fc6dc72f1be8bc71bd6fff209e48.tar.xz |
Merge tag 'docs-4.12' of git://git.lwn.net/linux
Pull documentation update from Jonathan Corbet:
"A reasonably busy cycle for documentation this time around. There is a
new guide for user-space API documents, rather sparsely populated at
the moment, but it's a start. Markus improved the infrastructure for
converting diagrams. Mauro has converted much of the USB documentation
over to RST. Plus the usual set of fixes, improvements, and tweaks.
There's a bit more than the usual amount of reaching out of
Documentation/ to fix comments elsewhere in the tree; I have acks for
those where I could get them"
* tag 'docs-4.12' of git://git.lwn.net/linux: (74 commits)
docs: Fix a couple typos
docs: Fix a spelling error in vfio-mediated-device.txt
docs: Fix a spelling error in ioctl-number.txt
MAINTAINERS: update file entry for HSI subsystem
Documentation: allow installing man pages to a user defined directory
Doc/PM: Sync with intel_powerclamp code behavior
zr364xx.rst: usb/devices is now at /sys/kernel/debug/
usb.rst: move documentation from proc_usb_info.txt to USB ReST book
convert philips.txt to ReST and add to media docs
docs-rst: usb: update old usbfs-related documentation
arm: Documentation: update a path name
docs: process/4.Coding.rst: Fix a couple of document refs
docs-rst: fix usb cross-references
usb: gadget.h: be consistent at kernel doc macros
usb: composite.h: fix two warnings when building docs
usb: get rid of some ReST doc build errors
usb.rst: get rid of some Sphinx errors
usb/URB.txt: convert to ReST and update it
usb/persist.txt: convert to ReST and add to driver-api book
usb/hotplug.txt: convert to ReST and add to driver-api book
...
Diffstat (limited to 'Documentation/usb/callbacks.txt')
-rw-r--r-- | Documentation/usb/callbacks.txt | 134 |
1 files changed, 0 insertions, 134 deletions
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. |