Commit fab92884 authored by Heikki Krogerus's avatar Heikki Krogerus Committed by Greg Kroah-Hartman
Browse files

usb: USB Type-C connector class 



The purpose of USB Type-C connector class is to provide
unified interface for the user space to get the status and
basic information about USB Type-C connectors on a system,
control over data role swapping, and when the port supports
USB Power Delivery, also control over power role swapping
and Alternate Modes.

Signed-off-by: default avatarHeikki Krogerus <heikki.krogerus@linux.intel.com>
Reviewed-by: default avatarMika Westerberg <mika.westerberg@linux.intel.com>
Reviewed-and-Tested-by: default avatarFelipe Balbi <felipe.balbi@linux.intel.com>
Tested-by: default avatarGuenter Roeck <linux@roeck-us.net>
Signed-off-by: default avatarGreg Kroah-Hartman <gregkh@linuxfoundation.org>
parent e1fe7b6a

Documentation/ABI/testing/sysfs-class-typec

0 → 100644
+276 −0
Original line number Diff line number Diff line 
USB Type-C port devices (eg. /sys/class/typec/port0/)



What:		/sys/class/typec/<port>/data_role

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		The supported USB data roles. This attribute can be used for

		requesting data role swapping on the port. Swapping is supported

		as synchronous operation, so write(2) to the attribute will not

		return until the operation has finished. The attribute is

		notified about role changes so that poll(2) on the attribute

		wakes up. Change on the role will also generate uevent

		KOBJ_CHANGE on the port. The current role is show in brackets,

		for example "[host] device" when DRP port is in host mode.



		Valid values: host, device



What:		/sys/class/typec/<port>/power_role

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		The supported power roles. This attribute can be used to request

		power role swap on the port when the port supports USB Power

		Delivery. Swapping is supported as synchronous operation, so

		write(2) to the attribute will not return until the operation

		has finished. The attribute is notified about role changes so

		that poll(2) on the attribute wakes up. Change on the role will

		also generate uevent KOBJ_CHANGE. The current role is show in

		brackets, for example "[source] sink" when in source mode.



		Valid values: source, sink



What:		/sys/class/typec/<port>/vconn_source

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Shows is the port VCONN Source. This attribute can be used to

		request VCONN swap to change the VCONN Source during connection

		when both the port and the partner support USB Power Delivery.

		Swapping is supported as synchronous operation, so write(2) to

		the attribute will not return until the operation has finished.

		The attribute is notified about VCONN source changes so that

		poll(2) on the attribute wakes up. Change on VCONN source also

		generates uevent KOBJ_CHANGE.



		Valid values:

		- "no" when the port is not the VCONN Source

		- "yes" when the port is the VCONN Source



What:		/sys/class/typec/<port>/power_operation_mode

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Shows the current power operational mode the port is in. The

		power operation mode means current level for VBUS. In case USB

		Power Delivery communication is used for negotiating the levels,

		power operation mode should show "usb_power_delivery".



		Valid values:

		- default

		- 1.5A

		- 3.0A

		- usb_power_delivery



What:		/sys/class/typec/<port>/preferred_role

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		The user space can notify the driver about the preferred role.

		It should be handled as enabling of Try.SRC or Try.SNK, as

		defined in USB Type-C specification, in the port drivers. By

		default the preferred role should come from the platform.



		Valid values: source, sink, none (to remove preference)



What:		/sys/class/typec/<port>/supported_accessory_modes

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Space separated list of accessory modes, defined in the USB

		Type-C specification, the port supports.



What:		/sys/class/typec/<port>/usb_power_delivery_revision

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Revision number of the supported USB Power Delivery

		specification, or 0 when USB Power Delivery is not supported.



What:		/sys/class/typec/<port>/usb_typec_revision

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Revision number of the supported USB Type-C specification.





USB Type-C partner devices (eg. /sys/class/typec/port0-partner/)



What:		/sys/class/typec/<port>-partner/accessory_mode

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Shows the Accessory Mode name when the partner is an Accessory.

		The Accessory Modes are defined in USB Type-C Specification.



