From patchwork Wed Nov 7 11:01:52 2012 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Anton Vorontsov X-Patchwork-Id: 12713 Return-Path: X-Original-To: patchwork@peony.canonical.com Delivered-To: patchwork@peony.canonical.com Received: from fiordland.canonical.com (fiordland.canonical.com [91.189.94.145]) by peony.canonical.com (Postfix) with ESMTP id 4124723E13 for ; Wed, 7 Nov 2012 11:05:00 +0000 (UTC) Received: from mail-ie0-f180.google.com (mail-ie0-f180.google.com [209.85.223.180]) by fiordland.canonical.com (Postfix) with ESMTP id DFD9AA1943C for ; Wed, 7 Nov 2012 11:04:59 +0000 (UTC) Received: by mail-ie0-f180.google.com with SMTP id e10so2037079iej.11 for ; Wed, 07 Nov 2012 03:04:59 -0800 (PST) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=20120113; h=x-forwarded-to:x-forwarded-for:delivered-to:received-spf:date:from :to:cc:subject:message-id:references:mime-version:content-type :content-disposition:in-reply-to:user-agent:x-gm-message-state; bh=RuCXQXIdSz4AmUx3Cb8B3HOh0tHL/lLuN0gWK2ZgAio=; b=nQdV4WSA3HZgd4zPKlo9+sygOJYmT0blg3yvk12Jptythm2D6q1KmArlLGC15zUj1Z ac6TIqOrOEaXYPUGKwt8svuZ79HDNDN9+dzBej+iNLMzNM3inH2yxu1J7+Nbg9m58aia PzVHDamwlDq0kConyDlGl2QJZsp3HzLQq45b3vvzCzPUShyV7dGSrUXpq5cYHfcZPMvl GVk40V4eYFU451847RBN/QIsDLPv1j3A4Jxv8jFVoTe0W8El8L3rbKYgVboshLjwEA83 xJMCBwZ1WFTMbShd9calwxraQMNn/5Z9GcnsDGbZ0t5amZyJFys5k8Hfn4CbUE8ZBWXw 5vZw== Received: by 10.50.140.97 with SMTP id rf1mr15946762igb.70.1352286299653; Wed, 07 Nov 2012 03:04:59 -0800 (PST) X-Forwarded-To: linaro-patchwork@canonical.com X-Forwarded-For: patch@linaro.org linaro-patchwork@canonical.com Delivered-To: patches@linaro.org Received: by 10.50.67.148 with SMTP id n20csp199035igt; Wed, 7 Nov 2012 03:04:59 -0800 (PST) Received: by 10.68.192.97 with SMTP id hf1mr12429181pbc.106.1352286299054; Wed, 07 Nov 2012 03:04:59 -0800 (PST) Received: from mail-pb0-f43.google.com (mail-pb0-f43.google.com [209.85.160.43]) by mx.google.com with ESMTPS id a6si30817850paw.12.2012.11.07.03.04.58 (version=TLSv1/SSLv3 cipher=OTHER); Wed, 07 Nov 2012 03:04:59 -0800 (PST) Received-SPF: neutral (google.com: 209.85.160.43 is neither permitted nor denied by best guess record for domain of anton.vorontsov@linaro.org) client-ip=209.85.160.43; Authentication-Results: mx.google.com; spf=neutral (google.com: 209.85.160.43 is neither permitted nor denied by best guess record for domain of anton.vorontsov@linaro.org) smtp.mail=anton.vorontsov@linaro.org Received: by mail-pb0-f43.google.com with SMTP id jt11so1217374pbb.30 for ; Wed, 07 Nov 2012 03:04:58 -0800 (PST) Received: by 10.66.86.101 with SMTP id o5mr11473733paz.15.1352286298779; Wed, 07 Nov 2012 03:04:58 -0800 (PST) Received: from localhost (c-71-204-165-222.hsd1.ca.comcast.net. [71.204.165.222]) by mx.google.com with ESMTPS id nd6sm13967118pbc.68.2012.11.07.03.04.57 (version=TLSv1/SSLv3 cipher=OTHER); Wed, 07 Nov 2012 03:04:58 -0800 (PST) Date: Wed, 7 Nov 2012 03:01:52 -0800 From: Anton Vorontsov To: Mel Gorman Cc: Pekka Enberg , Leonid Moiseichuk , KOSAKI Motohiro , Minchan Kim , Bartlomiej Zolnierkiewicz , John Stultz , linux-mm@kvack.org, linux-kernel@vger.kernel.org, linaro-kernel@lists.linaro.org, patches@linaro.org, kernel-team@android.com, linux-man@vger.kernel.org Subject: [RFC 3/3] man-pages: Add man page for vmpressure_fd(2) Message-ID: <20121107110152.GC30462@lizard> References: <20121107105348.GA25549@lizard> MIME-Version: 1.0 Content-Disposition: inline In-Reply-To: <20121107105348.GA25549@lizard> User-Agent: Mutt/1.5.21 (2010-09-15) X-Gm-Message-State: ALoCoQnzW0dQJuopMmFFhRIa6aunea1TcAPVasipE3N9jyjVdd8qP84OZ0o7ooyiaYvUPSxfi96p VMPRESSURE_FD(2) Linux Programmer's Manual VMPRESSURE_FD(2) NAME vmpressure_fd - Linux virtual memory pressure notifications SYNOPSIS #define _GNU_SOURCE #include #include #include #include #include int vmpressure_fd(struct vmpressure_config *config) { config->size = sizeof(*config); return syscall(__NR_vmpressure_fd, config); } DESCRIPTION This system call creates a new file descriptor that can be used with blocking (e.g. read(2)) and/or polling (e.g. poll(2)) rou- tines to get notified about system's memory pressure. Upon these notifications, userland programs can cooperate with the kernel, achieving better system's memory management. Memory pressure levels There are currently three memory pressure levels, each level is defined via vmpressure_level enumeration, and correspond to these constants: VMPRESSURE_LOW The system is reclaiming memory for new allocations. Moni- toring reclaiming activity might be useful for maintaining overall system's cache level. VMPRESSURE_MEDIUM The system is experiencing medium memory pressure, there might be some mild swapping activity. Upon this event, applications may decide to free any resources that can be easily reconstructed or re-read from a disk. VMPRESSURE_OOM The system is actively thrashing, it is about to out of memory (OOM) or even the in-kernel OOM killer is on its way to trigger. Applications should do whatever they can to help the system. See proc(5) for more information about OOM killer and its configuration options. Note that the behaviour of some levels can be tuned through the sysctl(5) mechanism. See /usr/src/linux/Documenta- tion/sysctl/vm.txt for various vmpressure_* tunables and their meanings. Configuration vmpressure_fd(2) accepts vmpressure_config structure to configure the notifications: struct vmpressure_config { __u32 size; __u32 threshold; }; size is a part of ABI versioning and must be initialized to sizeof(struct vmpressure_config). threshold is used to setup a minimal value of the pressure upon which the events will be delivered by the kernel (for algebraic comparisons, it is defined that VMPRESSURE_LOW < VMPRES- SURE_MEDIUM < VMPRESSURE_OOM, but applications should not put any meaning into the absolute values.) Events Upon a notification, application must read out events using read(2) system call. The events are delivered using the follow- ing structure: struct vmpressure_event { __u32 pressure; }; The pressure shows the most recent system's pressure level. RETURN VALUE On success, vmpressure_fd() returns a new file descriptor. On error, a negative value is returned and errno is set to indicate the error. ERRORS vmpressure_fd() can fail with errors similar to open(2). In addition, the following errors are possible: EINVAL The failure means that an improperly initalized config structure has been passed to the call. EFAULT The failure means that the kernel was unable to read the configuration structure, that is, config parameter points to an inaccessible memory. VERSIONS The system call is available on Linux since kernel 3.8. Library support is yet not provided by any glibc version. CONFORMING TO The system call is Linux-specific. EXAMPLE Examples can be found in /usr/src/linux/tools/testing/vmpressure/ directory. SEE ALSO poll(2), read(2), proc(5), sysctl(5), vmstat(8) Linux 2012-10-16 VMPRESSURE_FD(2) Signed-off-by: Anton Vorontsov --- man2/vmpressure_fd.2 | 163 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 163 insertions(+) create mode 100644 man2/vmpressure_fd.2 diff --git a/man2/vmpressure_fd.2 b/man2/vmpressure_fd.2 new file mode 100644 index 0000000..eaf07d4 --- /dev/null +++ b/man2/vmpressure_fd.2 @@ -0,0 +1,163 @@ +.\" Copyright (C) 2008 Michael Kerrisk +.\" Copyright (C) 2012 Linaro Ltd. +.\" Anton Vorontsov +.\" +.\" Based on ideas from: +.\" KOSAKI Motohiro, Leonid Moiseichuk, Mel Gorman, Minchan Kim and Pekka +.\" Enberg. +.\" +.\" This program is free software; you can redistribute it and/or modify +.\" it under the terms of the GNU General Public License as published by +.\" the Free Software Foundation; either version 2 of the License, or +.\" (at your option) any later version. +.\" +.\" This program is distributed in the hope that it will be useful, +.\" but WITHOUT ANY WARRANTY; without even the implied warranty of +.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +.\" GNU General Public License for more details. +.\" +.\" You should have received a copy of the GNU General Public License +.\" along with this program; if not, write to the Free Software +.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, +.\" MA 02111-1307 USA +.\" +.TH VMPRESSURE_FD 2 2012-10-16 Linux "Linux Programmer's Manual" +.SH NAME +vmpressure_fd \- Linux virtual memory pressure notifications +.SH SYNOPSIS +.nf +.B #define _GNU_SOURCE +.B #include +.B #include +.B #include +.B #include +.B #include +.\" TODO: libc wrapper + +.BI "int vmpressure_fd(struct vmpressure_config *"config ) +.B +{ +.B + config->size = sizeof(*config); +.B + return syscall(__NR_vmpressure_fd, config); +.B +} +.fi +.SH DESCRIPTION +This system call creates a new file descriptor that can be used with +blocking (e.g. +.BR read (2)) +and/or polling (e.g. +.BR poll (2)) +routines to get notified about system's memory pressure. + +Upon these notifications, userland programs can cooperate with the kernel, +achieving better system's memory management. +.SS Memory pressure levels +There are currently three memory pressure levels, each level is defined +via +.IR vmpressure_level " enumeration," +and correspond to these constants: +.TP +.B VMPRESSURE_LOW +The system is reclaiming memory for new allocations. Monitoring reclaiming +activity might be useful for maintaining overall system's cache level. +.TP +.B VMPRESSURE_MEDIUM +The system is experiencing medium memory pressure, there might be some +mild swapping activity. Upon this event, applications may decide to free +any resources that can be easily reconstructed or re-read from a disk. +.TP +.B VMPRESSURE_OOM +The system is actively thrashing, it is about to out of memory (OOM) or +even the in-kernel OOM killer is on its way to trigger. Applications +should do whatever they can to help the system. See +.BR proc (5) +for more information about OOM killer and its configuration options. +.TP 0 +Note that the behaviour of some levels can be tuned through the +.BR sysctl (5) +mechanism. See +.I /usr/src/linux/Documentation/sysctl/vm.txt +for various +.I vmpressure_* +tunables and their meanings. +.SS Configuration +.BR vmpressure_fd (2) +accepts +.I vmpressure_config +structure to configure the notifications: + +.nf +struct vmpressure_config { + __u32 size; + __u32 threshold; +}; +.fi + +.I size +is a part of ABI versioning and must be initialized to +.IR "sizeof(struct vmpressure_config)" . + +.I threshold +is used to setup a minimal value of the pressure upon which the events +will be delivered by the kernel (for algebraic comparisons, it is defined +that +.BR VMPRESSURE_LOW " <" +.BR VMPRESSURE_MEDIUM " <" +.BR VMPRESSURE_OOM , +but applications should not put any meaning into the absolute values.) +.SS Events +Upon a notification, application must read out events using +.BR read (2) +system call. +The events are delivered using the following structure: + +.nf +struct vmpressure_event { + __u32 pressure; +}; +.fi + +The +.I pressure +shows the most recent system's pressure level. +.SH "RETURN VALUE" +On success, +.BR vmpressure_fd () +returns a new file descriptor. On error, a negative value is returned and +.I errno +is set to indicate the error. +.SH ERRORS +.BR vmpressure_fd () +can fail with errors similar to +.BR open (2). + +In addition, the following errors are possible: +.TP +.B EINVAL +The failure means that an improperly initalized +.I config +structure has been passed to the call. +.TP +.B EFAULT +The failure means that the kernel was unable to read the configuration +structure, that is, +.I config +parameter points to an inaccessible memory. +.SH VERSIONS +The system call is available on Linux since kernel 3.8. Library support is +yet not provided by any glibc version. +.SH CONFORMING TO +The system call is Linux-specific. +.SH EXAMPLE +Examples can be found in +.I /usr/src/linux/tools/testing/vmpressure/ +directory. +.SH "SEE ALSO" +.BR poll (2), +.BR read (2), +.BR proc (5), +.BR sysctl (5), +.BR vmstat (8)