Re: [PATCH v5 1/2] usb: USB Type-C connector class

From: Frans Klaver
Date: Wed Aug 17 2016 - 09:14:10 EST


On Wed, Aug 17, 2016 at 12:34 PM, Heikki Krogerus
<heikki.krogerus@xxxxxxxxxxxxxxx> wrote:
> 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: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> ---
> Documentation/ABI/testing/sysfs-class-typec | 199 +++++
> Documentation/usb/typec.txt | 103 +++
> MAINTAINERS | 9 +
> drivers/usb/Kconfig | 2 +
> drivers/usb/Makefile | 2 +
> drivers/usb/typec/Kconfig | 7 +
> drivers/usb/typec/Makefile | 1 +
> drivers/usb/typec/typec.c | 1104 +++++++++++++++++++++++++++
> include/linux/usb/typec.h | 260 +++++++
> 9 files changed, 1687 insertions(+)
> create mode 100644 Documentation/ABI/testing/sysfs-class-typec
> create mode 100644 Documentation/usb/typec.txt
> create mode 100644 drivers/usb/typec/Kconfig
> create mode 100644 drivers/usb/typec/Makefile
> create mode 100644 drivers/usb/typec/typec.c
> create mode 100644 include/linux/usb/typec.h
>
> diff --git a/Documentation/ABI/testing/sysfs-class-typec b/Documentation/ABI/testing/sysfs-class-typec
> new file mode 100644
> index 0000000..e6179d3
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-class-typec
> @@ -0,0 +1,199 @@
> +USB Type-C port devices (eg. /sys/class/typec/usbc0/)
> +
> +What: /sys/class/typec/<port>/current_data_role
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + The current USB data role the port is operating in. This
> + attribute can be used for requesting data role swapping on the
> + port.
> +
> + Valid values:
> + - host
> + - device
> +
> +What: /sys/class/typec/<port>/current_power_role
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + The current power role of the port. This attribute can be used
> + to request power role swap on the port when the port supports
> + USB Power Delivery.
> +
> + Valid values:
> + - source
> + - sink
> +
> +What: /sys/class/typec/<port>/current_vconn_role
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + Shows the current VCONN role of the port. This attribute can be
> + used to request VCONN role swap on the port when the port
> + supports USB Power Delivery.
> +
> + Valid values are:
> + - source
> + - sink
> +
> +What: /sys/class/typec/<port>/power_operation_mode
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + Shows the current power operational mode the port is in.
> +
> + Valid values:
> + - USB - Normal power levels defined in USB specifications
> + - BC1.2 - Power levels defined in Battery Charging Specification
> + v1.2
> + - USB Type-C 1.5A - Higher 1.5A current defined in USB Type-C
> + specification.
> + - USB Type-C 3.0A - Higher 3A current defined in USB Type-C
> + specification.
> + - USB Power Delivery - The voltages and currents defined in USB
> + Power Delivery specification
> +
> +What: /sys/class/typec/<port>/preferred_role
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +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 there is no preferred role.
> +
> + Valid values:
> + - host
> + - device
> + - For example "none" to remove preference (anything else except
> + "host" or "device")
> +
> +What: /sys/class/typec/<port>/supported_accessory_modes
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + Lists the Accessory Modes, defined in the USB Type-C
> + specification, the port supports.
> +
> +What: /sys/class/typec/<port>/supported_data_roles
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + Lists the USB data roles the port is capable of supporting.
> +
> + Valid values:
> + - device
> + - host
> + - device, host (DRD as defined in USB Type-C specification v1.2)
> +
> +What: /sys/class/typec/<port>/supported_power_roles
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + Lists the power roles the port is capable of supporting.
> +
> + Valid values:
> + - source
> + - sink
> +
> +What: /sys/class/typec/<port>/supports_usb_power_delivery
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + Shows if the port supports USB Power Delivery.
> + - 1 if USB Power Delivery is supported
> + - 0 when it's not
> +
> +
> +USB Type-C partner devices (eg. /sys/class/typec/usbc0-partner/)
> +
> +What: /sys/class/typec/<port>-partner/accessory
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + The attribute is visible only when the partner's type is
> + "Accessory". The type can be read from its own attribute.
> +
> + Shows the name of the Accessory Mode. The Accessory Modes are
> + defined in USB Type-C Specification.
> +
> +What: /sys/class/typec/<port>-partner/type
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + Shows the type of the partner. Can be one of the following:
> + - USB - When the partner is normal USB host/peripheral.
> + - Charger - When the partner has been identified as dedicated
> + charger.
> + - Alternate Mode - When the partner supports Alternate Modes.
> + - Accessory - When the partner is one of the accessories with
> + specific Accessory Mode defined in USB Type-C
> + specification.
> +
> +
> +USB Type-C cable devices (eg. /sys/class/typec/usbc0-cable/)
> +
> +Note: Electronically Marked Cables will have a device also for one cable plug
> +(eg. /sys/class/typec/usbc0-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 their alternate modes
> +as described in USB Type-C and USB Power Delivery specifications.
> +
> +What: /sys/class/typec/<port>-cable/active
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + Shows if the cable is active or passive.
> +
> + Valid values:
> + - 0 when the cable is passive
> + - 1 when the cable is active
> +
> +What: /sys/class/typec/<port>-cable/plug_type
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + Shows type of the plug on the cable:
> + - Type-A - Standard A
> + - Type-B - Standard B
> + - Type-C - USB Type-C
> + - Captive - Non-standard
> +
> +
> +Alternate Mode devices (For example,
> +/sys/class/typec/usbc0-partner/usbc0-partner.svid:xxxx/). The ports, partners
> +and cable plugs can have alternate modes.
> +
> +What: /sys/class/typec/<dev>/<dev>.svid:<svid>/<mode>/active
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +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.
> +
> +What: /sys/class/typec/<dev>/<dev>.svid:<svid>/<mode>/description
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + Shows description of the mode. The description is optional for
> + the drivers, just like with the Billboard Devices.
> +
> +What: /sys/class/typec/<dev>/<dev>.svid:<svid>/<mode>/vdo
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + Shows the VDO in hexadecimal returned from the Discover Modes
> + command.
> +
> +What: /sys/class/typec/<port>/<port>.svid:<svid>/<mode>/supported_roles
> +Date: June 2016
> +Contact: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +Description:
> + Shows the roles, source or sink, the mode is supported with.
> +
> + 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.
> diff --git a/Documentation/usb/typec.txt b/Documentation/usb/typec.txt
> new file mode 100644
> index 0000000..dce5f07
> --- /dev/null
> +++ b/Documentation/usb/typec.txt
> @@ -0,0 +1,103 @@
> +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 the user space control
> +over the roles and alternate modes they support 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.
> +
> +
> +Interface
> +---------
> +Every port will be presented as its own device under /sys/class/typec/. The
> +first port will be named "usbc0", the second "usbc1" 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. The
> +partner attached to port "usbc0" will be named "usbc0-partner". Full patch to
> +the device would be /sys/class/typec/usb0/usb0-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 "usbc0" port
> +will be named usbc0-cable and the plug on the SOP Prime end (see USB Power
> +Delivery Specification ch. 2.4) will be named "usbc-plug0" and on the SOP Double
> +Prime end "usbc0-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 support Alternate Modes, every Alternate Mode
> +SVID will have their own device describing them. The Alternate Modes will not be
> +attached to the typec class. For the port's "usbc0" partner, the Alternate Modes
> +would have devices presented under /sys/class/typec/usbc0-partner/. Every mode
> +that is supported will have its own group under the Alternate Mode device named
> +"mode<id>". For example /sys/class/typec/usbc0/usbc0.svid:xxxx/mode0/. The
> +requests for entering/exiting the modes happens with the "active" attribute in
> +that group.
> +
> +
> +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:
> +
> +struct typec_port *typec_register_port(struct device *dev,
> + const struct typec_capability *cap);
> +
> +The class will provide handle to struct typec_port on success and ERR_PTR on
> +failure. The un-registration of the port happens with the following API:
> +
> +void typec_unregister_port(struct typec_port *port);
> +
> +
> +* Notifications
> +
> +When connection happens on a port, the port driver fills struct typec_connection
> +which is passed to the class. The class provides the following API for reporting
> +connection/disconnection:
> +
> +int typec_connect(struct typec_port *port, struct typec_connection *);
> +void typec_disconnect(struct typec_port *);
> +
> +When the partner end has executed a role change, the port driver uses the
> +following APIs to report it to the class:
> +
> +void typec_set_data_role(struct typec_port *, enum typec_data_role);
> +void typec_set_pwr_role(struct typec_port *, enum typec_role);
> +void typec_set_vconn_role(struct typec_port *, enum typec_role);
> +void typec_set_pwr_opmode(struct typec_port *, enum typec_pwr_opmode);
> +
> +
> +* Alternate Modes
> +
> +After connection, the port drivers register the alternate modes the partner
> +and/or cable plugs support. And before reporting disconnection, the port driver
> +_must_ unregister all the alternate modes registered for the partner and cable
> +plugs. The API takes the struct device of the partner or the cable plug as
> +parameter:
> +
> +int typec_register_altmodes(struct device *, struct typec_altmode *);
> +void typec_unregister_altmodes(struct device *);
> +
> +When the partner end enters or exits the modes, the port driver needs to notify
> +the class with the following API:
> +
> +void typec_altmode_update_active(struct typec_altmode *alt, int mode,
> + bool active);
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 45c9848..9e64ac2 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -12305,6 +12305,15 @@ F: drivers/usb/
> F: include/linux/usb.h
> F: include/linux/usb/
>
> +USB TYPEC SUBSYSTEM
> +M: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> +L: linux-usb@xxxxxxxxxxxxxxx
> +S: Maintained
> +F: Documentation/ABI/testing/sysfs-class-typec
> +F: Documentation/usb/typec.txt
> +F: drivers/usb/typec/
> +F: include/linux/usb/typec.h
> +
> USB UHCI DRIVER
> M: Alan Stern <stern@xxxxxxxxxxxxxxxxxxx>
> L: linux-usb@xxxxxxxxxxxxxxx
> diff --git a/drivers/usb/Kconfig b/drivers/usb/Kconfig
> index 8689dcb..f42a3d3 100644
> --- a/drivers/usb/Kconfig
> +++ b/drivers/usb/Kconfig
> @@ -150,6 +150,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 && USB_COMMON && LEDS_TRIGGERS
> diff --git a/drivers/usb/Makefile b/drivers/usb/Makefile
> index dca7856..51e381e 100644
> --- a/drivers/usb/Makefile
> +++ b/drivers/usb/Makefile
> @@ -61,3 +61,5 @@ obj-$(CONFIG_USB_GADGET) += gadget/
> obj-$(CONFIG_USB_COMMON) += common/
>
> obj-$(CONFIG_USBIP_CORE) += usbip/
> +
> +obj-$(CONFIG_TYPEC) += typec/
> diff --git a/drivers/usb/typec/Kconfig b/drivers/usb/typec/Kconfig
> new file mode 100644
> index 0000000..b229fb9
> --- /dev/null
> +++ b/drivers/usb/typec/Kconfig
> @@ -0,0 +1,7 @@
> +
> +menu "USB PD and Type-C drivers"
> +
> +config TYPEC
> + tristate
> +
> +endmenu
> diff --git a/drivers/usb/typec/Makefile b/drivers/usb/typec/Makefile
> new file mode 100644
> index 0000000..1012a8b
> --- /dev/null
> +++ b/drivers/usb/typec/Makefile
> @@ -0,0 +1 @@
> +obj-$(CONFIG_TYPEC) += typec.o
> diff --git a/drivers/usb/typec/typec.c b/drivers/usb/typec/typec.c
> new file mode 100644
> index 0000000..52a0431
> --- /dev/null
> +++ b/drivers/usb/typec/typec.c
> @@ -0,0 +1,1104 @@
> +/*
> + * USB Type-C Connector Class
> + *
> + * Copyright (C) 2016, Intel Corporation
> + * Author: Heikki Krogerus <heikki.krogerus@xxxxxxxxxxxxxxx>
> + *
> + * This program is free software; you can redistribute it and/or modify
> + * it under the terms of the GNU General Public License version 2 as
> + * published by the Free Software Foundation.
> + */
> +
> +#include <linux/device.h>
> +#include <linux/module.h>
> +#include <linux/slab.h>
> +#include <linux/usb/typec.h>
> +
> +struct typec_port {
> + unsigned int id;
> + struct device dev;
> +
> + int prefer_role;
> +
> + enum typec_data_role data_role;
> + enum typec_role pwr_role;
> + enum typec_role vconn_role;
> + enum typec_pwr_opmode pwr_opmode;
> +
> + struct typec_partner *partner;
> + struct typec_cable *cable;
> +
> + unsigned int connected:1;
> +
> + const struct typec_capability *cap;
> +};
> +
> +#define to_typec_port(p) container_of(p, struct typec_port, dev)
> +
> +static DEFINE_IDA(typec_index_ida);
> +
> +static struct class typec_class = {
> + .name = "typec",
> +};
> +
> +static const char * const typec_accessory_modes[] = {
> + [TYPEC_ACCESSORY_NONE] = "none",
> + [TYPEC_ACCESSORY_AUDIO] = "Audio",
> + [TYPEC_ACCESSORY_DEBUG] = "Debug",
> + [TYPEC_ACCESSORY_DAUDIO] = "Digital Audio",
> +};
> +
> +static int sysfs_strmatch(const char * const *array, size_t n, const char *str)
> +{
> + const char *item;
> + int index;
> +
> + for (index = 0; index < n; index++) {
> + item = array[index];
> + if (!item)
> + break;
> + if (!sysfs_streq(item, str))
> + return index;
> + }
> +
> + return -EINVAL;
> +}
> +
> +/* ------------------------------------------------------------------------- */
> +/* Type-C Partners */
> +
> +static void typec_dev_release(struct device *dev)
> +{
> +}
> +
> +static const char * const typec_partner_types[] = {
> + [TYPEC_PARTNER_USB] = "USB",
> + [TYPEC_PARTNER_CHARGER] = "Charger",
> + [TYPEC_PARTNER_ALTMODE] = "Alternate Mode",
> + [TYPEC_PARTNER_ACCESSORY] = "Accessory",
> +};
> +
> +static ssize_t partner_type_show(struct device *dev,
> + struct device_attribute *attr, char *buf)
> +{
> + struct typec_partner *partner = container_of(dev, struct typec_partner,
> + dev);
> +
> + return sprintf(buf, "%s\n", typec_partner_types[partner->type]);
> +}
> +
> +static struct device_attribute dev_attr_partner_type = {
> + .attr = {
> + .name = "type",
> + .mode = S_IRUGO,
> + },
> + .show = partner_type_show,
> +};

Why not use DEVICE_ATTR_RO() for this?

> +
> +static ssize_t
> +partner_accessory_mode_show(struct device *dev, struct device_attribute *attr,
> + char *buf)
> +{
> + struct typec_partner *partner = container_of(dev, struct typec_partner,
> + dev);
> +
> + return sprintf(buf, "%s\n", typec_accessory_modes[partner->accessory]);
> +}
> +
> +static struct device_attribute dev_attr_partner_accessory = {
> + .attr = {
> + .name = "accessory",
> + .mode = S_IRUGO,
> + },
> + .show = partner_accessory_mode_show,
> +};

And this

Thanks,
Frans