NUMA & hwpoison man page updates

I submitted those all some time ago, but they didn't seem to have made it into 3.24. Please include them this time.

-Andi

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Also clarify siginfo_t behaviour in signal.7 a bit with a new table.

Index: man-pages-3.24/man7/signal.7
===================================================================
@@ -40,6 +40,7 @@
 .\"     Added section on system call restarting (SA_RESTART)
 .\"     Added section on stop/cont signals interrupting syscalls.
 .\" 2008-10-05, mtk: various additions
+.\" 2009-10-03, Andi Kleen: add reference to implicit siginfo_t
 .\"
 .TH SIGNAL 7  2010-02-03 "Linux" "Linux Programmer's Manual"
 .SH NAME

@@ -335,6 +336,29 @@ is synonymous with
 .\" parisc is the only exception: SIGSYS is 12, SIGUNUSED is 31
 .B SIGSYS
 on most architectures.
+
+Some of these signals, carry special additional information in a siginfo_t argument,
+clarifying why they were sent.
+.TS
+l l
+_____
+lB l.
+Signal                    siginfo_t fields
+SIGKILL                   si_pid, si_uid
+SIGCHLD                   si_pid, si_uid, si_status, si_utime, si_stime
+SIGILL                    si_code, si_addr, si_trapno
+SIGFPE                    si_code, si_addr, si_trapno
+SIGSEGV                   si_code, si_addr, si_trapno
+SIGBUS                    si_code, si_addr, si_trapno, si_addr_lsb
+SIGTRAP                   si_code, si_addr, si_trapno
+SIGPOLL                   si_band, si_fd
+realtime signals > 32     si_pid, si_uid, si_value
+posix timer               si_tid, si_overrun, si_sigval
+.TE
+
+Please see the
+.I sigaction(2)
+manpage for more details on the various fields
 .SS "Real-time Signals"
 Linux supports real-time signals as originally defined in the POSIX.1b
 real-time extensions (and now included in POSIX.1-2001).

Index: man-pages-3.24/man2/sigaction.2
===================================================================
@@ -39,6 +39,7 @@
 .\" 2004-12-09, mtk, added SI_TKILL + other minor changes
 .\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend()
 .\"	out of this page into separate pages.
+.\" 2009-10-03 Andi Kleen, add hwpoison signal extensions
 .\"
 .TH SIGACTION 2 2009-07-25 "Linux" "Linux Programmer's Manual"
 .SH NAME

@@ -271,6 +272,7 @@ siginfo_t {
     void    *si_addr;     /* Memory location which caused fault */
     int      si_band;     /* Band event */
     int      si_fd;       /* File descriptor */
+    short    si_addr_lsb; /* Least Signifcant bit of address */
 }
 .fi
 .in

@@ -343,7 +345,20 @@ and
 .B SIGBUS
 fill in
 .I si_addr
-with the address of the fault.
+with the address of the fault. Some suberrors of
+.I SIGBUS,
+in particular
+.B BUS_MCEERR_AO
+and
+.B BUS_MCEERR_AR
+also fill in
+.B si_addr_lsb
+This field defines the least significant bit of the reported address and therefore the extent of
+the corruption. For example if a full page was corrupted it contains log2(get_page_size()).
+.I BUS_MCERR_*
+and
+.I si_addr_lsb
+are only available with Linux 2.6.32 and later and are a Linux specific extension.
 .B SIGPOLL
 fills in
 .IR si_band " and " si_fd .

@@ -483,6 +498,12 @@ nonexistent physical address
 .TP
 .B BUS_OBJERR
 object-specific hardware error
+.TP
+.B BUS_MCEERR_AR
+hardware memory error consumed after a machine check: action required. Program cannot continue current execution stream. For this error the si_addr_lsb field is valid. Since Linux 2.6.32 and a Linux specific extension.
+.TP
+.B BUS_MCEERR_AO
+hardware memory error detected in process but not consumed: action optional. Program is allowed to continue current execution stream, but the page containing the reported address is corrupted. The extent of the corruption is defined by the si_addr_lsb field. Since Linux 2.6.32 and a Linux specific extension.
 .RE
 .PP
 The following values can be placed in

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Hi Andi,

It would have been best to separate these two patches. I took the patch to sigaction.2, and enhanced slightly (some small grammar fixes, plus addition of the new BUS_MCERR constants in the list further down the page), as below. Thanks for that patch, and sorry for the long delay in dealing with it.

The update will be in man-pages-3.25.

Cheers,

Michael

