0001
0002 API for USB Type-C Alternate Mode drivers
0003 =========================================
0004
0005 Introduction
0006 ------------
0007
0008 Alternate modes require communication with the partner using Vendor Defined
0009 Messages (VDM) as defined in USB Type-C and USB Power Delivery Specifications.
0010 The communication is SVID (Standard or Vendor ID) specific, i.e. specific for
0011 every alternate mode, so every alternate mode will need a custom driver.
0012
0013 USB Type-C bus allows binding a driver to the discovered partner alternate
0014 modes by using the SVID and the mode number.
0015
0016 :ref:`USB Type-C Connector Class <typec>` provides a device for every alternate
0017 mode a port supports, and separate device for every alternate mode the partner
0018 supports. The drivers for the alternate modes are bound to the partner alternate
0019 mode devices, and the port alternate mode devices must be handled by the port
0020 drivers.
0021
0022 When a new partner alternate mode device is registered, it is linked to the
0023 alternate mode device of the port that the partner is attached to, that has
0024 matching SVID and mode. Communication between the port driver and alternate mode
0025 driver will happen using the same API.
0026
0027 The port alternate mode devices are used as a proxy between the partner and the
0028 alternate mode drivers, so the port drivers are only expected to pass the SVID
0029 specific commands from the alternate mode drivers to the partner, and from the
0030 partners to the alternate mode drivers. No direct SVID specific communication is
0031 needed from the port drivers, but the port drivers need to provide the operation
0032 callbacks for the port alternate mode devices, just like the alternate mode
0033 drivers need to provide them for the partner alternate mode devices.
0034
0035 Usage:
0036 ------
0037
0038 General
0039 ~~~~~~~
0040
0041 By default, the alternate mode drivers are responsible for entering the mode.
0042 It is also possible to leave the decision about entering the mode to the user
0043 space (See Documentation/ABI/testing/sysfs-class-typec). Port drivers should not
0044 enter any modes on their own.
0045
0046 ``->vdm`` is the most important callback in the operation callbacks vector. It
0047 will be used to deliver all the SVID specific commands from the partner to the
0048 alternate mode driver, and vice versa in case of port drivers. The drivers send
0049 the SVID specific commands to each other using :c:func:`typec_altmode_vdm()`.
0050
0051 If the communication with the partner using the SVID specific commands results
0052 in need to reconfigure the pins on the connector, the alternate mode driver
0053 needs to notify the bus using :c:func:`typec_altmode_notify()`. The driver
0054 passes the negotiated SVID specific pin configuration value to the function as
0055 parameter. The bus driver will then configure the mux behind the connector using
0056 that value as the state value for the mux.
0057
0058 NOTE: The SVID specific pin configuration values must always start from
0059 ``TYPEC_STATE_MODAL``. USB Type-C specification defines two default states for
0060 the connector: ``TYPEC_STATE_USB`` and ``TYPEC_STATE_SAFE``. These values are
0061 reserved by the bus as the first possible values for the state. When the
0062 alternate mode is entered, the bus will put the connector into
0063 ``TYPEC_STATE_SAFE`` before sending Enter or Exit Mode command as defined in USB
0064 Type-C Specification, and also put the connector back to ``TYPEC_STATE_USB``
0065 after the mode has been exited.
0066
0067 An example of working definitions for SVID specific pin configurations would
0068 look like this::
0069
0070 enum {
0071 ALTMODEX_CONF_A = TYPEC_STATE_MODAL,
0072 ALTMODEX_CONF_B,
0073 ...
0074 };
0075
0076 Helper macro ``TYPEC_MODAL_STATE()`` can also be used::
0077
0078 #define ALTMODEX_CONF_A = TYPEC_MODAL_STATE(0);
0079 #define ALTMODEX_CONF_B = TYPEC_MODAL_STATE(1);
0080
0081 Cable plug alternate modes
0082 ~~~~~~~~~~~~~~~~~~~~~~~~~~
0083
0084 The alternate mode drivers are not bound to cable plug alternate mode devices,
0085 only to the partner alternate mode devices. If the alternate mode supports, or
0086 requires, a cable that responds to SOP Prime, and optionally SOP Double Prime
0087 messages, the driver for that alternate mode must request handle to the cable
0088 plug alternate modes using :c:func:`typec_altmode_get_plug()`, and take over
0089 their control.
0090
0091 Driver API
0092 ----------
0093
0094 Alternate mode structs
0095 ~~~~~~~~~~~~~~~~~~~~~~
0096
0097 .. kernel-doc:: include/linux/usb/typec_altmode.h
0098 :functions: typec_altmode_driver typec_altmode_ops
0099
0100 Alternate mode driver registering/unregistering
0101 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0102
0103 .. kernel-doc:: include/linux/usb/typec_altmode.h
0104 :functions: typec_altmode_register_driver typec_altmode_unregister_driver
0105
0106 Alternate mode driver operations
0107 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
0108
0109 .. kernel-doc:: drivers/usb/typec/bus.c
0110 :functions: typec_altmode_enter typec_altmode_exit typec_altmode_attention typec_altmode_vdm typec_altmode_notify
0111
0112 API for the port drivers
0113 ~~~~~~~~~~~~~~~~~~~~~~~~
0114
0115 .. kernel-doc:: drivers/usb/typec/bus.c
0116 :functions: typec_match_altmode
0117
0118 Cable Plug operations
0119 ~~~~~~~~~~~~~~~~~~~~~
0120
0121 .. kernel-doc:: drivers/usb/typec/bus.c
0122 :functions: typec_altmode_get_plug typec_altmode_put_plug
