USB Type-C connector class

Introduction

The typec class is meant for describing the USB Type-C ports in a system to theuser space in unified fashion. The class is designed to provide nothing elseexcept the user space interface implementation in hope that it can be utilizedon as many platforms as possible.

The platforms are expected to register every USB Type-C port they have with theclass. In a normal case the registration will be done by a USB Type-C or PD PHYdriver, but it may be a driver for firmware interface such as UCSI, driver forUSB PD controller or even driver for Thunderbolt3 controller. This documentconsiders the component registering the USB Type-C ports with the class as “portdriver”.

On top of showing the capabilities, the class also offer user space control overthe roles and alternate modes of ports, partners and cable plugs when the portdriver is capable of supporting those features.

The class provides an API for the port drivers described in this document. Theattributes are described inABI file testing/sysfs-class-typec.

User space interface

Every port will be presented as its own device under /sys/class/typec/. Thefirst port will be named “port0”, the second “port1” and so on.

When connected, the partner will be presented also as its own device under/sys/class/typec/. The parent of the partner device will always be the port itis attached to. The partner attached to port “port0” will be named“port0-partner”. Full path to the device would be/sys/class/typec/port0/port0-partner/.

The cable and the two plugs on it may also be optionally presented as their owndevices under /sys/class/typec/. The cable attached to the port “port0” portwill be named port0-cable and the plug on the SOP Prime end (see USB PowerDelivery Specification ch. 2.4) will be named “port0-plug0” and on the SOPDouble Prime end “port0-plug1”. The parent of a cable will always be the port,and the parent of the cable plugs will always be the cable.

If the port, partner or cable plug supports Alternate Modes, every supportedAlternate Mode SVID will have their own device describing them. Note that theAlternate Mode devices will not be attached to the typec class. The parent of analternate mode will be the device that supports it, so for example an alternatemode of port0-partner will be presented under /sys/class/typec/port0-partner/.Every mode that is supported will have its own group under the Alternate Modedevice named “mode<index>”, for example /sys/class/typec/port0/<alternatemode>/mode1/. The requests for entering/exiting a mode can be done with “active”attribute file in that group.

Driver API

Registering the ports

The port drivers will describe every Type-C port they control withstructtypec_capability data structure, and register them with the following API:

structtypec_port*typec_register_port(structdevice*parent,conststructtypec_capability*cap)

Register a USB Type-C Port

Parameters

structdevice*parent

Parent device

conststructtypec_capability*cap

Description of the port

Description

Registers a device for USB Type-C Port described incap.

Returns handle to the port on success or ERR_PTR on failure.

voidtypec_unregister_port(structtypec_port*port)

Unregister a USB Type-C Port

Parameters

structtypec_port*port

The port to be unregistered

Description

Unregister device created withtypec_register_port().

When registering the ports, the prefer_role member instructtypec_capabilitydeserves special notice. If the port that is being registered does not haveinitial role preference, which means the port does not execute Try.SNK orTry.SRC by default, the member must have value TYPEC_NO_PREFERRED_ROLE.Otherwise if the port executes Try.SNK by default, the member must have valueTYPEC_DEVICE, and with Try.SRC the value must be TYPEC_HOST.

Registering Partners

After successful connection of a partner, the port driver needs to register thepartner with the class. Details about the partner need to be described instructtypec_partner_desc. The class copies the details of the partner duringregistration. The class offers the following API for registering/unregisteringpartners.

structtypec_partner*typec_register_partner(structtypec_port*port,structtypec_partner_desc*desc)

Register a USB Type-C Partner

Parameters

structtypec_port*port

The USB Type-C Port the partner is connected to

structtypec_partner_desc*desc

Description of the partner

Description

Registers a device for USB Type-C Partner described indesc.

Returns handle to the partner on success or ERR_PTR on failure.

voidtypec_unregister_partner(structtypec_partner*partner)

Unregister a USB Type-C Partner

Parameters

structtypec_partner*partner