@@ -39,8 +39,9 @@
 .\" 2004-12-09, mtk, added SI_TKILL + other minor changes
 .\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend()
 .\"    out of this page into separate pages.
++.\" 2010-06-10 Andi Kleen, add hwpoison signal extensions
 .\"
-.TH SIGACTION 2 2009-07-25 "Linux" "Linux Programmer's Manual"
+.TH SIGACTION 2 2010-06-11 "Linux" "Linux Programmer's Manual"
 .SH NAME
 sigaction \- examine and change a signal action
 .SH SYNOPSIS

@@ -271,6 +272,8 @@ siginfo_t {
     void    *si_addr;     /* Memory location which caused fault */
     int      si_band;     /* Band event */
     int      si_fd;       /* File descriptor */
+    short    si_addr_lsb; /* Least signifcant bit of address
+                             (since kernel 2.6.32) */
 }
 .fi
 .in

@@ -344,6 +347,24 @@ and
 fill in
 .I si_addr
 with the address of the fault.
+Some suberrors of
+.I SIGBUS,
+in particular
+.B BUS_MCEERR_AO
+and
+.BR BUS_MCEERR_AR ,
+also fill in
+.IR si_addr_lsb .
+This field indicates the least significant bit of the reported address
+and therefore the extent of the corruption.
+For example, if a full page was corrupted,
+.I si_addr_lsb
+contains
+.IR log2(sysconf(_SC_PAGESIZE)) .
+.B BUS_MCERR_*
+and
+.I si_addr_lsb
+are Linux-specific extensions.
 .B SIGPOLL
 fills in
 .IR si_band " and " si_fd .

@@ -483,6 +504,12 @@ nonexistent physical address
 .TP
 .B BUS_OBJERR
 object-specific hardware error
+.TP
+.BR BUS_MCEERR_AR " (since Linux 2.6.32)"
+Hardware memory error consumed on a machine check; action required.
+.TP
+.BR BUS_MCEERR_AO " (since Linux 2.6.32)"
+Hardware memory error detected in process but not consumed; action optional.
 .RE
 .PP
 The following values can be placed in

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Hi Andi,

@@ -39,7 +39,8 @@
 .\" 2004-12-09, mtk, added SI_TKILL + other minor changes
 .\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend()
 .\"    out of this page into separate pages.
-+.\" 2010-06-10 Andi Kleen, add hwpoison signal extensions
+.\" 2010-06-11 Andi Kleen, add hwpoison signal extensions
+.\" 2010-06-11 mtk, improvements to discussion of various siginfo_t fields.
 .\"
 .TH SIGACTION 2 2010-06-11 "Linux" "Linux Programmer's Manual"
 .SH NAME

@@ -174,7 +175,7 @@ or resume (i.e., they receive
 This flag is only meaningful when establishing a handler for
 .BR SIGCHLD .
 .TP
-.BR SA_NOCLDWAIT " (Since Linux 2.6)"
+.BR SA_NOCLDWAIT " (since Linux 2.6)"
 .\" To be precise: Linux 2.5.60 -- MTK
 If
 .I signum

@@ -270,9 +271,10 @@ siginfo_t {
     int      si_timerid;  /* Timer ID; POSIX.1b timers */
 .\" In the kernel: si_tid
     void    *si_addr;     /* Memory location which caused fault */
-    int      si_band;     /* Band event */
+    long     si_band;     /* Band event (was \fIint\fP in
+                             glibc 2.3.2 and earlier) */
     int      si_fd;       /* File descriptor */
-    short    si_addr_lsb; /* Least signifcant bit of address
+    short    si_addr_lsb; /* Least significant bit of address
                              (since kernel 2.6.32) */
 }
 .fi

@@ -285,8 +287,10 @@ is generally unused on Linux.)
 The rest of the struct may be a union, so that one should only
 read the fields that are meaningful for the given signal:
 .IP * 2
-POSIX.1b signals and
-.B SIGCHLD
+Signals sent with
+.BR kill (2)
+and
+.BR sigqueue (2)
 fill in
 .IR si_pid " and " si_uid .
 .IP *

@@ -299,15 +303,35 @@ The
 field is an internal ID used by the kernel to identify
 the timer; it is not the same as the timer ID returned by
 .BR timer_create (2).
+The
+.I si_overrun
+field is the timer overrun count;
+this is the same information as is obtained by a call to
+.BR timer_getoverrun (2).
+These fields are nonstandard Linux extensions.
 .IP *
 .B SIGCHLD
 fills in
