diff mbox

[1/2] doc, xen: document hypervisor sysfs nodes for xen

Message ID 20170522085700.488-2-jgross@suse.com (mailing list archive)
State New, archived
Headers show

Commit Message

Jürgen Groß May 22, 2017, 8:56 a.m. UTC 
Today only a few sysfs nodes under /sys/hypervisor/ are documented
for Xen in Documentation/ABI/testing/sysfs-hypervisor-pmu. Rename
this file to Documentation/ABI/testing/sysfs-hypervisor and add
descriptions of the other nodes.

Signed-off-by: Juergen Gross <jgross@suse.com>
---
 Documentation/ABI/testing/sysfs-hypervisor     | 131 +++++++++++++++++++++++++
 Documentation/ABI/testing/sysfs-hypervisor-pmu |  23 -----
 MAINTAINERS                                    |   1 +
 3 files changed, 132 insertions(+), 23 deletions(-)
 create mode 100644 Documentation/ABI/testing/sysfs-hypervisor
 delete mode 100644 Documentation/ABI/testing/sysfs-hypervisor-pmu

Comments

Boris Ostrovsky May 22, 2017, 1:30 p.m. UTC | #1 
On 05/22/2017 04:56 AM, Juergen Gross wrote:
> Today only a few sysfs nodes under /sys/hypervisor/ are documented
> for Xen in Documentation/ABI/testing/sysfs-hypervisor-pmu. Rename
> this file to Documentation/ABI/testing/sysfs-hypervisor and add
> descriptions of the other nodes.
>
> Signed-off-by: Juergen Gross <jgross@suse.com>
> ---
>  Documentation/ABI/testing/sysfs-hypervisor     | 131 +++++++++++++++++++++++++
>  Documentation/ABI/testing/sysfs-hypervisor-pmu |  23 -----
>  MAINTAINERS                                    |   1 +
>  3 files changed, 132 insertions(+), 23 deletions(-)
>  create mode 100644 Documentation/ABI/testing/sysfs-hypervisor
>  delete mode 100644 Documentation/ABI/testing/sysfs-hypervisor-pmu
>
> diff --git a/Documentation/ABI/testing/sysfs-hypervisor b/Documentation/ABI/testing/sysfs-hypervisor

I wonder whether at least some of the non-pmu entries should by now be
considered stable.

-boris
Jürgen Groß May 22, 2017, 2:20 p.m. UTC | #2 
On 22/05/17 15:30, Boris Ostrovsky wrote:
> On 05/22/2017 04:56 AM, Juergen Gross wrote:
>> Today only a few sysfs nodes under /sys/hypervisor/ are documented
>> for Xen in Documentation/ABI/testing/sysfs-hypervisor-pmu. Rename
>> this file to Documentation/ABI/testing/sysfs-hypervisor and add
>> descriptions of the other nodes.
>>
>> Signed-off-by: Juergen Gross <jgross@suse.com>
>> ---
>>  Documentation/ABI/testing/sysfs-hypervisor     | 131 +++++++++++++++++++++++++
>>  Documentation/ABI/testing/sysfs-hypervisor-pmu |  23 -----
>>  MAINTAINERS                                    |   1 +
>>  3 files changed, 132 insertions(+), 23 deletions(-)
>>  create mode 100644 Documentation/ABI/testing/sysfs-hypervisor
>>  delete mode 100644 Documentation/ABI/testing/sysfs-hypervisor-pmu
>>
>> diff --git a/Documentation/ABI/testing/sysfs-hypervisor b/Documentation/ABI/testing/sysfs-hypervisor
> 
> I wonder whether at least some of the non-pmu entries should by now be
> considered stable.

Hmm, do you think the pmu entries are not?

I could:

a) move sysfs-hypervisor as posted here to stable
b) leave the pmu entries in testing and just add another doc for
   the non-pmu entries in stable
c) do some split of the non-pmu entries (which to put where?)
d) or let it all in testing

Next question then: where to put the new guest_type of patch 2?


