[PATCH] docs, nvme: add a feature and quirk policy document

[PATCH] docs, nvme: add a feature and quirk policy document

[Christoph Hellwig]

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>
---
 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
+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.
diff --git a/MAINTAINERS b/MAINTAINERS
index bb77a3ed9d5423..59e9f2dfa842ad 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14827,6 +14827,7 @@ L:	linux-nvme@lists.infradead.org
 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*
-- 
2.35.1

Re: [PATCH] docs, nvme: add a feature and quirk policy document

[Jonathan Corbet]

Christoph Hellwig <hch@lst.de> writes:

> 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>
> ---
>  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

The document looks fine, but I do wonder if it wouldn't be better placed
with the other maintainer entries in Documentation/maintainer?

Thanks,

jon

Re: [PATCH] docs, nvme: add a feature and quirk policy document

[Christoph Hellwig]

On Thu, Dec 15, 2022 at 06:08:44AM -0700, Jonathan Corbet wrote:
> The document looks fine, but I do wonder if it wouldn't be better placed
> with the other maintainer entries in Documentation/maintainer?

Hmm, nothing in there looks very similar to me, while process
seems to have real policy documents.  But we can live with either
place.

Re: [PATCH] docs, nvme: add a feature and quirk policy document

[Randy Dunlap]

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@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>
> ---
>  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@infradead.org>

Thanks.

> diff --git a/MAINTAINERS b/MAINTAINERS
> index bb77a3ed9d5423..59e9f2dfa842ad 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -14827,6 +14827,7 @@ L:	linux-nvme@lists.infradead.org
>  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

Re: [PATCH] docs, nvme: add a feature and quirk policy document

[Christoph Hellwig]

Thanks Randy,

your nits look good to improve the language in the document.

Re: [PATCH] docs, nvme: add a feature and quirk policy document

[Christoph Hellwig]

On Thu, Dec 15, 2022 at 02:26:22PM +0100, Christoph Hellwig wrote:
> On Thu, Dec 15, 2022 at 06:08:44AM -0700, Jonathan Corbet wrote:
> > The document looks fine, but I do wonder if it wouldn't be better placed
> > with the other maintainer entries in Documentation/maintainer?
> 
> Hmm, nothing in there looks very similar to me, while process
> seems to have real policy documents.  But we can live with either
> place.

Any strong arguments for moving it Documentation/maintainer?

I'd like to merge this with the fixups from Randy through the nvme
tree ASAP, and need to decide on the location.

Re: [PATCH] docs, nvme: add a feature and quirk policy document

[Jonathan Corbet]

Christoph Hellwig <hch@lst.de> writes:

> On Thu, Dec 15, 2022 at 02:26:22PM +0100, Christoph Hellwig wrote:
>> On Thu, Dec 15, 2022 at 06:08:44AM -0700, Jonathan Corbet wrote:
>> > The document looks fine, but I do wonder if it wouldn't be better placed
>> > with the other maintainer entries in Documentation/maintainer?
>> 
>> Hmm, nothing in there looks very similar to me, while process
>> seems to have real policy documents.  But we can live with either
>> place.
>
> Any strong arguments for moving it Documentation/maintainer?
>
> I'd like to merge this with the fixups from Randy through the nvme
> tree ASAP, and need to decide on the location.

Sorry, the argument is that the subsystem profiles there were created
for the very purpose of documenting subsystem-specific patch policies
like those found in your document.  The hope is that, someday, people
will be able to go to one place to learn what special hoops any given
subsystem will make them jump through.

This isn't something I'm going to dig in my heels on, though.  But at a
minimum, could you add an entry to
Documentation/maintainer/maintainer-entry-profile.rst ?

Thanks,

jon

Re: [PATCH] docs, nvme: add a feature and quirk policy document

[Christoph Hellwig]

On Wed, Dec 21, 2022 at 06:45:32AM -0700, Jonathan Corbet wrote:
> Sorry, the argument is that the subsystem profiles there were created
> for the very purpose of documenting subsystem-specific patch policies
> like those found in your document.  The hope is that, someday, people
> will be able to go to one place to learn what special hoops any given
> subsystem will make them jump through.
> 
> This isn't something I'm going to dig in my heels on, though.  But at a
> minimum, could you add an entry to
> Documentation/maintainer/maintainer-entry-profile.rst ?

What about the following?  This moves the file to a new
Documentation/nvme/ directory and then links it form
Documentation/maintainer/maintainer-entry-profile.rst:

---
From 3471fc6f0b584c4372d7c4c2b2b8e1b5aed970f0 Mon Sep 17 00:00:00 2001
From: Christoph Hellwig <hch@lst.de>
Date: Mon, 12 Dec 2022 11:09:55 +0100
Subject: 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>
---
 .../maintainer/maintainer-entry-profile.rst   |  1 +
 .../nvme/feature-and-quirk-policy.rst         | 77 +++++++++++++++++++
 MAINTAINERS                                   |  1 +
 3 files changed, 79 insertions(+)
 create mode 100644 Documentation/nvme/feature-and-quirk-policy.rst

