summaryrefslogtreecommitdiff
path: root/Documentation/driver-api
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2018-04-05 03:55:35 +0300
committerLinus Torvalds <torvalds@linux-foundation.org>2018-04-05 03:55:35 +0300
commitac9053d2dcb9e8c3fa35ce458dfca8fddc141680 (patch)
tree3ffa30d58dac22ee0a80e2dd32f41b71da91132b /Documentation/driver-api
parentf9ca6a561d40115696a54f16085c4edb17effc74 (diff)
parent5267c5e09c25e2ee6242b37833a9bdf9d97f54a2 (diff)
downloadlinux-ac9053d2dcb9e8c3fa35ce458dfca8fddc141680.tar.xz
Merge tag 'usb-4.17-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/usb
Pull USB/PHY updates from Greg KH: "Here is the big set of USB and PHY driver patches for 4.17-rc1. Lots of USB typeC work happened this round, with code moving from the staging directory into the "real" part of the kernel, as well as new infrastructure being added to be able to handle the different types of "roles" that typeC requires. There is also the normal huge set of USB gadget controller and driver updates, along with XHCI changes, and a raft of other tiny fixes all over the USB tree. And the PHY driver updates are merged in here as well as they interacted with the USB drivers in some places. All of these have been in linux-next for a while with no reported issues" * tag 'usb-4.17-rc1' of git://git.kernel.org/pub/scm/linux/kernel/git/gregkh/usb: (250 commits) Revert "USB: serial: ftdi_sio: add Id for Physik Instrumente E-870" usb: musb: gadget: misplaced out of bounds check usb: chipidea: imx: Fix ULPI on imx53 usb: chipidea: imx: Cleanup ci_hdrc_imx_platform_flag usb: chipidea: usbmisc: small clean up usb: chipidea: usbmisc: evdo can be set e/o reset usb: chipidea: usbmisc: evdo is only specific to OTG port USB: serial: ftdi_sio: add Id for Physik Instrumente E-870 usb: dwc3: gadget: never call ->complete() from ->ep_queue() usb: gadget: udc: core: update usb_ep_queue() documentation usb: host: Remove the deprecated ATH79 USB host config options usb: roles: Fix return value check in intel_xhci_usb_probe() USB: gadget: f_midi: fixing a possible double-free in f_midi usb: core: Add USB_QUIRK_DELAY_CTRL_MSG to usbcore quirks usb: core: Copy parameter string correctly and remove superfluous null check USB: announce bcdDevice as well as idVendor, idProduct. USB:fix USB3 devices behind USB3 hubs not resuming at hibernate thaw usb: hub: Reduce warning to notice on power loss USB: serial: ftdi_sio: add support for Harman FirmwareHubEmulator USB: serial: cp210x: add ELDAT Easywave RX09 id ...
Diffstat (limited to 'Documentation/driver-api')
-rw-r--r--Documentation/driver-api/device_connection.rst43
-rw-r--r--Documentation/driver-api/usb/typec.rst73
2 files changed, 105 insertions, 11 deletions
diff --git a/Documentation/driver-api/device_connection.rst b/Documentation/driver-api/device_connection.rst
new file mode 100644
index 000000000000..affbc5566ab0
--- /dev/null
+++ b/Documentation/driver-api/device_connection.rst
@@ -0,0 +1,43 @@
+==================
+Device connections
+==================
+
+Introduction
+------------
+
+Devices often have connections to other devices that are outside of the direct
+child/parent relationship. A serial or network communication controller, which
+could be a PCI device, may need to be able to get a reference to its PHY
+component, which could be attached for example to the I2C bus. Some device
+drivers need to be able to control the clocks or the GPIOs for their devices,
+and so on.
+
+Device connections are generic descriptions of any type of connection between
+two separate devices.
+
+Device connections alone do not create a dependency between the two devices.
+They are only descriptions which are not tied to either of the devices directly.
+A dependency between the two devices exists only if one of the two endpoint
+devices requests a reference to the other. The descriptions themselves can be
+defined in firmware (not yet supported) or they can be built-in.
+
+Usage
+-----
+
+Device connections should exist before device ``->probe`` callback is called for
+either endpoint device in the description. If the connections are defined in
+firmware, this is not a problem. It should be considered if the connection
+descriptions are "built-in", and need to be added separately.
+
+The connection description consists of the names of the two devices with the
+connection, i.e. the endpoints, and unique identifier for the connection which
+is needed if there are multiple connections between the two devices.
+
+After a description exists, the devices in it can request reference to the other
+endpoint device, or they can request the description itself.
+
+API
+---
+
+.. kernel-doc:: drivers/base/devcon.c
+ : functions: device_connection_find_match device_connection_find device_connection_add device_connection_remove
diff --git a/Documentation/driver-api/usb/typec.rst b/Documentation/driver-api/usb/typec.rst
index 8a7249f2ff04..feb31946490b 100644
--- a/Documentation/driver-api/usb/typec.rst
+++ b/Documentation/driver-api/usb/typec.rst
@@ -61,7 +61,7 @@ Registering the ports
The port drivers will describe every Type-C port they control with struct
typec_capability data structure, and register them with the following API:
-.. kernel-doc:: drivers/usb/typec/typec.c
+.. kernel-doc:: drivers/usb/typec/class.c
:functions: typec_register_port typec_unregister_port
When registering the ports, the prefer_role member in struct typec_capability
@@ -80,7 +80,7 @@ typec_partner_desc. The class copies the details of the partner during
registration. The class offers the following API for registering/unregistering
partners.
-.. kernel-doc:: drivers/usb/typec/typec.c
+.. kernel-doc:: drivers/usb/typec/class.c
:functions: typec_register_partner typec_unregister_partner
The class will provide a handle to struct typec_partner if the registration was
@@ -92,7 +92,7 @@ should include handle to struct usb_pd_identity instance. The class will then
create a sysfs directory for the identity under the partner device. The result
of Discover Identity command can then be reported with the following API:
-.. kernel-doc:: drivers/usb/typec/typec.c
+.. kernel-doc:: drivers/usb/typec/class.c
:functions: typec_partner_set_identity
Registering Cables
@@ -113,7 +113,7 @@ typec_cable_desc and about a plug in struct typec_plug_desc. The class copies
the details during registration. The class offers the following API for
registering/unregistering cables and their plugs:
-.. kernel-doc:: drivers/usb/typec/typec.c
+.. kernel-doc:: drivers/usb/typec/class.c
:functions: typec_register_cable typec_unregister_cable typec_register_plug typec_unregister_plug
The class will provide a handle to struct typec_cable and struct typec_plug if
@@ -125,7 +125,7 @@ include handle to struct usb_pd_identity instance. The class will then create a
sysfs directory for the identity under the cable device. The result of Discover
Identity command can then be reported with the following API:
-.. kernel-doc:: drivers/usb/typec/typec.c
+.. kernel-doc:: drivers/usb/typec/class.c
:functions: typec_cable_set_identity
Notifications
@@ -135,7 +135,7 @@ When the partner has executed a role change, or when the default roles change
during connection of a partner or cable, the port driver must use the following
APIs to report it to the class:
-.. kernel-doc:: drivers/usb/typec/typec.c
+.. kernel-doc:: drivers/usb/typec/class.c
:functions: typec_set_data_role typec_set_pwr_role typec_set_vconn_role typec_set_pwr_opmode
Alternate Modes
@@ -150,7 +150,7 @@ and struct typec_altmode_desc which is a container for all the supported modes.
Ports that support Alternate Modes need to register each SVID they support with
the following API:
-.. kernel-doc:: drivers/usb/typec/typec.c
+.. kernel-doc:: drivers/usb/typec/class.c
:functions: typec_port_register_altmode
If a partner or cable plug provides a list of SVIDs as response to USB Power
@@ -159,12 +159,12 @@ registered.
API for the partners:
-.. kernel-doc:: drivers/usb/typec/typec.c
+.. kernel-doc:: drivers/usb/typec/class.c
:functions: typec_partner_register_altmode
API for the Cable Plugs:
-.. kernel-doc:: drivers/usb/typec/typec.c
+.. kernel-doc:: drivers/usb/typec/class.c
:functions: typec_plug_register_altmode
So ports, partners and cable plugs will register the alternate modes with their
@@ -172,11 +172,62 @@ own functions, but the registration will always return a handle to struct
typec_altmode on success, or NULL. The unregistration will happen with the same
function:
-.. kernel-doc:: drivers/usb/typec/typec.c
+.. kernel-doc:: drivers/usb/typec/class.c
:functions: typec_unregister_altmode
If a partner or cable plug enters or exits a mode, the port driver needs to
notify the class with the following API:
-.. kernel-doc:: drivers/usb/typec/typec.c
+.. kernel-doc:: drivers/usb/typec/class.c
:functions: typec_altmode_update_active
+
+Multiplexer/DeMultiplexer Switches
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+USB Type-C connectors may have one or more mux/demux switches behind them. Since
+the plugs can be inserted right-side-up or upside-down, a switch is needed to
+route the correct data pairs from the connector to the USB controllers. If
+Alternate or Accessory Modes are supported, another switch is needed that can
+route the pins on the connector to some other component besides USB. USB Type-C
+Connector Class supplies an API for registering those switches.
+
+.. kernel-doc:: drivers/usb/typec/mux.c
+ :functions: typec_switch_register typec_switch_unregister typec_mux_register typec_mux_unregister
+
+In most cases the same physical mux will handle both the orientation and mode.
+However, as the port drivers will be responsible for the orientation, and the
+alternate mode drivers for the mode, the two are always separated into their
+own logical components: "mux" for the mode and "switch" for the orientation.
+
+When a port is registered, USB Type-C Connector Class requests both the mux and
+the switch for the port. The drivers can then use the following API for
+controlling them:
+
+.. kernel-doc:: drivers/usb/typec/class.c
+ :functions: typec_set_orientation typec_set_mode
+
+If the connector is dual-role capable, there may also be a switch for the data
+role. USB Type-C Connector Class does not supply separate API for them. The
+port drivers can use USB Role Class API with those.
+
+Illustration of the muxes behind a connector that supports an alternate mode:
+
+ ------------------------
+ | Connector |
+ ------------------------
+ | |
+ ------------------------
+ \ Orientation /
+ --------------------
+ |
+ --------------------
+ / Mode \
+ ------------------------
+ / \
+ ------------------------ --------------------
+ | Alt Mode | / USB Role \
+ ------------------------ ------------------------
+ / \
+ ------------------------ ------------------------
+ | USB Host | | USB Device |
+ ------------------------ ------------------------