Juergen
Boris Ostrovsky May 22, 2017, 2:47 p.m. UTC | #3 
On 05/22/2017 10:20 AM, Juergen Gross wrote:
> On 22/05/17 15:30, Boris Ostrovsky wrote:
>> On 05/22/2017 04:56 AM, Juergen Gross wrote:
>>> Today only a few sysfs nodes under /sys/hypervisor/ are documented
>>> for Xen in Documentation/ABI/testing/sysfs-hypervisor-pmu. Rename
>>> this file to Documentation/ABI/testing/sysfs-hypervisor and add
>>> descriptions of the other nodes.
>>>
>>> Signed-off-by: Juergen Gross <jgross@suse.com>
>>> ---
>>>  Documentation/ABI/testing/sysfs-hypervisor     | 131 +++++++++++++++++++++++++
>>>  Documentation/ABI/testing/sysfs-hypervisor-pmu |  23 -----
>>>  MAINTAINERS                                    |   1 +
>>>  3 files changed, 132 insertions(+), 23 deletions(-)
>>>  create mode 100644 Documentation/ABI/testing/sysfs-hypervisor
>>>  delete mode 100644 Documentation/ABI/testing/sysfs-hypervisor-pmu
>>>
>>> diff --git a/Documentation/ABI/testing/sysfs-hypervisor b/Documentation/ABI/testing/sysfs-hypervisor
>> I wonder whether at least some of the non-pmu entries should by now be
>> considered stable.
> Hmm, do you think the pmu entries are not?

Given XSA-163 I don't think we can declare PMU stable.

>
> I could:
>
> a) move sysfs-hypervisor as posted here to stable
> b) leave the pmu entries in testing and just add another doc for
>    the non-pmu entries in stable
> c) do some split of the non-pmu entries (which to put where?)
> d) or let it all in testing

I'd say (b).

>
> Next question then: where to put the new guest_type of patch 2?

Since this is just being added testing/sysfs-hypervisor seems to be the
proper place. Especially with documentation suggesting that 2-year
back-compatibility is needed for an interface to be declared stable.

-boris
diff mbox

Patch

