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

[Frans Klaver]

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