diff options
Diffstat (limited to 'Documentation/admin-guide')
| -rw-r--r-- | Documentation/admin-guide/README.rst | 16 | ||||
| -rw-r--r-- | Documentation/admin-guide/kernel-parameters.rst | 1 | ||||
| -rw-r--r-- | Documentation/admin-guide/kernel-parameters.txt | 201 | ||||
| -rw-r--r-- | Documentation/admin-guide/module-signing.rst | 10 | ||||
| -rw-r--r-- | Documentation/admin-guide/mono.rst | 6 | ||||
| -rw-r--r-- | Documentation/admin-guide/security-bugs.rst | 24 | ||||
| -rw-r--r-- | Documentation/admin-guide/tainted-kernels.rst | 18 | ||||
| -rw-r--r-- | Documentation/admin-guide/thunderbolt.rst | 81 |
8 files changed, 233 insertions, 124 deletions
diff --git a/Documentation/admin-guide/README.rst b/Documentation/admin-guide/README.rst index 63066db39910..02caa7efd5ef 100644 --- a/Documentation/admin-guide/README.rst +++ b/Documentation/admin-guide/README.rst @@ -26,8 +26,8 @@ On what hardware does it run? Although originally developed first for 32-bit x86-based PCs (386 or higher), today Linux also runs on (at least) the Compaq Alpha AXP, Sun SPARC and UltraSPARC, Motorola 68000, PowerPC, PowerPC64, ARM, Hitachi SuperH, Cell, - IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64, AXIS CRIS, - Xtensa, Tilera TILE, ARC and Renesas M32R architectures. + IBM S/390, MIPS, HP PA-RISC, Intel IA-64, DEC VAX, AMD x86-64 Xtensa, and + ARC architectures. Linux is easily portable to most general-purpose 32- or 64-bit architectures as long as they have a paged memory management unit (PMMU) and a port of the @@ -170,11 +170,6 @@ Configuring the kernel your existing ./.config file and asking about new config symbols. - "make silentoldconfig" - Like above, but avoids cluttering the screen - with questions already answered. - Additionally updates the dependencies. - "make olddefconfig" Like above, but sets new symbols to their default values without prompting. @@ -223,6 +218,13 @@ Configuring the kernel "make localyesconfig" Similar to localmodconfig, except it will convert all module options to built in (=y) options. + "make kvmconfig" Enable additional options for kvm guest kernel support. + + "make xenconfig" Enable additional options for xen dom0 guest kernel + support. + + "make tinyconfig" Configure the tiniest possible kernel. + You can find more information on using the Linux kernel config tools in Documentation/kbuild/kconfig.txt. diff --git a/Documentation/admin-guide/kernel-parameters.rst b/Documentation/admin-guide/kernel-parameters.rst index 7242cbda15dd..b8d0bc07ed0a 100644 --- a/Documentation/admin-guide/kernel-parameters.rst +++ b/Documentation/admin-guide/kernel-parameters.rst @@ -89,7 +89,6 @@ parameter is applicable:: APM Advanced Power Management support is enabled. ARM ARM architecture is enabled. AX25 Appropriate AX.25 support is enabled. - BLACKFIN Blackfin architecture is enabled. CLK Common clock infrastructure is enabled. CMA Contiguous Memory Area support is enabled. DRM Direct Rendering Management support is enabled. diff --git a/Documentation/admin-guide/kernel-parameters.txt b/Documentation/admin-guide/kernel-parameters.txt index 93366b00bb62..7efed1ccddc9 100644 --- a/Documentation/admin-guide/kernel-parameters.txt +++ b/Documentation/admin-guide/kernel-parameters.txt @@ -114,7 +114,6 @@ This facility can be used to prevent such uncontrolled GPE floodings. Format: <int> - Support masking of GPEs numbered from 0x00 to 0x7f. acpi_no_auto_serialize [HW,ACPI] Disable auto-serialization of AML methods @@ -223,7 +222,7 @@ acpi_sleep= [HW,ACPI] Sleep options Format: { s3_bios, s3_mode, s3_beep, s4_nohwsig, - old_ordering, nonvs, sci_force_enable } + old_ordering, nonvs, sci_force_enable, nobl } See Documentation/power/video.txt for information on s3_bios and s3_mode. s3_beep is for debugging; it makes the PC's speaker beep @@ -239,6 +238,9 @@ sci_force_enable causes the kernel to set SCI_EN directly on resume from S1/S3 (which is against the ACPI spec, but some broken systems don't work without it). + nobl causes the internal blacklist of systems known to + behave incorrectly in some ways with respect to system + suspend and resume to be ignored (use wisely). acpi_use_timer_override [HW,ACPI] Use timer override. For some broken Nvidia NF5 boards @@ -644,6 +646,20 @@ console=brl,ttyS0 For now, only VisioBraille is supported. + console_msg_format= + [KNL] Change console messages format + default + By default we print messages on consoles in + "[time stamp] text\n" format (time stamp may not be + printed, depending on CONFIG_PRINTK_TIME or + `printk_time' param). + syslog + Switch to syslog format: "<%u>[time stamp] text\n" + IOW, each message will have a facility and loglevel + prefix. The format is similar to one used by syslog() + syscall, or to executing "dmesg -S --raw" or to reading + from /proc/kmsg. + consoleblank= [KNL] The console blank (screen saver) timeout in seconds. A value of 0 disables the blank timer. Defaults to 0. @@ -915,9 +931,12 @@ earlycon= [KNL] Output early console device and options. - When used with no options, the early console is - determined by the stdout-path property in device - tree's chosen node. + [ARM64] The early console is determined by the + stdout-path property in device tree's chosen node, + or determined by the ACPI SPCR table. + + [X86] When used with no options the early console is + determined by the ACPI SPCR table. cdns,<addr>[,options] Start an early, polled-mode console on a Cadence @@ -1006,7 +1025,7 @@ address. The serial port must already be setup and configured. Options are not yet supported. - earlyprintk= [X86,SH,BLACKFIN,ARM,M68k,S390] + earlyprintk= [X86,SH,ARM,M68k,S390] earlyprintk=vga earlyprintk=efi earlyprintk=sclp @@ -1328,10 +1347,6 @@ If specified, z/VM IUCV HVC accepts connections from listed z/VM user IDs only. - hwthread_map= [METAG] Comma-separated list of Linux cpu id to - hardware thread id mappings. - Format: <cpu>:<hwthread> - keep_bootcon [KNL] Do not unregister boot console at start. This is only useful for debugging when something happens in the window @@ -1724,6 +1739,14 @@ of a GICv2 controller even if the memory range exposed by the device tree is too small. + irqchip.gicv3_nolpi= + [ARM, ARM64] + Force the kernel to ignore the availability of + LPIs (and by consequence ITSs). Intended for system + that use the kernel as a bootloader, and thus want + to let secondary kernels in charge of setting up + LPIs. + irqfixup [HW] When an interrupt is not handled search all handlers for it. Intended to get systems with badly broken @@ -1747,6 +1770,17 @@ nohz Disable the tick when a single task runs. + + A residual 1Hz tick is offloaded to workqueues, which you + need to affine to housekeeping through the global + workqueue's affinity configured via the + /sys/devices/virtual/workqueue/cpumask sysfs file, or + by using the 'domain' flag described below. + + NOTE: by default the global workqueue runs on all CPUs, + so to protect individual CPUs the 'cpumask' file has to + be configured manually after bootup. + domain Isolate from the general SMP balancing and scheduling algorithms. Note that performing domain isolation this way @@ -1806,30 +1840,29 @@ keepinitrd [HW,ARM] kernelcore= [KNL,X86,IA-64,PPC] - Format: nn[KMGTPE] | "mirror" - This parameter - specifies the amount of memory usable by the kernel - for non-movable allocations. The requested amount is - spread evenly throughout all nodes in the system. The - remaining memory in each node is used for Movable - pages. In the event, a node is too small to have both - kernelcore and Movable pages, kernelcore pages will - take priority and other nodes will have a larger number - of Movable pages. The Movable zone is used for the - allocation of pages that may be reclaimed or moved - by the page migration subsystem. This means that - HugeTLB pages may not be allocated from this zone. - Note that allocations like PTEs-from-HighMem still - use the HighMem zone if it exists, and the Normal + Format: nn[KMGTPE] | nn% | "mirror" + This parameter specifies the amount of memory usable by + the kernel for non-movable allocations. The requested + amount is spread evenly throughout all nodes in the + system as ZONE_NORMAL. The remaining memory is used for + movable memory in its own zone, ZONE_MOVABLE. In the + event, a node is too small to have both ZONE_NORMAL and + ZONE_MOVABLE, kernelcore memory will take priority and + other nodes will have a larger ZONE_MOVABLE. + + ZONE_MOVABLE is used for the allocation of pages that + may be reclaimed or moved by the page migration + subsystem. Note that allocations like PTEs-from-HighMem + still use the HighMem zone if it exists, and the Normal zone if it does not. - Instead of specifying the amount of memory (nn[KMGTPE]), - you can specify "mirror" option. In case "mirror" + It is possible to specify the exact amount of memory in + the form of "nn[KMGTPE]", a percentage of total system + memory in the form of "nn%", or "mirror". If "mirror" option is specified, mirrored (reliable) memory is used for non-movable allocations and remaining memory is used - for Movable pages. nn[KMGTPE] and "mirror" are exclusive, - so you can NOT specify nn[KMGTPE] and "mirror" at the same - time. + for Movable pages. "nn[KMGTPE]", "nn%", and "mirror" + are exclusive, so you cannot specify multiple forms. kgdbdbgp= [KGDB,HW] kgdb over EHCI usb debug port. Format: <Controller#>[,poll interval] @@ -2050,9 +2083,6 @@ This tests the locking primitive's ability to transition abruptly to and from idle. - locktorture.torture_runnable= [BOOT] - Start locktorture running at boot time. - locktorture.torture_type= [KNL] Specify the locking implementation to test. @@ -2221,6 +2251,15 @@ The memory region may be marked as e820 type 12 (0xc) and is NVDIMM or ADR memory. + memmap=<size>%<offset>-<oldtype>+<newtype> + [KNL,ACPI] Convert memory within the specified region + from <oldtype> to <newtype>. If "-<oldtype>" is left + out, the whole region will be marked as <newtype>, + even if previously unavailable. If "+<newtype>" is left + out, matching memory will be removed. Types are + specified as e820 types, e.g., 1 = RAM, 2 = reserved, + 3 = ACPI, 12 = PRAM. + memory_corruption_check=0/1 [X86] Some BIOSes seem to corrupt the first 64k of memory when doing things like suspend/resume. @@ -2337,13 +2376,14 @@ mousedev.yres= [MOUSE] Vertical screen resolution, used for devices reporting absolute coordinates, such as tablets - movablecore=nn[KMG] [KNL,X86,IA-64,PPC] This parameter - is similar to kernelcore except it specifies the - amount of memory used for migratable allocations. - If both kernelcore and movablecore is specified, - then kernelcore will be at *least* the specified - value but may be more. If movablecore on its own - is specified, the administrator must be careful + movablecore= [KNL,X86,IA-64,PPC] + Format: nn[KMGTPE] | nn% + This parameter is the complement to kernelcore=, it + specifies the amount of memory used for migratable + allocations. If both kernelcore and movablecore is + specified, then kernelcore will be at *least* the + specified value but may be more. If movablecore on its + own is specified, the administrator must be careful that the amount of memory usable for all allocations is not too small. @@ -2539,6 +2579,9 @@ This is useful when you use a panic=... timeout and need the box quickly up again. + These settings can be accessed at runtime via + the nmi_watchdog and hardlockup_panic sysctls. + netpoll.carrier_timeout= [NET] Specifies amount of time (in seconds) that netpoll should wait for a carrier. By default netpoll @@ -2742,8 +2785,6 @@ norandmaps Don't use address space randomization. Equivalent to echo 0 > /proc/sys/kernel/randomize_va_space - noreplace-paravirt [X86,IA-64,PV_OPS] Don't patch paravirt_ops - noreplace-smp [X86-32,SMP] Don't replace SMP instructions with UP alternatives @@ -3486,9 +3527,6 @@ the same as for rcuperf.nreaders. N, where N is the number of CPUs - rcuperf.perf_runnable= [BOOT] - Start rcuperf running at boot time. - rcuperf.perf_type= [KNL] Specify the RCU implementation to test. @@ -3622,9 +3660,6 @@ Test RCU's dyntick-idle handling. See also the rcutorture.shuffle_interval parameter. - rcutorture.torture_runnable= [BOOT] - Start rcutorture running at boot time. - rcutorture.torture_type= [KNL] Specify the RCU implementation to test. @@ -3682,7 +3717,8 @@ rdt= [HW,X86,RDT] Turn on/off individual RDT features. List is: - cmt, mbmtotal, mbmlocal, l3cat, l3cdp, l2cat, mba. + cmt, mbmtotal, mbmlocal, l3cat, l3cdp, l2cat, l2cdp, + mba. E.g. to turn on cmt and turn off mba use: rdt=cmt,!mba @@ -3702,7 +3738,11 @@ [KNL, SMP] Set scheduler's default relax_domain_level. See Documentation/cgroup-v1/cpusets.txt. - reserve= [KNL,BUGS] Force the kernel to ignore some iomem area + reserve= [KNL,BUGS] Force kernel to ignore I/O ports or memory + Format: <base1>,<size1>[,<base2>,<size2>,...] + Reserve I/O ports or memory so the kernel won't use + them. If <base> is less than 0x10000, the region + is assumed to be I/O ports; otherwise it is memory. reservetop= [X86-32] Format: nn[KMG] @@ -4352,12 +4392,73 @@ usbcore.nousb [USB] Disable the USB subsystem + usbcore.quirks= + [USB] A list of quirk entries to augment the built-in + usb core quirk list. List entries are separated by + commas. Each entry has the form + VendorID:ProductID:Flags. The IDs are 4-digit hex + numbers and Flags is a set of letters. Each letter + will change the built-in quirk; setting it if it is + clear and clearing it if it is set. The letters have + the following meanings: + a = USB_QUIRK_STRING_FETCH_255 (string + descriptors must not be fetched using + a 255-byte read); + b = USB_QUIRK_RESET_RESUME (device can't resume + correctly so reset it instead); + c = USB_QUIRK_NO_SET_INTF (device can't handle + Set-Interface requests); + d = USB_QUIRK_CONFIG_INTF_STRINGS (device can't + handle its Configuration or Interface + strings); + e = USB_QUIRK_RESET (device can't be reset + (e.g morph devices), don't use reset); + f = USB_QUIRK_HONOR_BNUMINTERFACES (device has + more interface descriptions than the + bNumInterfaces count, and can't handle + talking to these interfaces); + g = USB_QUIRK_DELAY_INIT (device needs a pause + during initialization, after we read + the device descriptor); + h = USB_QUIRK_LINEAR_UFRAME_INTR_BINTERVAL (For + high speed and super speed interrupt + endpoints, the USB 2.0 and USB 3.0 spec + require the interval in microframes (1 + microframe = 125 microseconds) to be + calculated as interval = 2 ^ + (bInterval-1). + Devices with this quirk report their + bInterval as the result of this + calculation instead of the exponent + variable used in the calculation); + i = USB_QUIRK_DEVICE_QUALIFIER (device can't + handle device_qualifier descriptor + requests); + j = USB_QUIRK_IGNORE_REMOTE_WAKEUP (device + generates spurious wakeup, ignore + remote wakeup capability); + k = USB_QUIRK_NO_LPM (device can't handle Link + Power Management); + l = USB_QUIRK_LINEAR_FRAME_INTR_BINTERVAL + (Device reports its bInterval as linear + frames instead of the USB 2.0 + calculation); + m = USB_QUIRK_DISCONNECT_SUSPEND (Device needs + to be disconnected before suspend to + prevent spurious wakeup); + n = USB_QUIRK_DELAY_CTRL_MSG (Device needs a + pause after every control message); + Example: quirks=0781:5580:bk,0a5c:5834:gij + usbhid.mousepoll= [USBHID] The interval which mice are to be polled at. usbhid.jspoll= [USBHID] The interval which joysticks are to be polled at. + usbhid.kbpoll= + [USBHID] The interval which keyboards are to be polled at. + usb-storage.delay_use= [UMS] The delay in seconds before a new device is scanned for Logical Units (default 1). diff --git a/Documentation/admin-guide/module-signing.rst b/Documentation/admin-guide/module-signing.rst index 27e59498b487..f8b584179cff 100644 --- a/Documentation/admin-guide/module-signing.rst +++ b/Documentation/admin-guide/module-signing.rst @@ -180,11 +180,11 @@ Public keys in the kernel ========================= The kernel contains a ring of public keys that can be viewed by root. They're -in a keyring called ".system_keyring" that can be seen by:: +in a keyring called ".builtin_trusted_keys" that can be seen by:: [root@deneb ~]# cat /proc/keys ... - 223c7853 I------ 1 perm 1f030000 0 0 keyring .system_keyring: 1 + 223c7853 I------ 1 perm 1f030000 0 0 keyring .builtin_trusted_keys: 1 302d2d52 I------ 1 perm 1f010000 0 0 asymmetri Fedora kernel signing key: d69a84e6bce3d216b979e9505b3e3ef9a7118079: X509.RSA a7118079 [] ... @@ -197,15 +197,15 @@ add those in also (e.g. from the UEFI key database). Finally, it is possible to add additional public keys by doing:: - keyctl padd asymmetric "" [.system_keyring-ID] <[key-file] + keyctl padd asymmetric "" [.builtin_trusted_keys-ID] <[key-file] e.g.:: keyctl padd asymmetric "" 0x223c7853 <my_public_key.x509 Note, however, that the kernel will only permit keys to be added to -``.system_keyring _if_`` the new key's X.509 wrapper is validly signed by a key -that is already resident in the .system_keyring at the time the key was added. +``.builtin_trusted_keys`` **if** the new key's X.509 wrapper is validly signed by a key +that is already resident in the ``.builtin_trusted_keys`` at the time the key was added. ======================== diff --git a/Documentation/admin-guide/mono.rst b/Documentation/admin-guide/mono.rst index cdddc099af64..59e6d59f0ed9 100644 --- a/Documentation/admin-guide/mono.rst +++ b/Documentation/admin-guide/mono.rst @@ -9,14 +9,14 @@ This will allow you to execute Mono-based .NET binaries just like any other program after you have done the following: 1) You MUST FIRST install the Mono CLR support, either by downloading - a binary package, a source tarball or by installing from CVS. Binary + a binary package, a source tarball or by installing from Git. Binary packages for several distributions can be found at: - http://go-mono.com/download.html + http://www.mono-project.com/download/ Instructions for compiling Mono can be found at: - http://www.go-mono.com/compiling.html + http://www.mono-project.com/docs/compiling-mono/linux/ Once the Mono CLR support has been installed, just check that ``/usr/bin/mono`` (which could be located elsewhere, for example diff --git a/Documentation/admin-guide/security-bugs.rst b/Documentation/admin-guide/security-bugs.rst index 47574b382d75..30491d91e93d 100644 --- a/Documentation/admin-guide/security-bugs.rst +++ b/Documentation/admin-guide/security-bugs.rst @@ -29,18 +29,20 @@ made public. Disclosure ---------- -The goal of the Linux kernel security team is to work with the -bug submitter to bug resolution as well as disclosure. We prefer -to fully disclose the bug as soon as possible. It is reasonable to -delay disclosure when the bug or the fix is not yet fully understood, -the solution is not well-tested or for vendor coordination. However, we -expect these delays to be short, measurable in days, not weeks or months. -A disclosure date is negotiated by the security team working with the -bug submitter as well as vendors. However, the kernel security team -holds the final say when setting a disclosure date. The timeframe for -disclosure is from immediate (esp. if it's already publicly known) +The goal of the Linux kernel security team is to work with the bug +submitter to understand and fix the bug. We prefer to publish the fix as +soon as possible, but try to avoid public discussion of the bug itself +and leave that to others. + +Publishing the fix may be delayed when the bug or the fix is not yet +fully understood, the solution is not well-tested or for vendor +coordination. However, we expect these delays to be short, measurable in +days, not weeks or months. A release date is negotiated by the security +team working with the bug submitter as well as vendors. However, the +kernel security team holds the final say when setting a timeframe. The +timeframe varies from immediate (esp. if it's already publicly known bug) to a few weeks. As a basic default policy, we expect report date to -disclosure date to be on the order of 7 days. +release date to be on the order of 7 days. Coordination ------------ diff --git a/Documentation/admin-guide/tainted-kernels.rst b/Documentation/admin-guide/tainted-kernels.rst index 1df03b5cb02f..28a869c509a0 100644 --- a/Documentation/admin-guide/tainted-kernels.rst +++ b/Documentation/admin-guide/tainted-kernels.rst @@ -6,34 +6,34 @@ counter. This indicates that the kernel has been tainted by some mechanism. The string is followed by a series of position-sensitive characters, each representing a particular tainted value. - 1) 'G' if all modules loaded have a GPL or compatible license, 'P' if + 1) ``G`` if all modules loaded have a GPL or compatible license, ``P`` if any proprietary module has been loaded. Modules without a MODULE_LICENSE or with a MODULE_LICENSE that is not recognised by insmod as GPL compatible are assumed to be proprietary. - 2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all + 2) ``F`` if any module was force loaded by ``insmod -f``, ``' '`` if all modules were loaded normally. - 3) ``S`` if the oops occurred on an SMP kernel running on hardware that + 3) ``S`` if the oops occurred on an SMP kernel running on hardware that hasn't been certified as safe to run multiprocessor. Currently this occurs only on various Athlons that are not SMP capable. - 4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all + 4) ``R`` if a module was force unloaded by ``rmmod -f``, ``' '`` if all modules were unloaded normally. - 5) ``M`` if any processor has reported a Machine Check Exception, + 5) ``M`` if any processor has reported a Machine Check Exception, ``' '`` if no Machine Check Exceptions have occurred. - 6) ``B`` if a page-release function has found a bad page reference or + 6) ``B`` if a page-release function has found a bad page reference or some unexpected page flags. - 7) ``U`` if a user or user application specifically requested that the + 7) ``U`` if a user or user application specifically requested that the Tainted flag be set, ``' '`` otherwise. - 8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG. + 8) ``D`` if the kernel has died recently, i.e. there was an OOPS or BUG. - 9) ``A`` if the ACPI table has been overridden. + 9) ``A`` if the ACPI table has been overridden. 10) ``W`` if a warning has previously been issued by the kernel. (Though some warnings may set more specific taint flags.) diff --git a/Documentation/admin-guide/thunderbolt.rst b/Documentation/admin-guide/thunderbolt.rst index 9b55952039a6..35fccba6a9a6 100644 --- a/Documentation/admin-guide/thunderbolt.rst +++ b/Documentation/admin-guide/thunderbolt.rst @@ -3,13 +3,13 @@ ============= 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" @@ -20,12 +20,12 @@ 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. +Starting with Intel Falcon Ridge Thunderbolt controller there are 4 +security levels available. Intel Titan Ridge added one more security level +(usbonly). 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: @@ -37,14 +37,14 @@ The security levels are as follows: 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 @@ -52,6 +52,11 @@ The security levels are as follows: USB. No PCIe tunneling is done. In BIOS settings this is typically called *Display Port Only*. + usbonly + The firmware automatically creates tunnels for the USB controller and + Display Port in a dock. All PCIe links downstream of the dock are + removed. + 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 @@ -78,7 +83,7 @@ When a device is plugged in it will appear in sysfs as follows:: /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 @@ -86,7 +91,7 @@ This will create the PCIe tunnels and the device is now connected. 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 @@ -99,12 +104,12 @@ future connects:: 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 @@ -121,27 +126,27 @@ device using the same 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. @@ -151,7 +156,7 @@ 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 +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. @@ -171,7 +176,7 @@ 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 +We can verify that the new NVM firmware is active by running the following commands:: # cat /sys/bus/thunderbolt/devices/0-0/nvm_authenticate @@ -179,38 +184,38 @@ commands:: # 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 @@ -220,12 +225,12 @@ is built-in to the kernel image, there is no need to do anything. 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". |