tjh.dev
Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs, nvme: add a feature and quirk policy document
This adds a document about what specification features are supported by
the Linux NVMe driver, and what qualifies for a quirk if an implementation
has problems following the specification.
Signed-off-by: Jens Axboe <axboe@kernel.dk>
Signed-off-by: Keith Busch <kbusch@kernel.org>
Signed-off-by: Sagi Grimberg <sagi@grimberg.me>
Signed-off-by: Christoph Hellwig <hch@lst.de>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Jonathan Corbet <corbet@lwn.net>
+79
+1
Documentation/maintainer/maintainer-entry-profile.rst
+1
Documentation/maintainer/maintainer-entry-profile.rst
+77
Documentation/nvme/feature-and-quirk-policy.rst
+77
Documentation/nvme/feature-and-quirk-policy.rst
···
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.