[PATCH] [0/4] NUMA & hwpoison man page updates

[PATCH] [0/4] NUMA & hwpoison man page updates

[Andi Kleen]

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] [1/4] Document hwpoison signal extensions

[Andi Kleen]

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

Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

Index: man-pages-3.24/man7/signal.7
===================================================================
--- man-pages-3.24.orig/man7/signal.7
+++ 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
===================================================================
--- man-pages-3.24.orig/man2/sigaction.2
+++ 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [1/4] Document hwpoison signal extensions

[Michael Kerrisk]

Hi Andi,

On Sat, Mar 20, 2010 at 5:29 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
>
> Also clarify siginfo_t behaviour in signal.7 a bit with a new table.
>
> Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
>
> Index: man-pages-3.24/man7/signal.7
> ===================================================================
> --- man-pages-3.24.orig/man7/signal.7
> +++ 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
> ===================================================================
> --- man-pages-3.24.orig/man2/sigaction.2
> +++ 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
>

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


--- a/man2/sigaction.2
+++ b/man2/sigaction.2
@@ -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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [1/4] Document hwpoison signal extensions

[Michael Kerrisk]

Hi Andi,

On Sat, Mar 20, 2010 at 5:29 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
>
> Also clarify siginfo_t behaviour in signal.7 a bit with a new table.
>
> Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
>
> Index: man-pages-3.24/man7/signal.7
> ===================================================================
> --- man-pages-3.24.orig/man7/signal.7
> +++ 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

The information in this patch is rather incomplete, and is in any case
covered more completely in sigaction(2), so I haven't applied this
patch. On the other hand, it triggered me to make some improvements to
sigaction(2), as shown below.

Cheers,

Michael

--- a/man2/sigaction.2
+++ b/man2/sigaction.2
@@ -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)
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [1/4] Document hwpoison signal extensions

[Andi Kleen]

> The information in this patch is rather incomplete, and is in any case
> covered more completely in sigaction(2), so I haven't applied this

And impossible to find there.
 
> patch. On the other hand, it triggered me to make some improvements to
> sigaction(2), as shown below.

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [1/4] Document hwpoison signal extensions

[Michael Kerrisk]

Andi,

On Fri, Jun 11, 2010 at 10:31 AM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
>> The information in this patch is rather incomplete, and is in any case
>> covered more completely in sigaction(2), so I haven't applied this
>
> And impossible to find there.

I didn't think so, but see below.

>> patch. On the other hand, it triggered me to make some improvements to
>> sigaction(2), as shown below.
>
> I still think the table is useful, I added it originally when I couldn't
> find this information easily.

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [1/4] Document hwpoison signal extensions

[Andi Kleen]

On Fri, Jun 11, 2010 at 04:46:28PM +0200, Michael Kerrisk wrote:
> +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).

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

> 
> * 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.

Ok it could be listed.

> 
> * It's misleading. For example, it implies that some signals set
> si_code while others don't. But, AFAIK, all signals set this field.

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

Maybe that could be clarified in a introductionary sentence though.

> Likewise, it suggests that there is useful info in si_trapno, but
> usually there is not. The entry for SIGKILL also seems strange.

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

Why is SIGKILL 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.

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/CA@public.gmane.org -- Speaking for myself only.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [1/4] Document hwpoison signal extensions

[Michael Kerrisk]

Hi Andi,

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

On Sun, Jun 13, 2010 at 12:33 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
> On Fri, Jun 11, 2010 at 04:46:28PM +0200, Michael Kerrisk wrote:
>> +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).
>
> The latest version is better, but I'm pretty sure it wasn't
> like that when I submitted the pages.

That's true. I said earlier that though I didn't accept your patch, it
prompted me to make improvements to 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.
>
> Ok it could be listed.

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

