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>

Documentation/driver-api/usb/callbacks.rst

@@ -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
+ - @probe:
- *	interface on a device.
+	Called to see if the driver is willing to manage a particular
- * @disconnect: Called when the interface is no longer accessible, usually
+	interface on a device.
- *	because its device has been (or is being) disconnected or the
+
- *	driver module is being unloaded.
+ - @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
+ - @ioctl:
- *	the "usbfs" filesystem.  This lets devices provide ways to
+	Used for drivers that want to talk to userspace through
- *	expose information to user space regardless of where they
+	the "usbfs" filesystem.  This lets devices provide ways to
- *	do (or don't) show up otherwise in the filesystem.
+	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.
+ - @suspend:
- * @resume: Called when the device is being resumed.
+	Called when the device is going to be suspended.
- * @reset_resume: Called when the suspended device has been reset instead
+
- *	of being resumed.
+ - @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.
+ - @pre_reset:
- * @post_reset: Called after the device has been 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.

Documentation/driver-api/usb/index.rst

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