The partner to be unregistered

Description

Unregister device created withtypec_register_partner().

The class will provide a handle tostructtypec_partner if the registration wassuccessful, or NULL.

If the partner is USB Power Delivery capable, and the port driver is able toshow the result of Discover Identity command, the partner descriptor structureshould include handle tostructusb_pd_identity instance. The class will thencreate a sysfs directory for the identity under the partner device. The resultof Discover Identity command can then be reported with the following API:

inttypec_partner_set_identity(structtypec_partner*partner)

Report result from Discover Identity command

Parameters

structtypec_partner*partner

The partner updated identity values

Description

This routine is used to report that the result of Discover Identity USB powerdelivery command has become available.

Registering Cables

After successful connection of a cable that supports USB Power DeliveryStructured VDM “Discover Identity”, the port driver needs to register the cableand one or two plugs, depending if there is CC Double Prime controller presentin the cable or not. So a cable capable of SOP Prime communication, but not SOPDouble Prime communication, should only have one plug registered. For moreinformation about SOP communication, please read chapter about it from thelatest USB Power Delivery specification.

The plugs are represented as their own devices. The cable is registered first,followed by registration of the cable plugs. The cable will be the parent devicefor the plugs. Details about the cable need to be described instructtypec_cable_desc and about a plug instructtypec_plug_desc. The class copiesthe details during registration. The class offers the following API forregistering/unregistering cables and their plugs:

structtypec_plug*typec_register_plug(structtypec_cable*cable,structtypec_plug_desc*desc)

Register a USB Type-C Cable Plug

Parameters

structtypec_cable*cable

USB Type-C Cable with the plug

structtypec_plug_desc*desc

Description of the cable plug

Description

Registers a device for USB Type-C Cable Plug described indesc. A USB Type-CCable Plug represents a plug with electronics in it that can response to USBPower Delivery SOP Prime or SOP Double Prime packages.

Returns handle to the cable plug on success or ERR_PTR on failure.

voidtypec_unregister_plug(structtypec_plug*plug)

Unregister a USB Type-C Cable Plug

Parameters

structtypec_plug*plug

The cable plug to be unregistered

Description

Unregister device created withtypec_register_plug().

structtypec_cable*typec_register_cable(structtypec_port*port,structtypec_cable_desc*desc)

Register a USB Type-C Cable

Parameters

structtypec_port*port

The USB Type-C Port the cable is connected to

structtypec_cable_desc*desc

Description of the cable

Description

Registers a device for USB Type-C Cable described indesc. The cable will beparent for the optional cable plug devises.

Returns handle to the cable on success or ERR_PTR on failure.

voidtypec_unregister_cable(structtypec_cable*cable)

Unregister a USB Type-C Cable

Parameters

structtypec_cable*cable

The cable to be unregistered

Description

Unregister device created withtypec_register_cable().

The class will provide a handle tostructtypec_cable andstructtypec_plug ifthe registration is successful, or NULL if it isn’t.

If the cable is USB Power Delivery capable, and the port driver is able to showthe result of Discover Identity command, the cable descriptor structure shouldinclude handle tostructusb_pd_identity instance. The class will then create asysfs directory for the identity under the cable device. The result of DiscoverIdentity command can then be reported with the following API:

inttypec_cable_set_identity(structtypec_cable*cable)

Report result from Discover Identity command

Parameters

structtypec_cable*cable

The cable updated identity values

Description

This routine is used to report that the result of Discover Identity USB powerdelivery command has become available.

Notifications

When the partner has executed a role change, or when the default roles changeduring connection of a partner or cable, the port driver must use the followingAPIs to report it to the class:

voidtypec_set_data_role(structtypec_port*port,enumtypec_data_rolerole)

Report data role change

Parameters

structtypec_port*port

The USB Type-C Port where the role was changed

enumtypec_data_rolerole

The new data role

Description

This routine is used by the port drivers to report data role changes.

