78 lines · plain
1.. SPDX-License-Identifier: GPL-2.02 3===================================4Linux NVMe feature and quirk policy5===================================6 7This file explains the policy used to decide what is supported by the8Linux NVMe driver and what is not.9 10 11Introduction12============13 14NVM Express is an open collection of standards and information.15 16The Linux NVMe host driver in drivers/nvme/host/ supports devices17implementing the NVM Express (NVMe) family of specifications, which18currently consists of a number of documents:19 20 - the NVMe Base specification21 - various Command Set specifications (e.g. NVM Command Set)22 - various Transport specifications (e.g. PCIe, Fibre Channel, RDMA, TCP)23 - the NVMe Management Interface specification24 25See https://nvmexpress.org/developers/ for the NVMe specifications.26 27 28Supported features29==================30 31NVMe is a large suite of specifications, and contains features that are only32useful or suitable for specific use-cases. It is important to note that Linux33does not aim to implement every feature in the specification. Every additional34feature implemented introduces more code, more maintenance and potentially more35bugs. Hence there is an inherent tradeoff between functionality and36maintainability of the NVMe host driver.37 38Any feature implemented in the Linux NVMe host driver must support the39following requirements:40 41 1. The feature is specified in a release version of an official NVMe42 specification, or in a ratified Technical Proposal (TP) that is43 available on NVMe website. Or if it is not directly related to the44 on-wire protocol, does not contradict any of the NVMe specifications.45 2. Does not conflict with the Linux architecture, nor the design of the46 NVMe host driver.47 3. Has a clear, indisputable value-proposition and a wide consensus across48 the community.49 50Vendor specific extensions are generally not supported in the NVMe host51driver.52 53It is strongly recommended to work with the Linux NVMe and block layer54maintainers and get feedback on specification changes that are intended55to be used by the Linux NVMe host driver in order to avoid conflict at a56later stage.57 58 59Quirks60======61 62Sometimes implementations of open standards fail to correctly implement parts63of the standards. Linux uses identifier-based quirks to work around such64implementation bugs. The intent of quirks is to deal with widely available65hardware, usually consumer, which Linux users can't use without these quirks.66Typically these implementations are not or only superficially tested with Linux67by the hardware manufacturer.68 69The Linux NVMe maintainers decide ad hoc whether to quirk implementations70based on the impact of the problem to Linux users and how it impacts71maintainability of the driver. In general quirks are a last resort, if no72firmware updates or other workarounds are available from the vendor.73 74Quirks will not be added to the Linux kernel for hardware that isn't available75on the mass market. Hardware that fails qualification for enterprise Linux76distributions, ChromeOS, Android or other consumers of the Linux kernel77should be fixed before it is shipped instead of relying on Linux quirks.78