MD(4)                  FreeBSD Kernel Interfaces Manual                  MD(4)

NAME
     md - memory disk

SYNOPSIS
     To compile this driver into the kernel, place the following lines in your
     kernel configuration file:

           device md

     Alternatively, to load the driver as a module at boot time, place the
     following line in loader.conf(5):

           geom_md_load="YES"

DESCRIPTION
     The md driver provides support for four kinds of memory backed virtual
     disks:

     malloc   Backing store is allocated using malloc(9).  Only one malloc-
              bucket is used, which means that all md devices with malloc
              backing must share the malloc-per-bucket-quota.  The exact size
              of this quota varies, in particular with the amount of RAM in
              the system.  The exact value can be determined with vmstat(8).

     preload  A module loaded by loader(8) with type `md_image' is used for
              backing store.  For backwards compatibility the type `mfs_root'
              is also recognized.  See the description of module loading
              directives in loader.conf(5) and note that the module name will
              either be an absolute path to the image file or the name of a
              file in the module_path.

              If the kernel is created with option MD_ROOT the first preloaded
              image found will become the root file system.

     vnode    A regular file is used as backing store.  This allows for
              mounting ISO images without the tedious detour over actual
              physical media.

     swap     Backing store is allocated from buffer memory.  Pages get pushed
              out to the swap when the system is under memory pressure,
              otherwise they stay in the operating memory.  Using swap backing
              is generally preferable over malloc backing.

     For more information, please see mdconfig(8).

EXAMPLES
     To create a kernel with a ramdisk or MD file system, your kernel config
     needs the following options:

           options         MD_ROOT                 # MD is a potential root device
           options         MD_ROOT_READONLY        # disallow mounting root writeable
           options         MD_ROOT_SIZE=8192       # 8MB ram disk
           makeoptions     MFS_IMAGE=/h/foo/ARM-MD
           options         ROOTDEVNAME=\"ufs:md0\"

     The image in /h/foo/ARM-MD will be loaded as the initial image each boot.
     To create the image to use, please follow the steps to create a file-
     backed disk found in the mdconfig(8) man page.  Other tools will also
     create these images, such as NanoBSD.

ARM KERNEL OPTIONS
     On armv6 and armv7 architectures, an MD_ROOT image larger than
     approximately 55 MiB may require building a custom kernel using several
     tuning options related to kernel memory usage.

     options LOCORE_MAP_MB=<num>
             This configures how much memory is mapped for the kernel during
             the early initialization stages.  The value must be at least as
             large as the kernel plus all preloaded modules, including the
             root image.  There is no downside to setting this value too
             large, as long as it does not exceed the amount of physical
             memory.  The default is 64 MiB.

     options NKPT2PG=<num>
             This configures the number of kernel L2 page table pages to
             preallocate during kernel initialization.  Each L2 page can map 4
             MiB of kernel space.  The value must be large enough to map the
             kernel plus all preloaded modules, including the root image.  The
             default value is 32, which is sufficient to map 128 MiB.

     options VM_KMEM_SIZE_SCALE=<num>
             This configures the amount of kernel virtual address (KVA) space
             to dedicate to the kmem_arena map.  The scale value is the ratio
             of physical to virtual pages.  The default value of 3 allocates a
             page of KVA for each 3 pages of physical ram in the system.

             The kernel and modules, including the root image, also consume
             KVA.  The combination of a large root image and the default
             scaling may preallocate so much KVA that there is not enough
             remaining address space to allocate kernel stacks, IO buffers,
             and other resources that are not part of kmem_arena.
             Overallocating kmem_arena space is likely to manifest as failure
             to launch userland processes with "cannot allocate kernel stack"
             messages.

             Setting the scale value too high may result in kernel failure to
             allocate memory because kmem_arena is too small, and the failure
             may require significant runtime to manifest.  Empirically, a
             value of 5 works well for a 200 MiB root image on a system with 2
             GiB of physical ram.

SEE ALSO
     gpart(8), loader(8), mdconfig(8), mdmfs(8), newfs(8), vmstat(8)

HISTORY
     The md driver first appeared in FreeBSD 4.0 as a cleaner replacement for
     the MFS functionality previously used in PicoBSD and in the FreeBSD
     installation process.

     The md driver did a hostile takeover of the vn(4) driver in FreeBSD 5.0.

AUTHORS
     The md driver was written by Poul-Henning Kamp <phk@FreeBSD.org>.

FreeBSD 13.1-RELEASE-p6         January 8, 2020        FreeBSD 13.1-RELEASE-p6