share/man/man4/nvdimm.4

   1 .\" Copyright (c) 2019 The FreeBSD Foundation, Inc.
   2 .\"
   3 .\" This documentation was written by
   4 .\" Konstantin Belousov <kib@FreeBSD.org> under sponsorship
   5 .\" from the FreeBSD Foundation.
   6 .\"
   7 .\" Redistribution and use in source and binary forms, with or without
   8 .\" modification, are permitted provided that the following conditions
   9 .\" are met:
  10 .\" 1. Redistributions of source code must retain the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer.
  12 .\" 2. Redistributions in binary form must reproduce the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer in the
  14 .\"    documentation and/or other materials provided with the distribution.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\" $FreeBSD$
  29 .\"
  30 .Dd September 5, 2019
  31 .Dt NVDIMM 4
  32 .Os
  33 .Sh NAME
  34 .Nm nvdimm
  35 .Nd ACPI NVDIMM driver
  36 .Sh SYNOPSIS
  37 To load the driver as a module at boot, place the following line in
  38 .Xr loader.conf 5 :
  39 .Bd -literal -offset indent
  40 nvdimm_load="YES"
  41 .Ed
  42 .Sh DESCRIPTION
  43 .Bf -symbolic
  44 Note:
  45 The
  46 .Nm
  47 driver is under development and has some important limitations
  48 described below.
  49 .Ef
  50 .Pp
  51 The
  52 .Nm
  53 driver provides access to Non-Volatile DIMM (NVDIMM) persistent memory
  54 devices, which are ACPI-enumerated under the root NVDIMM device
  55 with a
  56 .Va _HID
  57 of
  58 .Dv ACPI0012
  59 and in the
  60 .Dv NFIT
  61 table.
  62 .Pp
  63 For each System Physical Address (SPA) Range described by NFIT, a
  64 device node
  65 .Pa /dev/nvdimm_spaNNN
  66 is created, where
  67 .Dv NNN
  68 is the SPA position in the table.
  69 The node can be used to
  70 .Xr read 2 ,
  71 .Xr write 2 ,
  72 or
  73 .Xr mmap 2
  74 the device.
  75 .Pp
  76 Also, for each SPA, the geom provider
  77 .Pa spaNNN
  78 is created, which can be used to create a conventional filesystem (e.g.,
  79 by
  80 .Xr newfs 8 )
  81 and
  82 .Xr mount 8
  83 it as any storage volume.
  84 Content accessible by
  85 .Pa /dev/nvdimm_spaNNN
  86 and
  87 .Pa /dev/spaNNN
  88 is coherent.
  89 .Pp
  90 The
  91 .Nm
  92 driver has support for reading NVDIMM namespaces (if supported by your
  93 hardware and already configured by some other mechanism, e.g., a BIOS
  94 configuration screen).
  95 The driver will provide a
  96 .Pa /dev/nvdimm_spaNNNnsMMM
  97 device node and
  98 .Pa spaNNNnsMMM
  99 geom provider for each namespace in a SPA, which behave analogously to their
 100 full-SPA cousins described above.
 101 .Sh SEE ALSO
 102 .Xr ACPI 4 ,
 103 .Xr GEOM 4 ,
 104 .Xr geom 8 ,
 105 .Xr mount 8 ,
 106 .Xr newfs 8 ,
 107 .Xr disk 9
 108 .Sh HISTORY
 109 The
 110 .Nm
 111 driver first appeared in
 112 .Fx 12.0 .
 113 .Sh AUTHORS
 114 .An -nosplit
 115 The
 116 .Nm
 117 driver was originally written by
 118 .An Konstantin Belousov Aq Mt kib@FreeBSD.org ,
 119 and then updated by
 120 .An D. Scott Phillips Aq Mt scottph@FreeBSD.org .
 121 .Sh BUGS
 122 The
 123 .Nm
 124 driver does not utilize the Block Window interface, so if a write to an
 125 NVDIMM is interrupted due to a system crash or power outage,
 126 the corresponding page might be left in a partially updated state.
 127 .Pp
 128 There is no support for Device-Specific Methods (DSM), used to report and
 129 control device health and wearing.
 130 .Pp
 131 The driver depends on the
 132 .Xr pmap_largemap 9
 133 pmap interface, which is currently only implemented on amd64.
 134 The interface can be only reasonable implemented on 64bit architectures.