1.\" Copyright (c) 2015 Adrian Chadd <adrian@FreeBSD.org> 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 AUTHORS 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 AUTHORS 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 October 22, 2018 26.Dt NUMA 4 27.Os 28.Sh NAME 29.Nm NUMA 30.Nd Non-Uniform Memory Access 31.Sh SYNOPSIS 32.Cd options MAXMEMDOM 33.Cd options NUMA 34.Sh DESCRIPTION 35Non-Uniform Memory Access is a computer architecture design which 36involves unequal costs between processors, memory and IO devices 37in a given system. 38.Pp 39In a 40.Nm 41architecture, the latency to access specific memory or IO devices 42depends upon which processor the memory or device is attached to. 43Accessing memory local to a processor is faster than accessing memory 44that is connected to one of the other processors. 45.Fx 46implements NUMA-aware memory allocation policies. 47By default it attempts to ensure that allocations are balanced across 48each domain. 49Users may override the default domain selection policy using 50.Xr cpuset 1 . 51.Pp 52.Nm 53support is enabled when the 54.Cd NUMA 55option is specified in the kernel configuration file. 56Each platform defines the 57.Cd MAXMEMDOM 58constant, which specifies the maximum number of supported NUMA domains. 59This constant may be specified in the kernel configuration file. 60.Nm 61support can be disabled at boot time by setting the 62.Va vm.numa.disabled 63tunable to 1. 64Other values for this tunable are currently ignored. 65.Pp 66Thread and process 67.Nm 68policies are controlled with the 69.Xr cpuset_getdomain 2 70and 71.Xr cpuset_setdomain 2 72syscalls. 73The 74.Xr cpuset 1 75tool is available for starting processes with a non-default 76policy, or to change the policy of an existing thread or process. 77See 78.Xr SMP 4 79for information about CPU to domain mapping. 80.Pp 81Systems with non-uniform access to I/O devices may mark those devices 82with the local VM domain identifier. 83Drivers can find out their local domain information by calling 84.Xr bus_get_domain 9 . 85.Ss MIB Variables 86The operation of 87.Nm 88is controlled and exposes information with these 89.Xr sysctl 8 90MIB variables: 91.Pp 92.Bl -tag -width indent -compact 93.It Va vm.ndomains 94The number of VM domains which have been detected. 95.Pp 96.It Va vm.phys_locality 97A table indicating the relative cost of each VM domain to each other. 98A value of 10 indicates equal cost. 99A value of -1 means the locality map is not available or no 100locality information is available. 101.Pp 102.It Va vm.phys_segs 103The map of physical memory, grouped by VM domain. 104.El 105.Sh IMPLEMENTATION NOTES 106The current 107.Nm 108implementation is VM-focused. 109The hardware 110.Nm 111domains are mapped into a contiguous, non-sparse 112VM domain space, starting from 0. 113Thus, VM domain information (for example, the domain identifier) is not 114necessarily the same as is found in the hardware specific information. 115Policy information is available in both struct thread and struct proc. 116.Sh SEE ALSO 117.Xr cpuset 1 , 118.Xr cpuset_getaffinity 2 , 119.Xr cpuset_setaffinity 2 , 120.Xr SMP 4 , 121.Xr bus_get_domain 9 122.Sh HISTORY 123.Nm 124first appeared in 125.Fx 9.0 126as a first-touch allocation policy with a fail-over to round-robin allocation 127and was not configurable. 128It was then modified in 129.Fx 10.0 130to implement a round-robin allocation policy and was also not configurable. 131.Pp 132The 133.Xr numa_getaffinity 2 134and 135.Xr numa_setaffinity 2 136syscalls and the 137.Xr numactl 1 138tool first appeared in 139.Fx 11.0 140and were removed in 141.Fx 12.0 . 142The current implementation appeared in 143.Fx 12.0 . 144.Sh AUTHORS 145This manual page written by 146.An Adrian Chadd Aq Mt adrian@FreeBSD.org . 147.Sh NOTES 148No statistics are kept to indicate how often 149.Nm 150allocation policies succeed or fail. 151