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