Merge tag 'docs-4.16-2' of git://git.lwn.net/linux

=============

The interface presented here is not meant for end users. Instead there

should be a userspace tool that handles all the low-level details, keeps

database of the authorized devices and prompts user for new connections.

a database of the authorized devices and prompts users for new connections.

More details about the sysfs interface for Thunderbolt devices can be

found in ``Documentation/ABI/testing/sysfs-bus-thunderbolt``.

Those users who just want to connect any device without any sort of

manual work, can add following line to

manual work can add following line to

``/etc/udev/rules.d/99-local.rules``::

  ACTION=="add", SUBSYSTEM=="thunderbolt", ATTR{authorized}=="0", ATTR{authorized}="1"

Security levels and how to use them

-----------------------------------

Starting from Intel Falcon Ridge Thunderbolt controller there are 4

Starting with Intel Falcon Ridge Thunderbolt controller there are 4

security levels available. The reason for these is the fact that the

connected devices can be DMA masters and thus read contents of the host

memory without CPU and OS knowing about it. There are ways to prevent

  user

    User is asked whether the device is allowed to be connected.

    Based on the device identification information available through

    ``/sys/bus/thunderbolt/devices``. user then can do the decision.

    ``/sys/bus/thunderbolt/devices``, the user then can make the decision.

    In BIOS settings this is typically called *Unique ID*.

  secure

    User is asked whether the device is allowed to be connected. In

    addition to UUID the device (if it supports secure connect) is sent

    a challenge that should match the expected one based on a random key

    written to ``key`` sysfs attribute. In BIOS settings this is

    written to the ``key`` sysfs attribute. In BIOS settings this is

    typically called *One time saved key*.

  dponly

  /sys/bus/thunderbolt/devices/0-1/unique_id	- e0376f00-0300-0100-ffff-ffffffffffff

The ``authorized`` attribute reads 0 which means no PCIe tunnels are

created yet. The user can authorize the device by simply::

created yet. The user can authorize the device by simply entering::

  # echo 1 > /sys/bus/thunderbolt/devices/0-1/authorized

If the device supports secure connect, and the domain security level is

set to ``secure``, it has an additional attribute ``key`` which can hold

a random 32 byte value used for authorization and challenging the device in

a random 32-byte value used for authorization and challenging the device in

future connects::

  /sys/bus/thunderbolt/devices/0-3/authorized	- 0

Notice the key is empty by default.

If the user does not want to use secure connect it can just ``echo 1``

If the user does not want to use secure connect they can just ``echo 1``

to the ``authorized`` attribute and the PCIe tunnels will be created in

the same way than in ``user`` security level.

the same way as in the ``user`` security level.

If the user wants to use secure connect, the first time the device is

plugged a key needs to be created and send to the device::

plugged a key needs to be created and sent to the device::

  # key=$(openssl rand -hex 32)

  # echo $key > /sys/bus/thunderbolt/devices/0-3/key

If the challenge the device returns back matches the one we expect based

on the key, the device is connected and the PCIe tunnels are created.

However, if the challenge failed no tunnels are created and error is

However, if the challenge fails no tunnels are created and error is

returned to the user.

If the user still wants to connect the device it can either approve

the device without a key or write new key and write 1 to the

If the user still wants to connect the device they can either approve

the device without a key or write a new key and write 1 to the

``authorized`` file to get the new key stored on the device NVM.

Upgrading NVM on Thunderbolt device or host

-------------------------------------------

Since most of the functionality is handled in a firmware running on a

Since most of the functionality is handled in firmware running on a

host controller or a device, it is important that the firmware can be

upgraded to the latest where possible bugs in it have been fixed.

Typically OEMs provide this firmware from their support site.

There is also a central site which has links where to download firmwares

There is also a central site which has links where to download firmware

for some machines:

  `Thunderbolt Updates <https://thunderbolttechnology.net/updates>`_

Before you upgrade firmware on a device or host, please make sure it is

the suitable. Failing to do that may render the device (or host) in a

Before you upgrade firmware on a device or host, please make sure it is a

suitable upgrade. Failing to do that may render the device (or host) in a

state where it cannot be used properly anymore without special tools!

Host NVM upgrade on Apple Macs is not supported.

matter which device is connected (unless you are upgrading NVM on a

device - then you need to connect that particular device).

Note OEM-specific method to power the controller up ("force power") may

Note an OEM-specific method to power the controller up ("force power") may

be available for your system in which case there is no need to plug in a

Thunderbolt device.

After a while the host controller appears again and this time it should

be fully functional.

We can verify that the new NVM firmware is active by running following

We can verify that the new NVM firmware is active by running the following

commands::

  # cat /sys/bus/thunderbolt/devices/0-0/nvm_authenticate

  # cat /sys/bus/thunderbolt/devices/0-0/nvm_version

  18.0