What:		/sys/class/typec/<port>-partner/supports_usb_power_delivery

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Shows if the partner supports USB Power Delivery communication:

		Valid values: yes, no



What:		/sys/class/typec/<port>-partner>/identity/

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		This directory appears only if the port device driver is capable

		of showing the result of Discover Identity USB power delivery

		command. That will not always be possible even when USB power

		delivery is supported, for example when USB power delivery

		communication for the port is mostly handled in firmware. If the

		directory exists, it will have an attribute file for every VDO

		in Discover Identity command result.



What:		/sys/class/typec/<port>-partner/identity/id_header

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		ID Header VDO part of Discover Identity command result. The

		value will show 0 until Discover Identity command result becomes

		available. The value can be polled.



What:		/sys/class/typec/<port>-partner/identity/cert_stat

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Cert Stat VDO part of Discover Identity command result. The

		value will show 0 until Discover Identity command result becomes

		available. The value can be polled.



What:		/sys/class/typec/<port>-partner/identity/product

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Product VDO part of Discover Identity command result. The value

		will show 0 until Discover Identity command result becomes

		available. The value can be polled.





USB Type-C cable devices (eg. /sys/class/typec/port0-cable/)



Note: Electronically Marked Cables will have a device also for one cable plug

(eg. /sys/class/typec/port0-plug0). If the cable is active and has also SOP

Double Prime controller (USB Power Deliver specification ch. 2.4) it will have

second device also for the other plug. Both plugs may have alternate modes as

described in USB Type-C and USB Power Delivery specifications.



What:		/sys/class/typec/<port>-cable/type

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Shows if the cable is active.

		Valid values: active, passive



What:		/sys/class/typec/<port>-cable/plug_type

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Shows type of the plug on the cable:

		- type-a - Standard A

		- type-b - Standard B

		- type-c

		- captive



What:		/sys/class/typec/<port>-cable/identity/

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		This directory appears only if the port device driver is capable

		of showing the result of Discover Identity USB power delivery

		command. That will not always be possible even when USB power

		delivery is supported. If the directory exists, it will have an

		attribute for every VDO returned by Discover Identity command.



What:		/sys/class/typec/<port>-cable/identity/id_header

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		ID Header VDO part of Discover Identity command result. The

		value will show 0 until Discover Identity command result becomes

		available. The value can be polled.



What:		/sys/class/typec/<port>-cable/identity/cert_stat

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Cert Stat VDO part of Discover Identity command result. The

		value will show 0 until Discover Identity command result becomes

		available. The value can be polled.



What:		/sys/class/typec/<port>-cable/identity/product

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Product VDO part of Discover Identity command result. The value

		will show 0 until Discover Identity command result becomes

		available. The value can be polled.





Alternate Mode devices.



The alternate modes will have Standard or Vendor ID (SVID) assigned by USB-IF.

The ports, partners and cable plugs can have alternate modes. A supported SVID

will consist of a set of modes. Every SVID a port/partner/plug supports will

have a device created for it, and every supported mode for a supported SVID will

have its own directory under that device. Below <dev> refers to the device for

the alternate mode.



What:		/sys/class/typec/<port|partner|cable>/<dev>/svid

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		The SVID (Standard or Vendor ID) assigned by USB-IF for this

		alternate mode.



What:		/sys/class/typec/<port|partner|cable>/<dev>/mode<index>/

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Every supported mode will have its own directory. The name of

		a mode will be "mode<index>" (for example mode1), where <index>

		is the actual index to the mode VDO returned by Discover Modes

		USB power delivery command.



What:		/sys/class/typec/<port|partner|cable>/<dev>/mode<index>/description

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Shows description of the mode. The description is optional for

		the drivers, just like with the Billboard Devices.



What:		/sys/class/typec/<port|partner|cable>/<dev>/mode<index>/vdo

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Shows the VDO in hexadecimal returned by Discover Modes command

		for this mode.