-.IR si_status ", " si_utime " and " si_stime .
+.IR si_pid ", " si_uid ", " si_status ", " si_utime " and " si_stime ,
+providing information about the child.
+The
+.I si_pid
+field is the process ID of the child;
+.I si_uid
+is the child's real user ID.
+The
+.I si_status
+field contains the exit status of the child (if
+.I si_code
+is
+.BR CLD_EXITED ),
+or the signal number that caused the process to change state.
 The
 .I si_utime
 and
 .I si_stime
-fields do not include the times used by waited-for children (unlike
+contain the user and system CPU time used by the child process;
+these fields do not include the times used by waited-for children (unlike
 .BR getrusage (2)
 and
 .BR time (2)).

@@ -318,7 +342,7 @@ In 2.6 kernels before 2.6.27,
 a bug meant that these fields reported time in units
 of the (configurable) system jiffy (see
 .BR time (7)).
-\" FIXME .
+.\" FIXME .
 .\" When si_utime and si_stime where originally implemented, the
 .\" measurement unit was HZ, which was the same as clock ticks
 .\" (sysconf(_SC_CLK_TCK)).  In 2.6, HZ became configurable, and

@@ -348,7 +372,7 @@ fill in
 .I si_addr
 with the address of the fault.
 Some suberrors of
-.I SIGBUS,
+.BR SIGBUS ,
 in particular
 .B BUS_MCEERR_AO
 and

@@ -365,9 +389,19 @@ contains
 and
 .I si_addr_lsb
 are Linux-specific extensions.
-.B SIGPOLL
+.IP *
+.BR SIGPOLL / SIGIO
 fills in
 .IR si_band " and " si_fd .
+The
+.I si_band
+event is a bit mask containing the same values as are filled in the
+.I revents
+field by
+.BR poll (2).
+The
+.I si_fd
+field indicates the file descriptor for which the I/O event occurred.
 .PP
 .I si_code
 is a value (not a bit mask)

And impossible to find there.

I still think the table is useful, I added it originally when I couldn't find this information easily.

-Andi
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Andi,

I didn't think so, but see below.

These were the problems I had with the patch:

+Signal                    siginfo_t fields
+SIGKILL                   si_pid, si_uid
+SIGCHLD                   si_pid, si_uid, si_status, si_utime, si_stime
+SIGILL                    si_code, si_addr, si_trapno
+SIGFPE                    si_code, si_addr, si_trapno
+SIGSEGV                   si_code, si_addr, si_trapno
+SIGBUS                    si_code, si_addr, si_trapno, si_addr_lsb
+SIGTRAP                   si_code, si_addr, si_trapno
+SIGPOLL                   si_band, si_fd
+realtime signals > 32     si_pid, si_uid, si_value
+posix timer               si_tid, si_overrun, si_sigval

* It duplicates info that can be found in sigaction(2).

* It's incomplete. If you compare against the corresponding information in sigaction(2) [better pull the latest page from git for this comparison], there is more information about which fields are set by the various signals. Also, various siginfo_t fields (si_signo) are missing from your table.

* It's misleading. For example, it implies that some signals set si_code while others don't. But, AFAIK, all signals set this field. Likewise, it suggests that there is useful info in si_trapno, but usually there is not. The entry for SIGKILL also seems strange.

It would help if you could explain what the problem was that you were trying to solve with this patch, and explain why sigaction(2) doesn't solve the problem.

Cheers,

Michael

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface" http://blog.man7.org/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

The latest version is better, but I'm pretty sure it wasn't like that when I submitted the pages.

Ok it could be listed.

The point was for which signals these fields contain useful information.

Maybe that could be clarified in a introductionary sentence though.

There is useful information in trapno for the signals where I listed it.

Why is SIGKILL strange?

My problem was that i had to look this up in the source code because I couldn't find it in the manpages.

And there was no clear place to put the fields for my hwpoison extensions.

Also even if there's a bit redundancy I don't understand why that is a problem? imho the goal should be for individual pages be useful without having to cross reference all the time.

-Andi

ak-VuQAYsv1563Yd54FQh9/[email protected] -- Speaking for myself only.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Hi Andi,

Aside from anything else, I'd especially like your input about si_trapno below.

That's true. I said earlier that though I didn't accept your patch, it prompted me to make improvements to sigaction.2.

This was an example. I didn't check for all incomplete pieces.

So, there may be a problem here. sigaction.2 currently states

int si_trapno; /* Trap number that caused
hardware-generated signal (unused on most architectures) */

Is the last line true? Checking this, my reading of the source is that si_trapno is only used on SPARC/MIPS/Alpha. (These are the architectures that define __ARCH_SI_TRAPNO) Is that wrong? In particular, x86 doesn't generally seem to set si_trapno, right?

I suspect that this should be a more general statement about signals sent with kill(2), right? There's nothing special about SIGKILL in this respect, AFAIK. By the way, the sigaction.2 page, has a statement that covers this.

It may not be the perfect solution, but I believe you can deduce the info you need from sigaction.2. If you still think that that is insufficient, then I'd entertain a patch of the style you suggest, for the sigaction.2 page, but it would need to be more complete and accurate than the earlier patch.

I don't have a problem with useful redundancy, but in combination with the problems I listed, plus the fact that this info is probably better on the sigaction.2 page (which shows the siginfo_t definition), I didn't think the patch worked.

Thanks,

Michael

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface" http://blog.man7.org/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

What else should be missing?

I generated the table by looking at the trap handlers.

It's not true.

I think it's also needed in some cases to figure out what exactly happened, although in most cases code gives this information.

arch/x86/kernel/signal.c:162: put_user_ex(current->thread.trap_no, &sc->trapno);

It was more a comparison to non KILL signals, but ok you're right RT signals would need to be listed too.

-Andi

ak-VuQAYsv1563Yd54FQh9/[email protected] -- Speaking for myself only.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Hi Andi,

I'm not sure. si_signo was one that immediately jumped out at me. I didn't exhaustively check. Another quick scan doesn't show anything else obviously missing.

Okay -- so at this point I plead ignorance/blindness. These are the things that confuse me (and I admit not being able to follow all the kernel code convolutions here):

1. It's not clear to me how the information in sc->trapno then gets into siginfo_t.si_trapno. The line you quote above appears to me to result in a change in the ucontext structure given as the third argument of the handler (but that's partly a guess).

