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