Documentation/nvdimm/nvdimm.txt

   1                           LIBNVDIMM: Non-Volatile Devices
   2               libnvdimm - kernel / libndctl - userspace helper library
   3                            linux-nvdimm@lists.01.org
   4                                       v13
   5
   6
   7         Glossary
   8         Overview
   9             Supporting Documents
  10             Git Trees
  11         LIBNVDIMM PMEM and BLK
  12         Why BLK?
  13             PMEM vs BLK
  14                 BLK-REGIONs, PMEM-REGIONs, Atomic Sectors, and DAX
  15         Example NVDIMM Platform
  16         LIBNVDIMM Kernel Device Model and LIBNDCTL Userspace API
  17             LIBNDCTL: Context
  18                 libndctl: instantiate a new library context example
  19             LIBNVDIMM/LIBNDCTL: Bus
  20                 libnvdimm: control class device in /sys/class
  21                 libnvdimm: bus
  22                 libndctl: bus enumeration example
  23             LIBNVDIMM/LIBNDCTL: DIMM (NMEM)
  24                 libnvdimm: DIMM (NMEM)
  25                 libndctl: DIMM enumeration example
  26             LIBNVDIMM/LIBNDCTL: Region
  27                 libnvdimm: region
  28                 libndctl: region enumeration example
  29                 Why Not Encode the Region Type into the Region Name?
  30                 How Do I Determine the Major Type of a Region?
  31             LIBNVDIMM/LIBNDCTL: Namespace
  32                 libnvdimm: namespace
  33                 libndctl: namespace enumeration example
  34                 libndctl: namespace creation example
  35                 Why the Term "namespace"?
  36             LIBNVDIMM/LIBNDCTL: Block Translation Table "btt"
  37                 libnvdimm: btt layout
  38                 libndctl: btt creation example
  39         Summary LIBNDCTL Diagram
  40
  41
  42 Glossary
  43 --------
  44
  45 PMEM: A system-physical-address range where writes are persistent.  A
  46 block device composed of PMEM is capable of DAX.  A PMEM address range
  47 may span an interleave of several DIMMs.
  48
  49 BLK: A set of one or more programmable memory mapped apertures provided
  50 by a DIMM to access its media.  This indirection precludes the
  51 performance benefit of interleaving, but enables DIMM-bounded failure
  52 modes.
  53
  54 DPA: DIMM Physical Address, is a DIMM-relative offset.  With one DIMM in
  55 the system there would be a 1:1 system-physical-address:DPA association.
  56 Once more DIMMs are added a memory controller interleave must be
  57 decoded to determine the DPA associated with a given
  58 system-physical-address.  BLK capacity always has a 1:1 relationship
  59 with a single-DIMM's DPA range.
  60
  61 DAX: File system extensions to bypass the page cache and block layer to
  62 mmap persistent memory, from a PMEM block device, directly into a
  63 process address space.
  64
  65 DSM: Device Specific Method: ACPI method to to control specific
  66 device - in this case the firmware.
  67
  68 DCR: NVDIMM Control Region Structure defined in ACPI 6 Section 5.2.25.5.
  69 It defines a vendor-id, device-id, and interface format for a given DIMM.
  70
  71 BTT: Block Translation Table: Persistent memory is byte addressable.
  72 Existing software may have an expectation that the power-fail-atomicity
  73 of writes is at least one sector, 512 bytes.  The BTT is an indirection
  74 table with atomic update semantics to front a PMEM/BLK block device
  75 driver and present arbitrary atomic sector sizes.
  76
  77 LABEL: Metadata stored on a DIMM device that partitions and identifies
  78 (persistently names) storage between PMEM and BLK.  It also partitions
  79 BLK storage to host BTTs with different parameters per BLK-partition.
  80 Note that traditional partition tables, GPT/MBR, are layered on top of a
  81 BLK or PMEM device.
  82
  83
  84 Overview
  85 --------
  86
  87 The LIBNVDIMM subsystem provides support for three types of NVDIMMs, namely,
  88 PMEM, BLK, and NVDIMM devices that can simultaneously support both PMEM
  89 and BLK mode access.  These three modes of operation are described by
  90 the "NVDIMM Firmware Interface Table" (NFIT) in ACPI 6.  While the LIBNVDIMM
  91 implementation is generic and supports pre-NFIT platforms, it was guided
  92 by the superset of capabilities need to support this ACPI 6 definition
  93 for NVDIMM resources.  The bulk of the kernel implementation is in place
  94 to handle the case where DPA accessible via PMEM is aliased with DPA
  95 accessible via BLK.  When that occurs a LABEL is needed to reserve DPA
  96 for exclusive access via one mode a time.
  97
  98 Supporting Documents
  99 ACPI 6: http://www.uefi.org/sites/default/files/resources/ACPI_6.0.pdf
 100 NVDIMM Namespace: http://pmem.io/documents/NVDIMM_Namespace_Spec.pdf
 101 DSM Interface Example: http://pmem.io/documents/NVDIMM_DSM_Interface_Example.pdf
 102 Driver Writer's Guide: http://pmem.io/documents/NVDIMM_Driver_Writers_Guide.pdf
 103
 104 Git Trees
 105 LIBNVDIMM: https://git.kernel.org/cgit/linux/kernel/git/djbw/nvdimm.git
 106 LIBNDCTL: https://github.com/pmem/ndctl.git
 107 PMEM: https://github.com/01org/prd
 108
 109
 110 LIBNVDIMM PMEM and BLK
 111 ------------------
 112
 113 Prior to the arrival of the NFIT, non-volatile memory was described to a
 114 system in various ad-hoc ways.  Usually only the bare minimum was
 115 provided, namely, a single system-physical-address range where writes
 116 are expected to be durable after a system power loss.  Now, the NFIT
 117 specification standardizes not only the description of PMEM, but also
 118 BLK and platform message-passing entry points for control and
 119 configuration.
 120
 121 For each NVDIMM access method (PMEM, BLK), LIBNVDIMM provides a block
 122 device driver:
 123
 124     1. PMEM (nd_pmem.ko): Drives a system-physical-address range.  This
 125     range is contiguous in system memory and may be interleaved (hardware
 126     memory controller striped) across multiple DIMMs.  When interleaved the
 127     platform may optionally provide details of which DIMMs are participating
 128     in the interleave.
 129
 130     Note that while LIBNVDIMM describes system-physical-address ranges that may
 131     alias with BLK access as ND_NAMESPACE_PMEM ranges and those without
 132     alias as ND_NAMESPACE_IO ranges, to the nd_pmem driver there is no
 133     distinction.  The different device-types are an implementation detail
 134     that userspace can exploit to implement policies like "only interface
 135     with address ranges from certain DIMMs".  It is worth noting that when
 136     aliasing is present and a DIMM lacks a label, then no block device can
 137     be created by default as userspace needs to do at least one allocation
 138     of DPA to the PMEM range.  In contrast ND_NAMESPACE_IO ranges, once
 139     registered, can be immediately attached to nd_pmem.
 140
 141     2. BLK (nd_blk.ko): This driver performs I/O using a set of platform
 142     defined apertures.  A set of apertures will access just one DIMM.
 143     Multiple windows (apertures) allow multiple concurrent accesses, much like
 144     tagged-command-queuing, and would likely be used by different threads or
 145     different CPUs.
 146
 147     The NFIT specification defines a standard format for a BLK-aperture, but
 148     the spec also allows for vendor specific layouts, and non-NFIT BLK
 149     implementations may have other designs for BLK I/O.  For this reason
 150     "nd_blk" calls back into platform-specific code to perform the I/O.
 151     One such implementation is defined in the "Driver Writer's Guide" and "DSM
 152     Interface Example".
 153
 154
 155 Why BLK?
 156 --------
 157
 158 While PMEM provides direct byte-addressable CPU-load/store access to
 159 NVDIMM storage, it does not provide the best system RAS (recovery,
 160 availability, and serviceability) model.  An access to a corrupted
 161 system-physical-address address causes a CPU exception while an access
 162 to a corrupted address through an BLK-aperture causes that block window
 163 to raise an error status in a register.  The latter is more aligned with
 164 the standard error model that host-bus-adapter attached disks present.
 165 Also, if an administrator ever wants to replace a memory it is easier to
 166 service a system at DIMM module boundaries.  Compare this to PMEM where
 167 data could be interleaved in an opaque hardware specific manner across
 168 several DIMMs.
 169
 170 PMEM vs BLK
 171 BLK-apertures solve these RAS problems, but their presence is also the
 172 major contributing factor to the complexity of the ND subsystem.  They
 173 complicate the implementation because PMEM and BLK alias in DPA space.
 174 Any given DIMM's DPA-range may contribute to one or more
 175 system-physical-address sets of interleaved DIMMs, *and* may also be
 176 accessed in its entirety through its BLK-aperture.  Accessing a DPA
 177 through a system-physical-address while simultaneously accessing the
 178 same DPA through a BLK-aperture has undefined results.  For this reason,
 179 DIMMs with this dual interface configuration include a DSM function to
 180 store/retrieve a LABEL.  The LABEL effectively partitions the DPA-space
 181 into exclusive system-physical-address and BLK-aperture accessible
 182 regions.  For simplicity a DIMM is allowed a PMEM "region" per each
 183 interleave set in which it is a member.  The remaining DPA space can be
 184 carved into an arbitrary number of BLK devices with discontiguous
 185 extents.
 186
 187 BLK-REGIONs, PMEM-REGIONs, Atomic Sectors, and DAX
 188 --------------------------------------------------
 189
 190 One of the few
 191 reasons to allow multiple BLK namespaces per REGION is so that each
 192 BLK-namespace can be configured with a BTT with unique atomic sector
 193 sizes.  While a PMEM device can host a BTT the LABEL specification does
 194 not provide for a sector size to be specified for a PMEM namespace.
 195 This is due to the expectation that the primary usage model for PMEM is
 196 via DAX, and the BTT is incompatible with DAX.  However, for the cases
 197 where an application or filesystem still needs atomic sector update
 198 guarantees it can register a BTT on a PMEM device or partition.  See
 199 LIBNVDIMM/NDCTL: Block Translation Table "btt"
 200
 201
 202 Example NVDIMM Platform
 203 -----------------------
 204
 205 For the remainder of this document the following diagram will be
 206 referenced for any example sysfs layouts.
 207
 208
 209                              (a)               (b)           DIMM   BLK-REGION
 210           +-------------------+--------+--------+--------+
 211 +------+  |       pm0.0       | blk2.0 | pm1.0  | blk2.1 |    0      region2
 212 | imc0 +--+- - - region0- - - +--------+        +--------+
 213 +--+---+  |       pm0.0       | blk3.0 | pm1.0  | blk3.1 |    1      region3
 214    |      +-------------------+--------v        v--------+
 215 +--+---+                               |                 |
 216 | cpu0 |                                     region1
 217 +--+---+                               |                 |
 218    |      +----------------------------^        ^--------+
 219 +--+---+  |           blk4.0           | pm1.0  | blk4.0 |    2      region4
 220 | imc1 +--+----------------------------|        +--------+
 221 +------+  |           blk5.0           | pm1.0  | blk5.0 |    3      region5
 222           +----------------------------+--------+--------+
 223
 224 In this platform we have four DIMMs and two memory controllers in one
 225 socket.  Each unique interface (BLK or PMEM) to DPA space is identified
 226 by a region device with a dynamically assigned id (REGION0 - REGION5).
 227
 228     1. The first portion of DIMM0 and DIMM1 are interleaved as REGION0. A
 229     single PMEM namespace is created in the REGION0-SPA-range that spans most
 230     of DIMM0 and DIMM1 with a user-specified name of "pm0.0". Some of that
 231     interleaved system-physical-address range is reclaimed as BLK-aperture
 232     accessed space starting at DPA-offset (a) into each DIMM.  In that
 233     reclaimed space we create two BLK-aperture "namespaces" from REGION2 and
 234     REGION3 where "blk2.0" and "blk3.0" are just human readable names that
 235     could be set to any user-desired name in the LABEL.
 236
 237     2. In the last portion of DIMM0 and DIMM1 we have an interleaved
 238     system-physical-address range, REGION1, that spans those two DIMMs as
 239     well as DIMM2 and DIMM3.  Some of REGION1 is allocated to a PMEM namespace
 240     named "pm1.0", the rest is reclaimed in 4 BLK-aperture namespaces (for
 241     each DIMM in the interleave set), "blk2.1", "blk3.1", "blk4.0", and
 242     "blk5.0".
 243
 244     3. The portion of DIMM2 and DIMM3 that do not participate in the REGION1
 245     interleaved system-physical-address range (i.e. the DPA address past
 246     offset (b) are also included in the "blk4.0" and "blk5.0" namespaces.
 247     Note, that this example shows that BLK-aperture namespaces don't need to
 248     be contiguous in DPA-space.
 249
 250     This bus is provided by the kernel under the device
 251     /sys/devices/platform/nfit_test.0 when CONFIG_NFIT_TEST is enabled and
 252     the nfit_test.ko module is loaded.  This not only test LIBNVDIMM but the
 253     acpi_nfit.ko driver as well.
 254
 255
 256 LIBNVDIMM Kernel Device Model and LIBNDCTL Userspace API
 257 ----------------------------------------------------
 258
 259 What follows is a description of the LIBNVDIMM sysfs layout and a
 260 corresponding object hierarchy diagram as viewed through the LIBNDCTL
 261 API.  The example sysfs paths and diagrams are relative to the Example
 262 NVDIMM Platform which is also the LIBNVDIMM bus used in the LIBNDCTL unit
 263 test.
 264
 265 LIBNDCTL: Context
 266 Every API call in the LIBNDCTL library requires a context that holds the
 267 logging parameters and other library instance state.  The library is
 268 based on the libabc template:
 269 https://git.kernel.org/cgit/linux/kernel/git/kay/libabc.git
 270
 271 LIBNDCTL: instantiate a new library context example
 272
 273         struct ndctl_ctx *ctx;
 274
 275         if (ndctl_new(&ctx) == 0)
 276                 return ctx;
 277         else
 278                 return NULL;
 279
 280 LIBNVDIMM/LIBNDCTL: Bus
 281 -------------------
 282
 283 A bus has a 1:1 relationship with an NFIT.  The current expectation for
 284 ACPI based systems is that there is only ever one platform-global NFIT.
 285 That said, it is trivial to register multiple NFITs, the specification
 286 does not preclude it.  The infrastructure supports multiple busses and
 287 we we use this capability to test multiple NFIT configurations in the
 288 unit test.
 289
 290 LIBNVDIMM: control class device in /sys/class
 291
 292 This character device accepts DSM messages to be passed to DIMM
 293 identified by its NFIT handle.
 294
 295         /sys/class/nd/ndctl0
 296         |-- dev
 297         |-- device -> ../../../ndbus0
 298         |-- subsystem -> ../../../../../../../class/nd
 299
 300
 301
 302 LIBNVDIMM: bus
 303
 304         struct nvdimm_bus *nvdimm_bus_register(struct device *parent,
 305                struct nvdimm_bus_descriptor *nfit_desc);
 306
 307         /sys/devices/platform/nfit_test.0/ndbus0
 308         |-- commands
 309         |-- nd
 310         |-- nfit
 311         |-- nmem0
 312         |-- nmem1
 313         |-- nmem2
 314         |-- nmem3
 315         |-- power
 316         |-- provider
 317         |-- region0
 318         |-- region1
 319         |-- region2
 320         |-- region3
 321         |-- region4
 322         |-- region5
 323         |-- uevent
 324         `-- wait_probe
 325
 326 LIBNDCTL: bus enumeration example
 327 Find the bus handle that describes the bus from Example NVDIMM Platform
 328
 329         static struct ndctl_bus *get_bus_by_provider(struct ndctl_ctx *ctx,
 330                         const char *provider)
 331         {
 332                 struct ndctl_bus *bus;
 333
 334                 ndctl_bus_foreach(ctx, bus)
 335                         if (strcmp(provider, ndctl_bus_get_provider(bus)) == 0)
 336                                 return bus;
 337
 338                 return NULL;
 339         }
 340
 341         bus = get_bus_by_provider(ctx, "nfit_test.0");
 342
 343
 344 LIBNVDIMM/LIBNDCTL: DIMM (NMEM)
 345 ---------------------------
 346
 347 The DIMM device provides a character device for sending commands to
 348 hardware, and it is a container for LABELs.  If the DIMM is defined by
 349 NFIT then an optional 'nfit' attribute sub-directory is available to add
 350 NFIT-specifics.
 351
 352 Note that the kernel device name for "DIMMs" is "nmemX".  The NFIT
 353 describes these devices via "Memory Device to System Physical Address
 354 Range Mapping Structure", and there is no requirement that they actually
 355 be physical DIMMs, so we use a more generic name.
 356
 357 LIBNVDIMM: DIMM (NMEM)
 358
 359         struct nvdimm *nvdimm_create(struct nvdimm_bus *nvdimm_bus, void *provider_data,
 360                         const struct attribute_group **groups, unsigned long flags,
 361                         unsigned long *dsm_mask);
 362
 363         /sys/devices/platform/nfit_test.0/ndbus0
 364         |-- nmem0
 365         |   |-- available_slots
 366         |   |-- commands
 367         |   |-- dev
 368         |   |-- devtype
 369         |   |-- driver -> ../../../../../bus/nd/drivers/nvdimm
 370         |   |-- modalias
 371         |   |-- nfit
 372         |   |   |-- device
 373         |   |   |-- format
 374         |   |   |-- handle
 375         |   |   |-- phys_id
 376         |   |   |-- rev_id
 377         |   |   |-- serial
 378         |   |   `-- vendor
 379         |   |-- state
 380         |   |-- subsystem -> ../../../../../bus/nd
 381         |   `-- uevent
 382         |-- nmem1
 383         [..]
 384
 385
 386 LIBNDCTL: DIMM enumeration example
 387
 388 Note, in this example we are assuming NFIT-defined DIMMs which are
 389 identified by an "nfit_handle" a 32-bit value where:
 390 Bit 3:0 DIMM number within the memory channel
 391 Bit 7:4 memory channel number
 392 Bit 11:8 memory controller ID
 393 Bit 15:12 socket ID (within scope of a Node controller if node controller is present)
 394 Bit 27:16 Node Controller ID
 395 Bit 31:28 Reserved
 396
 397         static struct ndctl_dimm *get_dimm_by_handle(struct ndctl_bus *bus,
 398                unsigned int handle)
 399         {
 400                 struct ndctl_dimm *dimm;
 401
 402                 ndctl_dimm_foreach(bus, dimm)
 403                         if (ndctl_dimm_get_handle(dimm) == handle)
 404                                 return dimm;
 405
 406                 return NULL;
 407         }
 408
 409         #define DIMM_HANDLE(n, s, i, c, d) \
 410                 (((n & 0xfff) << 16) | ((s & 0xf) << 12) | ((i & 0xf) << 8) \
 411                  | ((c & 0xf) << 4) | (d & 0xf))
 412
 413         dimm = get_dimm_by_handle(bus, DIMM_HANDLE(0, 0, 0, 0, 0));
 414
 415 LIBNVDIMM/LIBNDCTL: Region
 416 ----------------------
 417
 418 A generic REGION device is registered for each PMEM range or BLK-aperture
 419 set.  Per the example there are 6 regions: 2 PMEM and 4 BLK-aperture
 420 sets on the "nfit_test.0" bus.  The primary role of regions are to be a
 421 container of "mappings".  A mapping is a tuple of <DIMM,
 422 DPA-start-offset, length>.
 423
 424 LIBNVDIMM provides a built-in driver for these REGION devices.  This driver
 425 is responsible for reconciling the aliased DPA mappings across all
 426 regions, parsing the LABEL, if present, and then emitting NAMESPACE
 427 devices with the resolved/exclusive DPA-boundaries for the nd_pmem or
 428 nd_blk device driver to consume.
 429
 430 In addition to the generic attributes of "mapping"s, "interleave_ways"
 431 and "size" the REGION device also exports some convenience attributes.
 432 "nstype" indicates the integer type of namespace-device this region
 433 emits, "devtype" duplicates the DEVTYPE variable stored by udev at the
 434 'add' event, "modalias" duplicates the MODALIAS variable stored by udev
 435 at the 'add' event, and finally, the optional "spa_index" is provided in
 436 the case where the region is defined by a SPA.
 437
 438 LIBNVDIMM: region
 439
 440         struct nd_region *nvdimm_pmem_region_create(struct nvdimm_bus *nvdimm_bus,
 441                         struct nd_region_desc *ndr_desc);
 442         struct nd_region *nvdimm_blk_region_create(struct nvdimm_bus *nvdimm_bus,
 443                         struct nd_region_desc *ndr_desc);
 444
 445         /sys/devices/platform/nfit_test.0/ndbus0
 446         |-- region0
 447         |   |-- available_size
 448         |   |-- btt0
 449         |   |-- btt_seed
 450         |   |-- devtype
 451         |   |-- driver -> ../../../../../bus/nd/drivers/nd_region
 452         |   |-- init_namespaces
 453         |   |-- mapping0
 454         |   |-- mapping1
 455         |   |-- mappings
 456         |   |-- modalias
 457         |   |-- namespace0.0
 458         |   |-- namespace_seed
 459         |   |-- numa_node
 460         |   |-- nfit
 461         |   |   `-- spa_index
 462         |   |-- nstype
 463         |   |-- set_cookie
 464         |   |-- size
 465         |   |-- subsystem -> ../../../../../bus/nd
 466         |   `-- uevent
 467         |-- region1
 468         [..]
 469
 470 LIBNDCTL: region enumeration example
 471
 472 Sample region retrieval routines based on NFIT-unique data like
 473 "spa_index" (interleave set id) for PMEM and "nfit_handle" (dimm id) for
 474 BLK.
 475
 476         static struct ndctl_region *get_pmem_region_by_spa_index(struct ndctl_bus *bus,
 477                         unsigned int spa_index)
 478         {
 479                 struct ndctl_region *region;
 480
 481                 ndctl_region_foreach(bus, region) {
 482                         if (ndctl_region_get_type(region) != ND_DEVICE_REGION_PMEM)
 483                                 continue;
 484                         if (ndctl_region_get_spa_index(region) == spa_index)
 485                                 return region;
 486                 }
 487                 return NULL;
 488         }
 489
 490         static struct ndctl_region *get_blk_region_by_dimm_handle(struct ndctl_bus *bus,
 491                         unsigned int handle)
 492         {
 493                 struct ndctl_region *region;
 494
 495                 ndctl_region_foreach(bus, region) {
 496                         struct ndctl_mapping *map;
 497
 498                         if (ndctl_region_get_type(region) != ND_DEVICE_REGION_BLOCK)
 499                                 continue;
 500                         ndctl_mapping_foreach(region, map) {
 501                                 struct ndctl_dimm *dimm = ndctl_mapping_get_dimm(map);
 502
 503                                 if (ndctl_dimm_get_handle(dimm) == handle)
 504                                         return region;
 505                         }
 506                 }
 507                 return NULL;
 508         }
 509
 510
 511 Why Not Encode the Region Type into the Region Name?
 512 ----------------------------------------------------
 513
 514 At first glance it seems since NFIT defines just PMEM and BLK interface
 515 types that we should simply name REGION devices with something derived
 516 from those type names.  However, the ND subsystem explicitly keeps the
 517 REGION name generic and expects userspace to always consider the
 518 region-attributes for four reasons:
 519
 520     1. There are already more than two REGION and "namespace" types.  For
 521     PMEM there are two subtypes.  As mentioned previously we have PMEM where
 522     the constituent DIMM devices are known and anonymous PMEM.  For BLK
 523     regions the NFIT specification already anticipates vendor specific
 524     implementations.  The exact distinction of what a region contains is in
 525     the region-attributes not the region-name or the region-devtype.
 526
 527     2. A region with zero child-namespaces is a possible configuration.  For
 528     example, the NFIT allows for a DCR to be published without a
 529     corresponding BLK-aperture.  This equates to a DIMM that can only accept
 530     control/configuration messages, but no i/o through a descendant block
 531     device.  Again, this "type" is advertised in the attributes ('mappings'
 532     == 0) and the name does not tell you much.
 533
 534     3. What if a third major interface type arises in the future?  Outside
 535     of vendor specific implementations, it's not difficult to envision a
 536     third class of interface type beyond BLK and PMEM.  With a generic name
 537     for the REGION level of the device-hierarchy old userspace
 538     implementations can still make sense of new kernel advertised
 539     region-types.  Userspace can always rely on the generic region
 540     attributes like "mappings", "size", etc and the expected child devices
 541     named "namespace".  This generic format of the device-model hierarchy
 542     allows the LIBNVDIMM and LIBNDCTL implementations to be more uniform and
 543     future-proof.
 544
 545     4. There are more robust mechanisms for determining the major type of a
 546     region than a device name.  See the next section, How Do I Determine the
 547     Major Type of a Region?
 548
 549 How Do I Determine the Major Type of a Region?
 550 ----------------------------------------------
 551
 552 Outside of the blanket recommendation of "use libndctl", or simply
 553 looking at the kernel header (/usr/include/linux/ndctl.h) to decode the
 554 "nstype" integer attribute, here are some other options.
 555
 556     1. module alias lookup:
 557
 558     The whole point of region/namespace device type differentiation is to
 559     decide which block-device driver will attach to a given LIBNVDIMM namespace.
 560     One can simply use the modalias to lookup the resulting module.  It's
 561     important to note that this method is robust in the presence of a
 562     vendor-specific driver down the road.  If a vendor-specific
 563     implementation wants to supplant the standard nd_blk driver it can with
 564     minimal impact to the rest of LIBNVDIMM.
 565
 566     In fact, a vendor may also want to have a vendor-specific region-driver
 567     (outside of nd_region).  For example, if a vendor defined its own LABEL
 568     format it would need its own region driver to parse that LABEL and emit
 569     the resulting namespaces.  The output from module resolution is more
 570     accurate than a region-name or region-devtype.
 571
 572     2. udev:
 573
 574     The kernel "devtype" is registered in the udev database
 575     # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region0
 576     P: /devices/platform/nfit_test.0/ndbus0/region0
 577     E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region0
 578     E: DEVTYPE=nd_pmem
 579     E: MODALIAS=nd:t2
 580     E: SUBSYSTEM=nd
 581
 582     # udevadm info --path=/devices/platform/nfit_test.0/ndbus0/region4
 583     P: /devices/platform/nfit_test.0/ndbus0/region4
 584     E: DEVPATH=/devices/platform/nfit_test.0/ndbus0/region4
 585     E: DEVTYPE=nd_blk
 586     E: MODALIAS=nd:t3
 587     E: SUBSYSTEM=nd
 588
 589     ...and is available as a region attribute, but keep in mind that the
 590     "devtype" does not indicate sub-type variations and scripts should
 591     really be understanding the other attributes.
 592
 593     3. type specific attributes:
 594
 595     As it currently stands a BLK-aperture region will never have a
 596     "nfit/spa_index" attribute, but neither will a non-NFIT PMEM region.  A
 597     BLK region with a "mappings" value of 0 is, as mentioned above, a DIMM
 598     that does not allow I/O.  A PMEM region with a "mappings" value of zero
 599     is a simple system-physical-address range.
 600
 601
 602 LIBNVDIMM/LIBNDCTL: Namespace
 603 -------------------------
 604
 605 A REGION, after resolving DPA aliasing and LABEL specified boundaries,
 606 surfaces one or more "namespace" devices.  The arrival of a "namespace"
 607 device currently triggers either the nd_blk or nd_pmem driver to load
 608 and register a disk/block device.
 609
 610 LIBNVDIMM: namespace
 611 Here is a sample layout from the three major types of NAMESPACE where
 612 namespace0.0 represents DIMM-info-backed PMEM (note that it has a 'uuid'
 613 attribute), namespace2.0 represents a BLK namespace (note it has a
 614 'sector_size' attribute) that, and namespace6.0 represents an anonymous
 615 PMEM namespace (note that has no 'uuid' attribute due to not support a
 616 LABEL).
 617
 618         /sys/devices/platform/nfit_test.0/ndbus0/region0/namespace0.0
 619         |-- alt_name
 620         |-- devtype
 621         |-- dpa_extents
 622         |-- force_raw
 623         |-- modalias
 624         |-- numa_node
 625         |-- resource
 626         |-- size
 627         |-- subsystem -> ../../../../../../bus/nd
 628         |-- type
 629         |-- uevent
 630         `-- uuid
 631         /sys/devices/platform/nfit_test.0/ndbus0/region2/namespace2.0
 632         |-- alt_name
 633         |-- devtype
 634         |-- dpa_extents
 635         |-- force_raw
 636         |-- modalias
 637         |-- numa_node
 638         |-- sector_size
 639         |-- size
 640         |-- subsystem -> ../../../../../../bus/nd
 641         |-- type
 642         |-- uevent
 643         `-- uuid
 644         /sys/devices/platform/nfit_test.1/ndbus1/region6/namespace6.0
 645         |-- block
 646         |   `-- pmem0
 647         |-- devtype
 648         |-- driver -> ../../../../../../bus/nd/drivers/pmem
 649         |-- force_raw
 650         |-- modalias
 651         |-- numa_node
 652         |-- resource
 653         |-- size
 654         |-- subsystem -> ../../../../../../bus/nd
 655         |-- type
 656         `-- uevent
 657
 658 LIBNDCTL: namespace enumeration example
 659 Namespaces are indexed relative to their parent region, example below.
 660 These indexes are mostly static from boot to boot, but subsystem makes
 661 no guarantees in this regard.  For a static namespace identifier use its
 662 'uuid' attribute.
 663
 664 static struct ndctl_namespace *get_namespace_by_id(struct ndctl_region *region,
 665                 unsigned int id)
 666 {
 667         struct ndctl_namespace *ndns;
 668
 669         ndctl_namespace_foreach(region, ndns)
 670                 if (ndctl_namespace_get_id(ndns) == id)
 671                         return ndns;
 672
 673         return NULL;
 674 }
 675
 676 LIBNDCTL: namespace creation example
 677 Idle namespaces are automatically created by the kernel if a given
 678 region has enough available capacity to create a new namespace.
 679 Namespace instantiation involves finding an idle namespace and
 680 configuring it.  For the most part the setting of namespace attributes
 681 can occur in any order, the only constraint is that 'uuid' must be set
 682 before 'size'.  This enables the kernel to track DPA allocations
 683 internally with a static identifier.
 684
 685 static int configure_namespace(struct ndctl_region *region,
 686                 struct ndctl_namespace *ndns,
 687                 struct namespace_parameters *parameters)
 688 {
 689         char devname[50];
 690
 691         snprintf(devname, sizeof(devname), "namespace%d.%d",
 692                         ndctl_region_get_id(region), paramaters->id);
 693
 694         ndctl_namespace_set_alt_name(ndns, devname);
 695         /* 'uuid' must be set prior to setting size! */
 696         ndctl_namespace_set_uuid(ndns, paramaters->uuid);
 697         ndctl_namespace_set_size(ndns, paramaters->size);
 698         /* unlike pmem namespaces, blk namespaces have a sector size */
 699         if (parameters->lbasize)
 700                 ndctl_namespace_set_sector_size(ndns, parameters->lbasize);
 701         ndctl_namespace_enable(ndns);
 702 }
 703
 704
 705 Why the Term "namespace"?
 706
 707     1. Why not "volume" for instance?  "volume" ran the risk of confusing
 708     ND (libnvdimm subsystem) to a volume manager like device-mapper.
 709
 710     2. The term originated to describe the sub-devices that can be created
 711     within a NVME controller (see the nvme specification:
 712     http://www.nvmexpress.org/specifications/), and NFIT namespaces are
 713     meant to parallel the capabilities and configurability of
 714     NVME-namespaces.
 715
 716
 717 LIBNVDIMM/LIBNDCTL: Block Translation Table "btt"
 718 ---------------------------------------------
 719
 720 A BTT (design document: http://pmem.io/2014/09/23/btt.html) is a stacked
 721 block device driver that fronts either the whole block device or a
 722 partition of a block device emitted by either a PMEM or BLK NAMESPACE.
 723
 724 LIBNVDIMM: btt layout
 725 Every region will start out with at least one BTT device which is the
 726 seed device.  To activate it set the "namespace", "uuid", and
 727 "sector_size" attributes and then bind the device to the nd_pmem or
 728 nd_blk driver depending on the region type.
 729
 730         /sys/devices/platform/nfit_test.1/ndbus0/region0/btt0/
 731         |-- namespace
 732         |-- delete
 733         |-- devtype
 734         |-- modalias
 735         |-- numa_node
 736         |-- sector_size
 737         |-- subsystem -> ../../../../../bus/nd
 738         |-- uevent
 739         `-- uuid
 740
 741 LIBNDCTL: btt creation example
 742 Similar to namespaces an idle BTT device is automatically created per
 743 region.  Each time this "seed" btt device is configured and enabled a new
 744 seed is created.  Creating a BTT configuration involves two steps of
 745 finding and idle BTT and assigning it to consume a PMEM or BLK namespace.
 746
 747         static struct ndctl_btt *get_idle_btt(struct ndctl_region *region)
 748         {
 749                 struct ndctl_btt *btt;
 750
 751                 ndctl_btt_foreach(region, btt)
 752                         if (!ndctl_btt_is_enabled(btt)
 753                                         && !ndctl_btt_is_configured(btt))
 754                                 return btt;
 755
 756                 return NULL;
 757         }
 758
 759         static int configure_btt(struct ndctl_region *region,
 760                         struct btt_parameters *parameters)
 761         {
 762                 btt = get_idle_btt(region);
 763
 764                 ndctl_btt_set_uuid(btt, parameters->uuid);
 765                 ndctl_btt_set_sector_size(btt, parameters->sector_size);
 766                 ndctl_btt_set_namespace(btt, parameters->ndns);
 767                 /* turn off raw mode device */
 768                 ndctl_namespace_disable(parameters->ndns);
 769                 /* turn on btt access */
 770                 ndctl_btt_enable(btt);
 771         }
 772
 773 Once instantiated a new inactive btt seed device will appear underneath
 774 the region.
 775
 776 Once a "namespace" is removed from a BTT that instance of the BTT device
 777 will be deleted or otherwise reset to default values.  This deletion is
 778 only at the device model level.  In order to destroy a BTT the "info
 779 block" needs to be destroyed.  Note, that to destroy a BTT the media
 780 needs to be written in raw mode.  By default, the kernel will autodetect
 781 the presence of a BTT and disable raw mode.  This autodetect behavior
 782 can be suppressed by enabling raw mode for the namespace via the
 783 ndctl_namespace_set_raw_mode() API.
 784
 785
 786 Summary LIBNDCTL Diagram
 787 ------------------------
 788
 789 For the given example above, here is the view of the objects as seen by the
 790 LIBNDCTL API:
 791             +---+
 792             |CTX|    +---------+   +--------------+  +---------------+
 793             +-+-+  +-> REGION0 +---> NAMESPACE0.0 +--> PMEM8 "pm0.0" |
 794               |    | +---------+   +--------------+  +---------------+
 795 +-------+     |    | +---------+   +--------------+  +---------------+
 796 | DIMM0 <-+   |    +-> REGION1 +---> NAMESPACE1.0 +--> PMEM6 "pm1.0" |
 797 +-------+ |   |    | +---------+   +--------------+  +---------------+
 798 | DIMM1 <-+ +-v--+ | +---------+   +--------------+  +---------------+
 799 +-------+ +-+BUS0+---> REGION2 +-+-> NAMESPACE2.0 +--> ND6  "blk2.0" |
 800 | DIMM2 <-+ +----+ | +---------+ | +--------------+  +----------------------+
 801 +-------+ |        |             +-> NAMESPACE2.1 +--> ND5  "blk2.1" | BTT2 |
 802 | DIMM3 <-+        |               +--------------+  +----------------------+
 803 +-------+          | +---------+   +--------------+  +---------------+
 804                    +-> REGION3 +-+-> NAMESPACE3.0 +--> ND4  "blk3.0" |
 805                    | +---------+ | +--------------+  +----------------------+
 806                    |             +-> NAMESPACE3.1 +--> ND3  "blk3.1" | BTT1 |
 807                    |               +--------------+  +----------------------+
 808                    | +---------+   +--------------+  +---------------+
 809                    +-> REGION4 +---> NAMESPACE4.0 +--> ND2  "blk4.0" |
 810                    | +---------+   +--------------+  +---------------+
 811                    | +---------+   +--------------+  +----------------------+
 812                    +-> REGION5 +---> NAMESPACE5.0 +--> ND1  "blk5.0" | BTT0 |
 813                      +---------+   +--------------+  +---------------+------+
 814
 815