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 <mchehab@s-opensource.com>
Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab 2017-04-05 10:23:04 -03:00 committed by Jonathan Corbet
parent 401c7be2ba
commit 3b38e4f218
2 changed files with 43 additions and 19 deletions

View File

@ -1,3 +1,6 @@
USB core callbacks
~~~~~~~~~~~~~~~~~~
What callbacks will usbcore do?
===============================
@ -11,30 +14,42 @@ 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.
- @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.
- @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.
- @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
- @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
@ -58,7 +73,9 @@ an interface. A driver's bond to an interface is exclusive.
The probe() callback
--------------------
int (*probe) (struct usb_interface *intf,
::
int (*probe) (struct usb_interface *intf,
const struct usb_device_id *id);
Accept or decline an interface. If you accept the device return 0,
@ -75,7 +92,9 @@ initialisation that doesn't take too long is a good idea here.
The disconnect() callback
-------------------------
void (*disconnect) (struct usb_interface *intf);
::
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
@ -93,7 +112,9 @@ Device level callbacks
pre_reset
---------
int (*pre_reset)(struct usb_interface *intf);
::
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
@ -107,7 +128,9 @@ are in atomic context.
post_reset
----------
int (*post_reset)(struct usb_interface *intf);
::
int (*post_reset)(struct usb_interface *intf);
The reset has completed. Restore any saved device state and begin
using the device again.

View File

@ -8,6 +8,7 @@ Linux USB API
gadget
anchors
bulk-streams
callbacks
writing_usb_driver
writing_musb_glue_layer