voidtypec_set_pwr_role(structtypec_port*port,enumtypec_rolerole)

Report power role change

Parameters

structtypec_port*port

The USB Type-C Port where the role was changed

enumtypec_rolerole

The new data role

Description

This routine is used by the port drivers to report power role changes.

voidtypec_set_vconn_role(structtypec_port*port,enumtypec_rolerole)

Report VCONN source change

Parameters

structtypec_port*port

The USB Type-C Port which VCONN role changed

enumtypec_rolerole

Source whenport is sourcing VCONN, or Sink when it’s not

Description

This routine is used by the port drivers to report if the VCONN source ischanges.

voidtypec_set_pwr_opmode(structtypec_port*port,enumtypec_pwr_opmodeopmode)

Report changed power operation mode

Parameters

structtypec_port*port

The USB Type-C Port where the mode was changed

enumtypec_pwr_opmodeopmode

New power operation mode

Description

This routine is used by the port drivers to report changed power operationmode inport. The modes are USB (default), 1.5A, 3.0A as defined in USBType-C specification, and “USB Power Delivery” when the power levels arenegotiated with methods defined in USB Power Delivery specification.

Alternate Modes

USB Type-C ports, partners and cable plugs may support Alternate Modes. EachAlternate Mode will have identifier called SVID, which is either a Standard IDgiven by USB-IF or vendor ID, and each supported SVID can have 1 - 6 modes. Theclass providesstructtypec_mode_desc for describing individual mode of a SVID,andstructtypec_altmode_desc which is a container for all the supported modes.

Ports that support Alternate Modes need to register each SVID they support withthe following API:

structtypec_altmode*typec_port_register_altmode(structtypec_port*port,conststructtypec_altmode_desc*desc)

Register USB Type-C Port Alternate Mode

Parameters

structtypec_port*port

USB Type-C Port that supports the alternate mode

conststructtypec_altmode_desc*desc

Description of the alternate mode

Description

This routine is used to register an alternate mode thatport is capable ofsupporting.

Returns handle to the alternate mode on success or ERR_PTR on failure.

If a partner or cable plug provides a list of SVIDs as response to USB PowerDelivery Structured VDM Discover SVIDs message, each SVID needs to beregistered.

API for the partners:

structtypec_altmode*typec_partner_register_altmode(structtypec_partner*partner,conststructtypec_altmode_desc*desc)

Register USB Type-C Partner Alternate Mode

Parameters

structtypec_partner*partner

USB Type-C Partner that supports the alternate mode

conststructtypec_altmode_desc*desc

Description of the alternate mode

Description

This routine is used to register each alternate mode individually thatpartner has listed in response to Discover SVIDs command. The modes for aSVID listed in response to Discover Modes command need to be listed in anarray indesc.

Returns handle to the alternate mode on success or ERR_PTR on failure.

API for the Cable Plugs:

structtypec_altmode*typec_plug_register_altmode(structtypec_plug*plug,conststructtypec_altmode_desc*desc)

Register USB Type-C Cable Plug Alternate Mode

Parameters

structtypec_plug*plug

USB Type-C Cable Plug that supports the alternate mode

conststructtypec_altmode_desc*desc

Description of the alternate mode

Description

This routine is used to register each alternate mode individually thatplughas listed in response to Discover SVIDs command. The modes for a SVID thatthe plug lists in response to Discover Modes command need to be listed in anarray indesc.

Returns handle to the alternate mode on success or ERR_PTR on failure.

So ports, partners and cable plugs will register the alternate modes with theirown functions, but the registration will always return a handle tostructtypec_altmode on success, or NULL. The unregistration will happen with the samefunction:

voidtypec_unregister_altmode(structtypec_altmode*adev)

Unregister Alternate Mode

Parameters

structtypec_altmode*adev

The alternate mode to be unregistered

Description

Unregister device created withtypec_partner_register_altmode(),typec_plug_register_altmode() ortypec_port_register_altmode().

