Re: [PATCH 1/3] usb: USB Type-C Connector Class

[Heikki Krogerus]

Hi Oliver,

On Wed, Feb 17, 2016 at 03:07:27PM +0100, Oliver Neukum wrote:
> On Tue, 2016-02-09 at 19:01 +0200, Heikki Krogerus wrote:
> > 1. connected - Connection status of the connector
> > 2. alternate_mode - The current Alternate Mode
> > 3. alternate_modes - Lists all Alternate Modes the connector supports
> > 4. partner_alt_modes - Lists partner's Alternate Modes when connected
> 
> Now that I think about it, there's a gap.
> Which SVIDs do we expose if we are UFP (slave)?

In the alternate_modes listing the connectors alt modes, we can not
have modes that the hardware can not support of course, and it is the
responsibility of the drivers registering the type-c ports with this
clss to make sure they are not part of the list.

In partner alternate modes, we will list all alternate modes the
partner supports, even the ones our connector doesn't.

The modes that can actually be selected have to be supported by both
the connector and the partner, and this is where I'm putting the ball
on the userspace at the moment. I'm not offering a list of
"possible_alternate_modes" where I list the combination, but instead
expect the userspace to be figure out that on it's own.

Do you think we should add "possible_alternate_modes" file?


P.S. That reminds me, here's my current draft for the
Documentation/ABI/. Could you take a look?


Thanks,

-- 
heikki
What:		/sys/class/type-c/
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		USB Type-C Connectors can be used for other purposes than just
		connecting USB peripherals to USB host. Devices with USB Type-C
		connector can be of one of the following types:

		1. USB - In normal USB use
		2. Accessory Mode - Audio or Debug. Special purpose modes for
				    the connector which are defined in the USB
				    Type-C specification. When an Accessory is
				    connected to the connector, it can not be
				    used for anything besides what the Accessory
				    Mode defines, including USB.
		3. Alternate Mode - Modes where the connector can be used also
				    for other purposes then just connecting USB
				    peripherals to USB hosts, and which are not
				    defined in USB Type-C Specification. The
				    Alternate Modes depend on USB Power Delivery
				    support as they are controlled with protocol
				    defined in USB Power Delivery specification.

		There is also only one type of USB Type-C Connector, so
		the connector will be the same for both host and peripheral. If
		two systems that are both dual-role capable (can act as both USB
		Host and USB Device) are connected together, the roles are
		selected randomly.

		This class gives the userspace the control over the USB role and
		the Alternate Mode with USB Type-C connectors.

What:		/sys/class/type-c/usbcN/
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		A /sys/class/type-C/usbcN directory is created for each USB
		Type-C connector in the system. The N is the index of the
		connector.

What:		/sys/class/type-c/usbcN/connected
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		Connection status of the USB Type-C connector usbcN. "yes" when
		connected, otherwise "no".

What:		/sys/class/type-c/usbcN/current_alternate_mode
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		When connected to an Alternate Mode, displays the current Mode
		ID and the Standard of Vendor ID (SVID) of the Alternate Mode in
		form:

		<SVID>,<Mode>

		This file is writable and can be used to enter other modes both
		the connector usbcN and the partner support. The modes are
		Alternate Mode specific, and before they are to be changed with
		this file, the exact details of the modes under the given SVID
		should be known by the user.

What:		/sys/class/type-c/usbcN/current_data_role
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		The current USB data role, host or device. This file can be used
		by the userspace to execute data role swap by writing the
		requested role to it.

		When the connector is not connected, the file is used to store
		the preselected role which the system will attempt to use next
		time when connected.

What:		/sys/class/type-c/usbcN/current_power_role
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		The current power role of the connector, source or sink. This
		file can be used by the userspace to execute power role swap by
		writing the requested role to it. USB power role swap depends on
		USB Power Delivery support. When the connector usbcN, or the
		partner it's connected to, do not support USB Power Delivery,
		the power role is defined by the USB data role, i.e. host is
		source and device is sink, and can not be independently swapped
		with this file.

		When the connector is not connected, the file is used to store
		the preselected role which the system will attempt to use next
		time when connected.