What:		/sys/class/typec/<port|partner|cable>/<dev>/mode<index>/active

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Shows if the mode is active or not. The attribute can be used

		for entering/exiting the mode with partners and cable plugs, and

		with the port alternate modes it can be used for disabling

		support for specific alternate modes. Entering/exiting modes is

		supported as synchronous operation so write(2) to the attribute

		does not return until the enter/exit mode operation has

		finished. The attribute is notified when the mode is

		entered/exited so poll(2) on the attribute wakes up.

		Entering/exiting a mode will also generate uevent KOBJ_CHANGE.



		Valid values: yes, no



What:		/sys/class/typec/<port>/<dev>/mode<index>/supported_roles

Date:		April 2017

Contact:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

Description:

		Space separated list of the supported roles.



		This attribute is available for the devices describing the

		alternate modes a port supports, and it will not be exposed with

		the devices presenting the alternate modes the partners or cable

		plugs support.



		Valid values: source, sink

Documentation/usb/typec.rst

0 → 100644
+184 −0
Original line number Diff line number Diff line 


USB Type-C connector class

==========================



Introduction

------------



The typec class is meant for describing the USB Type-C ports in a system to the

user space in unified fashion. The class is designed to provide nothing else

except the user space interface implementation in hope that it can be utilized

on as many platforms as possible.



The platforms are expected to register every USB Type-C port they have with the

class. In a normal case the registration will be done by a USB Type-C or PD PHY

driver, but it may be a driver for firmware interface such as UCSI, driver for

USB PD controller or even driver for Thunderbolt3 controller. This document

considers the component registering the USB Type-C ports with the class as "port

driver".



On top of showing the capabilities, the class also offer user space control over

the roles and alternate modes of ports, partners and cable plugs when the port

driver is capable of supporting those features.



The class provides an API for the port drivers described in this document. The

attributes are described in Documentation/ABI/testing/sysfs-class-typec.



User space interface

--------------------

Every port will be presented as its own device under /sys/class/typec/. The

first 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 it

is 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 own

devices under /sys/class/typec/. The cable attached to the port "port0" port

will be named port0-cable and the plug on the SOP Prime end (see USB Power

Delivery Specification ch. 2.4) will be named "port0-plug0" and on the SOP

Double 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 supported

Alternate Mode SVID will have their own device describing them. Note that the

Alternate Mode devices will not be attached to the typec class. The parent of an

alternate mode will be the device that supports it, so for example an alternate

mode 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 Mode

device named "mode<index>", for example /sys/class/typec/port0/<alternate

mode>/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 with struct

typec_capability data structure, and register them with the following API:



.. kernel-doc:: drivers/usb/typec/typec.c

   :functions: typec_register_port typec_unregister_port



When registering the ports, the prefer_role member in struct typec_capability

deserves special notice. If the port that is being registered does not have

initial role preference, which means the port does not execute Try.SNK or

Try.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 value

TYPEC_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 the

partner with the class. Details about the partner need to be described in struct

typec_partner_desc. The class copies the details of the partner during

registration. The class offers the following API for registering/unregistering

partners.



.. kernel-doc:: drivers/usb/typec/typec.c

   :functions: typec_register_partner typec_unregister_partner



The class will provide a handle to struct typec_partner if the registration was

successful, or NULL.



If the partner is USB Power Delivery capable, and the port driver is able to

show the result of Discover Identity command, the partner descriptor structure

should include handle to struct usb_pd_identity instance. The class will then

create a sysfs directory for the identity under the partner device. The result

of Discover Identity command can then be reported with the following API:



.. kernel-doc:: drivers/usb/typec/typec.c

   :functions: typec_partner_set_identity



Registering Cables

~~~~~~~~~~~~~~~~~~



After successful connection of a cable that supports USB Power Delivery

Structured VDM "Discover Identity", the port driver needs to register the cable

and one or two plugs, depending if there is CC Double Prime controller present

in the cable or not. So a cable capable of SOP Prime communication, but not SOP

Double Prime communication, should only have one plug registered. For more

information about SOP communication, please read chapter about it from the

latest 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 device

for the plugs. Details about the cable need to be described in struct

typec_cable_desc and about a plug in struct typec_plug_desc. The class copies

the details during registration. The class offers the following API for

registering/unregistering cables and their plugs:



.. kernel-doc:: drivers/usb/typec/typec.c

   :functions: typec_register_cable typec_unregister_cable typec_register_plug

   typec_unregister_plug



The class will provide a handle to struct typec_cable and struct typec_plug if

the registration is successful, or NULL if it isn't.



If the cable is USB Power Delivery capable, and the port driver is able to show

the result of Discover Identity command, the cable descriptor structure should

include handle to struct usb_pd_identity instance. The class will then create a

sysfs directory for the identity under the cable device. The result of Discover

Identity command can then be reported with the following API:



.. kernel-doc:: drivers/usb/typec/typec.c

   :functions: typec_cable_set_identity



Notifications

~~~~~~~~~~~~~



When the partner has executed a role change, or when the default roles change

during connection of a partner or cable, the port driver must use the following

APIs to report it to the class:



.. kernel-doc:: drivers/usb/typec/typec.c

   :functions: typec_set_data_role typec_set_pwr_role typec_set_vconn_role

   typec_set_pwr_opmode



Alternate Modes

~~~~~~~~~~~~~~~



USB Type-C ports, partners and cable plugs may support Alternate Modes. Each

Alternate Mode will have identifier called SVID, which is either a Standard ID

given by USB-IF or vendor ID, and each supported SVID can have 1 - 6 modes. The

class provides struct typec_mode_desc for describing individual mode of a SVID,

and struct typec_altmode_desc which is a container for all the supported modes.



Ports that support Alternate Modes need to register each SVID they support with

the following API:



.. kernel-doc:: drivers/usb/typec/typec.c

   :functions: typec_port_register_altmode



If a partner or cable plug provides a list of SVIDs as response to USB Power

Delivery Structured VDM Discover SVIDs message, each SVID needs to be

registered.



API for the partners:



.. kernel-doc:: drivers/usb/typec/typec.c

   :functions: typec_partner_register_altmode



API for the Cable Plugs:



.. kernel-doc:: drivers/usb/typec/typec.c

   :functions: typec_plug_register_altmode



So ports, partners and cable plugs will register the alternate modes with their

own functions, but the registration will always return a handle to struct

typec_altmode on success, or NULL. The unregistration will happen with the same

function:



.. kernel-doc:: drivers/usb/typec/typec.c

   :functions: typec_unregister_altmode



If a partner or cable plug enters or exits a mode, the port driver needs to

notify the class with the following API:



.. kernel-doc:: drivers/usb/typec/typec.c

   :functions: typec_altmode_update_active

MAINTAINERS

+9 −0
Original line number Diff line number Diff line
@@ -13100,6 +13100,15 @@ F: drivers/usb/ 
F:	include/linux/usb.h

F:	include/linux/usb/



USB TYPEC SUBSYSTEM

M:	Heikki Krogerus <heikki.krogerus@linux.intel.com>

L:	linux-usb@vger.kernel.org

S:	Maintained

F:	Documentation/ABI/testing/sysfs-class-typec

F:	Documentation/usb/typec.rst

F:	drivers/usb/typec/

F:	include/linux/usb/typec.h



USB UHCI DRIVER

M:	Alan Stern <stern@rowland.harvard.edu>

L:	linux-usb@vger.kernel.org

drivers/usb/Kconfig

+2 −0
Original line number Diff line number Diff line
@@ -162,6 +162,8 @@ source "drivers/usb/phy/Kconfig" 


source "drivers/usb/gadget/Kconfig"



source "drivers/usb/typec/Kconfig"



config USB_LED_TRIG

	bool "USB LED Triggers"

	depends on LEDS_CLASS && LEDS_TRIGGERS

drivers/usb/Makefile

+2 −0
Original line number Diff line number Diff line
@@ -62,3 +62,5 @@ obj-$(CONFIG_USB_GADGET) += gadget/ 
obj-$(CONFIG_USB_COMMON)	+= common/



obj-$(CONFIG_USBIP_CORE)	+= usbip/



obj-$(CONFIG_TYPEC)		+= typec/

CRA Git | Maintained and supported by SUSTech CRA and CCSE