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