Documentation/driver-api/usb/typec.rst

   1 .. _typec:
   2
   3 USB Type-C connector class
   4 ==========================
   5
   6 Introduction
   7 ------------
   8
   9 The typec class is meant for describing the USB Type-C ports in a system to the
  10 user space in unified fashion. The class is designed to provide nothing else
  11 except the user space interface implementation in hope that it can be utilized
  12 on as many platforms as possible.
  13
  14 The platforms are expected to register every USB Type-C port they have with the
  15 class. In a normal case the registration will be done by a USB Type-C or PD PHY
  16 driver, but it may be a driver for firmware interface such as UCSI, driver for
  17 USB PD controller or even driver for Thunderbolt3 controller. This document
  18 considers the component registering the USB Type-C ports with the class as "port
  19 driver".
  20
  21 On top of showing the capabilities, the class also offer user space control over
  22 the roles and alternate modes of ports, partners and cable plugs when the port
  23 driver is capable of supporting those features.
  24
  25 The class provides an API for the port drivers described in this document. The
  26 attributes are described in Documentation/ABI/testing/sysfs-class-typec.
  27
  28 User space interface
  29 --------------------
  30 Every port will be presented as its own device under /sys/class/typec/. The
  31 first port will be named "port0", the second "port1" and so on.
  32
  33 When connected, the partner will be presented also as its own device under
  34 /sys/class/typec/. The parent of the partner device will always be the port it
  35 is attached to. The partner attached to port "port0" will be named
  36 "port0-partner". Full path to the device would be
  37 /sys/class/typec/port0/port0-partner/.
  38
  39 The cable and the two plugs on it may also be optionally presented as their own
  40 devices under /sys/class/typec/. The cable attached to the port "port0" port
  41 will be named port0-cable and the plug on the SOP Prime end (see USB Power
  42 Delivery Specification ch. 2.4) will be named "port0-plug0" and on the SOP
  43 Double Prime end "port0-plug1". The parent of a cable will always be the port,
  44 and the parent of the cable plugs will always be the cable.
  45
  46 If the port, partner or cable plug supports Alternate Modes, every supported
  47 Alternate Mode SVID will have their own device describing them. Note that the
  48 Alternate Mode devices will not be attached to the typec class. The parent of an
  49 alternate mode will be the device that supports it, so for example an alternate
  50 mode of port0-partner will be presented under /sys/class/typec/port0-partner/.
  51 Every mode that is supported will have its own group under the Alternate Mode
  52 device named "mode<index>", for example /sys/class/typec/port0/<alternate
  53 mode>/mode1/. The requests for entering/exiting a mode can be done with "active"
  54 attribute file in that group.
  55
  56 Driver API
  57 ----------
  58
  59 Registering the ports
  60 ~~~~~~~~~~~~~~~~~~~~~
  61
  62 The port drivers will describe every Type-C port they control with struct
  63 typec_capability data structure, and register them with the following API:
  64
  65 .. kernel-doc:: drivers/usb/typec/class.c
  66    :functions: typec_register_port typec_unregister_port
  67
  68 When registering the ports, the prefer_role member in struct typec_capability
  69 deserves special notice. If the port that is being registered does not have
  70 initial role preference, which means the port does not execute Try.SNK or
  71 Try.SRC by default, the member must have value TYPEC_NO_PREFERRED_ROLE.
  72 Otherwise if the port executes Try.SNK by default, the member must have value
  73 TYPEC_DEVICE, and with Try.SRC the value must be TYPEC_HOST.
  74
  75 Registering Partners
  76 ~~~~~~~~~~~~~~~~~~~~
  77
  78 After successful connection of a partner, the port driver needs to register the
  79 partner with the class. Details about the partner need to be described in struct
  80 typec_partner_desc. The class copies the details of the partner during
  81 registration. The class offers the following API for registering/unregistering
  82 partners.
  83
  84 .. kernel-doc:: drivers/usb/typec/class.c
  85    :functions: typec_register_partner typec_unregister_partner
  86
  87 The class will provide a handle to struct typec_partner if the registration was
  88 successful, or NULL.
  89
  90 If the partner is USB Power Delivery capable, and the port driver is able to
  91 show the result of Discover Identity command, the partner descriptor structure
  92 should include handle to struct usb_pd_identity instance. The class will then
  93 create a sysfs directory for the identity under the partner device. The result
  94 of Discover Identity command can then be reported with the following API:
  95
  96 .. kernel-doc:: drivers/usb/typec/class.c
  97    :functions: typec_partner_set_identity
  98
  99 Registering Cables
 100 ~~~~~~~~~~~~~~~~~~
 101
 102 After successful connection of a cable that supports USB Power Delivery
 103 Structured VDM "Discover Identity", the port driver needs to register the cable
 104 and one or two plugs, depending if there is CC Double Prime controller present
 105 in the cable or not. So a cable capable of SOP Prime communication, but not SOP
 106 Double Prime communication, should only have one plug registered. For more
 107 information about SOP communication, please read chapter about it from the
 108 latest USB Power Delivery specification.
 109
 110 The plugs are represented as their own devices. The cable is registered first,
 111 followed by registration of the cable plugs. The cable will be the parent device
 112 for the plugs. Details about the cable need to be described in struct
 113 typec_cable_desc and about a plug in struct typec_plug_desc. The class copies
 114 the details during registration. The class offers the following API for
 115 registering/unregistering cables and their plugs:
 116
 117 .. kernel-doc:: drivers/usb/typec/class.c
 118    :functions: typec_register_cable typec_unregister_cable typec_register_plug typec_unregister_plug
 119
 120 The class will provide a handle to struct typec_cable and struct typec_plug if
 121 the registration is successful, or NULL if it isn't.
 122
 123 If the cable is USB Power Delivery capable, and the port driver is able to show
 124 the result of Discover Identity command, the cable descriptor structure should
 125 include handle to struct usb_pd_identity instance. The class will then create a
 126 sysfs directory for the identity under the cable device. The result of Discover
 127 Identity command can then be reported with the following API:
 128
 129 .. kernel-doc:: drivers/usb/typec/class.c
 130    :functions: typec_cable_set_identity
 131
 132 Notifications
 133 ~~~~~~~~~~~~~
 134
 135 When the partner has executed a role change, or when the default roles change
 136 during connection of a partner or cable, the port driver must use the following
 137 APIs to report it to the class:
 138
 139 .. kernel-doc:: drivers/usb/typec/class.c
 140    :functions: typec_set_data_role typec_set_pwr_role typec_set_vconn_role typec_set_pwr_opmode
 141
 142 Alternate Modes
 143 ~~~~~~~~~~~~~~~
 144
 145 USB Type-C ports, partners and cable plugs may support Alternate Modes. Each
 146 Alternate Mode will have identifier called SVID, which is either a Standard ID
 147 given by USB-IF or vendor ID, and each supported SVID can have 1 - 6 modes. The
 148 class provides struct typec_mode_desc for describing individual mode of a SVID,
 149 and struct typec_altmode_desc which is a container for all the supported modes.
 150
 151 Ports that support Alternate Modes need to register each SVID they support with
 152 the following API:
 153
 154 .. kernel-doc:: drivers/usb/typec/class.c
 155    :functions: typec_port_register_altmode
 156
 157 If a partner or cable plug provides a list of SVIDs as response to USB Power
 158 Delivery Structured VDM Discover SVIDs message, each SVID needs to be
 159 registered.
 160
 161 API for the partners:
 162
 163 .. kernel-doc:: drivers/usb/typec/class.c
 164    :functions: typec_partner_register_altmode
 165
 166 API for the Cable Plugs:
 167
 168 .. kernel-doc:: drivers/usb/typec/class.c
 169    :functions: typec_plug_register_altmode
 170
 171 So ports, partners and cable plugs will register the alternate modes with their
 172 own functions, but the registration will always return a handle to struct
 173 typec_altmode on success, or NULL. The unregistration will happen with the same
 174 function:
 175
 176 .. kernel-doc:: drivers/usb/typec/class.c
 177    :functions: typec_unregister_altmode
 178
 179 If a partner or cable plug enters or exits a mode, the port driver needs to
 180 notify the class with the following API:
 181
 182 .. kernel-doc:: drivers/usb/typec/class.c
 183    :functions: typec_altmode_update_active
 184
 185 Multiplexer/DeMultiplexer Switches
 186 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 187
 188 USB Type-C connectors may have one or more mux/demux switches behind them. Since
 189 the plugs can be inserted right-side-up or upside-down, a switch is needed to
 190 route the correct data pairs from the connector to the USB controllers. If
 191 Alternate or Accessory Modes are supported, another switch is needed that can
 192 route the pins on the connector to some other component besides USB. USB Type-C
 193 Connector Class supplies an API for registering those switches.
 194
 195 .. kernel-doc:: drivers/usb/typec/mux.c
 196    :functions: typec_switch_register typec_switch_unregister typec_mux_register typec_mux_unregister
 197
 198 In most cases the same physical mux will handle both the orientation and mode.
 199 However, as the port drivers will be responsible for the orientation, and the
 200 alternate mode drivers for the mode, the two are always separated into their
 201 own logical components: "mux" for the mode and "switch" for the orientation.
 202
 203 When a port is registered, USB Type-C Connector Class requests both the mux and
 204 the switch for the port. The drivers can then use the following API for
 205 controlling them:
 206
 207 .. kernel-doc:: drivers/usb/typec/class.c
 208    :functions: typec_set_orientation typec_set_mode
 209
 210 If the connector is dual-role capable, there may also be a switch for the data
 211 role. USB Type-C Connector Class does not supply separate API for them. The
 212 port drivers can use USB Role Class API with those.
 213
 214 Illustration of the muxes behind a connector that supports an alternate mode::
 215
 216                      ------------------------
 217                      |       Connector      |
 218                      ------------------------
 219                             |         |
 220                      ------------------------
 221                       \     Orientation    /
 222                        --------------------
 223                                 |
 224                        --------------------
 225                       /        Mode        \
 226                      ------------------------
 227                          /              \
 228       ------------------------        --------------------
 229       |       Alt Mode       |       /      USB Role      \
 230       ------------------------      ------------------------
 231                                          /            \
 232                      ------------------------      ------------------------
 233                      |       USB Host       |      |       USB Device     |
 234                      ------------------------      ------------------------