2. In kernel/signal.c, we have:

#ifdef __ARCH_SI_TRAPNO
                err |= __put_user(from->si_trapno, &to->si_trapno);

#endif

But __ARCH_SI_TRAPNO appears not to be set on x86. In fact, only SPARC, MIPS, and Alpha seem to set it.

3. In the siginfo_t structure that glibc provides to userspace, there is the following:

#ifdef __ARCH_SI_TRAPNO
#define si_trapno _sifields._sigfault._trapno
#endif

And on x86, this means that si_trapno is not in the structure.

What have I missed?

In principle, I'd accept a patch like you suggest for sigaction.2 -- probably by the time we finish this discussion, I'll be able to write it myself ;-).

Cheers,

Michael

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface" http://blog.man7.org/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

On Tue, Jun 15, 2010 at 07:25:36AM +0200, Michael Kerrisk wrote:

Hi Michael,

Sorry, it was actually me being wrong. The trapno is only set in the sigcontext on x86, not in the siginfo.

So you're right on this.

Ok, I assume you'll be writing it.

-Andi

ak-VuQAYsv1563Yd54FQh9/[email protected] -- Speaking for myself only.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Hi Andi,

Thanks for the confirmation.

So, I did go away to do this, looked once again at the sigaction.2 page (please pull the latest version), and concluded that everything in your original patch really is covered in sigaction.2. (SIGTRAP wasn't covered, but is now.) I really can't see a benefit of adding a tabular summary to sigaction.2, so I decided not to do this. (Sorry!)

Cheers,

Michael

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface" http://blog.man7.org/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Based on move_pages.

Index: man-pages-3.24/man2/migrate_pages.2
===================================================================
@@ -0,0 +1,130 @@
+.\" Hey Emacs! This file is -*- nroff -*- source.
+.\"
+.\" Copyright 2009 Intel Coporation
+.\"                Author: Andi Kleen
+.\" Based on the move_pages manpage which was
+.\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc.
+.\"                               Christoph Lameter
+.\"
+.\" Permission is granted to make and distribute verbatim copies of this
+.\" manual provided the copyright notice and this permission notice are
+.\" preserved on all copies.
+.\"
+.\" Permission is granted to copy and distribute modified versions of this
+.\" manual under the conditions for verbatim copying, provided that the
+.\" entire resulting derived work is distributed under the terms of a
+.\" permission notice identical to this one.
+.TH MIGRATE_PAGES 2 2009-11-01 "Linux" "Linux Programmer's Manual"
+.SH NAME
+migrate_pages \- move all pages in a process to another set of nodes
+.SH SYNOPSIS
+.nf
+.B #include <numaif.h>
+.sp
+.BI "long migrate_pages(int " pid ", unsigned long " maxnode",
+.BI "                   const unsigned long * " old_nodes,
+.BI "                   const unsigned long * " new_nodes);
+.fi
+.sp
+Link with \fI\-lnuma\fP.
+.SH DESCRIPTION
+.BR migrate_pages ()
+moves all pages of the process
+.I pid
+that are in memory nodes
+.I old_nodes
+to
+.I new_nodes.
+Pages not placed in any node in
+.I old_nodes
+will not be migrated.
+The kernel keeps the relative topology relationship inside
+.I old_nodes
+in
+.I new_nodes
+as far as possible.
+
+.I old_nodes
+and
+.I new_nodes
+are pointers to bitmasks of node numbers, rounded to unsigned longs, with upto
+.I maxnode
+bits.
+.I maxnode
+is the maximum node number in the bitmask plus one (this is the same
+as in
+.I mbind (2),
+but different from
+.I select (2))
+
+.I pid
+is the ID of the process in which pages are to be moved.
+To move pages in another process,
+the caller must be privileged
+.RB ( CAP_SYS_NICE )
+or the real or effective user ID of the calling process must match the
+real or saved-set user ID of the target process.
+If
+.I pid
+is 0 then
+.BR migrate_pages ()
+moves pages of the calling process.
+
+Pages shared with another process will only be moved if the initiating
+process has the
+.RB CAP_SYS_NICE
+privilege.
+.SH "RETURN VALUE"
+On success
+.BR migrate_pages ()
+returns zero.
+On error, it returns \-1, and sets
+.I errno
+to indicate the error.
+.\" .SH ERRORS
+.\" FIXME write me
+.SH VERSIONS
+.BR migrate_pages ()
+first appeared on Linux in version 2.6.16.
+.SH CONFORMING TO
+This system call is Linux-specific.
+.SH "NOTES"
+For information on library support, see
+.BR numa (7).
+
+Use
+.BR get_mempolicy (2)
+with the
+.B MPOL_F_MEMS_ALLOWED
+flag to obtain the set of nodes that are allowed by
+.\" FIXME Clarify "current cpuset".  Is that the cpuset of the caller
+.\" or the target?
+the current cpuset.
+Note that this information is subject to change at any
+time by manual or automatic reconfiguration of the cpuset.
+
+Use of this function may result in pages whose location
+(node) violates the memory policy established for the
+specified addresses (See
+.BR mbind (2)]
+and/or the specified process [See
+.BR set_mempolicy (2)).
+That is, memory policy does not constrain the destination
+nodes used by
+.BR migrate_pages ().
+
+The
+.I numaif.h
+header is not included with glibc, but requires installing
+.I libnuma-devel
+or a similar package.
+.SH "SEE ALSO"
+.BR get_mempolicy (2),
+.BR mbind (2),
+.BR set_mempolicy (2),
+.BR numa (3),
+.BR numa_maps (5),
+.BR cpuset (7),
+.BR numa (7),
+.BR migratepages (8),
+.BR numa_stat (8)

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Andi,

