Skip to content

Commit 8a37d87

Browse files
Heikki Krogerusgregkh
Heikki Krogerus
authored and
gregkh
committed
usb: typec: Bus type for alternate modes
Introducing a simple bus for the alternate modes. Bus allows binding drivers to the discovered alternate modes the partners support. Signed-off-by: Heikki Krogerus <[email protected]> Tested-by: Hans de Goede <[email protected]> Signed-off-by: Greg Kroah-Hartman <[email protected]>
1 parent 4ab8c18 commit 8a37d87

File tree

14 files changed

+1174
-147
lines changed

14 files changed

+1174
-147
lines changed

‎Documentation/ABI/obsolete/sysfs-class-typec

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
These files are deprecated and will be removed. The same files are available
2+
under /sys/bus/typec (see Documentation/ABI/testing/sysfs-bus-typec).
3+
4+
What: /sys/class/typec/<port|partner|cable>/<dev>/svid
5+
Date: April 2017
6+
Contact: Heikki Krogerus <[email protected]>
7+
Description:
8+
The SVID (Standard or Vendor ID) assigned by USB-IF for this
9+
alternate mode.
10+
11+
What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/
12+
Date: April 2017
13+
Contact: Heikki Krogerus <[email protected]>
14+
Description:
15+
Every supported mode will have its own directory. The name of
16+
a mode will be "mode<index>" (for example mode1), where <index>
17+
is the actual index to the mode VDO returned by Discover Modes
18+
USB power delivery command.
19+
20+
What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/description
21+
Date: April 2017
22+
Contact: Heikki Krogerus <[email protected]>
23+
Description:
24+
Shows description of the mode. The description is optional for
25+
the drivers, just like with the Billboard Devices.
26+
27+
What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/vdo
28+
Date: April 2017
29+
Contact: Heikki Krogerus <[email protected]>
30+
Description:
31+
Shows the VDO in hexadecimal returned by Discover Modes command
32+
for this mode.
33+
34+
What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/active
35+
Date: April 2017
36+
Contact: Heikki Krogerus <[email protected]>
37+
Description:
38+
Shows if the mode is active or not. The attribute can be used
39+
for entering/exiting the mode with partners and cable plugs, and
40+
with the port alternate modes it can be used for disabling
41+
support for specific alternate modes. Entering/exiting modes is
42+
supported as synchronous operation so write(2) to the attribute
43+
does not return until the enter/exit mode operation has
44+
finished. The attribute is notified when the mode is
45+
entered/exited so poll(2) on the attribute wakes up.
46+
Entering/exiting a mode will also generate uevent KOBJ_CHANGE.
47+
48+
Valid values: yes, no

‎Documentation/ABI/testing/sysfs-bus-typec

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
What: /sys/bus/typec/devices/.../active
2+
Date: July 2018
3+
Contact: Heikki Krogerus <[email protected]>
4+
Description:
5+
Shows if the mode is active or not. The attribute can be used
6+
for entering/exiting the mode. Entering/exiting modes is
7+
supported as synchronous operation so write(2) to the attribute
8+
does not return until the enter/exit mode operation has
9+
finished. The attribute is notified when the mode is
10+
entered/exited so poll(2) on the attribute wakes up.
11+
Entering/exiting a mode will also generate uevent KOBJ_CHANGE.
12+
13+
Valid values are boolean.
14+
15+
What: /sys/bus/typec/devices/.../description
16+
Date: July 2018
17+
Contact: Heikki Krogerus <[email protected]>
18+
Description:
19+
Shows description of the mode. The description is optional for
20+
the drivers, just like with the Billboard Devices.
21+
22+
What: /sys/bus/typec/devices/.../mode
23+
Date: July 2018
24+
Contact: Heikki Krogerus <[email protected]>
25+
Description:
26+
The index number of the mode returned by Discover Modes USB
27+
Power Delivery command. Depending on the alternate mode, the
28+
mode index may be significant.
29+
30+
With some alternate modes (SVIDs), the mode index is assigned
31+
for specific functionality in the specification for that
32+
alternate mode.
33+
34+
With other alternate modes, the mode index values are not
35+
assigned, and can not be therefore used for identification. When
36+
the mode index is not assigned, identifying the alternate mode
37+
must be done with either mode VDO or the description.
38+
39+
What: /sys/bus/typec/devices/.../svid
40+
Date: July 2018
41+
Contact: Heikki Krogerus <[email protected]>
42+
Description:
43+
The Standard or Vendor ID (SVID) assigned by USB-IF for this
44+
alternate mode.
45+
46+
What: /sys/bus/typec/devices/.../vdo
47+
Date: July 2018
48+
Contact: Heikki Krogerus <[email protected]>
49+
Description:
50+
Shows the VDO in hexadecimal returned by Discover Modes command
51+
for this mode.

