PATCH 4/10 numactl - numa_maps man page clarifications and cleanup Against: numactl-1.0.3-rc1 1) clarify the meaning of "effective" policy displayed for each memory area. 2) stylistic rewording throughout. 3) add /proc/<pid>/maps to FILES--referenced in body. 4) add set_mempolicy() and mbind() to SEE ALSO, as these can change the vma and task policies, and affect the effective policy displayed. Note: the numa_maps man page describes a core kernel feature. IMO we should move this to the kernel man pages at some point. Signed-off-by: Lee Schermerhorn <lee.schermerhorn@xxxxxx> numa_maps.5 | 99 ++++++++++++++++++++++++++++++++++++------------------------ 1 file changed, 60 insertions(+), 39 deletions(-) Index: numactl-1.0.3-rc1/numa_maps.5 =================================================================== --- numactl-1.0.3-rc1.orig/numa_maps.5 2008-02-10 20:54:17.000000000 -0500 +++ numactl-1.0.3-rc1/numa_maps.5 2008-04-01 21:41:53.000000000 -0400 @@ -3,53 +3,69 @@ .\" .TH NUMA_MAPS 5 "06 March 2006" "Linux 2.6" "Linux Programmer's Manual" .SH NAME -numa_maps \- information about numa memory +numa_maps \- information about a process' numa memory policy and allocation .SH DESCRIPTION The file .B /proc/<pid>/numa_maps -contrains information about each memory area used by a given process -allowing--among other information--the determination of which nodes were used for the pages. +contains information about each memory range used by a given process, +displaying--among other information--the effective memory policy for +that memory range and on which nodes the pages have been allocated. .B numa_maps -is only read by programs or by shell commands, and not written to. -A read operation on the file will make the kernel scan the memory area -of a process to determine how memory is used. One line is displayed for each -memory area of the process. +is a read-only file. +When +.B /proc/<pid>/numa_maps +is read, the kernel will scan the virtual address space of the specified +process and report how memory is used. One line is displayed for each +unique memory range of the process. .P -The -.B numa_maps -format is very simple. The -.I first field -shown on each line is the starting address that allows a correlation with output from -.B /proc/<pid/maps. -The -.I second field -shows the memory policy currently in effect for this particular memory area. +The first field of each line shows the starting address of the memory range. +This field allows a correlation with contents of the +.B /proc/<pid>/maps +file which contains the end address of the range and other information, +such as the access permissions and sharing. +.P +The second field shows the memory policy currently in effect for the +memory range. +Note that the effective policy is not necessarily the policy installed by the +process for that memory range. +Specifically, if the process installed a "default" policy for that range, the +effective policy for that range will be the task policy which may or may not +be "default". .P -The rest of the line contains series of informationi items about the pages in the -memory area. +The rest of the line contains information about the pages allocated in +the memory range. .DT .SS Possible information items .TP 1.5i -.I N<node>=<pages> -The number of pages used on a node. The number of pages includes only pages -mapped by this process. If this is a shared mapping then other processes may -have mapped different pages in a memory area. Note also that page migration -may have temporarily unmapped pages. These may only show up again after the -process has attempted to reference these pages. +.I N<node>=<nr_pages> +The number of pages allocated on +.IR <node> . +.I <nr_pages> +includes only pages currently mapped by the process. +Page migration and memory reclaim may have temporarily unmapped pages +associated with this memory range. +These pages may only show up again after the process has attempted to reference +them. +If the memory range represents a shared memory area or file mapping, +other processes may currently have additional pages mapped in a +corresponding memory range. .TP 1.5i .I file=<filename> -The file backing the memory area. If COW (Copy-On-Write) pages were generated -then the memory area may contain additional anonymous pages. +The file backing the memory range. +If the file is mapped as private, write accesses may have generated +COW (Copy-On-Write) pages in this memory range. +These pages are displayed as anonymous pages. .TP 1.5i .I heap -Memory area is used for the heap. +Memory range is used for the heap. .TP 1.5i .I stack -Memory area is used for the stack. +Memory range is used for the stack. .TP 1.5i .I huge -Huge memory area. The page counts shown are huge pages and not regular sized pages. +Huge memory range. +The page counts shown are huge pages and not regular sized pages. .TP 1.5i .I anon=<pages> The number of anonymous page in the range. @@ -58,27 +74,32 @@ The number of anonymous page in the rang Number of dirty pages .TP 1.5i .I mapped=<pages> -Number of mapped pages for file backed files. Only shown if different from the count of anonymous and dirty pages. +Number of non-dirty, non-anonymous mapped pages for file backed memory areas. .TP 1.5i .I mapmax=<count> -Maximum mapcount (number of processes mapping a single page) encountered during scan. -This may be used as an indicator as to the sharing occuring in a given memory area. +Maximum mapcount (number of processes mapping a single page) encountered +during the scan. +This may be used as an indicator of the degree sharing occuring in a +given memory range. .TP 1.5i .I swapcache=<count> -Number of pages that have an associated entry on the swap device. +Number of pages that have an associated entry on a swap device. .TP 1.5i .I active=<pages> -The number of pages on the active list (only shown if different from the number -of pages in this area). If this item is shown then some inactive pages exist in that particular -memory area that may be removed from memory by the swapper soon. +The number of pages on the active list. +This field is only shown if different from the number of pages in this range. +This means that some inactive pages exist in the memory range that may be +removed from memory by the swapper soon. .TP 1.5i .I writeback=<pages> Number of pages that are currently being written out to disk. .SH FILES -.I /proc/<pid>/numa_maps +.IR /proc/<pid>/numa_maps , +.IR /proc/<pid>/maps . .SH "SEE ALSO" +.BR set_mempolicy (2), +.BR mbind (2), .BR migratepages (8), .BR numactl (8), -.BR cpuset (8), -.BR numactl (5) +.BR cpuset (8). -- To unsubscribe from this list: send the line "unsubscribe linux-numa" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
