svn commit: r327664 - stable/11/share/man/man4

[Ian Lepore]

Author: ian
Date: Sun Jan  7 01:08:10 2018
New Revision: 327664
URL: https://svnweb.freebsd.org/changeset/base/327664

Log:
  MFC r327226, r327356
  
  r327226:
  Add a section describing how to tune ARM kernel options to use an MD_ROOT
  filesystem larger than about 50-55 MiB.
  
  The description of VM_KMEM_SIZE_SCALE is roughly as hand-wavy as my
  understanding of the option, but at least mentioning that it's a factor
  and giving an empirical datapoint that works will give folks some idea
  of what to tweak if they have problems.
  
  r327356:
  Correct a mistake and reword a couple sentences to clarify that "the value"
  refers to the scale value, not the kmem_arena size that results from scaling.
  
  Suggested by: alc@

Modified:
  stable/11/share/man/man4/md.4
Directory Properties:
  stable/11/   (props changed)

Modified: stable/11/share/man/man4/md.4
==============================================================================
--- stable/11/share/man/man4/md.4	Sun Jan  7 01:06:04 2018	(r327663)
+++ stable/11/share/man/man4/md.4	Sun Jan  7 01:08:10 2018	(r327664)
@@ -7,7 +7,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd December 7, 2017
+.Dd December 26, 2017
 .Dt MD 4
 .Os
 .Sh NAME
@@ -93,6 +93,47 @@ disk found in the
 .Xr mdconfig 8
 man page.
 Other tools will also create these images, such as NanoBSD.
+.Sh 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.
+.Bl -tag -width indent
+.It Cd 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.
+.It Cd 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.
+.It Cd 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.
+.El
 .Sh SEE ALSO
 .Xr gpart 8 ,
 .Xr loader 8 ,