If ``nvm_authenticate`` contains anything else than 0x0 it is the error

If ``nvm_authenticate`` contains anything other than 0x0 it is the error

code from the last authentication cycle, which means the authentication

of the NVM image failed.

Note names of the NVMem devices ``nvm_activeN`` and ``nvm_non_activeN``

depends on the order they are registered in the NVMem subsystem. N in

depend on the order they are registered in the NVMem subsystem. N in

the name is the identifier added by the NVMem subsystem.

Upgrading NVM when host controller is in safe mode

--------------------------------------------------

If the existing NVM is not properly authenticated (or is missing) the

host controller goes into safe mode which means that only available

functionality is flashing new NVM image. When in this mode the reading

host controller goes into safe mode which means that the only available

functionality is flashing a new NVM image. When in this mode, reading

``nvm_version`` fails with ``ENODATA`` and the device identification

information is missing.

To recover from this mode, one needs to flash a valid NVM image to the

host host controller in the same way it is done in the previous chapter.

host controller in the same way it is done in the previous chapter.

Networking over Thunderbolt cable

---------------------------------

Thunderbolt technology allows software communication across two hosts

Thunderbolt technology allows software communication between two hosts

connected by a Thunderbolt cable.

It is possible to tunnel any kind of traffic over Thunderbolt link but

It is possible to tunnel any kind of traffic over a Thunderbolt link but

currently we only support Apple ThunderboltIP protocol.

If the other host is running Windows or macOS only thing you need to

do is to connect Thunderbolt cable between the two hosts, the

``thunderbolt-net`` is loaded automatically. If the other host is also

Linux you should load ``thunderbolt-net`` manually on one host (it does

not matter which one)::

If the other host is running Windows or macOS, the only thing you need to

do is to connect a Thunderbolt cable between the two hosts; the

``thunderbolt-net`` driver is loaded automatically. If the other host is

also Linux you should load ``thunderbolt-net`` manually on one host (it

does not matter which one)::

  # modprobe thunderbolt-net

The driver will create one virtual ethernet interface per Thunderbolt

port which are named like ``thunderbolt0`` and so on. From this point

you can either use standard userspace tools like ``ifconfig`` to

configure the interface or let your GUI to handle it automatically.

configure the interface or let your GUI handle it automatically.

Forcing power

-------------

Many OEMs include a method that can be used to force the power of a

thunderbolt controller to an "On" state even if nothing is connected.

Thunderbolt controller to an "On" state even if nothing is connected.

If supported by your machine this will be exposed by the WMI bus with

a sysfs attribute called "force_power".

  CONFIG_BLK_DEV_IDE_AU1XXX_PIO_DBDMA    - enable the PIO+DBDMA mode

  CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA  - enable the MWDMA mode

  CONFIG_BLK_DEV_IDE_AU1XXX_BURSTABLE_ON - set Burstable FIFO in DBDMA

                                           controller

SUPPORTED IDE MODES

CONFIG_BLK_DEV_IDEPCI=y

CONFIG_BLK_DEV_GENERIC=y

CONFIG_BLK_DEV_IDEDMA_PCI=y

CONFIG_IDEDMA_PCI_AUTO=y

CONFIG_BLK_DEV_IDE_AU1XXX=y

CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y

CONFIG_BLK_DEV_IDEDMA=y

CONFIG_IDEDMA_AUTO=y

Also define 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to enable

the burst support on DBDMA controller.

If the used system need the USB support enable the following kernel configs for

high IDE to USB throughput.

CONFIG_BLK_DEV_IDEDISK=y

CONFIG_IDE_GENERIC=y

CONFIG_BLK_DEV_IDEPCI=y

CONFIG_BLK_DEV_GENERIC=y

CONFIG_BLK_DEV_IDEDMA_PCI=y

CONFIG_IDEDMA_PCI_AUTO=y

CONFIG_BLK_DEV_IDE_AU1XXX=y

CONFIG_BLK_DEV_IDE_AU1XXX_MDMA2_DBDMA=y

CONFIG_BLK_DEV_IDEDMA=y

CONFIG_IDEDMA_AUTO=y

Also undefine 'IDE_AU1XXX_BURSTMODE' in 'drivers/ide/mips/au1xxx-ide.c' to

disable the burst support on DBDMA controller.

   development-process

   submitting-patches

   coding-style

   maintainer-pgp-guide

   email-clients

   kernel-enforcement-statement

   kernel-driver-statement

    * Title: **Linux Kernel Mailing List Glossary**

      :Author: various

      :URL: http://kernelnewbies.org/glossary/

      :URL: https://kernelnewbies.org/KernelGlossary

      :Date: rolling version

      :Keywords: glossary, terms, linux-kernel.

      :Description: From the introduction: "This glossary is intended as