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.\" $FreeBSD$ 26.\" 27.Dd March 22, 2017 28.Dt MEMGUARD 9 29.Os 30.Sh NAME 31.Nm MemGuard 32.Nd "memory allocator for debugging purposes" 33.Sh SYNOPSIS 34.Cd "options DEBUG_MEMGUARD" 35.Sh DESCRIPTION 36.Nm 37is a simple and small replacement memory allocator designed 38to help detect tamper-after-free scenarios. 39These problems are more and more common and likely with 40multithreaded kernels where race conditions are more prevalent. 41.Pp 42.Nm 43can take over 44.Fn malloc , 45.Fn realloc 46and 47.Fn free 48for a single malloc type. 49Alternatively 50.Nm 51can take over 52.Fn uma_zalloc , 53.Fn uma_zalloc_arg 54and 55.Fn uma_free 56for a single 57.Xr uma 9 58zone. 59Also 60.Nm 61can guard all allocations larger than 62.Dv PAGE_SIZE , 63and can guard a random fraction of all allocations. 64There is also a knob to prevent allocations smaller than a specified 65size from being guarded, to limit memory waste. 66.Sh EXAMPLES 67To use 68.Nm 69for a memory type, either add an entry to 70.Pa /boot/loader.conf : 71.Bd -literal -offset indent 72vm.memguard.desc=<memory_type> 73.Ed 74.Pp 75Or set the 76.Va vm.memguard.desc 77.Xr sysctl 8 78variable at run-time: 79.Bd -literal -offset indent 80sysctl vm.memguard.desc=<memory_type> 81.Ed 82.Pp 83Where 84.Ar memory_type 85can be either a short description of the memory type to monitor, 86either name of 87.Xr uma 9 88zone. 89Only allocations from that 90.Ar memory_type 91made after 92.Va vm.memguard.desc 93is set will potentially be guarded. 94If 95.Va vm.memguard.desc 96is modified at run-time then only allocations of the new 97.Ar memory_type 98will potentially be guarded once the 99.Xr sysctl 8 100is set. 101Existing guarded allocations will still be properly released by 102either 103.Xr free 9 104or 105.Xr uma_zfree 9 , 106depending on what kind of allocation was taken over. 107.Pp 108To determine short description of a 109.Xr malloc 9 110type one can either take it from the first column of 111.Xr vmstat 8 Fl m 112output, or to find it in the kernel source. 113It is the second argument to 114.Xr MALLOC_DEFINE 9 115macro. 116To determine name of 117.Xr uma 9 118zone one can either take it from the first column of 119.Xr vmstat 8 Fl z 120output, or to find it in the kernel source. 121It is the first argument to the 122.Xr uma_zcreate 9 123function. 124.Pp 125The 126.Va vm.memguard.divisor 127boot-time tunable is used to scale how much of the system's physical 128memory 129.Nm 130is allowed to consume. 131The default is 10, so up to 132.Va vm_cnt.v_page_count Ns /10 133pages can be used. 134.Nm 135will reserve 136.Va vm_kmem_max 137/ 138.Va vm.memguard.divisor 139bytes of virtual address space, limited by twice the physical memory 140size. 141The physical limit is reported as 142.Va vm.memguard.phys_limit 143and the virtual space reserved for 144.Nm 145is reported as 146.Va vm.memguard.mapsize . 147.Pp 148.Nm 149will not do page promotions for any allocation smaller than 150.Va vm.memguard.minsize 151bytes. 152The default is 0, meaning all allocations can potentially be guarded. 153.Nm 154can guard sufficiently large allocations randomly, with average 155frequency of every one in 100000 / 156.Va vm.memguard.frequency 157allocations. 158The default is 0, meaning no allocations are randomly guarded. 159.Pp 160.Nm 161can optionally add unmapped guard pages around each allocation to 162detect overflow and underflow, if 163.Va vm.memguard.options 164has the 1 bit set. 165This option is enabled by default. 166.Nm 167will optionally guard all allocations of 168.Dv PAGE_SIZE 169or larger if 170.Va vm.memguard.options 171has the 2 bit set. 172This option is off by default. 173By default 174.Nm 175does not guard 176.Xr uma 9 177zones that have been initialized with the 178.Dv UMA_ZONE_NOFREE 179flag set, since it can produce false positives on them. 180However, this safety measure can be turned off by setting bit 3 181of the 182.Va vm.memguard.options 183tunable. 184.Sh SEE ALSO 185.Xr sysctl 8 , 186.Xr vmstat 8 , 187.Xr contigmalloc 9 , 188.Xr malloc 9 , 189.Xr redzone 9 , 190.Xr uma 9 191.Sh HISTORY 192.Nm 193first appeared in 194.Fx 6.0 . 195.Sh AUTHORS 196.An -nosplit 197.Nm 198was originally written by 199.An Bosko Milekic Aq Mt bmilekic@FreeBSD.org . 200This manual page was originally written by 201.An Christian Brueffer Aq Mt brueffer@FreeBSD.org . 202Additions have been made by 203.An Matthew Fleming Aq Mt mdf@FreeBSD.org 204and 205.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org 206to both the implementation and the documentation. 207