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