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