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>

1 files changed, 0 insertions, 134 deletions

diff --git a/Documentation/usb/callbacks.txt b/Documentation/usb/callbacks.txt
deleted file mode 100644
index 9e85846bdb98..000000000000
--- a/Documentation/usb/callbacks.txt
+++ /dev/null
@@ -1,134 +0,0 @@
-What callbacks will usbcore do?
-===============================
-
-Usbcore will call into a driver through callbacks defined in the driver
-structure and through the completion handler of URBs a driver submits.
-Only the former are in the scope of this document. These two kinds of
-callbacks are completely independent of each other. Information on the
-completion callback can be found in Documentation/usb/URB.txt.
-
-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.
-
-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.
-
-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.
-
-4. Device level operations:
-
- * @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
-separately in Documentation/usb/power-management.txt.
-
-Calling conventions
-===================
-
-All callbacks are mutually exclusive. There's no need for locking
-against other USB callbacks. All callbacks are called from a task
-context. You may sleep. However, it is important that all sleeps have a
-small fixed upper limit in time. In particular you must not call out to
-user space and await results.
-
-Hotplugging callbacks
-=====================
-
-These callbacks are intended to associate and disassociate a driver with
-an interface. A driver's bond to an interface is exclusive.
-
-The probe() callback
---------------------
-
-int (*probe) (struct usb_interface *intf,
-		const struct usb_device_id *id);
-
-Accept or decline an interface. If you accept the device return 0,
-otherwise -ENODEV or -ENXIO. Other error codes should be used only if a
-genuine error occurred during initialisation which prevented a driver
-from accepting a device that would else have been accepted.
-You are strongly encouraged to use usbcore's facility,
-usb_set_intfdata(), to associate a data structure with an interface, so
-that you know which internal state and identity you associate with a
-particular interface. The device will not be suspended and you may do IO
-to the interface you are called for and endpoint 0 of the device. Device
-initialisation that doesn't take too long is a good idea here.
-
-The disconnect() callback
--------------------------
-
-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
-callback. You also may not do any other operation that may interfere
-with another driver bound the interface, eg. a power management
-operation.
-If you are called due to a physical disconnection, all your URBs will be
-killed by usbcore. Note that in this case disconnect will be called some
-time after the physical disconnection. Thus your driver must be prepared
-to deal with failing IO even prior to the callback.
-
-Device level callbacks
-======================
-
-pre_reset
----------
-
-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
-outstanding URBs to complete, and save any device state you need to
-restore.  No more URBs may be submitted until the post_reset method
-is called.
-
-If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you
-are in atomic context.
-
-post_reset
-----------
-
-int (*post_reset)(struct usb_interface *intf);
-
-The reset has completed.  Restore any saved device state and begin
-using the device again.
-
-If you need to allocate memory here, use GFP_NOIO or GFP_ATOMIC, if you
-are in atomic context.
-
-Call sequences
-==============
-
-No callbacks other than probe will be invoked for an interface
-that isn't bound to your driver.
-
-Probe will never be called for an interface bound to a driver.
-Hence following a successful probe, disconnect will be called
-before there is another probe for the same interface.
-
-Once your driver is bound to an interface, disconnect can be
-called at any time except in between pre_reset and post_reset.
-pre_reset is always followed by post_reset, even if the reset
-failed or the device has been unplugged.
-
-suspend is always followed by one of: resume, reset_resume, or
-disconnect.