1*8ca4fc32SChristoph Hellwig.. SPDX-License-Identifier: GPL-2.0 2*8ca4fc32SChristoph Hellwig 3*8ca4fc32SChristoph Hellwig======================================= 4*8ca4fc32SChristoph HellwigLinux NVMe feature and and quirk policy 5*8ca4fc32SChristoph Hellwig======================================= 6*8ca4fc32SChristoph Hellwig 7*8ca4fc32SChristoph HellwigThis file explains the policy used to decide what is supported by the 8*8ca4fc32SChristoph HellwigLinux NVMe driver and what is not. 9*8ca4fc32SChristoph Hellwig 10*8ca4fc32SChristoph Hellwig 11*8ca4fc32SChristoph HellwigIntroduction 12*8ca4fc32SChristoph Hellwig============ 13*8ca4fc32SChristoph Hellwig 14*8ca4fc32SChristoph HellwigNVM Express is an open collection of standards and information. 15*8ca4fc32SChristoph Hellwig 16*8ca4fc32SChristoph HellwigThe Linux NVMe host driver in drivers/nvme/host/ supports devices 17*8ca4fc32SChristoph Hellwigimplementing the NVM Express (NVMe) family of specifications, which 18*8ca4fc32SChristoph Hellwigcurrently consists of a number of documents: 19*8ca4fc32SChristoph Hellwig 20*8ca4fc32SChristoph Hellwig - the NVMe Base specification 21*8ca4fc32SChristoph Hellwig - various Command Set specifications (e.g. NVM Command Set) 22*8ca4fc32SChristoph Hellwig - various Transport specifications (e.g. PCIe, Fibre Channel, RDMA, TCP) 23*8ca4fc32SChristoph Hellwig - the NVMe Management Interface specification 24*8ca4fc32SChristoph Hellwig 25*8ca4fc32SChristoph HellwigSee https://nvmexpress.org/developers/ for the NVMe specifications. 26*8ca4fc32SChristoph Hellwig 27*8ca4fc32SChristoph Hellwig 28*8ca4fc32SChristoph HellwigSupported features 29*8ca4fc32SChristoph Hellwig================== 30*8ca4fc32SChristoph Hellwig 31*8ca4fc32SChristoph HellwigNVMe is a large suite of specifications, and contains features that are only 32*8ca4fc32SChristoph Hellwiguseful or suitable for specific use-cases. It is important to note that Linux 33*8ca4fc32SChristoph Hellwigdoes not aim to implement every feature in the specification. Every additional 34*8ca4fc32SChristoph Hellwigfeature implemented introduces more code, more maintenance and potentially more 35*8ca4fc32SChristoph Hellwigbugs. Hence there is an inherent tradeoff between functionality and 36*8ca4fc32SChristoph Hellwigmaintainability of the NVMe host driver. 37*8ca4fc32SChristoph Hellwig 38*8ca4fc32SChristoph HellwigAny feature implemented in the Linux NVMe host driver must support the 39*8ca4fc32SChristoph Hellwigfollowing requirements: 40*8ca4fc32SChristoph Hellwig 41*8ca4fc32SChristoph Hellwig 1. The feature is specified in a release version of an official NVMe 42*8ca4fc32SChristoph Hellwig specification, or in a ratified Technical Proposal (TP) that is 43*8ca4fc32SChristoph Hellwig available on NVMe website. Or if it is not directly related to the 44*8ca4fc32SChristoph Hellwig on-wire protocol, does not contradict any of the NVMe specifications. 45*8ca4fc32SChristoph Hellwig 2. Does not conflict with the Linux architecture, nor the design of the 46*8ca4fc32SChristoph Hellwig NVMe host driver. 47*8ca4fc32SChristoph Hellwig 3. Has a clear, indisputable value-proposition and a wide consensus across 48*8ca4fc32SChristoph Hellwig the community. 49*8ca4fc32SChristoph Hellwig 50*8ca4fc32SChristoph HellwigVendor specific extensions are generally not supported in the NVMe host 51*8ca4fc32SChristoph Hellwigdriver. 52*8ca4fc32SChristoph Hellwig 53*8ca4fc32SChristoph HellwigIt is strongly recommended to work with the Linux NVMe and block layer 54*8ca4fc32SChristoph Hellwigmaintainers and get feedback on specification changes that are intended 55*8ca4fc32SChristoph Hellwigto be used by the Linux NVMe host driver in order to avoid conflict at a 56*8ca4fc32SChristoph Hellwiglater stage. 57*8ca4fc32SChristoph Hellwig 58*8ca4fc32SChristoph Hellwig 59*8ca4fc32SChristoph HellwigQuirks 60*8ca4fc32SChristoph Hellwig====== 61*8ca4fc32SChristoph Hellwig 62*8ca4fc32SChristoph HellwigSometimes implementations of open standards fail to correctly implement parts 63*8ca4fc32SChristoph Hellwigof the standards. Linux uses identifier-based quirks to work around such 64*8ca4fc32SChristoph Hellwigimplementation bugs. The intent of quirks is to deal with widely available 65*8ca4fc32SChristoph Hellwighardware, usually consumer, which Linux users can't use without these quirks. 66*8ca4fc32SChristoph HellwigTypically these implementations are not or only superficially tested with Linux 67*8ca4fc32SChristoph Hellwigby the hardware manufacturer. 68*8ca4fc32SChristoph Hellwig 69*8ca4fc32SChristoph HellwigThe Linux NVMe maintainers decide ad hoc whether to quirk implementations 70*8ca4fc32SChristoph Hellwigbased on the impact of the problem to Linux users and how it impacts 71*8ca4fc32SChristoph Hellwigmaintainability of the driver. In general quirks are a last resort, if no 72*8ca4fc32SChristoph Hellwigfirmware updates or other workarounds are available from the vendor. 73*8ca4fc32SChristoph Hellwig 74*8ca4fc32SChristoph HellwigQuirks will not be added to the Linux kernel for hardware that isn't available 75*8ca4fc32SChristoph Hellwigon the mass market. Hardware that fails qualification for enterprise Linux 76*8ca4fc32SChristoph Hellwigdistributions, ChromeOS, Android or other consumers of the Linux kernel 77*8ca4fc32SChristoph Hellwigshould be fixed before it is shipped instead of relying on Linux quirks. 78