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