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