Documentation/driver-api/usb/typec_bus.rst

   1
   2 API for USB Type-C Alternate Mode drivers
   3 =========================================
   4
   5 Introduction
   6 ------------
   7
   8 Alternate modes require communication with the partner using Vendor Defined
   9 Messages (VDM) as defined in USB Type-C and USB Power Delivery Specifications.
  10 The communication is SVID (Standard or Vendor ID) specific, i.e. specific for
  11 every alternate mode, so every alternate mode will need a custom driver.
  12
  13 USB Type-C bus allows binding a driver to the discovered partner alternate
  14 modes by using the SVID and the mode number.
  15
  16 USB Type-C Connector Class provides a device for every alternate mode a port
  17 supports, and separate device for every alternate mode the partner supports.
  18 The drivers for the alternate modes are bound to the partner alternate mode
  19 devices, and the port alternate mode devices must be handled by the port
  20 drivers.
  21
  22 When a new partner alternate mode device is registered, it is linked to the
  23 alternate mode device of the port that the partner is attached to, that has
  24 matching SVID and mode. Communication between the port driver and alternate mode
  25 driver will happen using the same API.
  26
  27 The port alternate mode devices are used as a proxy between the partner and the
  28 alternate mode drivers, so the port drivers are only expected to pass the SVID
  29 specific commands from the alternate mode drivers to the partner, and from the
  30 partners to the alternate mode drivers. No direct SVID specific communication is
  31 needed from the port drivers, but the port drivers need to provide the operation
  32 callbacks for the port alternate mode devices, just like the alternate mode
  33 drivers need to provide them for the partner alternate mode devices.
  34
  35 Usage:
  36 ------
  37
  38 General
  39 ~~~~~~~
  40
  41 By default, the alternate mode drivers are responsible for entering the mode.
  42 It is also possible to leave the decision about entering the mode to the user
  43 space (See Documentation/ABI/testing/sysfs-class-typec). Port drivers should not
  44 enter any modes on their own.
  45
  46 ``->vdm`` is the most important callback in the operation callbacks vector. It
  47 will be used to deliver all the SVID specific commands from the partner to the
  48 alternate mode driver, and vice versa in case of port drivers. The drivers send
  49 the SVID specific commands to each other using :c:func:`typec_altmode_vmd()`.
  50
  51 If the communication with the partner using the SVID specific commands results
  52 in need to reconfigure the pins on the connector, the alternate mode driver
  53 needs to notify the bus using :c:func:`typec_altmode_notify()`. The driver
  54 passes the negotiated SVID specific pin configuration value to the function as
  55 parameter. The bus driver will then configure the mux behind the connector using
  56 that value as the state value for the mux, and also call blocking notification
  57 chain to notify the external drivers about the state of the connector that need
  58 to know it.
  59
  60 NOTE: The SVID specific pin configuration values must always start from
  61 ``TYPEC_STATE_MODAL``. USB Type-C specification defines two default states for
  62 the connector: ``TYPEC_STATE_USB`` and ``TYPEC_STATE_SAFE``. These values are
  63 reserved by the bus as the first possible values for the state. When the
  64 alternate mode is entered, the bus will put the connector into
  65 ``TYPEC_STATE_SAFE`` before sending Enter or Exit Mode command as defined in USB
  66 Type-C Specification, and also put the connector back to ``TYPEC_STATE_USB``
  67 after the mode has been exited.
  68
  69 An example of working definitions for SVID specific pin configurations would
  70 look like this:
  71
  72 enum {
  73         ALTMODEX_CONF_A = TYPEC_STATE_MODAL,
  74         ALTMODEX_CONF_B,
  75         ...
  76 };
  77
  78 Helper macro ``TYPEC_MODAL_STATE()`` can also be used:
  79
  80 #define ALTMODEX_CONF_A = TYPEC_MODAL_STATE(0);
  81 #define ALTMODEX_CONF_B = TYPEC_MODAL_STATE(1);
  82
  83 Notification chain
  84 ~~~~~~~~~~~~~~~~~~
  85
  86 The drivers for the components that the alternate modes are designed for need to
  87 get details regarding the results of the negotiation with the partner, and the
  88 pin configuration of the connector. In case of DisplayPort alternate mode for
  89 example, the GPU drivers will need to know those details. In case of
  90 Thunderbolt alternate mode, the thunderbolt drivers will need to know them, and
  91 so on.
  92
  93 The notification chain is designed for this purpose. The drivers can register
  94 notifiers with :c:func:`typec_altmode_register_notifier()`.
  95
  96 Cable plug alternate modes
  97 ~~~~~~~~~~~~~~~~~~~~~~~~~~
  98
  99 The alternate mode drivers are not bound to cable plug alternate mode devices,
 100 only to the partner alternate mode devices. If the alternate mode supports, or
 101 requires, a cable that responds to SOP Prime, and optionally SOP Double Prime
 102 messages, the driver for that alternate mode must request handle to the cable
 103 plug alternate modes using :c:func:`typec_altmode_get_plug()`, and take over
 104 their control.
 105
 106 Driver API
 107 ----------
 108
 109 Alternate mode driver registering/unregistering
 110 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 111
 112 .. kernel-doc:: drivers/usb/typec/bus.c
 113    :functions: typec_altmode_register_driver typec_altmode_unregister_driver
 114
 115 Alternate mode driver operations
 116 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 117
 118 .. kernel-doc:: drivers/usb/typec/bus.c
 119    :functions: typec_altmode_enter typec_altmode_exit typec_altmode_attention typec_altmode_vdm typec_altmode_notify
 120
 121 API for the port drivers
 122 ~~~~~~~~~~~~~~~~~~~~~~~~
 123
 124 .. kernel-doc:: drivers/usb/typec/bus.c
 125    :functions: typec_match_altmode
 126
 127 Cable Plug operations
 128 ~~~~~~~~~~~~~~~~~~~~~
 129
 130 .. kernel-doc:: drivers/usb/typec/bus.c
 131    :functions: typec_altmode_get_plug typec_altmode_put_plug
 132
 133 Notifications
 134 ~~~~~~~~~~~~~
 135 .. kernel-doc:: drivers/usb/typec/class.c
 136    :functions: typec_altmode_register_notifier typec_altmode_unregister_notifier