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