Thanks for this page!

I made some language edits, and add a couple of errors in the (still incomplete) ERRORS section.

Could you please review, to make sure my changes are okay?

Also, if you have any insights on the FIXME related to "current cpset", let me know.

Thanks,

Michael

.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright 2009 Intel Coporation
.\" Author: Andi Kleen
.\" Based on the move_pages manpage which was
.\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc.
.\" Christoph Lameter
.\"
.\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one.
.TH MIGRATE_PAGES 2 2010-06-11 "Linux" "Linux Programmer's Manual" .SH NAME
migrate_pages \- move all pages in a process to another set of nodes .SH SYNOPSIS
.nf
.B #include <numaif.h>
.sp
.BI "long migrate_pages(int " pid ", unsigned long " maxnode,
.BI " const unsigned long * " old_nodes,
.BI " const unsigned long * " new_nodes);
.fi
.sp
Link with \fI\-lnuma\fP.
.SH DESCRIPTION
.BR migrate_pages ()
moves all pages of the process
.I pid
that are in memory nodes
.I old_nodes
to the memory nodes in
.I new_nodes.
Pages not located in any node in
.I old_nodes
will not be migrated.
As far as possible,
the kernel maintains the relative topology relationship inside .I old_nodes
during the migration to
.IR new_nodes .

The
.I old_nodes
and
.I new_nodes
arguments are pointers to bit masks of node numbers, with up to .I maxnode
bits in each mask.
These masks are maintained as arrays of unsigned
.I long
integers (in the last
.I long
integer, the bits beyond those specified by
.I maxnode
are ignored).
The
.I maxnode
argument is the maximum node number in the bit mask plus one (this is the same as in
.BR mbind (2),
but different from
.BR select (2))

