diff options
Diffstat (limited to 'Documentation')
| -rw-r--r-- | Documentation/acpi/osi.txt | 187 | ||||
| -rw-r--r-- | Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.txt (renamed from Documentation/devicetree/bindings/ipmi/aspeed,ast2400-bt-bmc.txt) | 4 | ||||
| -rw-r--r-- | Documentation/devicetree/bindings/net/ethernet.txt | 24 | ||||
| -rw-r--r-- | Documentation/devicetree/bindings/sound/omap-abe-twl6040.txt | 2 | ||||
| -rw-r--r-- | Documentation/i2c/i2c-topology | 4 | ||||
| -rw-r--r-- | Documentation/networking/dsa/dsa.txt | 3 | ||||
| -rw-r--r-- | Documentation/networking/nf_conntrack-sysctl.txt | 7 | ||||
| -rw-r--r-- | Documentation/virtual/kvm/api.txt | 11 |
8 files changed, 230 insertions, 12 deletions
diff --git a/Documentation/acpi/osi.txt b/Documentation/acpi/osi.txt new file mode 100644 index 000000000000..50cde0ceb9b0 --- /dev/null +++ b/Documentation/acpi/osi.txt @@ -0,0 +1,187 @@ +ACPI _OSI and _REV methods +-------------------------- + +An ACPI BIOS can use the "Operating System Interfaces" method (_OSI) +to find out what the operating system supports. Eg. If BIOS +AML code includes _OSI("XYZ"), the kernel's AML interpreter +can evaluate that method, look to see if it supports 'XYZ' +and answer YES or NO to the BIOS. + +The ACPI _REV method returns the "Revision of the ACPI specification +that OSPM supports" + +This document explains how and why the BIOS and Linux should use these methods. +It also explains how and why they are widely misused. + +How to use _OSI +--------------- + +Linux runs on two groups of machines -- those that are tested by the OEM +to be compatible with Linux, and those that were never tested with Linux, +but where Linux was installed to replace the original OS (Windows or OSX). + +The larger group is the systems tested to run only Windows. Not only that, +but many were tested to run with just one specific version of Windows. +So even though the BIOS may use _OSI to query what version of Windows is running, +only a single path through the BIOS has actually been tested. +Experience shows that taking untested paths through the BIOS +exposes Linux to an entire category of BIOS bugs. +For this reason, Linux _OSI defaults must continue to claim compatibility +with all versions of Windows. + +But Linux isn't actually compatible with Windows, and the Linux community +has also been hurt with regressions when Linux adds the latest version of +Windows to its list of _OSI strings. So it is possible that additional strings +will be more thoroughly vetted before shipping upstream in the future. +But it is likely that they will all eventually be added. + +What should an OEM do if they want to support Linux and Windows +using the same BIOS image? Often they need to do something different +for Linux to deal with how Linux is different from Windows. +Here the BIOS should ask exactly what it wants to know: + +_OSI("Linux-OEM-my_interface_name") +where 'OEM' is needed if this is an OEM-specific hook, +and 'my_interface_name' describes the hook, which could be a +quirk, a bug, or a bug-fix. + +In addition, the OEM should send a patch to upstream Linux +via the linux-acpi@vger.kernel.org mailing list. When that patch +is checked into Linux, the OS will answer "YES" when the BIOS +on the OEM's system uses _OSI to ask if the interface is supported +by the OS. Linux distributors can back-port that patch for Linux +pre-installs, and it will be included by all distributions that +re-base to upstream. If the distribution can not update the kernel binary, +they can also add an acpi_osi=Linux-OEM-my_interface_name +cmdline parameter to the boot loader, as needed. + +If the string refers to a feature where the upstream kernel +eventually grows support, a patch should be sent to remove +the string when that support is added to the kernel. + +That was easy. Read on, to find out how to do it wrong. + +Before _OSI, there was _OS +-------------------------- + +ACPI 1.0 specified "_OS" as an +"object that evaluates to a string that identifies the operating system." + +The ACPI BIOS flow would include an evaluation of _OS, and the AML +interpreter in the kernel would return to it a string identifying the OS: + +Windows 98, SE: "Microsoft Windows" +Windows ME: "Microsoft WindowsME:Millenium Edition" +Windows NT: "Microsoft Windows NT" + +The idea was on a platform tasked with running multiple OS's, +the BIOS could use _OS to enable devices that an OS +might support, or enable quirks or bug workarounds +necessary to make the platform compatible with that pre-existing OS. + +But _OS had fundamental problems. First, the BIOS needed to know the name +of every possible version of the OS that would run on it, and needed to know +all the quirks of those OS's. Certainly it would make more sense +for the BIOS to ask *specific* things of the OS, such +"do you support a specific interface", and thus in ACPI 3.0, +_OSI was born to replace _OS. + +_OS was abandoned, though even today, many BIOS look for +_OS "Microsoft Windows NT", though it seems somewhat far-fetched +that anybody would install those old operating systems +over what came with the machine. + +Linux answers "Microsoft Windows NT" to please that BIOS idiom. +That is the *only* viable strategy, as that is what modern Windows does, +and so doing otherwise could steer the BIOS down an untested path. + +_OSI is born, and immediately misused +-------------------------------------- + +With _OSI, the *BIOS* provides the string describing an interface, +and asks the OS: "YES/NO, are you compatible with this interface?" + +eg. _OSI("3.0 Thermal Model") would return TRUE if the OS knows how +to deal with the thermal extensions made to the ACPI 3.0 specification. +An old OS that doesn't know about those extensions would answer FALSE, +and a new OS may be able to return TRUE. + +For an OS-specific interface, the ACPI spec said that the BIOS and the OS +were to agree on a string of the form such as "Windows-interface_name". + +But two bad things happened. First, the Windows ecosystem used _OSI +not as designed, but as a direct replacement for _OS -- identifying +the OS version, rather than an OS supported interface. Indeed, right +from the start, the ACPI 3.0 spec itself codified this misuse +in example code using _OSI("Windows 2001"). + +This misuse was adopted and continues today. + +Linux had no choice but to also return TRUE to _OSI("Windows 2001") +and its successors. To do otherwise would virtually guarantee breaking +a BIOS that has been tested only with that _OSI returning TRUE. + +This strategy is problematic, as Linux is never completely compatible with +the latest version of Windows, and sometimes it takes more than a year +to iron out incompatibilities. + +Not to be out-done, the Linux community made things worse by returning TRUE +to _OSI("Linux"). Doing so is even worse than the Windows misuse +of _OSI, as "Linux" does not even contain any version information. +_OSI("Linux") led to some BIOS' malfunctioning due to BIOS writer's +using it in untested BIOS flows. But some OEM's used _OSI("Linux") +in tested flows to support real Linux features. In 2009, Linux +removed _OSI("Linux"), and added a cmdline parameter to restore it +for legacy systems still needed it. Further a BIOS_BUG warning prints +for all BIOS's that invoke it. + +No BIOS should use _OSI("Linux"). + +The result is a strategy for Linux to maximize compatibility with +ACPI BIOS that are tested on Windows machines. There is a real risk +of over-stating that compatibility; but the alternative has often been +catastrophic failure resulting from the BIOS taking paths that +were never validated under *any* OS. + +Do not use _REV +--------------- + +Since _OSI("Linux") went away, some BIOS writers used _REV +to support Linux and Windows differences in the same BIOS. + +_REV was defined in ACPI 1.0 to return the version of ACPI +supported by the OS and the OS AML interpreter. + +Modern Windows returns _REV = 2. Linux used ACPI_CA_SUPPORT_LEVEL, +which would increment, based on the version of the spec supported. + +Unfortunately, _REV was also misused. eg. some BIOS would check +for _REV = 3, and do something for Linux, but when Linux returned +_REV = 4, that support broke. + +In response to this problem, Linux returns _REV = 2 always, +from mid-2015 onward. The ACPI specification will also be updated +to reflect that _REV is deprecated, and always returns 2. + +Apple Mac and _OSI("Darwin") +---------------------------- + +On Apple's Mac platforms, the ACPI BIOS invokes _OSI("Darwin") +to determine if the machine is running Apple OSX. + +Like Linux's _OSI("*Windows*") strategy, Linux defaults to +answering YES to _OSI("Darwin") to enable full access +to the hardware and validated BIOS paths seen by OSX. +Just like on Windows-tested platforms, this strategy has risks. + +Starting in Linux-3.18, the kernel answered YES to _OSI("Darwin") +for the purpose of enabling Mac Thunderbolt support. Further, +if the kernel noticed _OSI("Darwin") being invoked, it additionally +disabled all _OSI("*Windows*") to keep poorly written Mac BIOS +from going down untested combinations of paths. + +The Linux-3.18 change in default caused power regressions on Mac +laptops, and the 3.18 implementation did not allow changing +the default via cmdline "acpi_osi=!Darwin". Linux-4.7 fixed +the ability to use acpi_osi=!Darwin as a workaround, and +we hope to see Mac Thunderbolt power management support in Linux-4.11. diff --git a/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-bt-bmc.txt b/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.txt index fbbacd958240..6f28969af9dc 100644 --- a/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-bt-bmc.txt +++ b/Documentation/devicetree/bindings/ipmi/aspeed,ast2400-ibt-bmc.txt @@ -6,7 +6,7 @@ perform in-band IPMI communication with their host. Required properties: -- compatible : should be "aspeed,ast2400-bt-bmc" +- compatible : should be "aspeed,ast2400-ibt-bmc" - reg: physical address and size of the registers Optional properties: @@ -17,7 +17,7 @@ Optional properties: Example: ibt@1e789140 { - compatible = "aspeed,ast2400-bt-bmc"; + compatible = "aspeed,ast2400-ibt-bmc"; reg = <0x1e789140 0x18>; interrupts = <8>; }; diff --git a/Documentation/devicetree/bindings/net/ethernet.txt b/Documentation/devicetree/bindings/net/ethernet.txt index e1d76812419c..05150957ecfd 100644 --- a/Documentation/devicetree/bindings/net/ethernet.txt +++ b/Documentation/devicetree/bindings/net/ethernet.txt @@ -9,10 +9,26 @@ The following properties are common to the Ethernet controllers: - max-speed: number, specifies maximum speed in Mbit/s supported by the device; - max-frame-size: number, maximum transfer unit (IEEE defined MTU), rather than the maximum frame size (there's contradiction in ePAPR). -- phy-mode: string, operation mode of the PHY interface; supported values are - "mii", "gmii", "sgmii", "qsgmii", "tbi", "rev-mii", "rmii", "rgmii", "rgmii-id", - "rgmii-rxid", "rgmii-txid", "rtbi", "smii", "xgmii", "trgmii"; this is now a - de-facto standard property; +- phy-mode: string, operation mode of the PHY interface. This is now a de-facto + standard property; supported values are: + * "mii" + * "gmii" + * "sgmii" + * "qsgmii" + * "tbi" + * "rev-mii" + * "rmii" + * "rgmii" (RX and TX delays are added by the MAC when required) + * "rgmii-id" (RGMII with internal RX and TX delays provided by the PHY, the + MAC should not add the RX or TX delays in this case) + * "rgmii-rxid" (RGMII with internal RX delay provided by the PHY, the MAC + should not add an RX delay in this case) + * "rgmii-txid" (RGMII with internal TX delay provided by the PHY, the MAC + should not add an TX delay in this case) + * "rtbi" + * "smii" + * "xgmii" + * "trgmii" - phy-connection-type: the same as "phy-mode" property but described in ePAPR; - phy-handle: phandle, specifies a reference to a node representing a PHY device; this property is described in ePAPR and so preferred; diff --git a/Documentation/devicetree/bindings/sound/omap-abe-twl6040.txt b/Documentation/devicetree/bindings/sound/omap-abe-twl6040.txt index fd40c852d7c7..462b04e8209f 100644 --- a/Documentation/devicetree/bindings/sound/omap-abe-twl6040.txt +++ b/Documentation/devicetree/bindings/sound/omap-abe-twl6040.txt @@ -12,7 +12,7 @@ Required properties: Optional properties: - ti,dmic: phandle for the OMAP dmic node if the machine have it connected -- ti,jack_detection: Need to be present if the board capable to detect jack +- ti,jack-detection: Need to be present if the board capable to detect jack insertion, removal. Available audio endpoints for the audio-routing table: diff --git a/Documentation/i2c/i2c-topology b/Documentation/i2c/i2c-topology index e0aefeece551..1a014fede0b7 100644 --- a/Documentation/i2c/i2c-topology +++ b/Documentation/i2c/i2c-topology @@ -326,7 +326,7 @@ Two parent-locked sibling muxes This is a good topology. - .--------. + .--------. .----------. .--| dev D1 | | parent- |--' '--------' .--| locked | .--------. @@ -350,7 +350,7 @@ Mux-locked and parent-locked sibling muxes This is a good topology. - .--------. + .--------. .----------. .--| dev D1 | | mux- |--' '--------' .--| locked | .--------. diff --git a/Documentation/networking/dsa/dsa.txt b/Documentation/networking/dsa/dsa.txt index 6d6c07cf1a9a..63912ef34606 100644 --- a/Documentation/networking/dsa/dsa.txt +++ b/Documentation/networking/dsa/dsa.txt @@ -67,13 +67,14 @@ Note that DSA does not currently create network interfaces for the "cpu" and Switch tagging protocols ------------------------ -DSA currently supports 4 different tagging protocols, and a tag-less mode as +DSA currently supports 5 different tagging protocols, and a tag-less mode as well. The different protocols are implemented in: net/dsa/tag_trailer.c: Marvell's 4 trailer tag mode (legacy) net/dsa/tag_dsa.c: Marvell's original DSA tag net/dsa/tag_edsa.c: Marvell's enhanced DSA tag net/dsa/tag_brcm.c: Broadcom's 4 bytes tag +net/dsa/tag_qca.c: Qualcomm's 2 bytes tag The exact format of the tag protocol is vendor specific, but in general, they all contain something which: diff --git a/Documentation/networking/nf_conntrack-sysctl.txt b/Documentation/networking/nf_conntrack-sysctl.txt index 399e4e866a9c..433b6724797a 100644 --- a/Documentation/networking/nf_conntrack-sysctl.txt +++ b/Documentation/networking/nf_conntrack-sysctl.txt @@ -62,10 +62,13 @@ nf_conntrack_generic_timeout - INTEGER (seconds) protocols. nf_conntrack_helper - BOOLEAN - 0 - disabled - not 0 - enabled (default) + 0 - disabled (default) + not 0 - enabled Enable automatic conntrack helper assignment. + If disabled it is required to set up iptables rules to assign + helpers to connections. See the CT target description in the + iptables-extensions(8) man page for further information. nf_conntrack_icmp_timeout - INTEGER (seconds) default 30 diff --git a/Documentation/virtual/kvm/api.txt b/Documentation/virtual/kvm/api.txt index 739db9ab16b2..6bbceb9a3a19 100644 --- a/Documentation/virtual/kvm/api.txt +++ b/Documentation/virtual/kvm/api.txt @@ -777,6 +777,17 @@ Gets the current timestamp of kvmclock as seen by the current guest. In conjunction with KVM_SET_CLOCK, it is used to ensure monotonicity on scenarios such as migration. +When KVM_CAP_ADJUST_CLOCK is passed to KVM_CHECK_EXTENSION, it returns the +set of bits that KVM can return in struct kvm_clock_data's flag member. + +The only flag defined now is KVM_CLOCK_TSC_STABLE. If set, the returned +value is the exact kvmclock value seen by all VCPUs at the instant +when KVM_GET_CLOCK was called. If clear, the returned value is simply +CLOCK_MONOTONIC plus a constant offset; the offset can be modified +with KVM_SET_CLOCK. KVM will try to make all VCPUs follow this clock, +but the exact value read by each VCPU could differ, because the host +TSC is not stable. + struct kvm_clock_data { __u64 clock; /* kvmclock current value */ __u32 flags; |