1.\" Copyright (c) 2005 Christian Brueffer 2.\" All rights reserved. 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd March 22, 2017 26.Dt MEMGUARD 9 27.Os 28.Sh NAME 29.Nm MemGuard 30.Nd "memory allocator for debugging purposes" 31.Sh SYNOPSIS 32.Cd "options DEBUG_MEMGUARD" 33.Sh DESCRIPTION 34.Nm 35is a simple and small replacement memory allocator designed 36to help detect tamper-after-free scenarios. 37These problems are more and more common and likely with 38multithreaded kernels where race conditions are more prevalent. 39.Pp 40.Nm 41can take over 42.Fn malloc , 43.Fn realloc 44and 45.Fn free 46for a single malloc type. 47Alternatively 48.Nm 49can take over 50.Fn uma_zalloc , 51.Fn uma_zalloc_arg 52and 53.Fn uma_free 54for a single 55.Xr uma 9 56zone. 57Also 58.Nm 59can guard all allocations larger than 60.Dv PAGE_SIZE , 61and can guard a random fraction of all allocations. 62There is also a knob to prevent allocations smaller than a specified 63size from being guarded, to limit memory waste. 64.Sh EXAMPLES 65To use 66.Nm 67for a memory type, either add an entry to 68.Pa /boot/loader.conf : 69.Bd -literal -offset indent 70vm.memguard.desc=<memory_type> 71.Ed 72.Pp 73Or set the 74.Va vm.memguard.desc 75.Xr sysctl 8 76variable at run-time: 77.Bd -literal -offset indent 78sysctl vm.memguard.desc=<memory_type> 79.Ed 80.Pp 81Where 82.Ar memory_type 83can be either a short description of the memory type to monitor, 84either name of 85.Xr uma 9 86zone. 87Only allocations from that 88.Ar memory_type 89made after 90.Va vm.memguard.desc 91is set will potentially be guarded. 92If 93.Va vm.memguard.desc 94is modified at run-time then only allocations of the new 95.Ar memory_type 96will potentially be guarded once the 97.Xr sysctl 8 98is set. 99Existing guarded allocations will still be properly released by 100either 101.Xr free 9 102or 103.Xr uma_zfree 9 , 104depending on what kind of allocation was taken over. 105.Pp 106To determine short description of a 107.Xr malloc 9 108type one can either take it from the first column of 109.Xr vmstat 8 Fl m 110output, or to find it in the kernel source. 111It is the second argument to 112.Xr MALLOC_DEFINE 9 113macro. 114To determine name of 115.Xr uma 9 116zone one can either take it from the first column of 117.Xr vmstat 8 Fl z 118output, or to find it in the kernel source. 119It is the first argument to the 120.Xr uma_zcreate 9 121function. 122.Pp 123The 124.Va vm.memguard.divisor 125boot-time tunable is used to scale how much of the system's physical 126memory 127.Nm 128is allowed to consume. 129The default is 10, so up to 130.Va vm_cnt.v_page_count Ns /10 131pages can be used. 132.Nm 133will reserve 134.Va vm_kmem_max 135/ 136.Va vm.memguard.divisor 137bytes of virtual address space, limited by twice the physical memory 138size. 139The physical limit is reported as 140.Va vm.memguard.phys_limit 141and the virtual space reserved for 142.Nm 143is reported as 144.Va vm.memguard.mapsize . 145.Pp 146.Nm 147will not do page promotions for any allocation smaller than 148.Va vm.memguard.minsize 149bytes. 150The default is 0, meaning all allocations can potentially be guarded. 151.Nm 152can guard sufficiently large allocations randomly, with average 153frequency of every one in 100000 / 154.Va vm.memguard.frequency 155allocations. 156The default is 0, meaning no allocations are randomly guarded. 157.Pp 158.Nm 159can optionally add unmapped guard pages around each allocation to 160detect overflow and underflow, if 161.Va vm.memguard.options 162has the 1 bit set. 163This option is enabled by default. 164.Nm 165will optionally guard all allocations of 166.Dv PAGE_SIZE 167or larger if 168.Va vm.memguard.options 169has the 2 bit set. 170This option is off by default. 171By default 172.Nm 173does not guard 174.Xr uma 9 175zones that have been initialized with the 176.Dv UMA_ZONE_NOFREE 177flag set, since it can produce false positives on them. 178However, this safety measure can be turned off by setting bit 3 179of the 180.Va vm.memguard.options 181tunable. 182.Sh SEE ALSO 183.Xr sysctl 8 , 184.Xr vmstat 8 , 185.Xr contigmalloc 9 , 186.Xr malloc 9 , 187.Xr redzone 9 , 188.Xr uma 9 189.Sh HISTORY 190.Nm 191first appeared in 192.Fx 6.0 . 193.Sh AUTHORS 194.An -nosplit 195.Nm 196was originally written by 197.An Bosko Milekic Aq Mt bmilekic@FreeBSD.org . 198This manual page was originally written by 199.An Christian Brueffer Aq Mt brueffer@FreeBSD.org . 200Additions have been made by 201.An Matthew Fleming Aq Mt mdf@FreeBSD.org 202and 203.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org 204to both the implementation and the documentation. 205