Re: [PATCH] xen: document balloon driver sysfs files

[Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>]

On Wed, Oct 26, 2011 at 09:12:12PM +0200, Daniel Kiper wrote:
> On Wed, Oct 26, 2011 at 11:57:43AM +0100, David Vrabel wrote:
> > From: David Vrabel <david.vrabel@citrix.com>
> >
> > Add ABI documentation for the balloon driver's sysfs files.
> >
> > Signed-off-by: David Vrabel <david.vrabel@citrix.com>
> > ---
> >  .../ABI/stable/sysfs-devices-system-xen_memory     |   72 ++++++++++++++++++++
> >  1 files changed, 72 insertions(+), 0 deletions(-)
> >  create mode 100644 Documentation/ABI/stable/sysfs-devices-system-xen_memory
> >
> > diff --git a/Documentation/ABI/stable/sysfs-devices-system-xen_memory b/Documentation/ABI/stable/sysfs-devices-system-xen_memory
> > new file mode 100644
> > index 0000000..4fbc446
> > --- /dev/null
> > +++ b/Documentation/ABI/stable/sysfs-devices-system-xen_memory
> > @@ -0,0 +1,72 @@
> > +What:		/sys/devices/system/xen_memory/xen_memory0/max_retry_count
> > +Date:		April 2008
> 
> May 2011
> 
> > +KernelVersion:	2.6.26
> 
> 2.6.39, git commit 95d2ac4a0c904942a4fecf815781ebd4171e7a30
> and 40095de1f9082f058970b985a96d2fbef43f94f4.
> 
> Additionally, I think it is worth to add default value and special
> cases description (e.g. max_retry_count == 0 => RETRY_UNLIMITED).
> Please look into drivers/xen/{balloon.c,xen-balloon.c}
> and include/xen/balloon.h for details.
> 
> > +Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
> > +Description:
> > +		The maximum number of times the balloon driver will
> > +		attempt to increase the balloon before giving up.  See
> > +		also 'retry_count' below.
> > +
> > +What:		/sys/devices/system/xen_memory/xen_memory0/max_schedule_delay
> > +Date:		April 2008
> 
> Ditto.
> 
> > +KernelVersion:	2.6.26
> 
> Ditto.
> 
> > +Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
> > +Description:
> > +		The limit that 'schedule_delay' (see below) will be
> > +		increased to.
> > +
> > +What:		/sys/devices/system/xen_memory/xen_memory0/retry_count
> > +Date:		April 2008
> 
> Ditto.
> 
> > +KernelVersion:	2.6.26
> 
> Ditto.
> 
> > +Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
> > +Description:
> > +		The current number of times that the balloon driver
> > +		has attempted to increase the size of the balloon.
> > +
> > +What:		/sys/devices/system/xen_memory/xen_memory0/schedule_delay
> > +Date:		April 2008
> 
> Ditto.
> 
> > +KernelVersion:	2.6.26
> 
> Ditto.
> 
> Daniel

Daniel, how does this look ? I added your Reviewed-by, but if you want
to make some more modifications I can certainly do so.


>From d759668b660f111b6f35b632031eaf1a136a22f3 Mon Sep 17 00:00:00 2001
From: David Vrabel <david.vrabel@citrix.com>
Date: Wed, 26 Oct 2011 11:57:43 +0100
Subject: [PATCH] xen: document balloon driver sysfs files

Add ABI documentation for the balloon driver's sysfs files.

Signed-off-by: David Vrabel <david.vrabel@citrix.com>
Reviewed-by: Daniel Kiper <dkiper@net-space.pl>
[v2: Added comments from Daniel]
Signed-off-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
---
 .../ABI/stable/sysfs-devices-system-xen_memory     |   77 ++++++++++++++++++++
 1 files changed, 77 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/ABI/stable/sysfs-devices-system-xen_memory

diff --git a/Documentation/ABI/stable/sysfs-devices-system-xen_memory b/Documentation/ABI/stable/sysfs-devices-system-xen_memory
new file mode 100644
index 0000000..39463d0
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-devices-system-xen_memory
@@ -0,0 +1,77 @@
+What:		/sys/devices/system/xen_memory/xen_memory0/max_retry_count
+Date:		May 2011
+KernelVersion:	2.6.39
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+		The maximum number of times the balloon driver will
+		attempt to increase the balloon before giving up.  See
+		also 'retry_count' below.
+		A value of zero means retry forever and is the default one.
+
+What:		/sys/devices/system/xen_memory/xen_memory0/max_schedule_delay
+Date:		May 2011
+KernelVersion:	2.6.39
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+		The limit that 'schedule_delay' (see below) will be
+		increased to. The default value is 32.
+
+What:		/sys/devices/system/xen_memory/xen_memory0/retry_count
+Date:		May 2011
+KernelVersion:	2.6.39
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+		The current number of times that the balloon driver
+		has attempted to increase the size of the balloon.
+		The default value is one. With max_retry_count being
+		zero (unlimited), this means that the driver will attempt
+		to retry with a 'schedule_delay' delay.
+
+What:		/sys/devices/system/xen_memory/xen_memory0/schedule_delay
+Date:		May 2011
+KernelVersion:	2.6.39
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+		The time (in jiffies) to wait between attempts to
+		increase the balloon.  Each time the balloon cannot be
+		increased, 'schedule_delay' is increased (until
+		'max_schedule_delay' is reached at which point it
+		will use that value).
+
+What:		/sys/devices/system/xen_memory/xen_memory0/target
+Date:		April 2008
+KernelVersion:	2.6.26
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+		The target number of pages to adjust this domain's
+		memory reservation to.
+
+What:		/sys/devices/system/xen_memory/xen_memory0/target_kb
+Date:		April 2008
+KernelVersion:	2.6.26
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+		As target above, except the value is in KiB.
+
+What:		/sys/devices/system/xen_memory/xen_memory0/info/current_kb
+Date:		April 2008
+KernelVersion:	2.6.26
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+		Current size (in KiB) of this domain's memory
+		reservation.
+
+What:		/sys/devices/system/xen_memory/xen_memory0/info/high_kb
+Date:		April 2008
+KernelVersion:	2.6.26
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+		Amount (in KiB) of high memory in the balloon.
+
+What:		/sys/devices/system/xen_memory/xen_memory0/info/low_kb
+Date:		April 2008
+KernelVersion:	2.6.26
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+		Amount (in KiB) of low (or normal) memory in the
+		balloon.
-- 
1.7.7.1