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 .\" ----------------------------------------------------------------------------
17 To compile this driver into the kernel,
18 place the following lines in your
19 kernel configuration file:
20 .Bd -ragged -offset indent
24 Alternatively, to load the driver as a
25 module at boot time, place the following line in
27 .Bd -literal -offset indent
33 driver provides support for four kinds of memory backed virtual disks:
34 .Bl -tag -width preload
36 Backing store is allocated using
38 Only one malloc-bucket is used, which means that all
42 backing must share the malloc-per-bucket-quota.
43 The exact size of this quota varies, in particular with the amount
46 The exact value can be determined with
53 is used for backing store.
54 For backwards compatibility the type
57 If the kernel is created with option
59 the first preloaded image found will become the root file system.
61 A regular file is used as backing store.
62 This allows for mounting ISO images without the tedious
63 detour over actual physical media.
65 Backing store is allocated from buffer memory.
66 Pages get pushed out to the swap when the system is under memory
67 pressure, otherwise they stay in the operating memory.
70 backing is generally preferable over
75 For more information, please see
78 To create a kernel with a ramdisk or MD file system, your kernel config
79 needs the following options:
80 .Bd -literal -offset indent
81 options MD_ROOT # MD is a potential root device
82 options MD_ROOT_READONLY # disallow mounting root writeable
83 options MD_ROOT_SIZE=8192 # 8MB ram disk
84 makeoptions MFS_IMAGE=/h/foo/ARM-MD
85 options ROOTDEVNAME=\\"ufs:md0\\"
90 will be loaded as the initial image each boot.
91 To create the image to use, please follow the steps to create a file-backed
95 Other tools will also create these images, such as NanoBSD.
96 .Sh ARM KERNEL OPTIONS
97 On armv6 and armv7 architectures, an MD_ROOT image larger than
98 approximately 55 MiB may require building a custom kernel using
99 several tuning options related to kernel memory usage.
100 .Bl -tag -width indent
101 .It Cd options LOCORE_MAP_MB=<num>
102 This configures how much memory is mapped for the kernel during
103 the early initialization stages.
104 The value must be at least as large as the kernel plus all preloaded
105 modules, including the root image.
106 There is no downside to setting this value too large, as long
107 as it does not exceed the amount of physical memory.
108 The default is 64 MiB.
109 .It Cd options NKPT2PG=<num>
110 This configures the number of kernel L2 page table pages to
111 preallocate during kernel initialization.
112 Each L2 page can map 4 MiB of kernel space.
113 The value must be large enough to map the kernel plus all preloaded
114 modules, including the root image.
115 The default value is 32, which is sufficient to map 128 MiB.
116 .It Cd options VM_KMEM_SIZE_SCALE=<num>
117 This configures the amount of kernel virtual address (KVA) space to
118 dedicate to the kmem_arena map.
119 The scale value is the ratio of physical to virtual pages.
120 The default value of 3 allocates a page of KVA for each 3 pages
121 of physical ram in the system.
123 The kernel and modules, including the root image, also consume KVA.
124 The combination of a large root image and the default scaling
125 may preallocate so much KVA that there is not enough
126 remaining address space to allocate kernel stacks, IO buffers,
127 and other resources that are not part of kmem_arena.
128 Overallocating kmem_arena space is likely to manifest as failure to
129 launch userland processes with "cannot allocate kernel stack" messages.
131 Setting the scale value too high may result in kernel failure to allocate
132 memory because kmem_arena is too small, and the failure may require
133 significant runtime to manifest.
134 Empirically, a value of 5 works well for a 200 MiB root image on
135 a system with 2 GiB of physical ram.
147 driver first appeared in
149 as a cleaner replacement
150 for the MFS functionality previously used in
154 installation process.
158 driver did a hostile takeover of the
165 driver was written by
166 .An Poul-Henning Kamp Aq Mt phk@FreeBSD.org .