Document the prctl/signal hwpoison extensions for 2.6.32
PATCH 1/3 Document the prctl/signal hwpoison extensions for 2.6.32
sigaction.2 renamed from sigaction.2-o +22 -1
@@ -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 @@ 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 @@ .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 @@ .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
prctl.2 renamed from prctl.2-o +46 -0
64 lines not on this page · raw message
madvise.2 renamed from madvise.2-o +12 -1
@@ -141,6 +141,15 @@ .BR MADV_DONTFORK , restoring the default behavior, whereby a mapping is inherited across .BR fork (2). +.TP +.BR MADV_HWPOISON " (Since Linux 2.6.32) +Poison a page and handle it like a hardware memory corruption. +Only allowed for processes with +.I CAP_SYS_ADMIN +privileges. This may result in the calling process receiving a +.I SIGBUS +and the page being unmapped. +Intended for testing. .SH "RETURN VALUE" On success .BR madvise ()
@@ -148,6 +157,7 @@ On error, it returns \-1 and .I errno is set appropriately. +.\" XXX someone document the KSM extensions .SH ERRORS .TP .B EAGAIN
@@ -198,8 +208,9 @@ .BR MADV_REMOVE , .BR MADV_DONTFORK , +.BR MADV_DOFORK , and -.B MADV_DOFORK +.BR MADV_HWPOISON are Linux-specific. .SH NOTES .SS "Linux Notes"
--
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
PATCH 2/3 Add missing migrate_pages manpage
In reply to a message not in the archiveBased on the move_pages manpage.
Also some minor improvements to move_pages.
migrate_pages.2 renamed from migrate_pages.2-o +130 -0
@@ -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)
move_pages.2 renamed from move_pages.2-o +8 -0
@@ -25,6 +25,8 @@ .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 @@ 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
PATCH 3/3 Better documentation for the siginfo_t passed to signal handlers
In reply to a message not in the archivesignal.7 renamed from signal.7-o +25 -0
@@ -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 2008-10-15 "Linux" "Linux Programmer's Manual" .SH NAME
@@ -328,6 +329,30 @@ .B SIGIO (which is not specified in POSIX.1-2001) is ignored by default on several other Unix systems. + +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).
--
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
Re: [PATCH] [2/3] Add missing migrate_pages manpage
In reply to a message not in the archivemigrate_pages.2 line 38
Quoted 7 lines · Andi Kleen
migrate_pages.2 renamed from migrate_pages.2-o +7
-0+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
in -> on?
migrate_pages.2 line 102
Quoted 8 lines
migrate_pages.2 renamed from migrate_pages.2-o +8
-0+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.
get_mempolicy is restricted to the cpuset of the caller. What target?
If you are talking about migrate_pages() then the restriction is that the targets have to be within the callers cpuset.
--
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
Re: [PATCH] [2/3] Add missing migrate_pages manpage
Quoted 11 lines · Christoph Lameter
migrate_pages.2 line 38
Quoted 7 lines · Andi Kleen
migrate_pages.2 renamed from migrate_pages.2-o +7
-0+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 inin -> on?
Probably.
Quoted 12 lines
migrate_pages.2 line 102
Quoted 9 lines
migrate_pages.2 renamed from migrate_pages.2-o +8
-0+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.
get_mempolicyis restricted to the cpuset of the caller. What target?
Quoted 2 lines
If you are talking about
migrate_pages()then the restriction is that the targets have to be within the callers cpuset.
I just copied that from the other manpage (it started as a copy), I haven't really thought about that.
-Andi
Signature · 5 lines
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
Re: [PATCH] [2/3] Add missing migrate_pages manpage
In reply to Christoph LameterHi Christoph,
A long time after the fact, but...
Quoted 23 lines · Christoph Lameter
migrate_pages.2 line 38
Quoted 7 lines · Andi Kleen
migrate_pages.2 renamed from migrate_pages.2-o +7
-0+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 inin -> on?
migrate_pages.2 line 102
Quoted 8 lines
migrate_pages.2 renamed from migrate_pages.2-o +8
-0+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.
get_mempolicyis restricted to the cpuset of the caller. What target?
Quoted 2 lines
If you are talking about
migrate_pages()then the restriction is that the targets have to be within the callers cpuset.
Thanks for that clarification. I have added it to the current draft of the page.
Cheers,
Michael
Signature · 7 lines
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
Hi Andi,
Earlier, I missed you MADV_HWPOISON patch.
I applied the following slightly modified version of your patch. Could you please review:
man2/madvise.2 +14 -1
@@ -144,6 +144,18 @@ Undo the effect of .BR MADV_DONTFORK , restoring the default behavior, whereby a mapping is inherited across .BR fork (2). +.TP +.BR MADV_HWPOISON " (Since Linux 2.6.32) +Poison a page and handle it like a hardware memory corruption. +This operation is only available for privileged +.RB ( CAP_SYS_ADMIN ) +processes. +This operation may result in the calling process receiving a +.B SIGBUS +and the page being unmapped. +This feature is intended for memory testing. +This feature is only available if the kernel was configured with +.BR CONFIG_MEMORY_FAILURE . .SH "RETURN VALUE" On success .BR madvise ()
@@ -201,8 +213,9 @@ for file access. .BR MADV_REMOVE , .BR MADV_DONTFORK , +.BR MADV_DOFORK , and -.B MADV_DOFORK +.BR MAD_HWPOISON are Linux-specific. .SH NOTES .SS "Linux Notes"
Cheers,
Michael
Quoted 163 lines · Andi Kleen
diff -u man2/sigaction.2-o man2/sigaction.2
sigaction.2 2009-10-03 21:49:25.000000000 +0200 renamed from sigaction.2-o 2009-10-03 21:38:22.000000000 +0200 +0
-0@@ -39,6 +39,7 @@.\" 2004-12-09, mtk, added
SI_TKILL+ other minor changes .\" 2005-09-15, mtk, splitsigpending(),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 NAMEsigaction.2 2009-10-03 21:49:25.000000000 +0200 renamed from sigaction.2-o 2009-10-03 21:38:22.000000000 +0200 +0
-0@@ -271,6 +272,7 @@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
.insigaction.2 2009-10-03 21:49:25.000000000 +0200 renamed from sigaction.2-o 2009-10-03 21:38:22.000000000 +0200 +0
-0@@ -343,7 +345,20 @@.B SIGBUS
fill in
.Isi_addrsigaction.2 2009-10-03 21:49:25.000000000 +0200 renamed from sigaction.2-o 2009-10-03 21:38:22.000000000 +0200 +14
-1-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
.IRsi_band" and "si_fd.sigaction.2 2009-10-03 21:49:25.000000000 +0200 renamed from sigaction.2-o 2009-10-03 21:38:22.000000000 +0200 +0
-0@@ -483,6 +498,12 @@.TP
.BBUS_OBJERR
object-specific hardware error
+.TP
+.BBUS_MCEERR_ARsigaction.2 2009-10-03 21:49:25.000000000 +0200 renamed from sigaction.2-o 2009-10-03 21:38:22.000000000 +0200 +4
-0+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
diff -u man2/prctl.2-o man2/prctl.2prctl.2 2009-11-06 18:35:35.000000000 +0100 renamed from prctl.2-o 2009-10-03 23:29:33.000000000 +0200 +0
-0@@ -37,6 +37,7 @@.\" 2008-06-13 Erik Bosman, <[email protected]> .\" Document
PR_GET_TSCandPR_SET_TSC.
.\" 2008-06-15 mtk, DocumentPR_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 NAMEprctl.2 2009-11-06 18:35:35.000000000 +0100 renamed from prctl.2-o 2009-10-03 23:29:33.000000000 +0200 +0
-0@@ -318,6 +319,45 @@ for information on versions and architectures)Return unaligned access control bits, in the location pointed to by .IR "(int\ *) arg2" .
+.TP
+.BRPR_MCE_KILLprctl.2 2009-11-06 18:35:35.000000000 +0100 renamed from prctl.2-o 2009-10-03 23:29:33.000000000 +0200 +37
-0+(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,
.BRPR_GET_DUMPABLE,prctl.2 2009-11-06 18:35:35.000000000 +0100 renamed from prctl.2-o 2009-10-03 23:29:33.000000000 +0200 +0
-0@@ -400,6 +440,12 @@The
.BR prctl ()
system call was introduced in Linux 2.1.57.prctl.2 2009-11-06 18:35:35.000000000 +0100 renamed from prctl.2-o 2009-10-03 23:29:33.000000000 +0200 +6
-0+ +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.madvise.2 2009-11-06 18:49:54.000000000 +0100 renamed from madvise.2-o 2009-11-06 18:45:57.000000000 +0100 +0
-0@@ -141,6 +141,15 @@ .BR MADV_DONTFORK ,restoring the default behavior, whereby a mapping is inherited across .BR fork (2).
+.TP
+.BRMADV_HWPOISON" (Since Linux 2.6.32)madvise.2 2009-11-06 18:49:54.000000000 +0100 renamed from madvise.2-o 2009-11-06 18:45:57.000000000 +0100 +7
-0+Poison a page and handle it like a hardware memory corruption. +Only allowed for processes with +.I CAP_SYS_ADMIN +privileges. This may result in the calling process receiving a +.I SIGBUS +and the page being unmapped. +Intended for testing..SH "RETURN VALUE"
On success
.BR madvise ()madvise.2 2009-11-06 18:49:54.000000000 +0100 renamed from madvise.2-o 2009-11-06 18:45:57.000000000 +0100 +0
-0@@ -148,6 +157,7 @@On error, it returns \-1 and
.I errno
is set appropriately.
+.\" XXX someone document the KSM extensions
.SH ERRORS
.TP
.B EAGAINmadvise.2 2009-11-06 18:49:54.000000000 +0100 renamed from madvise.2-o 2009-11-06 18:45:57.000000000 +0100 +1
-0@@ -198,8 +208,9 @@ .BR MADV_REMOVE , .BR MADV_DONTFORK , +.BR MADV_DOFORK ,and
-.BMADV_DOFORK
+.BRMADV_HWPOISON
are Linux-specific.
.SH NOTES
.SS "Linux Notes"
Signature · 7 lines
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