| 1 |
.\" Copyright 2003-2004, Andi Kleen <[email protected]> |
| 2 |
.\" Copyright 2003-2004, SuSE GmbH |
| 3 |
.\" Copyright 2005, Silicon Graphics, Inc. |
| 4 |
.\" Copyright, the authors of the Linux man-pages project |
| 5 |
.\" |
| 6 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 7 |
.\" |
| 8 |
.TH numa 7 2026-02-08 "Linux man-pages 6.18" |
| 9 |
.SH NAME |
| 10 |
numa \- overview of Non-Uniform Memory Architecture |
| 11 |
.SH DESCRIPTION |
| 12 |
Non-Uniform Memory Access (NUMA) refers to multiprocessor systems |
| 13 |
whose memory is divided into multiple memory nodes. |
| 14 |
The access time of a memory node depends on |
| 15 |
the relative locations of the accessing CPU and the accessed node. |
| 16 |
(This contrasts with a symmetric multiprocessor system, |
| 17 |
where the access time for all of the memory is the same for all CPUs.) |
| 18 |
Normally, each CPU on a NUMA system has a local memory node whose |
| 19 |
contents can be accessed faster than the memory in |
| 20 |
the node local to another CPU |
| 21 |
or the memory on a bus shared by all CPUs. |
| 22 |
.SS NUMA system calls |
| 23 |
The Linux kernel implements the following NUMA-related system calls: |
| 24 |
.BR get_mempolicy (2), |
| 25 |
.BR mbind (2), |
| 26 |
.BR migrate_pages (2), |
| 27 |
.BR move_pages (2), |
| 28 |
and |
| 29 |
.BR set_mempolicy (2). |
| 30 |
However, applications should normally use the interface provided by |
| 31 |
.IR libnuma ; |
| 32 |
see "Library Support" below. |
| 33 |
.SS \f[I]/proc/\f[]pid\f[I]/numa_maps\f[] (since Linux 2.6.14) |
| 34 |
.\" See also Changelog-2.6.14 |
| 35 |
This file displays information about a process's |
| 36 |
NUMA memory policy and allocation. |
| 37 |
.P |
| 38 |
Each line contains information about a memory range used by the process, |
| 39 |
displaying\[em]among other information\[em]the effective memory policy for |
| 40 |
that memory range and on which nodes the pages have been allocated. |
| 41 |
.P |
| 42 |
.I numa_maps |
| 43 |
is a read-only file. |
| 44 |
When |
| 45 |
.IR /proc/ pid /numa_maps |
| 46 |
is read, the kernel will scan the virtual address space of the |
| 47 |
process and report how memory is used. |
| 48 |
One line is displayed for each unique memory range of the process. |
| 49 |
.P |
| 50 |
The first field of each line shows the starting address of the memory range. |
| 51 |
This field allows a correlation with the contents of the |
| 52 |
.IR /proc/ pid /maps |
| 53 |
file, |
| 54 |
which contains the end address of the range and other information, |
| 55 |
such as the access permissions and sharing. |
| 56 |
.P |
| 57 |
The second field shows the memory policy currently in effect for the |
| 58 |
memory range. |
| 59 |
Note that the effective policy is not necessarily the policy |
| 60 |
installed by the process for that memory range. |
| 61 |
Specifically, if the process installed a "default" policy for that range, |
| 62 |
the effective policy for that range will be the process policy, |
| 63 |
which may or may not be "default". |
| 64 |
.P |
| 65 |
The rest of the line contains information about the pages allocated in |
| 66 |
the memory range, as follows: |
| 67 |
.TP |
| 68 |
.I N<node>=<nr_pages> |
| 69 |
The number of pages allocated on |
| 70 |
.IR <node> . |
| 71 |
.I <nr_pages> |
| 72 |
includes only pages currently mapped by the process. |
| 73 |
Page migration and memory reclaim may have temporarily unmapped pages |
| 74 |
associated with this memory range. |
| 75 |
These pages may show up again only after the process has |
| 76 |
attempted to reference them. |
| 77 |
If the memory range represents a shared memory area or file mapping, |
| 78 |
other processes may currently have additional pages mapped in a |
| 79 |
corresponding memory range. |
| 80 |
.TP |
| 81 |
.I file=<filename> |
| 82 |
The file backing the memory range. |
| 83 |
If the file is mapped as private, write accesses may have generated |
| 84 |
COW (Copy-On-Write) pages in this memory range. |
| 85 |
These pages are displayed as anonymous pages. |
| 86 |
.TP |
| 87 |
.I heap |
| 88 |
Memory range is used for the heap. |
| 89 |
.TP |
| 90 |
.I stack |
| 91 |
Memory range is used for the stack. |
| 92 |
.TP |
| 93 |
.I huge |
| 94 |
Huge memory range. |
| 95 |
The page counts shown are huge pages and not regular sized pages. |
| 96 |
.TP |
| 97 |
.I anon=<pages> |
| 98 |
The number of anonymous page in the range. |
| 99 |
.TP |
| 100 |
.I dirty=<pages> |
| 101 |
Number of dirty pages. |
| 102 |
.TP |
| 103 |
.I mapped=<pages> |
| 104 |
Total number of mapped pages, if different from |
| 105 |
.I dirty |
| 106 |
and |
| 107 |
.I anon |
| 108 |
pages. |
| 109 |
.TP |
| 110 |
.I mapmax=<count> |
| 111 |
Maximum mapcount (number of processes mapping a single page) encountered |
| 112 |
during the scan. |
| 113 |
This may be used as an indicator of the degree of sharing occurring in a |
| 114 |
given memory range. |
| 115 |
.TP |
| 116 |
.I swapcache=<count> |
| 117 |
Number of pages that have an associated entry on a swap device. |
| 118 |
.TP |
| 119 |
.I active=<pages> |
| 120 |
The number of pages on the active list. |
| 121 |
This field is shown only if different from the number of pages in this range. |
| 122 |
This means that some inactive pages exist in the memory range that may be |
| 123 |
removed from memory by the swapper soon. |
| 124 |
.TP |
| 125 |
.I writeback=<pages> |
| 126 |
Number of pages that are currently being written out to disk. |
| 127 |
.SH STANDARDS |
| 128 |
None. |
| 129 |
.SH NOTES |
| 130 |
The Linux NUMA system calls and |
| 131 |
.I /proc |
| 132 |
interface are available only |
| 133 |
if the kernel was configured and built with the |
| 134 |
.B CONFIG_NUMA |
| 135 |
option. |
| 136 |
.SS Library support |
| 137 |
Link with |
| 138 |
.I \-lnuma |
| 139 |
to get the system call definitions. |
| 140 |
.I libnuma |
| 141 |
and the required |
| 142 |
.I <numaif.h> |
| 143 |
header are available in the |
| 144 |
.I numactl |
| 145 |
package. |
| 146 |
.P |
| 147 |
However, applications should not use these system calls directly. |
| 148 |
Instead, the higher level interface provided by the |
| 149 |
.BR numa (3) |
| 150 |
functions in the |
| 151 |
.I numactl |
| 152 |
package is recommended. |
| 153 |
The |
| 154 |
.I numactl |
| 155 |
package is available at |
| 156 |
.UR ftp:\://oss.sgi.com\:/www\:/projects\:/libnuma\:/download/ |
| 157 |
.UE . |
| 158 |
The package is also included in some Linux distributions. |
| 159 |
Some distributions include the development library and header |
| 160 |
in the separate |
| 161 |
.I numactl\-devel |
| 162 |
package. |
| 163 |
.SH SEE ALSO |
| 164 |
.BR get_mempolicy (2), |
| 165 |
.BR mbind (2), |
| 166 |
.BR move_pages (2), |
| 167 |
.BR set_mempolicy (2), |
| 168 |
.BR numa (3), |
| 169 |
.BR cpuset (7), |
| 170 |
.BR numactl (8) |