If a partner or cable plug enters or exits a mode, the port driver needs tonotify the class with the following API:

voidtypec_altmode_update_active(structtypec_altmode*adev,boolactive)

Report Enter/Exit mode

Parameters

structtypec_altmode*adev

Handle to the alternate mode

boolactive

True when the mode has been entered

Description

If a partner or cable plug executes Enter/Exit Mode command successfully, thedrivers use this routine to report the updated state of the mode.

Multiplexer/DeMultiplexer Switches

USB Type-C connectors may have one or more mux/demux switches behind them. Sincethe plugs can be inserted right-side-up or upside-down, a switch is needed toroute the correct data pairs from the connector to the USB controllers. IfAlternate or Accessory Modes are supported, another switch is needed that canroute the pins on the connector to some other component besides USB. USB Type-CConnector Class supplies an API for registering those switches.

structtypec_switch_dev*typec_switch_register(structdevice*parent,conststructtypec_switch_desc*desc)

Register USB Type-C orientation switch

Parameters

structdevice*parent

Parent device

conststructtypec_switch_desc*desc

Orientation switch description

Description

This function registers a switch that can be used for routing the correctdata pairs depending on the cable plug orientation from the USB Type-Cconnector to the USB controllers. USB Type-C plugs can be insertedright-side-up or upside-down.

voidtypec_switch_unregister(structtypec_switch_dev*sw_dev)

Unregister USB Type-C orientation switch

Parameters

structtypec_switch_dev*sw_dev

USB Type-C orientation switch

Description

Unregister switch that was registered withtypec_switch_register().

structtypec_mux_dev*typec_mux_register(structdevice*parent,conststructtypec_mux_desc*desc)

Register Multiplexer routing USB Type-C pins

Parameters

structdevice*parent

Parent device

conststructtypec_mux_desc*desc

Multiplexer description

Description

USB Type-C connectors can be used for alternate modes of operation besidesUSB when Accessory/Alternate Modes are supported. With some of those modes,the pins on the connector need to be reconfigured. This function registersmultiplexer switches routing the pins on the connector.

voidtypec_mux_unregister(structtypec_mux_dev*mux_dev)

Unregister Multiplexer Switch

Parameters

structtypec_mux_dev*mux_dev

USB Type-C Connector Multiplexer/DeMultiplexer

Description

Unregister mux that was registered withtypec_mux_register().

In most cases the same physical mux will handle both the orientation and mode.However, as the port drivers will be responsible for the orientation, and thealternate mode drivers for the mode, the two are always separated into theirown logical components: “mux” for the mode and “switch” for the orientation.

When a port is registered, USB Type-C Connector Class requests both the mux andthe switch for the port. The drivers can then use the following API forcontrolling them:

inttypec_set_orientation(structtypec_port*port,enumtypec_orientationorientation)

Set USB Type-C cable plug orientation

Parameters

structtypec_port*port

USB Type-C Port

enumtypec_orientationorientation

USB Type-C cable plug orientation

Description

Set cable plug orientation forport.

inttypec_set_mode(structtypec_port*port,intmode)

Set mode of operation for USB Type-C connector

Parameters

structtypec_port*port

USB Type-C connector

intmode

Accessory Mode, USB Operation or Safe State

Description

Configureport for Accessory Modemode. This function will configure themuxes needed formode.

If the connector is dual-role capable, there may also be a switch for the datarole. USB Type-C Connector Class does not supply separate API for them. Theport drivers can use USB Role Class API with those.

Illustration of the muxes behind a connector that supports an alternate mode:

               ------------------------               |       Connector      |               ------------------------                      |         |               ------------------------                \     Orientation    /                 --------------------                          |                 --------------------                /        Mode        \               ------------------------                   /              \------------------------        --------------------|       Alt Mode       |       /      USB Role      \------------------------      ------------------------                                   /            \               ------------------------      ------------------------               |       USB Host       |      |       USB Device     |               ------------------------      ------------------------