What:		/sys/class/type-c/usbcN/partner_alternate_modes
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		When connected, this file lists the Alternate Modes the partner
		connected to connector usbcN supports in the following form:

		<SVID 0>,<Mode 0>
		<SVID 0>,<Mode 1>
		...
		<SVID 0>,<Mode n>
		<SVID 1>,<Mode 0>
		...
		<SVID n>,<Mode n>

		Where the SVID is the 16 bit Standard of Vendor ID, and 32 bit
		Mode n is the ID of the Mode. The modes are Alternate Mode
		specific and are defined in the separate specifications for the
		Alternate Modes.

What:		/sys/class/type-c/usbcN/partner_type
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		This read only file returns the type of partner when connected.
		The partner can be of type:

		- USB - When connected to normal USB host or device
		- Charger - When connected dedicated charger
		- Alternate Mode - when connected to Alternate Mode
		- Audio Accessory
		- Debug Accessory

What:		/sys/class/type-c/usbcN/power_operation_mode
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		This file is read only, and it returns indication of the current
		power level of the connector when connected. It does not return
		the exact voltage and current in use except in case of 1.5A and
		3.0A modes which are defined in USB Type-C specification. The
		power operation mode can be one of the following:

		- USB - When normal power levels defined in USB specifications
			are in use
		- BC1.2 - When power levels defined in Battery Charging
			  Specification v1.2 are in use
		- USB Type-C 1.5A -  Higher 1.5A current compared to the
				     standard USB currents is possible, as
				     defined in USB Type-C specification
		- USB Type-C 3.0A -  Higher 3.0A current compared to the
				     standard USB currents is possible, as
				     defined in USB Type-C specification
		- USB Power Delivery - The voltages and currents defined in USB
				       Power Delivery specification are in use

		The exact power levels are outside the scope of this interface,
		and if needed by userspace, need to be extracted from an other
		source.

What:		/sys/class/type-c/usbcN/supported_alternate_modes
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		This read only file lists the Alternate Modes the connector usbN
		supports in the following form:

		<SVID 0>,<Mode 0>
		<SVID 0>,<Mode 1>
		...
		<SVID 0>,<Mode n>
		<SVID 1>,<Mode 0>
		...
		<SVID n>,<Mode n>

		Where the SVID is the 16 bit Standard or Vendor ID, and 32 bit
		Mode n is the ID of the Mode. The modes are Alternate Mode
		specific and are defined in the separate specifications for the
		Alternate Modes.

What:		/sys/class/type-c/usbcN/supported_data_roles
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		The USB data roles that the connector support.

		Valid values:
		- host
		- device

What:		/sys/class/type-c/usbcN/supported_power_roles
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		The power roles that the connector usbcN support.

		Valid values:
		- source
		- sink

What:		/sys/class/type-c/usbcN/supports_audio_accessory
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		Returns "yes" if the connector usbcN can be used in Audio
		Accessory Mode, otherwise "no". The file is read only.

		In Audio Accessory Mode the connector usbcN will be used as a
		replacement for 3.5mm audio plug, and the pins of the connector
		that the Audio Accessory Mode in USB Type-C specification defines
		are routed to the audio hardware on the system.

What:		/sys/class/type-c/usbcN/supports_debug_accessory
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		Returns "yes" if the connector usbcN can be used in Debug
		Accessory Mode, otherwise "no". The file is read only.

		USB Type-C Specification does not define any details about Debug
		Accessory Mode, not even the pins on the connector. The Debug
		Accessory Mode will therefore be completely platform specific.
		Possible uses of the connector in this mode could be, serial
		port connected to 16550 compatible UART, or for example JTAG
		interface.

What:		/sys/class/type-c/usbcN/supports_usb_power_delivery
Date:		February 2016
Contact:	Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
Description:
		Returns "yes" if the connector usbcN is USB Power Delivery
		capable, otherwise "no". The file is read only.

		USB Power Delivery support will define if the connector usbcN is
		able to use Alternate Modes and swap the power role
		independently of the USB data role.