The
.I pid
argument is the ID of the process whose pages are to be moved. To move pages in another process,
the caller must be privileged
.RB ( CAP_SYS_NICE )
or the real or effective user ID of the calling process must match the real or saved-set user ID of the target process.
If
.I pid
is 0, then
.BR migrate_pages ()
moves pages of the calling process.

Pages shared with another process will only be moved if the initiating process has the
.B CAP_SYS_NICE
privilege.
.SH "RETURN VALUE"
On success
.BR migrate_pages ()
returns zero.
On error, it returns \-1, and sets
.I errno
to indicate the error.
.SH ERRORS
.TP
.B EPERM
Insufficient privilege
.RB ( CAP_SYS_NICE )
to move pages of the process specified by
.IR pid ,
or insufficient privilege
.RB ( CAP_SYS_NICE )
to access the specified target nodes.
.TP
.B ESRCH
No process matching
.I pid
could be found.
.\" FIXME There are other errors
.SH VERSIONS
The
.BR migrate_pages ()
system call first appeared on Linux in version 2.6.16.
.SH CONFORMING TO
This system call is Linux-specific.
.SH "NOTES"
For information on library support, see
.BR numa (7).

Use
.BR get_mempolicy (2)
with the
.B MPOL_F_MEMS_ALLOWED
flag to obtain the set of nodes that are allowed by
.\" FIXME Clarify "current cpuset". Is that the cpuset of the caller .\" or the target?
the current cpuset.
Note that this information is subject to change at any time by manual or automatic reconfiguration of the cpuset.

Use of
.BR migrate_pages ()
may result in pages whose location
(node) violates the memory policy established for the specified addresses (see
.BR mbind (2))
and/or the specified process (see
.BR set_mempolicy (2)).
That is, memory policy does not constrain the destination nodes used by
.BR migrate_pages ().

The
.I <numaif.h>
header is not included with glibc, but requires installing
.I libnuma-devel
or a similar package.
.SH "SEE ALSO"
.BR get_mempolicy (2),
.BR mbind (2),
.BR set_mempolicy (2),
.BR numa (3),
.BR numa_maps (5),
.BR cpuset (7),
.BR numa (7),
.BR migratepages (8),
.BR numa_stat (8)
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Hi Andi, (and Christoph),

I just now noticed Christoph's note to your earlier mail submitting this page. I've changed as Christoph suggested. Here's the new page below, if you care to review it.

.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright 2009 Intel Coporation
.\" Author: Andi Kleen
.\" Based on the move_pages manpage which was
.\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc.
.\" Christoph Lameter
.\"
.\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are .\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this .\" manual under the conditions for verbatim copying, provided that the .\" entire resulting derived work is distributed under the terms of a .\" permission notice identical to this one.
.TH MIGRATE_PAGES 2 2010-06-11 "Linux" "Linux Programmer's Manual" .SH NAME
migrate_pages \- move all pages in a process to another set of nodes .SH SYNOPSIS
.nf
.B #include <numaif.h>
.sp
.BI "long migrate_pages(int " pid ", unsigned long " maxnode,
.BI " const unsigned long * " old_nodes,
.BI " const unsigned long * " new_nodes);
.fi
.sp
Link with \fI\-lnuma\fP.
.SH DESCRIPTION
.BR migrate_pages ()
moves all pages of the process
.I pid
that are in memory nodes
.I old_nodes
to the memory nodes in
.I new_nodes.
Pages not located in any node in
.I old_nodes
will not be migrated.
As far as possible,
the kernel maintains the relative topology relationship inside .I old_nodes
during the migration to
.IR new_nodes .

The
.I old_nodes
and
.I new_nodes
arguments are pointers to bit masks of node numbers, with up to .I maxnode
bits in each mask.
These masks are maintained as arrays of unsigned
.I long
integers (in the last
.I long
integer, the bits beyond those specified by
.I maxnode
are ignored).
The
.I maxnode
argument is the maximum node number in the bit mask plus one (this is the same as in
.BR mbind (2),
but different from
.BR select (2))

The
.I pid
argument is the ID of the process whose pages are to be moved. To move pages in another process,
the caller must be privileged
.RB ( CAP_SYS_NICE )
or the real or effective user ID of the calling process must match the real or saved-set user ID of the target process.
If
.I pid
is 0, then
.BR migrate_pages ()
moves pages of the calling process.