>> * It's misleading. For example, it implies that some signals set
>> si_code while others don't. But, AFAIK, all signals set this field.
>
> The point was for which signals these fields contain useful
> information.
>
> Maybe that could be clarified in a introductionary sentence though.
>
>> Likewise, it suggests that there is useful info in si_trapno, but
>> usually there is not. The entry for SIGKILL also seems strange.
>
> There is useful information in trapno for the signals where
> I listed it.

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?

> Why is SIGKILL strange?

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 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.
>
> My problem was that i had to look this up in the source code because
> I couldn't find it in the manpages.

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.

> 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.

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [1/4] Document hwpoison signal extensions

[Andi Kleen]

On Mon, Jun 14, 2010 at 07:10:06AM +0200, Michael Kerrisk wrote:
> >> * 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.
> >
> > Ok it could be listed.
> 
> This was an example. I didn't check for all incomplete pieces.

What else should be missing?

I generated the table by looking at the trap handlers.

> >> Likewise, it suggests that there is useful info in si_trapno, but
> >> usually there is not. The entry for SIGKILL also seems strange.
> >
> > There is useful information in trapno for the signals where
> > I listed it.
> 
> 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

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.

> 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?

arch/x86/kernel/signal.c:162:             put_user_ex(current->thread.trap_no, &sc->trapno);
> 
> > Why is SIGKILL strange?
> 
> 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 was more a comparison to non KILL signals, but ok
you're right RT signals would need to be listed too.

-Andi
-- 
ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org -- Speaking for myself only.
--
To unsubscribe from this list: send the line "unsubscribe linux-man" in
the body of a message to majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [1/4] Document hwpoison signal extensions

[Michael Kerrisk]

Hi Andi,

On Mon, Jun 14, 2010 at 10:20 AM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
> On Mon, Jun 14, 2010 at 07:10:06AM +0200, Michael Kerrisk wrote:
>> >> * 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.
>> >
>> > Ok it could be listed.
>>
>> This was an example. I didn't check for all incomplete pieces.
>
> What else should be missing?

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.

> I generated the table by looking at the trap handlers.
>
>> >> Likewise, it suggests that there is useful info in si_trapno, but
>> >> usually there is not. The entry for SIGKILL also seems strange.
>> >
>> > There is useful information in trapno for the signals where
>> > I listed it.
>>
>> 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
>
> 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.
>
>> 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?
>
> arch/x86/kernel/signal.c:162:             put_user_ex(current->thread.trap_no, &sc->trapno);

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?

>> > Why is SIGKILL strange?
>>
>> 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 was more a comparison to non KILL signals, but ok
> you're right RT signals would need to be listed too.

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [1/4] Document hwpoison signal extensions

[Andi Kleen]

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

Hi Michael,

> 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):

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.

> 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 ;-).

Ok, I assume you'll be writing it.

-Andi

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

Re: [PATCH] [1/4] Document hwpoison signal extensions

[Michael Kerrisk]

Hi Andi,

On Tue, Jun 15, 2010 at 1:05 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
> On Tue, Jun 15, 2010 at 07:25:36AM +0200, Michael Kerrisk wrote:
>
> Hi Michael,
>
>> 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):
>
> 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.

Thanks for the confirmation.

>> 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 ;-).
>
> Ok, I assume you'll be writing it.

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] [2/4] Add a migrate_pages(2) page

[Andi Kleen]

Based on move_pages.

Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

Index: man-pages-3.24/man2/migrate_pages.2
===================================================================
--- /dev/null
+++ 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [2/4] Add a migrate_pages(2) page

[Michael Kerrisk]

Andi,

On Sat, Mar 20, 2010 at 5:29 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
>
> Based on move_pages.
>
> Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
>
> Index: man-pages-3.24/man2/migrate_pages.2

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [2/4] Add a migrate_pages(2) page

[Michael Kerrisk]

Hi Andi, (and Christoph),


On Fri, Jun 11, 2010 at 5:38 PM, Michael Kerrisk
<mtk.manpages-gM/Ye1E23mwN+BqQ9rBEUg@public.gmane.org> wrote:
> Andi,
>
> On Sat, Mar 20, 2010 at 5:29 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
>>
>> Based on move_pages.
>>
>> Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
>>
>> Index: man-pages-3.24/man2/migrate_pages.2
>
> 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.

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [2/4] Add a migrate_pages(2) page

