Documentation/ABI/testing/sysfs-bus-thunderbolt

   1 What:           /sys/bus/thunderbolt/devices/.../domainX/boot_acl
   2 Date:           Jun 2018
   3 KernelVersion:  4.17
   4 Contact:        thunderbolt-software@lists.01.org
   5 Description:    Holds a comma separated list of device unique_ids that
   6                 are allowed to be connected automatically during system
   7                 startup (e.g boot devices). The list always contains
   8                 maximum supported number of unique_ids where unused
   9                 entries are empty. This allows the userspace software
  10                 to determine how many entries the controller supports.
  11                 If there are multiple controllers, each controller has
  12                 its own ACL list and size may be different between the
  13                 controllers.
  14
  15                 System BIOS may have an option "Preboot ACL" or similar
  16                 that needs to be selected before this list is taken into
  17                 consideration.
  18
  19                 Software always updates a full list in each write.
  20
  21                 If a device is authorized automatically during boot its
  22                 boot attribute is set to 1.
  23
  24 What:           /sys/bus/thunderbolt/devices/.../domainX/deauthorization
  25 Date:           May 2021
  26 KernelVersion:  5.12
  27 Contact:        Mika Westerberg <mika.westerberg@linux.intel.com>
  28 Description:    This attribute tells whether the system supports
  29                 de-authorization of devices. Value of 1 means user can
  30                 de-authorize PCIe tunnel by writing 0 to authorized
  31                 attribute under each device.
  32
  33 What:           /sys/bus/thunderbolt/devices/.../domainX/iommu_dma_protection
  34 Date:           Mar 2019
  35 KernelVersion:  4.21
  36 Contact:        thunderbolt-software@lists.01.org
  37 Description:    This attribute tells whether the system uses IOMMU
  38                 for DMA protection. Value of 1 means IOMMU is used 0 means
  39                 it is not (DMA protection is solely based on Thunderbolt
  40                 security levels).
  41
  42 What:           /sys/bus/thunderbolt/devices/.../domainX/security
  43 Date:           Sep 2017
  44 KernelVersion:  4.13
  45 Contact:        thunderbolt-software@lists.01.org
  46 Description:    This attribute holds current Thunderbolt security level
  47                 set by the system BIOS. Possible values are:
  48
  49                 =======  ==================================================
  50                 none     All devices are automatically authorized
  51                 user     Devices are only authorized based on writing
  52                          appropriate value to the authorized attribute
  53                 secure   Require devices that support secure connect at
  54                          minimum. User needs to authorize each device.
  55                 dponly   Automatically tunnel Display port (and USB). No
  56                          PCIe tunnels are created.
  57                 usbonly  Automatically tunnel USB controller of the
  58                          connected Thunderbolt dock (and Display Port). All
  59                          PCIe links downstream of the dock are removed.
  60                 nopcie   USB4 system where PCIe tunneling is disabled from
  61                          the BIOS.
  62                 =======  ==================================================
  63
  64 What:           /sys/bus/thunderbolt/devices/.../authorized
  65 Date:           Sep 2017
  66 KernelVersion:  4.13
  67 Contact:        thunderbolt-software@lists.01.org
  68 Description:    This attribute is used to authorize Thunderbolt devices
  69                 after they have been connected. If the device is not
  70                 authorized, no PCIe devices are available to the system.
  71
  72                 Contents of this attribute will be 0 when the device is not
  73                 yet authorized.
  74
  75                 Possible values are supported:
  76
  77                 ==  ===================================================
  78                 0   The device will be de-authorized (only supported if
  79                     deauthorization attribute under domain contains 1)
  80                 1   The device will be authorized and connected
  81                 ==  ===================================================
  82
  83                 When key attribute contains 32 byte hex string the possible
  84                 values are:
  85
  86                 ==  ========================================================
  87                 0   The device will be de-authorized (only supported if
  88                     deauthorization attribute under domain contains 1)
  89                 1   The 32 byte hex string is added to the device NVM and
  90                     the device is authorized.
  91                 2   Send a challenge based on the 32 byte hex string. If the
  92                     challenge response from device is valid, the device is
  93                     authorized. In case of failure errno will be ENOKEY if
  94                     the device did not contain a key at all, and
  95                     EKEYREJECTED if the challenge response did not match.
  96                 ==  ========================================================
  97
  98 What:           /sys/bus/thunderbolt/devices/.../boot
  99 Date:           Jun 2018
 100 KernelVersion:  4.17
 101 Contact:        thunderbolt-software@lists.01.org
 102 Description:    This attribute contains 1 if Thunderbolt device was already
 103                 authorized on boot and 0 otherwise.
 104
 105 What:           /sys/bus/thunderbolt/devices/.../generation
 106 Date:           Jan 2020
 107 KernelVersion:  5.5
 108 Contact:        Christian Kellner <christian@kellner.me>
 109 Description:    This attribute contains the generation of the Thunderbolt
 110                 controller associated with the device. It will contain 4
 111                 for USB4.
 112
 113 What:           /sys/bus/thunderbolt/devices/.../key
 114 Date:           Sep 2017
 115 KernelVersion:  4.13
 116 Contact:        thunderbolt-software@lists.01.org
 117 Description:    When a devices supports Thunderbolt secure connect it will
 118                 have this attribute. Writing 32 byte hex string changes
 119                 authorization to use the secure connection method instead.
 120                 Writing an empty string clears the key and regular connection
 121                 method can be used again.
 122
 123 What:           /sys/bus/thunderbolt/devices/.../device
 124 Date:           Sep 2017
 125 KernelVersion:  4.13
 126 Contact:        thunderbolt-software@lists.01.org
 127 Description:    This attribute contains id of this device extracted from
 128                 the device DROM.
 129
 130 What:           /sys/bus/thunderbolt/devices/.../device_name
 131 Date:           Sep 2017
 132 KernelVersion:  4.13
 133 Contact:        thunderbolt-software@lists.01.org
 134 Description:    This attribute contains name of this device extracted from
 135                 the device DROM.
 136
 137 What:           /sys/bus/thunderbolt/devices/.../maxhopid
 138 Date:           Jul 2021
 139 KernelVersion:  5.13
 140 Contact:        Mika Westerberg <mika.westerberg@linux.intel.com>
 141 Description:    Only set for XDomains. The maximum HopID the other host
 142                 supports as its input HopID.
 143
 144 What:           /sys/bus/thunderbolt/devices/.../rx_speed
 145 Date:           Jan 2020
 146 KernelVersion:  5.5
 147 Contact:        Mika Westerberg <mika.westerberg@linux.intel.com>
 148 Description:    This attribute reports the device RX speed per lane.
 149                 All RX lanes run at the same speed.
 150
 151 What:           /sys/bus/thunderbolt/devices/.../rx_lanes
 152 Date:           Jan 2020
 153 KernelVersion:  5.5
 154 Contact:        Mika Westerberg <mika.westerberg@linux.intel.com>
 155 Description:    This attribute reports number of RX lanes the device is
 156                 using simultaneusly through its upstream port.
 157
 158 What:           /sys/bus/thunderbolt/devices/.../tx_speed
 159 Date:           Jan 2020
 160 KernelVersion:  5.5
 161 Contact:        Mika Westerberg <mika.westerberg@linux.intel.com>
 162 Description:    This attribute reports the TX speed per lane.
 163                 All TX lanes run at the same speed.
 164
 165 What:           /sys/bus/thunderbolt/devices/.../tx_lanes
 166 Date:           Jan 2020
 167 KernelVersion:  5.5
 168 Contact:        Mika Westerberg <mika.westerberg@linux.intel.com>
 169 Description:    This attribute reports number of TX lanes the device is
 170                 using simultaneusly through its upstream port.
 171
 172 What:           /sys/bus/thunderbolt/devices/.../vendor
 173 Date:           Sep 2017
 174 KernelVersion:  4.13
 175 Contact:        thunderbolt-software@lists.01.org
 176 Description:    This attribute contains vendor id of this device extracted
 177                 from the device DROM.
 178
 179 What:           /sys/bus/thunderbolt/devices/.../vendor_name
 180 Date:           Sep 2017
 181 KernelVersion:  4.13
 182 Contact:        thunderbolt-software@lists.01.org
 183 Description:    This attribute contains vendor name of this device extracted
 184                 from the device DROM.
 185
 186 What:           /sys/bus/thunderbolt/devices/.../unique_id
 187 Date:           Sep 2017
 188 KernelVersion:  4.13
 189 Contact:        thunderbolt-software@lists.01.org
 190 Description:    This attribute contains unique_id string of this device.
 191                 This is either read from hardware registers (UUID on
 192                 newer hardware) or based on UID from the device DROM.
 193                 Can be used to uniquely identify particular device.
 194
 195 What:           /sys/bus/thunderbolt/devices/.../nvm_version
 196 Date:           Sep 2017
 197 KernelVersion:  4.13
 198 Contact:        thunderbolt-software@lists.01.org
 199 Description:    If the device has upgradeable firmware the version
 200                 number is available here. Format: %x.%x, major.minor.
 201                 If the device is in safe mode reading the file returns
 202                 -ENODATA instead as the NVM version is not available.
 203
 204 What:           /sys/bus/thunderbolt/devices/.../nvm_authenticate
 205 Date:           Sep 2017
 206 KernelVersion:  4.13
 207 Contact:        thunderbolt-software@lists.01.org
 208 Description:    When new NVM image is written to the non-active NVM
 209                 area (through non_activeX NVMem device), the
 210                 authentication procedure is started by writing to
 211                 this file.
 212                 If everything goes well, the device is
 213                 restarted with the new NVM firmware. If the image
 214                 verification fails an error code is returned instead.
 215
 216                 This file will accept writing values "1", "2" or "3".
 217
 218                 - Writing "1" will flush the image to the storage
 219                   area and authenticate the image in one action.
 220                 - Writing "2" will run some basic validation on the image
 221                   and flush it to the storage area.
 222                 - Writing "3" will authenticate the image that is
 223                   currently written in the storage area. This is only
 224                   supported with USB4 devices and retimers.
 225
 226                 When read holds status of the last authentication
 227                 operation if an error occurred during the process. This
 228                 is directly the status value from the DMA configuration
 229                 based mailbox before the device is power cycled. Writing
 230                 0 here clears the status.
 231
 232 What:           /sys/bus/thunderbolt/devices/.../nvm_authenticate_on_disconnect
 233 Date:           Oct 2020
 234 KernelVersion:  v5.9
 235 Contact:        Mario Limonciello <mario.limonciello@outlook.com>
 236 Description:    For supported devices, automatically authenticate the new Thunderbolt
 237                 image when the device is disconnected from the host system.
 238
 239                 This file will accept writing values "1" or "2"
 240
 241                 - Writing "1" will flush the image to the storage
 242                   area and prepare the device for authentication on disconnect.
 243                 - Writing "2" will run some basic validation on the image
 244                   and flush it to the storage area.
 245
 246 What:           /sys/bus/thunderbolt/devices/<xdomain>.<service>/key
 247 Date:           Jan 2018
 248 KernelVersion:  4.15
 249 Contact:        thunderbolt-software@lists.01.org
 250 Description:    This contains name of the property directory the XDomain
 251                 service exposes. This entry describes the protocol in
 252                 question. Following directories are already reserved by
 253                 the Apple XDomain specification:
 254
 255                 ========  ===============================================
 256                 network   IP/ethernet over Thunderbolt
 257                 targetdm  Target disk mode protocol over Thunderbolt
 258                 extdisp   External display mode protocol over Thunderbolt
 259                 ========  ===============================================
 260
 261 What:           /sys/bus/thunderbolt/devices/<xdomain>.<service>/modalias
 262 Date:           Jan 2018
 263 KernelVersion:  4.15
 264 Contact:        thunderbolt-software@lists.01.org
 265 Description:    Stores the same MODALIAS value emitted by uevent for
 266                 the XDomain service. Format: tbtsvc:kSpNvNrN
 267
 268 What:           /sys/bus/thunderbolt/devices/<xdomain>.<service>/prtcid
 269 Date:           Jan 2018
 270 KernelVersion:  4.15
 271 Contact:        thunderbolt-software@lists.01.org
 272 Description:    This contains XDomain protocol identifier the XDomain
 273                 service supports.
 274
 275 What:           /sys/bus/thunderbolt/devices/<xdomain>.<service>/prtcvers
 276 Date:           Jan 2018
 277 KernelVersion:  4.15
 278 Contact:        thunderbolt-software@lists.01.org
 279 Description:    This contains XDomain protocol version the XDomain
 280                 service supports.
 281
 282 What:           /sys/bus/thunderbolt/devices/<xdomain>.<service>/prtcrevs
 283 Date:           Jan 2018
 284 KernelVersion:  4.15
 285 Contact:        thunderbolt-software@lists.01.org
 286 Description:    This contains XDomain software version the XDomain
 287                 service supports.
 288
 289 What:           /sys/bus/thunderbolt/devices/<xdomain>.<service>/prtcstns
 290 Date:           Jan 2018
 291 KernelVersion:  4.15
 292 Contact:        thunderbolt-software@lists.01.org
 293 Description:    This contains XDomain service specific settings as
 294                 bitmask. Format: %x
 295
 296 What:           /sys/bus/thunderbolt/devices/usb4_portX/link
 297 Date:           Sep 2021
 298 KernelVersion:  v5.14
 299 Contact:        Mika Westerberg <mika.westerberg@linux.intel.com>
 300 Description:    Returns the current link mode. Possible values are
 301                 "usb4", "tbt" and "none".
 302
 303 What:           /sys/bus/thunderbolt/devices/usb4_portX/offline
 304 Date:           Sep 2021
 305 KernelVersion:  v5.14
 306 Contact:        Rajmohan Mani <rajmohan.mani@intel.com>
 307 Description:    Writing 1 to this attribute puts the USB4 port into
 308                 offline mode. Only allowed when there is nothing
 309                 connected to the port (link attribute returns "none").
 310                 Once the port is in offline mode it does not receive any
 311                 hotplug events. This is used to update NVM firmware of
 312                 on-board retimers. Writing 0 puts the port back to
 313                 online mode.
 314
 315                 This attribute is only visible if the platform supports
 316                 powering on retimers when there is no cable connected.
 317
 318 What:           /sys/bus/thunderbolt/devices/usb4_portX/rescan
 319 Date:           Sep 2021
 320 KernelVersion:  v5.14
 321 Contact:        Rajmohan Mani <rajmohan.mani@intel.com>
 322 Description:    When the USB4 port is in offline mode writing 1 to this
 323                 attribute forces rescan of the sideband for on-board
 324                 retimers. Each retimer appear under the USB4 port as if
 325                 the USB4 link was up. These retimers act in the same way
 326                 as if the cable was connected so upgrading their NVM
 327                 firmware can be done the usual way.
 328
 329 What:           /sys/bus/thunderbolt/devices/<device>:<port>.<index>/device
 330 Date:           Oct 2020
 331 KernelVersion:  v5.9
 332 Contact:        Mika Westerberg <mika.westerberg@linux.intel.com>
 333 Description:    Retimer device identifier read from the hardware.
 334
 335 What:           /sys/bus/thunderbolt/devices/<device>:<port>.<index>/nvm_authenticate
 336 Date:           Oct 2020
 337 KernelVersion:  v5.9
 338 Contact:        Mika Westerberg <mika.westerberg@linux.intel.com>
 339 Description:    When new NVM image is written to the non-active NVM
 340                 area (through non_activeX NVMem device), the
 341                 authentication procedure is started by writing 1 to
 342                 this file. If everything goes well, the device is
 343                 restarted with the new NVM firmware. If the image
 344                 verification fails an error code is returned instead.
 345
 346                 When read holds status of the last authentication
 347                 operation if an error occurred during the process.
 348                 Format: %x.
 349
 350 What:           /sys/bus/thunderbolt/devices/<device>:<port>.<index>/nvm_version
 351 Date:           Oct 2020
 352 KernelVersion:  v5.9
 353 Contact:        Mika Westerberg <mika.westerberg@linux.intel.com>
 354 Description:    Holds retimer NVM version number. Format: %x.%x, major.minor.
 355
 356 What:           /sys/bus/thunderbolt/devices/<device>:<port>.<index>/vendor
 357 Date:           Oct 2020
 358 KernelVersion:  v5.9
 359 Contact:        Mika Westerberg <mika.westerberg@linux.intel.com>
 360 Description:    Retimer vendor identifier read from the hardware.