235 lines · plain
1.. _typec:2 3USB Type-C connector class4==========================5 6Introduction7------------8 9The typec class is meant for describing the USB Type-C ports in a system to the10user space in unified fashion. The class is designed to provide nothing else11except the user space interface implementation in hope that it can be utilized12on as many platforms as possible.13 14The platforms are expected to register every USB Type-C port they have with the15class. In a normal case the registration will be done by a USB Type-C or PD PHY16driver, but it may be a driver for firmware interface such as UCSI, driver for17USB PD controller or even driver for Thunderbolt3 controller. This document18considers the component registering the USB Type-C ports with the class as "port19driver".20 21On top of showing the capabilities, the class also offer user space control over22the roles and alternate modes of ports, partners and cable plugs when the port23driver is capable of supporting those features.24 25The class provides an API for the port drivers described in this document. The26attributes are described in Documentation/ABI/testing/sysfs-class-typec.27 28User space interface29--------------------30Every port will be presented as its own device under /sys/class/typec/. The31first port will be named "port0", the second "port1" and so on.32 33When connected, the partner will be presented also as its own device under34/sys/class/typec/. The parent of the partner device will always be the port it35is attached to. The partner attached to port "port0" will be named36"port0-partner". Full path to the device would be37/sys/class/typec/port0/port0-partner/.38 39The cable and the two plugs on it may also be optionally presented as their own40devices under /sys/class/typec/. The cable attached to the port "port0" port41will be named port0-cable and the plug on the SOP Prime end (see USB Power42Delivery Specification ch. 2.4) will be named "port0-plug0" and on the SOP43Double Prime end "port0-plug1". The parent of a cable will always be the port,44and the parent of the cable plugs will always be the cable.45 46If the port, partner or cable plug supports Alternate Modes, every supported47Alternate Mode SVID will have their own device describing them. Note that the48Alternate Mode devices will not be attached to the typec class. The parent of an49alternate mode will be the device that supports it, so for example an alternate50mode of port0-partner will be presented under /sys/class/typec/port0-partner/.51Every mode that is supported will have its own group under the Alternate Mode52device named "mode<index>", for example /sys/class/typec/port0/<alternate53mode>/mode1/. The requests for entering/exiting a mode can be done with "active"54attribute file in that group.55 56Driver API57----------58 59Registering the ports60~~~~~~~~~~~~~~~~~~~~~61 62The port drivers will describe every Type-C port they control with struct63typec_capability data structure, and register them with the following API:64 65.. kernel-doc:: drivers/usb/typec/class.c66 :functions: typec_register_port typec_unregister_port67 68When registering the ports, the prefer_role member in struct typec_capability69deserves special notice. If the port that is being registered does not have70initial role preference, which means the port does not execute Try.SNK or71Try.SRC by default, the member must have value TYPEC_NO_PREFERRED_ROLE.72Otherwise if the port executes Try.SNK by default, the member must have value73TYPEC_DEVICE, and with Try.SRC the value must be TYPEC_HOST.74 75Registering Partners76~~~~~~~~~~~~~~~~~~~~77 78After successful connection of a partner, the port driver needs to register the79partner with the class. Details about the partner need to be described in struct80typec_partner_desc. The class copies the details of the partner during81registration. The class offers the following API for registering/unregistering82partners.83 84.. kernel-doc:: drivers/usb/typec/class.c85 :functions: typec_register_partner typec_unregister_partner86 87The class will provide a handle to struct typec_partner if the registration was88successful, or NULL.89 90If the partner is USB Power Delivery capable, and the port driver is able to91show the result of Discover Identity command, the partner descriptor structure92should include handle to struct usb_pd_identity instance. The class will then93create a sysfs directory for the identity under the partner device. The result94of Discover Identity command can then be reported with the following API:95 96.. kernel-doc:: drivers/usb/typec/class.c97 :functions: typec_partner_set_identity98 99Registering Cables100~~~~~~~~~~~~~~~~~~101 102After successful connection of a cable that supports USB Power Delivery103Structured VDM "Discover Identity", the port driver needs to register the cable104and one or two plugs, depending if there is CC Double Prime controller present105in the cable or not. So a cable capable of SOP Prime communication, but not SOP106Double Prime communication, should only have one plug registered. For more107information about SOP communication, please read chapter about it from the108latest USB Power Delivery specification.109 110The plugs are represented as their own devices. The cable is registered first,111followed by registration of the cable plugs. The cable will be the parent device112for the plugs. Details about the cable need to be described in struct113typec_cable_desc and about a plug in struct typec_plug_desc. The class copies114the details during registration. The class offers the following API for115registering/unregistering cables and their plugs:116 117.. kernel-doc:: drivers/usb/typec/class.c118 :functions: typec_register_cable typec_unregister_cable typec_register_plug typec_unregister_plug119 120The class will provide a handle to struct typec_cable and struct typec_plug if121the registration is successful, or NULL if it isn't.122 123If the cable is USB Power Delivery capable, and the port driver is able to show124the result of Discover Identity command, the cable descriptor structure should125include handle to struct usb_pd_identity instance. The class will then create a126sysfs directory for the identity under the cable device. The result of Discover127Identity command can then be reported with the following API:128 129.. kernel-doc:: drivers/usb/typec/class.c130 :functions: typec_cable_set_identity131 132Notifications133~~~~~~~~~~~~~134 135When the partner has executed a role change, or when the default roles change136during connection of a partner or cable, the port driver must use the following137APIs to report it to the class:138 139.. kernel-doc:: drivers/usb/typec/class.c140 :functions: typec_set_data_role typec_set_pwr_role typec_set_vconn_role typec_set_pwr_opmode141 142Alternate Modes143~~~~~~~~~~~~~~~144 145USB Type-C ports, partners and cable plugs may support Alternate Modes. Each146Alternate Mode will have identifier called SVID, which is either a Standard ID147given by USB-IF or vendor ID, and each supported SVID can have 1 - 6 modes. The148class provides struct typec_mode_desc for describing individual mode of a SVID,149and struct typec_altmode_desc which is a container for all the supported modes.150 151Ports that support Alternate Modes need to register each SVID they support with152the following API:153 154.. kernel-doc:: drivers/usb/typec/class.c155 :functions: typec_port_register_altmode156 157If a partner or cable plug provides a list of SVIDs as response to USB Power158Delivery Structured VDM Discover SVIDs message, each SVID needs to be159registered.160 161API for the partners:162 163.. kernel-doc:: drivers/usb/typec/class.c164 :functions: typec_partner_register_altmode165 166API for the Cable Plugs:167 168.. kernel-doc:: drivers/usb/typec/class.c169 :functions: typec_plug_register_altmode170 171So ports, partners and cable plugs will register the alternate modes with their172own functions, but the registration will always return a handle to struct173typec_altmode on success, or NULL. The unregistration will happen with the same174function:175 176.. kernel-doc:: drivers/usb/typec/class.c177 :functions: typec_unregister_altmode178 179If a partner or cable plug enters or exits a mode, the port driver needs to180notify the class with the following API:181 182.. kernel-doc:: drivers/usb/typec/class.c183 :functions: typec_altmode_update_active184 185Multiplexer/DeMultiplexer Switches186~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~187 188USB Type-C connectors may have one or more mux/demux switches behind them. Since189the plugs can be inserted right-side-up or upside-down, a switch is needed to190route the correct data pairs from the connector to the USB controllers. If191Alternate or Accessory Modes are supported, another switch is needed that can192route the pins on the connector to some other component besides USB. USB Type-C193Connector Class supplies an API for registering those switches.194 195.. kernel-doc:: drivers/usb/typec/mux.c196 :functions: typec_switch_register typec_switch_unregister typec_mux_register typec_mux_unregister197 198In most cases the same physical mux will handle both the orientation and mode.199However, as the port drivers will be responsible for the orientation, and the200alternate mode drivers for the mode, the two are always separated into their201own logical components: "mux" for the mode and "switch" for the orientation.202 203When a port is registered, USB Type-C Connector Class requests both the mux and204the switch for the port. The drivers can then use the following API for205controlling them:206 207.. kernel-doc:: drivers/usb/typec/class.c208 :functions: typec_set_orientation typec_set_mode209 210If the connector is dual-role capable, there may also be a switch for the data211role. USB Type-C Connector Class does not supply separate API for them. The212port drivers can use USB Role Class API with those.213 214Illustration 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 ------------------------ ------------------------235