| 1 | USB core callbacks
|
| 2 | ~~~~~~~~~~~~~~~~~~
|
| 3 |
|
| 4 | What callbacks will usbcore do?
|
| 5 | ===============================
|
| 6 |
|
| 7 | Usbcore will call into a driver through callbacks defined in the driver
|
| 8 | structure and through the completion handler of URBs a driver submits.
|
| 9 | Only the former are in the scope of this document. These two kinds of
|
| 10 | callbacks are completely independent of each other. Information on the
|
| 11 | completion callback can be found in :ref:`usb-urb`.
|
| 12 |
|
| 13 | The callbacks defined in the driver structure are:
|
| 14 |
|
| 15 | 1. Hotplugging callbacks:
|
| 16 |
|
| 17 | - @probe:
|
| 18 | Called to see if the driver is willing to manage a particular
|
| 19 | interface on a device.
|
| 20 |
|
| 21 | - @disconnect:
|
| 22 | Called when the interface is no longer accessible, usually
|
| 23 | because its device has been (or is being) disconnected or the
|
| 24 | driver module is being unloaded.
|
| 25 |
|
| 26 | 2. Odd backdoor through usbfs:
|
| 27 |
|
| 28 | - @ioctl:
|
| 29 | Used for drivers that want to talk to userspace through
|
| 30 | the "usbfs" filesystem. This lets devices provide ways to
|
| 31 | expose information to user space regardless of where they
|
| 32 | do (or don't) show up otherwise in the filesystem.
|
| 33 |
|
| 34 | 3. Power management (PM) callbacks:
|
| 35 |
|
| 36 | - @suspend:
|
| 37 | Called when the device is going to be suspended.
|
| 38 |
|
| 39 | - @resume:
|
| 40 | Called when the device is being resumed.
|
| 41 |
|
| 42 | - @reset_resume:
|
| 43 | Called when the suspended device has been reset instead
|
| 44 | of being resumed.
|
| 45 |
|
| 46 | 4. Device level operations:
|
| 47 |
|
| 48 | - @pre_reset:
|
| 49 | Called when the device is about to be reset.
|
| 50 |
|
| 51 | - @post_reset:
|
| 52 | Called after the device has been reset
|
| 53 |
|
| 54 | The ioctl interface (2) should be used only if you have a very good
|
| 55 | reason. Sysfs is preferred these days. The PM callbacks are covered
|
| 56 | separately in :ref:`usb-power-management`.
|
| 57 |
|
| 58 | Calling conventions
|
| 59 | ===================
|
| 60 |
|
| 61 | All callbacks are mutually exclusive. There's no need for locking
|
| 62 | against other USB callbacks. All callbacks are called from a task
|
| 63 | context. You may sleep. However, it is important that all sleeps have a
|
| 64 | small fixed upper limit in time. In particular you must not call out to
|
| 65 | user space and await results.
|
| 66 |
|
| 67 | Hotplugging callbacks
|
| 68 | =====================
|
| 69 |
|
| 70 | These callbacks are intended to associate and disassociate a driver with
|
| 71 | an interface. A driver's bond to an interface is exclusive.
|
| 72 |
|
| 73 | The probe() callback
|
| 74 | --------------------
|
| 75 |
|
| 76 | ::
|
| 77 |
|
| 78 | int (*probe) (struct usb_interface *intf,
|
| 79 | const struct usb_device_id *id);
|
| 80 |
|
| 81 | Accept or decline an interface. If you accept the device return 0,
|
| 82 | otherwise -ENODEV or -ENXIO. Other error codes should be used only if a
|
| 83 | genuine error occurred during initialisation which prevented a driver
|
| 84 | from accepting a device that would else have been accepted.
|
| 85 | You are strongly encouraged to use usbcore's facility,
|
| 86 | usb_set_intfdata(), to associate a data structure with an interface, so
|
| 87 | that you know which internal state and identity you associate with a
|
| 88 | particular interface. The device will not be suspended and you may do IO
|
| 89 | to the interface you are called for and endpoint 0 of the device. Device
|
| 90 | initialisation that doesn't take too long is a good idea here.
|
| 91 |
|
| 92 | The disconnect() callback
|
| 93 | -------------------------
|
| 94 |
|
| 95 | ::
|
| 96 |
|
| 97 | void (*disconnect) (struct usb_interface *intf);
|
| 98 |
|
| 99 | This callback is a signal to break any connection with an interface.
|
| 100 | You are not allowed any IO to a device after returning from this
|
| 101 | callback. You also may not do any other operation that may interfere
|
| 102 | with another driver bound to the interface, eg. a power management
|
| 103 | operation. Outstanding operations on the device must be completed or
|
| 104 | aborted before this callback may return.
|
| 105 |
|
| 106 | If you are called due to a physical disconnection, all your URBs will be
|
| 107 | killed by usbcore. Note that in this case disconnect will be called some
|
| 108 | time after the physical disconnection. Thus your driver must be prepared
|
| 109 | to deal with failing IO even prior to the callback.
|
| 110 |
|
| 111 | Device level callbacks
|
| 112 | ======================
|
| 113 |
|
| 114 | pre_reset
|
| 115 | ---------
|
| 116 |
|
| 117 | ::
|
| 118 |
|
| 119 | int (*pre_reset)(struct usb_interface *intf);
|
| 120 |
|
| 121 | A driver or user space is triggering a reset on the device which
|
| 122 | contains the interface passed as an argument. Cease IO, wait for all
|
| 123 | outstanding URBs to complete, and save any device state you need to
|
| 124 | restore. No more URBs may be submitted until the post_reset method
|
| 125 | is called.
|
| 126 |
|
| 127 | If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you
|
| 128 | are in atomic context.
|
| 129 |
|
| 130 | post_reset
|
| 131 | ----------
|
| 132 |
|
| 133 | ::
|
| 134 |
|
| 135 | int (*post_reset)(struct usb_interface *intf);
|
| 136 |
|
| 137 | The reset has completed. Restore any saved device state and begin
|
| 138 | using the device again.
|
| 139 |
|
| 140 | If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you
|
| 141 | are in atomic context.
|
| 142 |
|
| 143 | Call sequences
|
| 144 | ==============
|
| 145 |
|
| 146 | No callbacks other than probe will be invoked for an interface
|
| 147 | that isn't bound to your driver.
|
| 148 |
|
| 149 | Probe will never be called for an interface bound to a driver.
|
| 150 | Hence following a successful probe, disconnect will be called
|
| 151 | before there is another probe for the same interface.
|
| 152 |
|
| 153 | Once your driver is bound to an interface, disconnect can be
|
| 154 | called at any time except in between pre_reset and post_reset.
|
| 155 | pre_reset is always followed by post_reset, even if the reset
|
| 156 | failed or the device has been unplugged.
|
| 157 |
|
| 158 | suspend is always followed by one of: resume, reset_resume, or
|
| 159 | disconnect.
|