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