‎Documentation/ABI/testing/sysfs-class-typec

Lines changed: 2 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -222,70 +222,12 @@ Description:
222222
available. The value can be polled.
223223

224224

225-
Alternate Mode devices.
225+
USB Type-C port alternate mode devices.
226226

227-
The alternate modes will have Standard or Vendor ID (SVID) assigned by USB-IF.
228-
The ports, partners and cable plugs can have alternate modes. A supported SVID
229-
will consist of a set of modes. Every SVID a port/partner/plug supports will
230-
have a device created for it, and every supported mode for a supported SVID will
231-
have its own directory under that device. Below <dev> refers to the device for
232-
the alternate mode.
233-
234-
What: /sys/class/typec/<port|partner|cable>/<dev>/svid
235-
Date: April 2017
236-
Contact: Heikki Krogerus <[email protected]>
237-
Description:
238-
The SVID (Standard or Vendor ID) assigned by USB-IF for this
239-
alternate mode.
240-
241-
What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/
242-
Date: April 2017
243-
Contact: Heikki Krogerus <[email protected]>
244-
Description:
245-
Every supported mode will have its own directory. The name of
246-
a mode will be "mode<index>" (for example mode1), where <index>
247-
is the actual index to the mode VDO returned by Discover Modes
248-
USB power delivery command.
249-
250-
What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/description
251-
Date: April 2017
252-
Contact: Heikki Krogerus <[email protected]>
253-
Description:
254-
Shows description of the mode. The description is optional for
255-
the drivers, just like with the Billboard Devices.
256-
257-
What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/vdo
258-
Date: April 2017
259-
Contact: Heikki Krogerus <[email protected]>
260-
Description:
261-
Shows the VDO in hexadecimal returned by Discover Modes command
262-
for this mode.
263-
264-
What: /sys/class/typec/<port|partner|cable>/<dev>/mode<index>/active
265-
Date: April 2017
266-
Contact: Heikki Krogerus <[email protected]>
267-
Description:
268-
Shows if the mode is active or not. The attribute can be used
269-
for entering/exiting the mode with partners and cable plugs, and
270-
with the port alternate modes it can be used for disabling
271-
support for specific alternate modes. Entering/exiting modes is
272-
supported as synchronous operation so write(2) to the attribute
273-
does not return until the enter/exit mode operation has
274-
finished. The attribute is notified when the mode is
275-
entered/exited so poll(2) on the attribute wakes up.
276-
Entering/exiting a mode will also generate uevent KOBJ_CHANGE.
277-
278-
Valid values: yes, no
279-
280-
What: /sys/class/typec/<port>/<dev>/mode<index>/supported_roles
227+
What: /sys/class/typec/<port>/<alt mode>/supported_roles
281228
Date: April 2017
282229
Contact: Heikki Krogerus <[email protected]>
283230
Description:
284231
Space separated list of the supported roles.
285232

286-
This attribute is available for the devices describing the
287-
alternate modes a port supports, and it will not be exposed with
288-
the devices presenting the alternate modes the partners or cable
289-
plugs support.
290-
291233
Valid values: source, sink

