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