diff --git a/Documentation/ABI/testing/sysfs-hypervisor b/Documentation/ABI/testing/sysfs-hypervisor
new file mode 100644
index 000000000000..443196f0aa1c
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-hypervisor
@@ -0,0 +1,131 @@ 
+What:		/sys/hypervisor/compilation/compile_date
+Date:		March 2009
+KernelVersion:	2.6.30
+Contact:	xen-devel@lists.xenproject.org
+Description:
+		Contains the build time stamp of the Xen hypervisor
+
+What:		/sys/hypervisor/compilation/compiled_by
+Date:		March 2009
+KernelVersion:	2.6.30
+Contact:	xen-devel@lists.xenproject.org
+Description:
+		Contains information who built the Xen hypervisor
+
+What:		/sys/hypervisor/compilation/compiler
+Date:		March 2009
+KernelVersion:	2.6.30
+Contact:	xen-devel@lists.xenproject.org
+Description:
+		Compiler which was used to build the Xen hypervisor
+
+What:		/sys/hypervisor/pmu/pmu_mode
+Date:		August 2015
+KernelVersion:	4.3
+Contact:	Boris Ostrovsky <boris.ostrovsky@oracle.com>
+Description:
+		Describes mode that Xen's performance-monitoring unit (PMU)
+		uses. Accepted values are
+			"off"  -- PMU is disabled
+			"self" -- The guest can profile itself
+			"hv"   -- The guest can profile itself and, if it is
+				  privileged (e.g. dom0), the hypervisor
+			"all" --  The guest can profile itself, the hypervisor
+				  and all other guests. Only available to
+				  privileged guests.
+
+What:           /sys/hypervisor/pmu/pmu_features
+Date:           August 2015
+KernelVersion:  4.3
+Contact:        Boris Ostrovsky <boris.ostrovsky@oracle.com>
+Description:
+		Describes Xen PMU features (as an integer). A set bit indicates
+		that the corresponding feature is enabled. See
+		include/xen/interface/xenpmu.h for available features
+
+What:		/sys/hypervisor/properties/capabilities
+Date:		March 2009
+KernelVersion:	2.6.30
+Contact:	xen-devel@lists.xenproject.org
+Description:
+		Space separated list of supported guest system types. Each type
+		is in the format: <class>-<major>.<minor>-<arch>
+		With:
+			<class>: "xen" -- x86: paravirtualized, arm: standard
+				 "hvm" -- x86 only: full virtualized
+			<major>: major guest interface version
+			<minor>: minor guest interface version
+			<arch>:  architecture, e.g.:
+				 "x86_32": 32 bit x86 guest without PAE
+				 "x86_32p": 32 bit x86 guest with PAE
+				 "x86_64": 64 bit x86 guest
+				 "armv7l": 32 bit arm guest
+				 "aarch64": 64 bit arm guest
+
+What:		/sys/hypervisor/properties/changeset
+Date:		March 2009
+KernelVersion:	2.6.30
+Contact:	xen-devel@lists.xenproject.org
+Description:
+		Changeset of the hypervisor (git commit)
+
+What:		/sys/hypervisor/properties/features
+Date:		March 2009
+KernelVersion:	2.6.30
+Contact:	xen-devel@lists.xenproject.org
+Description:
+		Features the Xen hypervisor supports for the guest as defined
+		in include/xen/interface/features.h printed as a hex value.
+
+What:		/sys/hypervisor/properties/pagesize
+Date:		March 2009
+KernelVersion:	2.6.30
+Contact:	xen-devel@lists.xenproject.org
+Description:
+		Default page size of the hypervisor printed as a hex value.
+
+What:		/sys/hypervisor/properties/virtual_start
+Date:		March 2009
+KernelVersion:	2.6.30
+Contact:	xen-devel@lists.xenproject.org
+Description:
+		Virtual address of the hypervisor as a hex value.
+
+What:		/sys/hypervisor/type
+Date:		March 2009
+KernelVersion:	2.6.30
+Contact:	xen-devel@lists.xenproject.org
+Description:
+		Type of hypervisor:
+		"xen": Xen hypervisor
+
+What:		/sys/hypervisor/uuid
+Date:		March 2009
+KernelVersion:	2.6.30
+Contact:	xen-devel@lists.xenproject.org
+Description:
+		UUID of the guest as known to the Xen hypervisor.
+
+What:		/sys/hypervisor/version/extra
+Date:		March 2009
+KernelVersion:	2.6.30
+Contact:	xen-devel@lists.xenproject.org
+Description:
+		The Xen version is in the format <major>.<minor><extra>
+		This is the <extra> part of it.
+
+What:		/sys/hypervisor/version/major
+Date:		March 2009
+KernelVersion:	2.6.30
+Contact:	xen-devel@lists.xenproject.org
+Description:
+		The Xen version is in the format <major>.<minor><extra>
+		This is the <major> part of it.
+
+What:		/sys/hypervisor/version/minor
+Date:		March 2009
+KernelVersion:	2.6.30
+Contact:	xen-devel@lists.xenproject.org
+Description:
+		The Xen version is in the format <major>.<minor><extra>
+		This is the <minor> part of it.
diff --git a/Documentation/ABI/testing/sysfs-hypervisor-pmu b/Documentation/ABI/testing/sysfs-hypervisor-pmu
deleted file mode 100644
index 224faa105e18..000000000000
--- a/Documentation/ABI/testing/sysfs-hypervisor-pmu
+++ /dev/null
@@ -1,23 +0,0 @@ 
-What:		/sys/hypervisor/pmu/pmu_mode
-Date:		August 2015
-KernelVersion:	4.3
-Contact:	Boris Ostrovsky <boris.ostrovsky@oracle.com>
-Description:
-		Describes mode that Xen's performance-monitoring unit (PMU)
-		uses. Accepted values are
-			"off"  -- PMU is disabled
-			"self" -- The guest can profile itself
-			"hv"   -- The guest can profile itself and, if it is
-				  privileged (e.g. dom0), the hypervisor
-			"all" --  The guest can profile itself, the hypervisor
-				  and all other guests. Only available to
-				  privileged guests.
-
-What:           /sys/hypervisor/pmu/pmu_features
-Date:           August 2015
-KernelVersion:  4.3
-Contact:        Boris Ostrovsky <boris.ostrovsky@oracle.com>
-Description:
-		Describes Xen PMU features (as an integer). A set bit indicates
-		that the corresponding feature is enabled. See
-		include/xen/interface/xenpmu.h for available features
diff --git a/MAINTAINERS b/MAINTAINERS
index 503bcf4e3e8f..a5d2af148798 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -13976,6 +13976,7 @@  F:	drivers/xen/
 F:	arch/x86/include/asm/xen/
 F:	include/xen/
 F:	include/uapi/xen/
+F:	Documentation/ABI/testing/sysfs-hypervisor
 
 XEN HYPERVISOR ARM
 M:	Stefano Stabellini <sstabellini@kernel.org>