From: Mika Westerberg <mika.westerberg@linux.intel.com>
To: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Cc: Andreas Noever <andreas.noever@gmail.com>,
Michael Jamet <michael.jamet@intel.com>,
Yehezkel Bernat <yehezkel.bernat@intel.com>,
Lukas Wunner <lukas@wunner.de>,
Amir Levy <amir.jer.levy@intel.com>,
Andy Lutomirski <luto@kernel.org>,
Mario.Limonciello@dell.com, Jared.Dominguez@dell.com,
Andy Shevchenko <andriy.shevchenko@linux.intel.com>,
Mika Westerberg <mika.westerberg@linux.intel.com>,
linux-kernel@vger.kernel.org
Subject: [PATCH v2 26/27] thunderbolt: Add documentation how Thunderbolt bus can be used
Date: Fri, 26 May 2017 19:09:35 +0300 [thread overview]
Message-ID: <20170526160936.54265-27-mika.westerberg@linux.intel.com> (raw)
In-Reply-To: <20170526160936.54265-1-mika.westerberg@linux.intel.com>
Since there are no such tool yet that handles all the low-level details
of connecting devices and upgrading their firmware, add a small document
that shows how the Thunderbolt bus can be used directly from command
line.
Signed-off-by: Mika Westerberg <mika.westerberg@linux.intel.com>
Reviewed-by: Yehezkel Bernat <yehezkel.bernat@intel.com>
Reviewed-by: Michael Jamet <michael.jamet@intel.com>
Reviewed-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
---
Documentation/admin-guide/index.rst | 1 +
Documentation/admin-guide/thunderbolt.rst | 197 ++++++++++++++++++++++++++++++
2 files changed, 198 insertions(+)
create mode 100644 Documentation/admin-guide/thunderbolt.rst
diff --git a/Documentation/admin-guide/index.rst b/Documentation/admin-guide/index.rst
index 8c60a8a32a1a..6d99a7ce6e21 100644
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -61,6 +61,7 @@ configure specific aspects of kernel behavior to your liking.
java
ras
pm/index
+ thunderbolt
.. only:: subproject and html
diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst
new file mode 100644
index 000000000000..c985241c8521
--- /dev/null
+++ b/Documentation/admin-guide/thunderbolt.rst
@@ -0,0 +1,197 @@
+=============
+ Thunderbolt
+=============
+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.
+
+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
+``/etc/udev/rules.d/99-local.rules``::
+
+ ACTION=="add", SUBSYSTEM=="thunderbolt", ATTR{authorized}=="0", ATTR{authorized}="1"
+
+This will authorize all devices automatically when they appear. However,
+keep in mind that this bypasses the security levels and makes the system
+vulnerable to DMA attacks.
+
+Security levels and how to use them
+-----------------------------------
+Starting from 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
+this by setting up an IOMMU but it is not always available for various
+reasons.
+
+The security levels are as follows:
+
+ none
+ All devices are automatically connected by the firmware. No user
+ approval is needed. In BIOS settings this is typically called
+ *Legacy mode*.
+
+ 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.
+ 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
+ typically called *One time saved key*.
+
+ dponly
+ The firmware automatically creates tunnels for Display Port and
+ USB. No PCIe tunneling is done. In BIOS settings this is
+ typically called *Display Port Only*.
+
+The current security level can be read from
+``/sys/bus/thunderbolt/devices/domainX/security`` where ``domainX`` is
+the Thunderbolt domain the host controller manages. There is typically
+one domain per Thunderbolt host controller.
+
+If the security level reads as ``user`` or ``secure`` the connected
+device must be authorized by the user before PCIe tunnels are created
+(e.g the PCIe device appears).
+
+Each Thunderbolt device plugged in will appear in sysfs under
+``/sys/bus/thunderbolt/devices``. The device directory carries
+information that can be used to identify the particular device,
+including its name and UUID.
+
+Authorizing devices when security level is ``user`` or ``secure``
+-----------------------------------------------------------------
+When a device is plugged in it will appear in sysfs as follows::
+
+ /sys/bus/thunderbolt/devices/0-1/authorized - 0
+ /sys/bus/thunderbolt/devices/0-1/device - 0x8004
+ /sys/bus/thunderbolt/devices/0-1/device_name - Thunderbolt to FireWire Adapter
+ /sys/bus/thunderbolt/devices/0-1/vendor - 0x1
+ /sys/bus/thunderbolt/devices/0-1/vendor_name - Apple, Inc.
+ /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::
+
+ # echo 1 > /sys/bus/thunderbolt/devices/0-1/authorized
+
+This will create the PCIe tunnels and the device is now connected.
+
+If the device supports secure connect it has an additional attribute
+``key`` which can hold a random value used for authorization and
+challenging the device in future connects::
+
+ /sys/bus/thunderbolt/devices/0-3/authorized - 0
+ /sys/bus/thunderbolt/devices/0-3/device - 0x305
+ /sys/bus/thunderbolt/devices/0-3/device_name - AKiTiO Thunder3 PCIe Box
+ /sys/bus/thunderbolt/devices/0-3/key -
+ /sys/bus/thunderbolt/devices/0-3/vendor - 0x41
+ /sys/bus/thunderbolt/devices/0-3/vendor_name - inXtron
+ /sys/bus/thunderbolt/devices/0-3/unique_id - dc010000-0000-8508-a22d-32ca6421cb16
+
+Notice the key is empty by default.
+
+If the user does not want to use secure connect it can just echo 1 to
+the ``authorized`` attribute and the PCIe tunnels will be created.
+
+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::
+
+ # key=$(openssl rand -hex 32)
+ # echo $key > /sys/bus/thunderbolt/devices/0-3/key
+ # echo 1 > /sys/bus/thunderbolt/devices/0-3/authorized
+
+Now the device is connected (PCIe tunnels are created) and in addition
+the key is stored on the device NVM.
+
+Next time the device is plugged in the user can verify (challenge) the
+device using the same key::
+
+ # echo $key > /sys/bus/thunderbolt/devices/0-3/key
+ # echo 2 > /sys/bus/thunderbolt/devices/0-3/authorized
+
+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
+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
+``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
+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
+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
+state where it cannot be used properly anymore without special tools!
+
+Host NVM upgrade on Apple Macs is not supported.
+
+Once the NVM image has been downloaded, you need to plug in a
+Thunderbolt device so that the host controller appears. It does not
+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
+be available for your system in which case there is no need to plug in a
+Thunderbolt device.
+
+After that we can write the firmware to the non-active parts of the NVM
+of the host or device. As an example here is how Intel NUC6i7KYK (Skull
+Canyon) Thunderbolt controller NVM is upgraded::
+
+ # dd if=KYK_TBT_FW_0018.bin of=/sys/bus/thunderbolt/devices/0-0/nvm_non_active0/nvmem
+
+Once the operation completes we can trigger NVM authentication and
+upgrade process as follows::
+
+ # echo 1 > /sys/bus/thunderbolt/devices/0-0/nvm_authenticate
+
+If no errors are returned, the host controller shortly disappears. Once
+it comes back the driver notices it and initiates a full power cycle.
+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
+commands::
+
+ # cat /sys/bus/thunderbolt/devices/0-0/nvm_authenticate
+ 0x0
+ # cat /sys/bus/thunderbolt/devices/0-0/nvm_version
+ 18.0
+
+If ``nvm_authenticate`` contains anything else 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
+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
+``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.
--
2.11.0
next prev parent reply other threads:[~2017-05-26 16:10 UTC|newest]
Thread overview: 43+ messages / expand[flat|nested] mbox.gz Atom feed top
2017-05-26 16:09 [PATCH v2 00/27] Thunderbolt security levels and NVM firmware upgrade Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 01/27] thunderbolt: Use const buffer pointer in write operations Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 02/27] thunderbolt: No need to read UID of the root switch on resume Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 03/27] thunderbolt: Do not try to read UID if DROM offset is read as 0 Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 04/27] thunderbolt: Do not warn about newer DROM versions Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 05/27] thunderbolt: Add MSI-X support Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 06/27] thunderbolt: Rework capability handling Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 07/27] thunderbolt: Allow passing NULL to tb_ctl_free() Mika Westerberg
2017-05-27 15:41 ` Andy Shevchenko
2017-05-28 8:13 ` Mika Westerberg
2017-05-29 12:14 ` Andy Shevchenko
2017-05-26 16:09 ` [PATCH v2 08/27] thunderbolt: Introduce thunderbolt bus and connection manager Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 09/27] thunderbolt: Convert switch to a device Mika Westerberg
2017-05-27 15:45 ` Andy Shevchenko
2017-05-28 8:40 ` Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 10/27] thunderbolt: Fail switch adding operation if reading DROM fails Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 11/27] thunderbolt: Do not fail if DROM data CRC32 is invalid Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 12/27] thunderbolt: Refactor and fix parsing of port drom entries Mika Westerberg
2017-05-27 15:46 ` Andy Shevchenko
2017-05-26 16:09 ` [PATCH v2 13/27] thunderbolt: Read vendor and device name from DROM Mika Westerberg
2017-05-27 15:57 ` Andy Shevchenko
2017-05-27 15:58 ` Andy Shevchenko
2017-05-28 8:45 ` Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 14/27] thunderbolt: Move control channel messages to tb_msgs.h Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 15/27] thunderbolt: Expose get_route() to other files Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 16/27] thunderbolt: Expose make_header() " Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 17/27] thunderbolt: Let the connection manager handle all notifications Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 18/27] thunderbolt: Rework control channel to be more reliable Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 19/27] thunderbolt: Add new Thunderbolt PCI IDs Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 20/27] thunderbolt: Add support for NHI mailbox Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 21/27] thunderbolt: Store Thunderbolt generation in the switch structure Mika Westerberg
2017-05-27 16:03 ` Andy Shevchenko
2017-05-26 16:09 ` [PATCH v2 22/27] thunderbolt: Add support for DMA configuration based mailbox Mika Westerberg
2017-05-27 16:08 ` Andy Shevchenko
2017-05-28 9:10 ` Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 23/27] thunderbolt: Do not touch the hardware if the NHI is gone on resume Mika Westerberg
2017-05-26 16:09 ` [PATCH v2 24/27] thunderbolt: Add support for Internal Connection Manager (ICM) Mika Westerberg
2017-05-27 20:45 ` Andy Shevchenko
2017-05-28 9:13 ` Mika Westerberg
2017-05-28 10:13 ` Andy Shevchenko
2017-05-26 16:09 ` [PATCH v2 25/27] thunderbolt: Add support for host and device NVM firmware upgrade Mika Westerberg
2017-05-26 16:09 ` Mika Westerberg [this message]
2017-05-26 16:09 ` [PATCH v2 27/27] MAINTAINERS: Add maintainers for Thunderbolt driver Mika Westerberg
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20170526160936.54265-27-mika.westerberg@linux.intel.com \
--to=mika.westerberg@linux.intel.com \
--cc=Jared.Dominguez@dell.com \
--cc=Mario.Limonciello@dell.com \
--cc=amir.jer.levy@intel.com \
--cc=andreas.noever@gmail.com \
--cc=andriy.shevchenko@linux.intel.com \
--cc=gregkh@linuxfoundation.org \
--cc=linux-kernel@vger.kernel.org \
--cc=lukas@wunner.de \
--cc=luto@kernel.org \
--cc=michael.jamet@intel.com \
--cc=yehezkel.bernat@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).