share/man/man4/md.4

   1 .\" ----------------------------------------------------------------------------
   2 .\" "THE BEER-WARE LICENSE" (Revision 42):
   3 .\" <phk@FreeBSD.ORG> wrote this file.  As long as you retain this notice you
   4 .\" can do whatever you want with this stuff. If we meet some day, and you think
   5 .\" this stuff is worth it, you can buy me a beer in return.   Poul-Henning Kamp
   6 .\" ----------------------------------------------------------------------------
   7 .\"
   8 .\" $FreeBSD: src/share/man/man4/md.4,v 1.3.2.4 2001/06/18 22:00:12 dd Exp $
   9 .\"
  10 .Dd September 28, 2009
  11 .Dt MD 4
  12 .Os
  13 .Sh NAME
  14 .Nm md
  15 .Nd memory disk
  16 .Sh SYNOPSIS
  17 To compile this driver into the kernel,
  18 place the following line in your
  19 kernel configuration file:
  20 .Bd -ragged -offset indent
  21 .Cd device md
  22 .Ed
  23 .Pp
  24 Alternatively, to load the driver as a module at boot time, place the
  25 following line in
  26 .Pa /boot/loader.conf :
  27 .Bd -literal -offset indent
  28 md_load="YES"
  29 .Ed
  30 .Pp
  31 To specify the default maximum size of
  32 .Xr kmalloc 9
  33 backed disks:
  34 .Cd options MD_NSECT=20000
  35 .Sh DESCRIPTION
  36 The
  37 .Nm
  38 driver provides support for two kinds of memory backed virtual disks:
  39 .Xr kmalloc 9
  40 backed
  41 and pre-loaded module backed.
  42 .Pp
  43 The
  44 .Xr kmalloc 9
  45 backed
  46 disks
  47 are severely limited in size by constraints imposed by
  48 .Xr kmalloc 9 .
  49 Specifically, only one malloc bucket is used, which means that all
  50 .Nm
  51 devices with
  52 .Xr kmalloc 9
  53 backing must share the malloc per-bucket quota.
  54 The exact size of this quota varies,
  55 in particular with the amount of RAM in the system.
  56 The exact value can be determined with
  57 .Xr vmstat 8 .
  58 .Pp
  59 A sector filled with identical bytes does not consume storage,
  60 and therefore the storage allocated by a
  61 .Nm
  62 disk can be freed with a command such as this:
  63 .Bd -literal -offset indent
  64 dd if=/dev/zero of=/dev/md567
  65 .Ed
  66 .Pp
  67 The default maximum size of a
  68 .Nm
  69 disk
  70 backed by
  71 .Xr kmalloc 9
  72 is 20,000 sectors of 512 bytes each.
  73 This can be changed
  74 with the kernel option
  75 .Dv MD_NSECT .
  76 .Pp
  77 At boot time the
  78 .Nm
  79 driver will search for pre-loaded modules of type
  80 .Sq md_image
  81 and instantiate a
  82 .Nm
  83 device for each of these modules.
  84 The type
  85 .Sq mfs_root
  86 is also allowed for backward compatibility.
  87 These devices are backed by the RAM reserved by the
  88 .Xr loader 8 ,
  89 and as such not limited by the
  90 .Xr kmalloc 9
  91 size constraints.
  92 However, this also means that the storage cannot be released.
  93 For the same reason,
  94 the
  95 .Dq identical byte
  96 detection is not applicable.
  97 .Pp
  98 The
  99 .Nm
 100 driver uses the
 101 .Dq almost-clone
 102 convention,
 103 whereby opening device number N creates device instance number N+1.
 104 .Pp
 105 The
 106 .Xr vmstat 8
 107 utility can be used to monitor memory usage by
 108 .Xr kmalloc 9
 109 backed
 110 .Nm
 111 disks,
 112 but not those backed by pre-loaded modules.
 113 .Sh EXAMPLES
 114 To mount a
 115 .Xr kmalloc 9
 116 backed
 117 .Nm
 118 device on
 119 .Pa /tmp :
 120 .Bd -literal
 121 if [ -e /dev/md0 ]; then
 122         newfs /dev/md0 && \\
 123         mount /dev/md0 /tmp && \\
 124         chmod 1777 /tmp
 125 fi
 126 .Ed
 127 .Sh SEE ALSO
 128 .Xr disklabel 5 ,
 129 .Xr disklabel 8 ,
 130 .Xr fdisk 8 ,
 131 .Xr loader 8 ,
 132 .Xr newfs 8 ,
 133 .Xr vmstat 8
 134 .Sh HISTORY
 135 The
 136 .Nm
 137 driver first appeared in
 138 .Fx 4.0
 139 as a cleaner replacement
 140 for the MFS functionality previously used in PicoBSD
 141 and in the
 142 .Fx
 143 installation process.
 144 .Sh AUTHORS
 145 The
 146 .Nm
 147 driver was written by
 148 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .