|
| 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. |
0 commit comments