diff --git a/Documentation/maintainer/maintainer-entry-profile.rst b/Documentation/maintainer/maintainer-entry-profile.rst
index 93b2ae6c34a99b..cfd37f31077f6c 100644
--- a/Documentation/maintainer/maintainer-entry-profile.rst
+++ b/Documentation/maintainer/maintainer-entry-profile.rst
@@ -104,3 +104,4 @@ to do something different in the near future.
    ../riscv/patch-acceptance
    ../driver-api/media/maintainer-entry-profile
    ../driver-api/vfio-pci-device-specific-driver-acceptance
+   ../nvme/feature-and-quirk-policy
diff --git a/Documentation/nvme/feature-and-quirk-policy.rst b/Documentation/nvme/feature-and-quirk-policy.rst
new file mode 100644
index 00000000000000..c01d836d8e4151
--- /dev/null
+++ b/Documentation/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 identifier-based quirks to work around such
+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 relying on Linux quirks.
diff --git a/MAINTAINERS b/MAINTAINERS
index bb77a3ed9d5423..d53b3a6cdc67d2 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -14827,6 +14827,7 @@ L:	linux-nvme@lists.infradead.org
 S:	Supported
 W:	http://git.infradead.org/nvme.git
 T:	git://git.infradead.org/nvme.git
+F:	Documentation/nvme/
 F:	drivers/nvme/host/
 F:	drivers/nvme/common/
 F:	include/linux/nvme*
-- 
2.35.1

Re: [PATCH] docs, nvme: add a feature and quirk policy document

[Jonathan Corbet]

Christoph Hellwig <hch@lst.de> writes:

> On Wed, Dec 21, 2022 at 06:45:32AM -0700, Jonathan Corbet wrote:
>> Sorry, the argument is that the subsystem profiles there were created
>> for the very purpose of documenting subsystem-specific patch policies
>> like those found in your document.  The hope is that, someday, people
>> will be able to go to one place to learn what special hoops any given
>> subsystem will make them jump through.
>> 
>> This isn't something I'm going to dig in my heels on, though.  But at a
>> minimum, could you add an entry to
>> Documentation/maintainer/maintainer-entry-profile.rst ?
>
> What about the following?  This moves the file to a new
> Documentation/nvme/ directory and then links it form
> Documentation/maintainer/maintainer-entry-profile.rst:

I'm not really a fan of adding more top-level directories; one of these
years I'd like to try to move things in the opposite direction.  That is
a battle for another day, though; for now let's just go with this and
get the document merged.

That said, I suspect you'll add a build warning about the new document
not being included in any toctree.  Fixing that would involve adding a
basic index.rst to the new directory and adding that to a file like
Documentation/subsystem-apis.rst.

Thanks,

jon

Re: [PATCH] docs, nvme: add a feature and quirk policy document

[Christoph Hellwig]

On Thu, Dec 22, 2022 at 01:54:35PM -0700, Jonathan Corbet wrote:
> I'm not really a fan of adding more top-level directories; one of these
> years I'd like to try to move things in the opposite direction.  That is
> a battle for another day, though; for now let's just go with this and
> get the document merged.

I though about that, but could not thing of a good subdirectory.

> 
> That said, I suspect you'll add a build warning about the new document
> not being included in any toctree.  Fixing that would involve adding a
> basic index.rst to the new directory and adding that to a file like
> Documentation/subsystem-apis.rst.

The new document is included in
Documentation/maintainer/maintainer-entry-profile.rst in this path.

I also did check for new warnings and did not see any, even if that's
a little difficult with the rather chatty shpinx output.

Re: [PATCH] docs, nvme: add a feature and quirk policy document

[Jonathan Corbet]

Christoph Hellwig <hch@lst.de> writes:

> On Thu, Dec 22, 2022 at 01:54:35PM -0700, Jonathan Corbet wrote:
>> I'm not really a fan of adding more top-level directories; one of these
>> years I'd like to try to move things in the opposite direction.  That is
>> a battle for another day, though; for now let's just go with this and
>> get the document merged.
>
> I though about that, but could not thing of a good subdirectory.

We can paint that shed another day :)

>> That said, I suspect you'll add a build warning about the new document
>> not being included in any toctree.  Fixing that would involve adding a
>> basic index.rst to the new directory and adding that to a file like
>> Documentation/subsystem-apis.rst.
>
> The new document is included in
> Documentation/maintainer/maintainer-entry-profile.rst in this path.

Duh sorry, I'm not quite sure what I was thinking there.

> I also did check for new warnings and did not see any, even if that's
> a little difficult with the rather chatty shpinx output.

Someday we'll get all those warnings gone...I hope...

Meanwhile, if it's useful:

Acked-by: Jonathan Corbet <corbet@lwn.net>

Thanks,

jon