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$
   9 .\"
  10 .Dd January 8, 2020
  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 lines 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
  25 module at boot time, place the following line in
  26 .Xr loader.conf 5 :
  27 .Bd -literal -offset indent
  28 geom_md_load="YES"
  29 .Ed
  30 .Sh DESCRIPTION
  31 The
  32 .Nm
  33 driver provides support for four kinds of memory backed virtual disks:
  34 .Bl -tag -width preload
  35 .It Cm malloc
  36 Backing store is allocated using
  37 .Xr malloc 9 .
  38 Only one malloc-bucket is used, which means that all
  39 .Nm
  40 devices with
  41 .Cm malloc
  42 backing must share the malloc-per-bucket-quota.
  43 The exact size of this quota varies, in particular with the amount
  44 of RAM in the
  45 system.
  46 The exact value can be determined with
  47 .Xr vmstat 8 .
  48 .It Cm preload
  49 A module loaded by
  50 .Xr loader 8
  51 with type
  52 .Sq md_image
  53 is used for backing store.
  54 For backwards compatibility the type
  55 .Sq mfs_root
  56 is also recognized.
  57 See the description of module loading directives in
  58 .Xr loader.conf 5
  59 and note that the module name will either be an absolute path to the image file
  60 or the name of a file in the
  61 .Va module_path .
  62 .Pp
  63 If the kernel is created with option
  64 .Dv MD_ROOT
  65 the first preloaded image found will become the root file system.
  66 .It Cm vnode
  67 A regular file is used as backing store.
  68 This allows for mounting ISO images without the tedious
  69 detour over actual physical media.
  70 .It Cm swap
  71 Backing store is allocated from buffer memory.
  72 Pages get pushed out to the swap when the system is under memory
  73 pressure, otherwise they stay in the operating memory.
  74 Using
  75 .Cm swap
  76 backing is generally preferable over
  77 .Cm malloc
  78 backing.
  79 .El
  80 .Pp
  81 For more information, please see
  82 .Xr mdconfig 8 .
  83 .Sh EXAMPLES
  84 To create a kernel with a ramdisk or MD file system, your kernel config
  85 needs the following options:
  86 .Bd -literal -offset indent
  87 options         MD_ROOT                 # MD is a potential root device
  88 options         MD_ROOT_READONLY        # disallow mounting root writeable
  89 options         MD_ROOT_SIZE=8192       # 8MB ram disk
  90 makeoptions     MFS_IMAGE=/h/foo/ARM-MD
  91 options         ROOTDEVNAME=\\"ufs:md0\\"
  92 .Ed
  93 .Pp
  94 The image in
  95 .Pa /h/foo/ARM-MD
  96 will be loaded as the initial image each boot.
  97 To create the image to use, please follow the steps to create a file-backed
  98 disk found in the
  99 .Xr mdconfig 8
 100 man page.
 101 Other tools will also create these images, such as NanoBSD.
 102 .Sh ARM KERNEL OPTIONS
 103 On armv6 and armv7 architectures, an MD_ROOT image larger than
 104 approximately 55 MiB may require building a custom kernel using
 105 several tuning options related to kernel memory usage.
 106 .Bl -tag -width indent
 107 .It Cd options LOCORE_MAP_MB=<num>
 108 This configures how much memory is mapped for the kernel during
 109 the early initialization stages.
 110 The value must be at least as large as the kernel plus all preloaded
 111 modules, including the root image.
 112 There is no downside to setting this value too large, as long
 113 as it does not exceed the amount of physical memory.
 114 The default is 64 MiB.
 115 .It Cd options NKPT2PG=<num>
 116 This configures the number of kernel L2 page table pages to
 117 preallocate during kernel initialization.
 118 Each L2 page can map 4 MiB of kernel space.
 119 The value must be large enough to map the kernel plus all preloaded
 120 modules, including the root image.
 121 The default value is 32, which is sufficient to map 128 MiB.
 122 .It Cd options VM_KMEM_SIZE_SCALE=<num>
 123 This configures the amount of kernel virtual address (KVA) space to
 124 dedicate to the kmem_arena map.
 125 The scale value is the ratio of physical to virtual pages.
 126 The default value of 3 allocates a page of KVA for each 3 pages
 127 of physical ram in the system.
 128
 129 The kernel and modules, including the root image, also consume KVA.
 130 The combination of a large root image and the default scaling
 131 may preallocate so much KVA that there is not enough
 132 remaining address space to allocate kernel stacks, IO buffers,
 133 and other resources that are not part of kmem_arena.
 134 Overallocating kmem_arena space is likely to manifest as failure to
 135 launch userland processes with "cannot allocate kernel stack" messages.
 136
 137 Setting the scale value too high may result in kernel failure to allocate
 138 memory because kmem_arena is too small, and the failure may require
 139 significant runtime to manifest.
 140 Empirically, a value of 5 works well for a 200 MiB root image on
 141 a system with 2 GiB of physical ram.
 142 .El
 143 .Sh SEE ALSO
 144 .Xr gpart 8 ,
 145 .Xr loader 8 ,
 146 .Xr mdconfig 8 ,
 147 .Xr mdmfs 8 ,
 148 .Xr newfs 8 ,
 149 .Xr vmstat 8
 150 .Sh HISTORY
 151 The
 152 .Nm
 153 driver first appeared in
 154 .Fx 4.0
 155 as a cleaner replacement
 156 for the MFS functionality previously used in
 157 .Tn PicoBSD
 158 and in the
 159 .Fx
 160 installation process.
 161 .Pp
 162 The
 163 .Nm
 164 driver did a hostile takeover of the
 165 .Xr vn 4
 166 driver in
 167 .Fx 5.0 .
 168 .Sh AUTHORS
 169 The
 170 .Nm
 171 driver was written by
 172 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .