projects / linux.git / blame
| Commit | Line | Data |
|---|---|---|
| 8ca4fc32 CH |
1 | .. SPDX-License-Identifier: GPL-2.0 |
| 2 | ||
| 3 | ======================================= | |
| 4 | Linux NVMe feature and and quirk policy | |
| 5 | ======================================= | |
| 6 | ||
| 7 | This file explains the policy used to decide what is supported by the | |
| 8 | Linux NVMe driver and what is not. | |
| 9 | ||
| 10 | ||
| 11 | Introduction | |
| 12 | ============ | |
| 13 | ||
| 14 | NVM Express is an open collection of standards and information. | |
| 15 | ||
| 16 | The Linux NVMe host driver in drivers/nvme/host/ supports devices | |
| 17 | implementing the NVM Express (NVMe) family of specifications, which | |
| 18 | currently consists of a number of documents: | |
| 19 | ||
| 20 | - the NVMe Base specification | |
| 21 | - 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 specification | |
| 24 | ||
| 25 | See https://nvmexpress.org/developers/ for the NVMe specifications. | |
| 26 | ||
| 27 | ||
| 28 | Supported features | |
| 29 | ================== | |
| 30 | ||
| 31 | NVMe is a large suite of specifications, and contains features that are only | |
| 32 | useful or suitable for specific use-cases. It is important to note that Linux | |
| 33 | does not aim to implement every feature in the specification. Every additional | |
| 34 | feature implemented introduces more code, more maintenance and potentially more | |
| 35 | bugs. Hence there is an inherent tradeoff between functionality and | |
| 36 | maintainability of the NVMe host driver. | |
| 37 | ||
| 38 | Any feature implemented in the Linux NVMe host driver must support the | |
| 39 | following requirements: | |
| 40 | ||
| 41 | 1. The feature is specified in a release version of an official NVMe | |
| 42 | specification, or in a ratified Technical Proposal (TP) that is | |
| 43 | available on NVMe website. Or if it is not directly related to the | |
| 44 | on-wire protocol, does not contradict any of the NVMe specifications. | |
| 45 | 2. Does not conflict with the Linux architecture, nor the design of the | |
| 46 | NVMe host driver. | |
| 47 | 3. Has a clear, indisputable value-proposition and a wide consensus across | |
| 48 | the community. | |
| 49 | ||
| 50 | Vendor specific extensions are generally not supported in the NVMe host | |
| 51 | driver. | |
| 52 | ||
| 53 | It is strongly recommended to work with the Linux NVMe and block layer | |
| 54 | maintainers and get feedback on specification changes that are intended | |
| 55 | to be used by the Linux NVMe host driver in order to avoid conflict at a | |
| 56 | later stage. | |
| 57 | ||
| 58 | ||
| 59 | Quirks | |
| 60 | ====== | |
| 61 | ||
| 62 | Sometimes implementations of open standards fail to correctly implement parts | |
| 63 | of the standards. Linux uses identifier-based quirks to work around such | |
| 64 | implementation bugs. The intent of quirks is to deal with widely available | |
| 65 | hardware, usually consumer, which Linux users can't use without these quirks. | |
| 66 | Typically these implementations are not or only superficially tested with Linux | |
| 67 | by the hardware manufacturer. | |
| 68 | ||
| 69 | The Linux NVMe maintainers decide ad hoc whether to quirk implementations | |
| 70 | based on the impact of the problem to Linux users and how it impacts | |
| 71 | maintainability of the driver. In general quirks are a last resort, if no | |
| 72 | firmware updates or other workarounds are available from the vendor. | |
| 73 | ||
| 74 | Quirks will not be added to the Linux kernel for hardware that isn't available | |
| 75 | on the mass market. Hardware that fails qualification for enterprise Linux | |
| 76 | distributions, ChromeOS, Android or other consumers of the Linux kernel | |
| 77 | should be fixed before it is shipped instead of relying on Linux quirks. |