Pages shared with another process will only be moved if the initiating process has the
.B CAP_SYS_NICE
privilege.
.SH "RETURN VALUE"
On success
.BR migrate_pages ()
returns zero.
On error, it returns \-1, and sets
.I errno
to indicate the error.
.SH ERRORS
.TP
.B EPERM
Insufficient privilege
.RB ( CAP_SYS_NICE )
to move pages of the process specified by
.IR pid ,
or insufficient privilege
.RB ( CAP_SYS_NICE )
to access the specified target nodes.
.TP
.B ESRCH
No process matching
.I pid
could be found.
.\" FIXME There are other errors
.SH VERSIONS
The
.BR migrate_pages ()
system call first appeared on Linux in version 2.6.16.
.SH CONFORMING TO
This system call is Linux-specific.
.SH "NOTES"
For information on library support, see
.BR numa (7).

Use
.BR get_mempolicy (2)
with the
.B MPOL_F_MEMS_ALLOWED
flag to obtain the set of nodes that are allowed by the calling process's cpuset.
Note that this information is subject to change at any time by manual or automatic reconfiguration of the cpuset.

Use of
.BR migrate_pages ()
may result in pages whose location
(node) violates the memory policy established for the specified addresses (see
.BR mbind (2))
and/or the specified process (see
.BR set_mempolicy (2)).
That is, memory policy does not constrain the destination nodes used by
.BR migrate_pages ().

The
.I <numaif.h>
header is not included with glibc, but requires installing
.I libnuma-devel
or a similar package.
.SH "SEE ALSO"
.BR get_mempolicy (2),
.BR mbind (2),
.BR set_mempolicy (2),
.BR numa (3),
.BR numa_maps (5),
.BR cpuset (7),
.BR numa (7),
.BR migratepages (8),
.BR numa_stat (8)
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

I did a quick read and don't see anything wrong.

get_mempolicy always acts on the current task, so current. Yes it means it cannot be done for a target with different cpuset.

-Andi
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Hi Andi.

Thanks.

Okay.

Cheers,

Michael

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface" http://blog.man7.org/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Index: man-pages-3.24/man2/move_pages.2
===================================================================
@@ -25,6 +25,8 @@ move_pages \- move individual pages of a
 .BI "long move_pages(int " pid ", unsigned long count, void **" pages ,
 .BI "                const int *" nodes ", int *" status ", int " flags );
 .fi
+.sp
+Link with \fI\-lnuma\fP.
 .SH DESCRIPTION
 .BR move_pages ()
 moves the specified

@@ -214,6 +216,12 @@ and/or the specified process [See
 That is, memory policy does not constrain the destination
 nodes used by
 .BR move_pages ().
+
+The
+.I numaif.h
+header is not included with glibc, but requires installing
+.I libnuma-devel
+or a similar package.
 .SH "SEE ALSO"
 .BR get_mempolicy (2),
 .BR mbind (2),

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Thanks. Applied for man-pages-3.25.

Cheers,

Michael

===================================================================

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface" http://blog.man7.org/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Index: man-pages-3.24/man2/prctl.2
===================================================================
@@ -37,6 +37,7 @@
 .\" 2008-06-13 Erik Bosman, <[email protected]>
 .\"     Document PR_GET_TSC and PR_SET_TSC.
 .\" 2008-06-15 mtk, Document PR_SET_SECCOMP, PR_GET_SECCOMP
+.\" 2009-10-03 Andi Kleen, document PR_MCE_KILL_*
 .\"
 .TH PRCTL 2 2008-07-16 "Linux" "Linux Programmer's Manual"
 .SH NAME

@@ -318,6 +319,45 @@ on unaligned user access.
 for information on versions and architectures)
 Return unaligned access control bits, in the location pointed to by
 .IR "(int\ *) arg2" .
+.TP
+.BR PR_MCE_KILL
+(Since Linux 2.6.32)
+Set the machine check memory corruption kill policy for the current thread.
+When
+.I arg2
+is
+.B PR_MCE_KILL_CLEAR
+clear thread memory corruption kill policy and use system-wide default.
+When
+.I arg2
+is
+.B PR_MCE_KILL_SET
+use a thread-specific memory corruption kill policy.   In this case
+.I arg3
+defines whether the policy is
+.I early kill (
+.B PR_MCE_KILL_EARLY
+)
+or
+.I late kill (
+.B PR_MCE_KILL_LATE
+) or
+.B PR_MCE_KILL_DEFAULT.
+Early kill means that the task receives a
+.I SIGBUS
+signal as soon as hardware memory corruption is detected inside its address space.
+In late kill mode the process is only killed when it accesses a corrupted page.
+See
+.I sigaction(2)
+for more information on the
+.I SIGBUS.
+The policy is inherited by children.
+Unused arguments upto 6 must be zero for future compatibility.
+.TP
+.BR PR_MCE_KILL_GET
+returns the current per process machine check kill policy as defined above.
+All following arguments upto 6 must be 0.
+
 .SH "RETURN VALUE"
 On success,
 .BR PR_GET_DUMPABLE ,

