[PATCH] Documentation for sysfs attributes for 3.3 (xen related)

[PATCH] Documentation for sysfs attributes for 3.3 (xen related)

[Konrad Rzeszutek Wilk]

Please accept the following two patches that describe the
SysFS of some of the Xen drivers. Thank you.

David Vrabel (2):
      xen: document balloon driver sysfs files
      xen: document backend sysfs files

 Documentation/ABI/stable/sysfs-bus-xen-backend     |   75 +++++++++++++++++++
 .../ABI/stable/sysfs-devices-system-xen_memory     |   77 ++++++++++++++++++++
 2 files changed, 152 insertions(+), 0 deletions(-)

[PATCH 1/2] xen: document balloon driver sysfs files

[Konrad Rzeszutek Wilk]

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>
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..caa311d
--- /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 seconds.
+
+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 seconds) 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 the max 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

[PATCH 2/2] xen: document backend sysfs files

[Konrad Rzeszutek Wilk]

From: David Vrabel <david.vrabel@citrix.com>

Add ABI documentation for the /sys/bus/xen-backend sysfs files,
including those specific to xen-blkback devices.

Signed-off-by: David Vrabel <david.vrabel@citrix.com>
Signed-off-by: Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
---
 Documentation/ABI/stable/sysfs-bus-xen-backend |   75 ++++++++++++++++++++++++
 1 files changed, 75 insertions(+), 0 deletions(-)
 create mode 100644 Documentation/ABI/stable/sysfs-bus-xen-backend

diff --git a/Documentation/ABI/stable/sysfs-bus-xen-backend b/Documentation/ABI/stable/sysfs-bus-xen-backend
new file mode 100644
index 0000000..3d5951c
--- /dev/null
+++ b/Documentation/ABI/stable/sysfs-bus-xen-backend
@@ -0,0 +1,75 @@
+What:		/sys/bus/xen-backend/devices/*/devtype
+Date:		Feb 2009
+KernelVersion:	2.6.38
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+                The type of the device.  e.g., one of: 'vbd' (block),
+                'vif' (network), or 'vfb' (framebuffer).
+
+What:		/sys/bus/xen-backend/devices/*/nodename
+Date:		Feb 2009
+KernelVersion:	2.6.38
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+                XenStore node (under /local/domain/NNN/) for this
+                backend device.
+
+What:		/sys/bus/xen-backend/devices/vbd-*/physical_device
+Date:		April 2011
+KernelVersion:	3.0
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+                The major:minor number (in hexidecimal) of the
+                physical device providing the storage for this backend
+                block device.
+
+What:		/sys/bus/xen-backend/devices/vbd-*/mode
+Date:		April 2011
+KernelVersion:	3.0
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+                Whether the block device is read-only ('r') or
+                read-write ('w').
+
+What:		/sys/bus/xen-backend/devices/vbd-*/statistics/f_req
+Date:		April 2011
+KernelVersion:	3.0
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+                Number of flush requests from the frontend.
+
+What:		/sys/bus/xen-backend/devices/vbd-*/statistics/oo_req
+Date:		April 2011
+KernelVersion:	3.0
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+                Number of requests delayed because the backend was too
+                busy processing previous requests.
+
+What:		/sys/bus/xen-backend/devices/vbd-*/statistics/rd_req
+Date:		April 2011
+KernelVersion:	3.0
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+                Number of read requests from the frontend.
+
+What:		/sys/bus/xen-backend/devices/vbd-*/statistics/rd_sect
+Date:		April 2011
+KernelVersion:	3.0
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+                Number of sectors read by the frontend.
+
+What:		/sys/bus/xen-backend/devices/vbd-*/statistics/wr_req
+Date:		April 2011
+KernelVersion:	3.0
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+                Number of write requests from the frontend.
+
+What:		/sys/bus/xen-backend/devices/vbd-*/statistics/wr_sect
+Date:		April 2011
+KernelVersion:	3.0
+Contact:	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
+Description:
+                Number of sectors written by the frontend.
-- 
1.7.7.1

Re: [PATCH] Documentation for sysfs attributes for 3.3 (xen related)

[Randy Dunlap]

On 11/18/2011 10:19 AM, Konrad Rzeszutek Wilk wrote:
> Please accept the following two patches that describe the
> SysFS of some of the Xen drivers. Thank you.
> 
> David Vrabel (2):
>       xen: document balloon driver sysfs files
>       xen: document backend sysfs files
> 
>  Documentation/ABI/stable/sysfs-bus-xen-backend     |   75 +++++++++++++++++++
>  .../ABI/stable/sysfs-devices-system-xen_memory     |   77 ++++++++++++++++++++
>  2 files changed, 152 insertions(+), 0 deletions(-)

Hey,

Documentation/ABI/ patches should go to GregKH.

Greg, can we clarify that in MAINTAINERS ?

