Hi-- Just a couple of small nits below... On 12/15/22 04:51, Christoph Hellwig wrote: > 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@xxxxxxxxx> > Signed-off-by: Keith Busch <kbusch@xxxxxxxxxx> > Signed-off-by: Sagi Grimberg <sagi@xxxxxxxxxxx> > Signed-off-by: Christoph Hellwig <hch@xxxxxx> > --- > Documentation/process/index.rst | 1 + > .../process/nvme-feature-and-quirk-policy.rst | 77 +++++++++++++++++++ > MAINTAINERS | 1 + > 3 files changed, 79 insertions(+) > create mode 100644 Documentation/process/nvme-feature-and-quirk-policy.rst > > diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst > index d4b6217472b0a0..0dc33994ddefc5 100644 > --- a/Documentation/process/index.rst > +++ b/Documentation/process/index.rst > @@ -50,6 +50,7 @@ Other guides to the community that are of interest to most developers are: > embargoed-hardware-issues > maintainers > researcher-guidelines > + nvme-feature-and-quirk-policy > > These are some overall technical guides that have been put here for now for > lack of a better place. > diff --git a/Documentation/process/nvme-feature-and-quirk-policy.rst b/Documentation/process/nvme-feature-and-quirk-policy.rst > new file mode 100644 > index 00000000000000..eee19f3d9904bd > --- /dev/null > +++ b/Documentation/process/nvme-feature-and-quirk-policy.rst > @@ -0,0 +1,77 @@ > +.. SPDX-License-Identifier: GPL-2.0 > + > +======================================= > +Linux NVMe feature and and quirk policy > +======================================= > + > +This file explains the policy used to decide what is supported by the > +Linux NVMe driver and what is not. > + > + > +Introduction > +============ > + > +NVM Express is an open collection of standards and information. > + > +The Linux NVMe host driver in drivers/nvme/host/ supports devices > +implementing the NVM Express (NVMe) family of specifications, which > +currently consists of a number of documents: > + > + - the NVMe Base specification > + - various Command Set specifications (e.g. NVM Command Set) > + - various Transport specifications (e.g. PCIe, Fibre Channel, RDMA, TCP) > + - the NVMe Management Interface specification > + > +See https://nvmexpress.org/developers/ for the NVMe specifications. > + > + > +Supported features > +================== > + > +NVMe is a large suite of specifications, and contains features that are only > +useful or suitable for specific use-cases. It is important to note that Linux > +does not aim to implement every feature in the specification. Every additional > +feature implemented introduces more code, more maintenance and potentially more > +bugs. Hence there is an inherent tradeoff between functionality and > +maintainability of the NVMe host driver. > + > +Any feature implemented in the Linux NVMe host driver must support the > +following requirements: > + > + 1. The feature is specified in a release version of an official NVMe > + specification, or in a ratified Technical Proposal (TP) that is > + available on NVMe website. Or if it is not directly related to the > + on-wire protocol, does not contradict any of the NVMe specifications. > + 2. Does not conflict with the Linux architecture, nor the design of the > + NVMe host driver. > + 3. Has a clear, indisputable value-proposition and a wide consensus across > + the community. > + > +Vendor specific extensions are generally not supported in the NVMe host > +driver. > + > +It is strongly recommended to work with the Linux NVMe and block layer > +maintainers and get feedback on specification changes that are intended > +to be used by the Linux NVMe host driver in order to avoid conflict at a > +later stage. > + > + > +Quirks > +====== > + > +Sometimes implementations of open standards fail to correctly implement parts > +of the standards. Linux uses identifiers based quirks to work around such Linux uses identifier-based quirks > +implementation bugs. The intent of quirks is to deal with widely available > +hardware, usually consumer, which Linux users can't use without these quirks. > +Typically these implementations are not or only superficially tested with Linux > +by the hardware manufacturer. > + > +The Linux NVMe maintainers decide ad hoc whether to quirk implementations > +based on the impact of the problem to Linux users and how it impacts > +maintainability of the driver. In general quirks are a last resort, if no > +firmware updates or other workarounds are available from the vendor. > + > +Quirks will not be added to the Linux kernel for hardware that isn't available > +on the mass market. Hardware that fails qualification for enterprise Linux > +distributions, ChromeOS, Android or other consumers of the Linux kernel > +should be fixed before it is shipped instead of rely on Linux quirk. I would s/rely/relying/, but either way: Reviewed-by: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> Thanks. > diff --git a/MAINTAINERS b/MAINTAINERS > index bb77a3ed9d5423..59e9f2dfa842ad 100644 > --- a/MAINTAINERS > +++ b/MAINTAINERS > @@ -14827,6 +14827,7 @@ L: linux-nvme@xxxxxxxxxxxxxxxxxxx > S: Supported > W: http://git.infradead.org/nvme.git > T: git://git.infradead.org/nvme.git > +F: Documentation/process/nvme-feature-and-quirk-policy.rst > F: drivers/nvme/host/ > F: drivers/nvme/common/ > F: include/linux/nvme* -- ~Randy