‎Documentation/driver-api/usb/typec_bus.rst

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
2+
API for USB Type-C Alternate Mode drivers
3+
=========================================
4+
5+
Introduction
6+
------------
7+
8+
Alternate modes require communication with the partner using Vendor Defined
9+
Messages (VDM) as defined in USB Type-C and USB Power Delivery Specifications.
10+
The communication is SVID (Standard or Vendor ID) specific, i.e. specific for
11+
every alternate mode, so every alternate mode will need a custom driver.
12+
13+
USB Type-C bus allows binding a driver to the discovered partner alternate
14+
modes by using the SVID and the mode number.
15+
16+
USB Type-C Connector Class provides a device for every alternate mode a port
17+
supports, and separate device for every alternate mode the partner supports.
18+
The drivers for the alternate modes are bound to the partner alternate mode
19+
devices, and the port alternate mode devices must be handled by the port
20+
drivers.
21+
22+
When a new partner alternate mode device is registered, it is linked to the
23+
alternate mode device of the port that the partner is attached to, that has
24+
matching SVID and mode. Communication between the port driver and alternate mode
25+
driver will happen using the same API.
26+
27+
The port alternate mode devices are used as a proxy between the partner and the
28+
alternate mode drivers, so the port drivers are only expected to pass the SVID
29+
specific commands from the alternate mode drivers to the partner, and from the
30+
partners to the alternate mode drivers. No direct SVID specific communication is
31+
needed from the port drivers, but the port drivers need to provide the operation
32+
callbacks for the port alternate mode devices, just like the alternate mode
33+
drivers need to provide them for the partner alternate mode devices.
34+
35+
Usage:
36+
------
37+
38+
General
39+
~~~~~~~
40+
41+
By default, the alternate mode drivers are responsible for entering the mode.
42+
It is also possible to leave the decision about entering the mode to the user
43+
space (See Documentation/ABI/testing/sysfs-class-typec). Port drivers should not
44+
enter any modes on their own.
45+
46+
``->vdm`` is the most important callback in the operation callbacks vector. It
47+
will be used to deliver all the SVID specific commands from the partner to the
48+
alternate mode driver, and vice versa in case of port drivers. The drivers send
49+
the SVID specific commands to each other using :c:func:`typec_altmode_vmd()`.
50+
51+
If the communication with the partner using the SVID specific commands results
52+
in need to reconfigure the pins on the connector, the alternate mode driver
53+
needs to notify the bus using :c:func:`typec_altmode_notify()`. The driver
54+
passes the negotiated SVID specific pin configuration value to the function as
55+
parameter. The bus driver will then configure the mux behind the connector using
56+
that value as the state value for the mux, and also call blocking notification
57+
chain to notify the external drivers about the state of the connector that need
58+
to know it.
59+
60+
NOTE: The SVID specific pin configuration values must always start from
61+
``TYPEC_STATE_MODAL``. USB Type-C specification defines two default states for
62+
the connector: ``TYPEC_STATE_USB`` and ``TYPEC_STATE_SAFE``. These values are
63+
reserved by the bus as the first possible values for the state. When the
64+
alternate mode is entered, the bus will put the connector into
65+
``TYPEC_STATE_SAFE`` before sending Enter or Exit Mode command as defined in USB
66+
Type-C Specification, and also put the connector back to ``TYPEC_STATE_USB``
67+
after the mode has been exited.
68+
69+
An example of working definitions for SVID specific pin configurations would
70+
look like this:
71+
72+
enum {
73+
ALTMODEX_CONF_A = TYPEC_STATE_MODAL,
74+
ALTMODEX_CONF_B,
75+
...
76+
};
77+
78+
Helper macro ``TYPEC_MODAL_STATE()`` can also be used:
79+
80+
#define ALTMODEX_CONF_A = TYPEC_MODAL_STATE(0);
81+
#define ALTMODEX_CONF_B = TYPEC_MODAL_STATE(1);
82+
83+
Notification chain
84+
~~~~~~~~~~~~~~~~~~
85+
86+
The drivers for the components that the alternate modes are designed for need to
87+
get details regarding the results of the negotiation with the partner, and the
88+
pin configuration of the connector. In case of DisplayPort alternate mode for
89+
example, the GPU drivers will need to know those details. In case of
90+
Thunderbolt alternate mode, the thunderbolt drivers will need to know them, and
91+
so on.
92+
93+
The notification chain is designed for this purpose. The drivers can register
94+
notifiers with :c:func:`typec_altmode_register_notifier()`.
95+
96+
Cable plug alternate modes
97+
~~~~~~~~~~~~~~~~~~~~~~~~~~
98+
99+
The alternate mode drivers are not bound to cable plug alternate mode devices,
100+
only to the partner alternate mode devices. If the alternate mode supports, or
101+
requires, a cable that responds to SOP Prime, and optionally SOP Double Prime
102+
messages, the driver for that alternate mode must request handle to the cable
103+
plug alternate modes using :c:func:`typec_altmode_get_plug()`, and take over
104+
their control.
105+
106+
Driver API
107+
----------
108+
109+
Alternate mode driver registering/unregistering
110+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
111+
112+
.. kernel-doc:: drivers/usb/typec/bus.c
113+
:functions: typec_altmode_register_driver typec_altmode_unregister_driver
114+
115+
Alternate mode driver operations
116+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
117+
118+
.. kernel-doc:: drivers/usb/typec/bus.c
119+
:functions: typec_altmode_enter typec_altmode_exit typec_altmode_attention typec_altmode_vdm typec_altmode_notify
120+
121+
API for the port drivers
122+
~~~~~~~~~~~~~~~~~~~~~~~~
123+
124+
.. kernel-doc:: drivers/usb/typec/bus.c
125+
:functions: typec_match_altmode
126+
127+
Cable Plug operations
128+
~~~~~~~~~~~~~~~~~~~~~
129+
130+
.. kernel-doc:: drivers/usb/typec/bus.c
131+
:functions: typec_altmode_get_plug typec_altmode_put_plug
132+
133+
Notifications
134+
~~~~~~~~~~~~~
135+
.. kernel-doc:: drivers/usb/typec/class.c
136+
:functions: typec_altmode_register_notifier typec_altmode_unregister_notifier

