From: Mauro Carvalho Chehab <mchehab@s-opensource.com>
To: Linux Media Mailing List <linux-media@vger.kernel.org>,
Linux Doc Mailing List <linux-doc@vger.kernel.org>,
Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@s-opensource.com>,
Mauro Carvalho Chehab <mchehab@infradead.org>,
Greg Kroah-Hartman <gregkh@linuxfoundation.org>,
linux-usb@vger.kernel.org
Subject: [PATCH v2 10/21] usb/callbacks.txt: convert to ReST and add to driver-api book
Date: Wed, 5 Apr 2017 10:23:04 -0300 [thread overview]
Message-ID: <020f2c077f926c1622f748c90c3b6bcec59bf854.1491398120.git.mchehab@s-opensource.com> (raw)
In-Reply-To: <cover.1491398120.git.mchehab@s-opensource.com>
In-Reply-To: <cover.1491398120.git.mchehab@s-opensource.com>
This document describe some USB core functions. Add it to the
driver-api book.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
---
.../callbacks.txt => driver-api/usb/callbacks.rst} | 61 +++++++++++++++-------
Documentation/driver-api/usb/index.rst | 1 +
2 files changed, 43 insertions(+), 19 deletions(-)
rename Documentation/{usb/callbacks.txt => driver-api/usb/callbacks.rst} (78%)
diff --git a/Documentation/usb/callbacks.txt b/Documentation/driver-api/usb/callbacks.rst
similarity index 78%
rename from Documentation/usb/callbacks.txt
rename to Documentation/driver-api/usb/callbacks.rst
index 9e85846bdb98..93a8d53e27e7 100644
--- a/Documentation/usb/callbacks.txt
+++ b/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
- * 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.
diff --git a/Documentation/driver-api/usb/index.rst b/Documentation/driver-api/usb/index.rst
index 6fe7611f7332..441c5dacdf27 100644
--- a/Documentation/driver-api/usb/index.rst
+++ b/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
--
2.9.3
next prev parent reply other threads:[~2017-04-05 13:23 UTC|newest]
Thread overview: 28+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-04-05 13:22 [PATCH v2 00/21] Convert USB documentation to ReST format Mauro Carvalho Chehab
2017-04-05 13:22 ` [PATCH v2 01/21] tmplcvt: make the tool more robust Mauro Carvalho Chehab
2017-04-05 13:22 ` [PATCH v2 02/21] driver-api/basics.rst: add device table header Mauro Carvalho Chehab
2017-04-05 13:22 ` [PATCH v2 03/21] docs-rst: convert usb docbooks to ReST Mauro Carvalho Chehab
2017-04-05 13:22 ` [PATCH v2 04/21] usb.rst: Enrich its ReST representation Mauro Carvalho Chehab
2017-04-05 13:22 ` [PATCH v2 05/21] gadget.rst: Enrich its ReST representation and add kernel-doc tag Mauro Carvalho Chehab
2017-04-05 13:23 ` [PATCH v2 06/21] writing_usb_driver.rst: Enrich its ReST representation Mauro Carvalho Chehab
2017-04-05 13:23 ` [PATCH v2 07/21] writing_musb_glue_layer.rst: " Mauro Carvalho Chehab
2017-04-05 13:23 ` [PATCH v2 08/21] usb/anchors.txt: convert to ReST and add to driver-api book Mauro Carvalho Chehab
2017-04-05 13:23 ` [PATCH v2 09/21] usb/bulk-streams.txt: " Mauro Carvalho Chehab
2017-04-05 13:23 ` Mauro Carvalho Chehab [this message]
2017-04-05 13:23 ` [PATCH v2 11/21] usb/power-management.txt: " Mauro Carvalho Chehab
2017-04-05 13:23 ` [PATCH v2 12/21] usb/dma.txt: " Mauro Carvalho Chehab
2017-04-05 13:23 ` [PATCH v2 13/21] error-codes.rst: " Mauro Carvalho Chehab
2017-04-05 13:23 ` [PATCH v2 14/21] usb/hotplug.txt: " Mauro Carvalho Chehab
2017-04-05 13:23 ` [PATCH v2 15/21] usb/persist.txt: " Mauro Carvalho Chehab
2017-04-05 13:23 ` [PATCH v2 16/21] usb/URB.txt: convert to ReST and update it Mauro Carvalho Chehab
2017-04-05 13:23 ` [PATCH v2 17/21] usb.rst: get rid of some Sphinx errors Mauro Carvalho Chehab
2017-04-05 13:23 ` [PATCH v2 18/21] usb: get rid of some ReST doc build errors Mauro Carvalho Chehab
2017-04-05 13:23 ` [PATCH v2 19/21] usb: composite.h: fix two warnings when building docs Mauro Carvalho Chehab
2017-04-05 13:23 ` [PATCH v2 20/21] usb: gadget.h: be consistent at kernel doc macros Mauro Carvalho Chehab
2017-04-05 13:23 ` [PATCH v2 21/21] docs-rst: fix usb cross-references Mauro Carvalho Chehab
2017-04-08 17:23 ` [PATCH v2 00/21] Convert USB documentation to ReST format Jonathan Corbet
2017-04-08 20:04 ` Greg Kroah-Hartman
2017-04-11 14:58 ` Greg Kroah-Hartman
2017-04-11 18:36 ` Mauro Carvalho Chehab
2017-04-11 18:41 ` Greg Kroah-Hartman
2017-04-11 20:49 ` Jonathan Corbet
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=020f2c077f926c1622f748c90c3b6bcec59bf854.1491398120.git.mchehab@s-opensource.com \
--to=mchehab@s-opensource.com \
--cc=corbet@lwn.net \
--cc=gregkh@linuxfoundation.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-media@vger.kernel.org \
--cc=linux-usb@vger.kernel.org \
--cc=mchehab@infradead.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.