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