-- 
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: [PATCH] Documentation for sysfs attributes for 3.3 (xen related)

[Greg KH]

On Fri, Nov 18, 2011 at 10:24:22AM -0800, Randy Dunlap wrote:
> On 11/18/2011 10:19 AM, Konrad Rzeszutek Wilk wrote:
> > Please accept the following two patches that describe the
> > SysFS of some of the Xen drivers. Thank you.
> > 
> > David Vrabel (2):
> >       xen: document balloon driver sysfs files
> >       xen: document backend sysfs files
> > 
> >  Documentation/ABI/stable/sysfs-bus-xen-backend     |   75 +++++++++++++++++++
> >  .../ABI/stable/sysfs-devices-system-xen_memory     |   77 ++++++++++++++++++++
> >  2 files changed, 152 insertions(+), 0 deletions(-)
> 
> Hey,
> 
> Documentation/ABI/ patches should go to GregKH.

Really?  I'm now in charge of the kernel ABI?

Ah, the power...

/me rubs his hands together

> Greg, can we clarify that in MAINTAINERS ?

Seriously, I'm not in charge of it, that's up to the subsystem for which
the API comes from, I am not the one in charge of the whole thing.

So, for this type of patch, they should go through the xen subsystem
maintainers directly.

thanks,

greg k-h

Re: [PATCH] Documentation for sysfs attributes for 3.3 (xen related)

[Konrad Rzeszutek Wilk]

> Seriously, I'm not in charge of it, that's up to the subsystem for which
> the API comes from, I am not the one in charge of the whole thing.
> 
> So, for this type of patch, they should go through the xen subsystem
> maintainers directly.

Oh. Cool. Then please ignore these patches. Thanks.

Re: [PATCH] Documentation for sysfs attributes for 3.3 (xen related)

[Randy Dunlap]

On 11/18/2011 10:33 AM, Greg KH wrote:
> On Fri, Nov 18, 2011 at 10:24:22AM -0800, Randy Dunlap wrote:
>> On 11/18/2011 10:19 AM, Konrad Rzeszutek Wilk wrote:
>>> Please accept the following two patches that describe the
>>> SysFS of some of the Xen drivers. Thank you.
>>>
>>> David Vrabel (2):
>>>       xen: document balloon driver sysfs files
>>>       xen: document backend sysfs files
>>>
>>>  Documentation/ABI/stable/sysfs-bus-xen-backend     |   75 +++++++++++++++++++
>>>  .../ABI/stable/sysfs-devices-system-xen_memory     |   77 ++++++++++++++++++++
>>>  2 files changed, 152 insertions(+), 0 deletions(-)
>>
>> Hey,
>>
>> Documentation/ABI/ patches should go to GregKH.
> 
> Really?  I'm now in charge of the kernel ABI?

Well, you are the person who usually tells people that they need
to provide Documentation/ABI/ patches for sysfs files AFAICT.

> Ah, the power...

:(

> /me rubs his hands together
> 
>> Greg, can we clarify that in MAINTAINERS ?
> 
> Seriously, I'm not in charge of it, that's up to the subsystem for which
> the API comes from, I am not the one in charge of the whole thing.
> 
> So, for this type of patch, they should go through the xen subsystem
> maintainers directly.

Sounds good.  Thanks.

-- 
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***

Re: [PATCH] Documentation for sysfs attributes for 3.3 (xen related)

[Greg KH]

On Fri, Nov 18, 2011 at 10:58:34AM -0800, Randy Dunlap wrote:
> On 11/18/2011 10:33 AM, Greg KH wrote:
> > On Fri, Nov 18, 2011 at 10:24:22AM -0800, Randy Dunlap wrote:
> >> On 11/18/2011 10:19 AM, Konrad Rzeszutek Wilk wrote:
> >>> Please accept the following two patches that describe the
> >>> SysFS of some of the Xen drivers. Thank you.
> >>>
> >>> David Vrabel (2):
> >>>       xen: document balloon driver sysfs files
> >>>       xen: document backend sysfs files
> >>>
> >>>  Documentation/ABI/stable/sysfs-bus-xen-backend     |   75 +++++++++++++++++++
> >>>  .../ABI/stable/sysfs-devices-system-xen_memory     |   77 ++++++++++++++++++++
> >>>  2 files changed, 152 insertions(+), 0 deletions(-)
> >>
> >> Hey,
> >>
> >> Documentation/ABI/ patches should go to GregKH.
> > 
> > Really?  I'm now in charge of the kernel ABI?
> 
> Well, you are the person who usually tells people that they need
> to provide Documentation/ABI/ patches for sysfs files AFAICT.

Yes, because that's a requirement of the whole kernel development
process, not because I'm the maintainer of Documentation/ABI.

Everyone should be reminding people of doing this, not just me.

thanks,

greg k-h