‎MAINTAINERS

Lines changed: 10 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14955,7 +14955,7 @@ L: [email protected]
1495514955
S: Maintained
1495614956
F: drivers/usb/typec/mux/pi3usb30532.c
1495714957

14958-
USB TYPEC SUBSYSTEM
14958+
USB TYPEC CLASS
1495914959
M: Heikki Krogerus <[email protected]>
1496014960
L: [email protected]
1496114961
S: Maintained
@@ -14964,6 +14964,15 @@ F: Documentation/driver-api/usb/typec.rst
1496414964
F: drivers/usb/typec/
1496514965
F: include/linux/usb/typec.h
1496614966

14967+
USB TYPEC BUS FOR ALTERNATE MODES
14968+
M: Heikki Krogerus <[email protected]>
14969+
L: [email protected]
14970+
S: Maintained
14971+
F: Documentation/ABI/testing/sysfs-bus-typec
14972+
F: Documentation/driver-api/usb/typec_bus.rst
14973+
F: drivers/usb/typec/altmodes/
14974+
F: include/linux/usb/typec_altmode.h
14975+
1496714976
USB UHCI DRIVER
1496814977
M: Alan Stern <[email protected]>
1496914978
L: [email protected]

‎drivers/usb/typec/Makefile

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
# SPDX-License-Identifier: GPL-2.0
22
obj-$(CONFIG_TYPEC) += typec.o
3-
typec-y := class.o mux.o
3+
typec-y := class.o mux.o bus.o
44
obj-$(CONFIG_TYPEC_TCPM) += tcpm.o
55
obj-y += fusb302/
66
obj-$(CONFIG_TYPEC_WCOVE) += typec_wcove.o

0 commit comments

Comments
 (0)