[Andi Kleen]

On Fri, Jun 11, 2010 at 05:38:19PM +0200, Michael Kerrisk wrote:
> Andi,
> 
> On Sat, Mar 20, 2010 at 5:29 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
> >
> > Based on move_pages.
> >
> > Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
> >
> > Index: man-pages-3.24/man2/migrate_pages.2
> 
> 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?

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

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

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [2/4] Add a migrate_pages(2) page

[Michael Kerrisk]

Hi Andi.

On Sun, Jun 13, 2010 at 12:23 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
> On Fri, Jun 11, 2010 at 05:38:19PM +0200, Michael Kerrisk wrote:
>> Andi,
>>
>> On Sat, Mar 20, 2010 at 5:29 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
>> >
>> > Based on move_pages.
>> >
>> > Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
>> >
>> > Index: man-pages-3.24/man2/migrate_pages.2
>>
>> 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?
>
> I did a quick read and don't see anything wrong.

Thanks.

>>
>> Also, if you have any insights on the FIXME related to "current
>> cpset", let me know.
>
> get_mempolicy always acts on the current task, so current.
> Yes it means it cannot be done for a target with different cpuset.

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] [3/4] Clarify includes/libraries in move_pages page

[Andi Kleen]

Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

Index: man-pages-3.24/man2/move_pages.2
===================================================================
--- man-pages-3.24.orig/man2/move_pages.2
+++ 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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [3/4] Clarify includes/libraries in move_pages page

[Michael Kerrisk]

On Sat, Mar 20, 2010 at 5:29 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
>
> Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
>
> Index: man-pages-3.24/man2/move_pages.2

Thanks. Applied for man-pages-3.25.

Cheers,

Michael


===================================================================
> --- man-pages-3.24.orig/man2/move_pages.2
> +++ 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),
>



-- 
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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

[PATCH] [4/4] Document the hwpoison prctls in 2.6.32

[Andi Kleen]

Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

Index: man-pages-3.24/man2/prctl.2
===================================================================
--- man-pages-3.24.orig/man2/prctl.2
+++ man-pages-3.24/man2/prctl.2
@@ -37,6 +37,7 @@
 .\" 2008-06-13 Erik Bosman, <ejbosman-FV+mU1CFjts@public.gmane.org>
 .\"     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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [4/4] Document the hwpoison prctls in 2.6.32

[Michael Kerrisk]

Hi Andi,

On Sat, Mar 20, 2010 at 5:29 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
>
> Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>

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


--- a/man2/prctl.2
+++ b/man2/prctl.2
@@ -37,6 +37,7 @@
 .\" 2008-06-13 Erik Bosman, <ejbosman-FV+mU1CFjts@public.gmane.org>
 .\"     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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [4/4] Document the hwpoison prctls in 2.6.32

[Andi Kleen]

On Sat, Jun 12, 2010 at 04:50:55PM +0200, Michael Kerrisk wrote:
> Hi Andi,
> 
> On Sat, Mar 20, 2010 at 5:29 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
> >
> > Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
> 
> 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?

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH] [4/4] Document the hwpoison prctls in 2.6.32

[Michael Kerrisk]

Hi Andi,

On Sun, Jun 13, 2010 at 12:19 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
> On Sat, Jun 12, 2010 at 04:50:55PM +0200, Michael Kerrisk wrote:
>> Hi Andi,
>>
>> On Sat, Mar 20, 2010 at 5:29 PM, Andi Kleen <andi-Vw/NltI1exuRpAAqCnN02g@public.gmane.org> wrote:
>> >
>> > Signed-off-by: Andi Kleen <ak-VuQAYsv1563Yd54FQh9/CA@public.gmane.org>
>>
>> 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?
>
> 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.

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 majordomo-u79uwXL29TY76Z2rM5mHXA@public.gmane.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html