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.