@@ -400,6 +440,12 @@ capability.
 The
 .BR prctl ()
 system call was introduced in Linux 2.1.57.
+
+The
+.I PR_MCE_KILL
+and
+.I PR_MCE_KILL_GET
+suboptions were introduced with Linux 2.6.32.
 .\" The library interface was added in glibc 2.0.6
 .SH "CONFORMING TO"
 This call is Linux-specific.

--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Hi Andi,

Thanks for this patch. I've done a few language fixes, and also attempted to refine some details. Could you review the below, which will be in 3.25?

Thanks,

Michael

@@ -37,6 +37,7 @@
 .\" 2008-06-13 Erik Bosman, <[email protected]>
 .\"     Document PR_GET_TSC and PR_SET_TSC.
 .\" 2008-06-15 mtk, Document PR_SET_SECCOMP, PR_GET_SECCOMP
+.\" 2009-10-03 Andi Kleen, document PR_MCE_KILL_*
 .\"
 .TH PRCTL 2 2010-05-13 "Linux" "Linux Programmer's Manual"
 .SH NAME

@@ -324,6 +325,52 @@ on unaligned user access.
 for information on versions and architectures)
 Return unaligned access control bits, in the location pointed to by
 .IR "(int\ *) arg2" .
+.TP
+.BR PR_MCE_KILL " (since Linux 2.6.32)"
+Set the machine check memory corruption kill policy for the current thread.
+If
+.I arg2
+is
+.BR PR_MCE_KILL_CLEAR ,
+clear the thread memory corruption kill policy and use the system-wide default.
+(The system-wide default is defined by
+.IR /proc/sys/vm/memory_failure_early_kill ;
+see
+.BR proc (5).)
+If
+.I arg2
+is
+.BR PR_MCE_KILL_SET ,
+use a thread-specific memory corruption kill policy.
+In this case,
+.I arg3
+defines whether the policy is
+.I early kill
+.RB ( PR_MCE_KILL_EARLY ),
+.I late kill
+.RB ( PR_MCE_KILL_LATE ),
+or the system-wide default
+.RB ( PR_MCE_KILL_DEFAULT ).
+Early kill means that the task receives a
+.B SIGBUS
+signal as soon as hardware memory corruption is detected inside
+its address space.
+In late kill mode, the process is only killed when it accesses a

corrupted page.
+See
+.I sigaction(2)
+for more information on the
+.BR SIGBUS
+signal.
+The policy is inherited by children.
+The remaining unused
+.BR prctl ()
+arguments must be zero for future compatibility.
+.TP
+.BR PR_MCE_KILL_GET " (since Linux 2.6.32)"
+Return the current per-process machine check kill policy. +All unused
+.BR prctl ()
+arguments must be zero.
.SH "RETURN VALUE"
On success,
.BR PR_GET_DUMPABLE ,
@@ -331,6 +378,7 @@ On success,
.BR PR_CAPBSET_READ ,
.BR PR_GET_TIMING ,
.BR PR_GET_SECUREBITS ,
+.BR PR_MCE_KILL_GET ,
and (if it returns)
.BR PR_GET_SECCOMP
return the nonnegative values described above.
@@ -352,6 +400,16 @@ The value of
is not recognized.
.TP
.B EINVAL
+.I option
+is
+.BR PR_MCE_KILL
+or
+.BR PR_MCE_KILL_GET ,
+and unused
+.BR prctl ()
+arguments were not specified as zero.
+.TP
+.B EINVAL
.I arg2
is not valid value for this
.IR option .
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Looks good thanks

I don't remember if this was in my original, but I would have clarified that the SIGBUS has a BUS_MCEERR_AR or _AO subclass.

-Andi
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in the body of a message to [email protected] More majordomo info at http://vger.kernel.org/majordomo-info.html

Hi Andi,

You covered that in your patch to sigaction(2), which the prctl() text refers to. Probably that suffices?

Cheers,

Michael

Michael Kerrisk
Linux man-pages maintainer; http://www.kernel.org/doc/man-pages/
Author of "The Linux Programming Interface" http://blog.man7.org/
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to [email protected]
More majordomo info at  http://vger.kernel.org/majordomo-info.html