forked from torvalds/linux
-
Notifications
You must be signed in to change notification settings - Fork 14
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
usb: typec: Bus type for alternate modes
Introducing a simple bus for the alternate modes. Bus allows binding drivers to the discovered alternate modes the partners support. Signed-off-by: Heikki Krogerus <[email protected]> Tested-by: Hans de Goede <[email protected]> Signed-off-by: Greg Kroah-Hartman <[email protected]>
- Loading branch information
Showing
14 changed files
with
1,174 additions
and
147 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| These files are deprecated and will be removed. The same files are available | ||
| under /sys/bus/typec (see Documentation/ABI/testing/sysfs-bus-typec). | ||
|
|
||
| What: /sys/class/typec/<port|partner|cable>/<dev>/svid | ||
| Date: April 2017 | ||
| Contact: Heikki Krogerus <[email protected]> | ||
| 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 <[email protected]> | ||
| 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 <[email protected]> | ||
| 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 <[email protected]> | ||
| 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 <[email protected]> | ||
| 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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,51 @@ | ||
| What: /sys/bus/typec/devices/.../active | ||
| Date: July 2018 | ||
| Contact: Heikki Krogerus <[email protected]> | ||
| Description: | ||
| Shows if the mode is active or not. The attribute can be used | ||
| for entering/exiting the mode. 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 are boolean. | ||
|
|
||
| What: /sys/bus/typec/devices/.../description | ||
| Date: July 2018 | ||
| Contact: Heikki Krogerus <[email protected]> | ||
| Description: | ||
| Shows description of the mode. The description is optional for | ||
| the drivers, just like with the Billboard Devices. | ||
|
|
||
| What: /sys/bus/typec/devices/.../mode | ||
| Date: July 2018 | ||
| Contact: Heikki Krogerus <[email protected]> | ||
| Description: | ||
| The index number of the mode returned by Discover Modes USB | ||
| Power Delivery command. Depending on the alternate mode, the | ||
| mode index may be significant. | ||
|
|
||
| With some alternate modes (SVIDs), the mode index is assigned | ||
| for specific functionality in the specification for that | ||
| alternate mode. | ||
|
|
||
| With other alternate modes, the mode index values are not | ||
| assigned, and can not be therefore used for identification. When | ||
| the mode index is not assigned, identifying the alternate mode | ||
| must be done with either mode VDO or the description. | ||
|
|
||
| What: /sys/bus/typec/devices/.../svid | ||
| Date: July 2018 | ||
| Contact: Heikki Krogerus <[email protected]> | ||
| Description: | ||
| The Standard or Vendor ID (SVID) assigned by USB-IF for this | ||
| alternate mode. | ||
|
|
||
| What: /sys/bus/typec/devices/.../vdo | ||
| Date: July 2018 | ||
| Contact: Heikki Krogerus <[email protected]> | ||
| Description: | ||
| Shows the VDO in hexadecimal returned by Discover Modes command | ||
| for this mode. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -222,70 +222,12 @@ Description: | |
| available. The value can be polled. | ||
|
|
||
|
|
||
| Alternate Mode devices. | ||
| USB Type-C port 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 <[email protected]> | ||
| 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 <[email protected]> | ||
| 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 <[email protected]> | ||
| 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 <[email protected]> | ||
| 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 <[email protected]> | ||
| 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 | ||
| What: /sys/class/typec/<port>/<alt mode>/supported_roles | ||
| Date: April 2017 | ||
| Contact: Heikki Krogerus <[email protected]> | ||
| 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 | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,136 @@ | ||
|
|
||
| API for USB Type-C Alternate Mode drivers | ||
| ========================================= | ||
|
|
||
| Introduction | ||
| ------------ | ||
|
|
||
| Alternate modes require communication with the partner using Vendor Defined | ||
| Messages (VDM) as defined in USB Type-C and USB Power Delivery Specifications. | ||
| The communication is SVID (Standard or Vendor ID) specific, i.e. specific for | ||
| every alternate mode, so every alternate mode will need a custom driver. | ||
|
|
||
| USB Type-C bus allows binding a driver to the discovered partner alternate | ||
| modes by using the SVID and the mode number. | ||
|
|
||
| USB Type-C Connector Class provides a device for every alternate mode a port | ||
| supports, and separate device for every alternate mode the partner supports. | ||
| The drivers for the alternate modes are bound to the partner alternate mode | ||
| devices, and the port alternate mode devices must be handled by the port | ||
| drivers. | ||
|
|
||
| When a new partner alternate mode device is registered, it is linked to the | ||
| alternate mode device of the port that the partner is attached to, that has | ||
| matching SVID and mode. Communication between the port driver and alternate mode | ||
| driver will happen using the same API. | ||
|
|
||
| The port alternate mode devices are used as a proxy between the partner and the | ||
| alternate mode drivers, so the port drivers are only expected to pass the SVID | ||
| specific commands from the alternate mode drivers to the partner, and from the | ||
| partners to the alternate mode drivers. No direct SVID specific communication is | ||
| needed from the port drivers, but the port drivers need to provide the operation | ||
| callbacks for the port alternate mode devices, just like the alternate mode | ||
| drivers need to provide them for the partner alternate mode devices. | ||
|
|
||
| Usage: | ||
| ------ | ||
|
|
||
| General | ||
| ~~~~~~~ | ||
|
|
||
| By default, the alternate mode drivers are responsible for entering the mode. | ||
| It is also possible to leave the decision about entering the mode to the user | ||
| space (See Documentation/ABI/testing/sysfs-class-typec). Port drivers should not | ||
| enter any modes on their own. | ||
|
|
||
| ``->vdm`` is the most important callback in the operation callbacks vector. It | ||
| will be used to deliver all the SVID specific commands from the partner to the | ||
| alternate mode driver, and vice versa in case of port drivers. The drivers send | ||
| the SVID specific commands to each other using :c:func:`typec_altmode_vmd()`. | ||
|
|
||
| If the communication with the partner using the SVID specific commands results | ||
| in need to reconfigure the pins on the connector, the alternate mode driver | ||
| needs to notify the bus using :c:func:`typec_altmode_notify()`. The driver | ||
| passes the negotiated SVID specific pin configuration value to the function as | ||
| parameter. The bus driver will then configure the mux behind the connector using | ||
| that value as the state value for the mux, and also call blocking notification | ||
| chain to notify the external drivers about the state of the connector that need | ||
| to know it. | ||
|
|
||
| NOTE: The SVID specific pin configuration values must always start from | ||
| ``TYPEC_STATE_MODAL``. USB Type-C specification defines two default states for | ||
| the connector: ``TYPEC_STATE_USB`` and ``TYPEC_STATE_SAFE``. These values are | ||
| reserved by the bus as the first possible values for the state. When the | ||
| alternate mode is entered, the bus will put the connector into | ||
| ``TYPEC_STATE_SAFE`` before sending Enter or Exit Mode command as defined in USB | ||
| Type-C Specification, and also put the connector back to ``TYPEC_STATE_USB`` | ||
| after the mode has been exited. | ||
|
|
||
| An example of working definitions for SVID specific pin configurations would | ||
| look like this: | ||
|
|
||
| enum { | ||
| ALTMODEX_CONF_A = TYPEC_STATE_MODAL, | ||
| ALTMODEX_CONF_B, | ||
| ... | ||
| }; | ||
|
|
||
| Helper macro ``TYPEC_MODAL_STATE()`` can also be used: | ||
|
|
||
| #define ALTMODEX_CONF_A = TYPEC_MODAL_STATE(0); | ||
| #define ALTMODEX_CONF_B = TYPEC_MODAL_STATE(1); | ||
|
|
||
| Notification chain | ||
| ~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| The drivers for the components that the alternate modes are designed for need to | ||
| get details regarding the results of the negotiation with the partner, and the | ||
| pin configuration of the connector. In case of DisplayPort alternate mode for | ||
| example, the GPU drivers will need to know those details. In case of | ||
| Thunderbolt alternate mode, the thunderbolt drivers will need to know them, and | ||
| so on. | ||
|
|
||
| The notification chain is designed for this purpose. The drivers can register | ||
| notifiers with :c:func:`typec_altmode_register_notifier()`. | ||
|
|
||
| Cable plug alternate modes | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| The alternate mode drivers are not bound to cable plug alternate mode devices, | ||
| only to the partner alternate mode devices. If the alternate mode supports, or | ||
| requires, a cable that responds to SOP Prime, and optionally SOP Double Prime | ||
| messages, the driver for that alternate mode must request handle to the cable | ||
| plug alternate modes using :c:func:`typec_altmode_get_plug()`, and take over | ||
| their control. | ||
|
|
||
| Driver API | ||
| ---------- | ||
|
|
||
| Alternate mode driver registering/unregistering | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| .. kernel-doc:: drivers/usb/typec/bus.c | ||
| :functions: typec_altmode_register_driver typec_altmode_unregister_driver | ||
|
|
||
| Alternate mode driver operations | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| .. kernel-doc:: drivers/usb/typec/bus.c | ||
| :functions: typec_altmode_enter typec_altmode_exit typec_altmode_attention typec_altmode_vdm typec_altmode_notify | ||
|
|
||
| API for the port drivers | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| .. kernel-doc:: drivers/usb/typec/bus.c | ||
| :functions: typec_match_altmode | ||
|
|
||
| Cable Plug operations | ||
| ~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| .. kernel-doc:: drivers/usb/typec/bus.c | ||
| :functions: typec_altmode_get_plug typec_altmode_put_plug | ||
|
|
||
| Notifications | ||
| ~~~~~~~~~~~~~ | ||
| .. kernel-doc:: drivers/usb/typec/class.c | ||
| :functions: typec_altmode_register_notifier typec_altmode_unregister_notifier |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -14955,7 +14955,7 @@ L: [email protected] | |
| S: Maintained | ||
| F: drivers/usb/typec/mux/pi3usb30532.c | ||
|
|
||
| USB TYPEC SUBSYSTEM | ||
| USB TYPEC CLASS | ||
| M: Heikki Krogerus <[email protected]> | ||
| L: [email protected] | ||
| S: Maintained | ||
|
|
@@ -14964,6 +14964,15 @@ F: Documentation/driver-api/usb/typec.rst | |
| F: drivers/usb/typec/ | ||
| F: include/linux/usb/typec.h | ||
|
|
||
| USB TYPEC BUS FOR ALTERNATE MODES | ||
| M: Heikki Krogerus <[email protected]> | ||
| L: [email protected] | ||
| S: Maintained | ||
| F: Documentation/ABI/testing/sysfs-bus-typec | ||
| F: Documentation/driver-api/usb/typec_bus.rst | ||
| F: drivers/usb/typec/altmodes/ | ||
| F: include/linux/usb/typec_altmode.h | ||
|
|
||
| USB UHCI DRIVER | ||
| M: Alan Stern <[email protected]> | ||
| L: [email protected] | ||
|
|
||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.