[PATCH 0/7] Documentation: document /sys/devices/system/cpu/

[PATCH 0/7] Documentation: document /sys/devices/system/cpu/

[Alex Chiang]

Hi Greg, Randy,

Not sure who actually maintains Documentation/ABI/; if it's not either of
y'all then please point me at the correct maintainer.

Anyhow, I was proposing some patches to enhance the NUMA sysfs interface:

	http://thread.gmane.org/gmane.linux.kernel.mm/40084/

I documented my changes, but David Rientjes suggested that I take this
as an opportunity to do a more thorough job, so here is an attempt at
doing so by documenting at least the files that I saw on my system. Maybe
there are more that I didn't configure in, but I think this series covers
a good amount.

One thing David suggested was following the sysfs hierarchy a bit more
strictly wrt to the file name in Documentation/ABI. I renamed one existing
file, and then stuck all the new stuff into the result.

I made the decision to keep the granularity at the top level sysfs
CPU interface rather than break out each subdirectory into a separate
file. If that's not ok or preferred, let me know and I can split it out
(but I hope to avoid having to do that).

I split out each group of files into a separate patch, with my best
guess at interested parties cc'ed. That way, they can each bike-shed
me individually. ;)

Thanks,
/ac

---

Alex Chiang (7):
      Documentation: ABI: rename sysfs-devices-cache_disable properly
      Documentation: ABI: document /sys/devices/system/cpu/
      Documentation: ABI: /sys/devices/system/cpu/ topology files
      Documentation: ABI: /sys/devices/system/cpu/cpu#/ topology files
      Documentation: ABI: /sys/devices/system/cpu/sched_[mc|smt]_power_savings
      Documentation: ABI: /sys/devices/system/cpu/cpuidle/
      Documentation: ABI: /sys/devices/system/cpu/cpu#/cpufreq/


 .../ABI/testing/sysfs-devices-cache_disable        |   18 --
 Documentation/ABI/testing/sysfs-devices-system-cpu |  159 ++++++++++++++++++++
 Documentation/cputopology.txt                      |   47 ++++--
 3 files changed, 189 insertions(+), 35 deletions(-)
 delete mode 100644 Documentation/ABI/testing/sysfs-devices-cache_disable
 create mode 100644 Documentation/ABI/testing/sysfs-devices-system-cpu

[PATCH 1/7] Documentation: ABI: rename sysfs-devices-cache_disable properly

[Alex Chiang]

Rename sysfs-devices-cache_disable to sysfs-devices-system-cpu, in
order to keep a stricter correlation between a sysfs directory and
its documentation.

Reported-by: David Rientjes <rientjes@google.com>
Signed-off-by: Alex Chiang <achiang@hp.com>
---

 .../ABI/testing/sysfs-devices-cache_disable        |   18 ------------------
 Documentation/ABI/testing/sysfs-devices-system-cpu |   18 ++++++++++++++++++
 2 files changed, 18 insertions(+), 18 deletions(-)
 delete mode 100644 Documentation/ABI/testing/sysfs-devices-cache_disable
 create mode 100644 Documentation/ABI/testing/sysfs-devices-system-cpu

diff --git a/Documentation/ABI/testing/sysfs-devices-cache_disable b/Documentation/ABI/testing/sysfs-devices-cache_disable
deleted file mode 100644
index 175bb4f..0000000
--- a/Documentation/ABI/testing/sysfs-devices-cache_disable
+++ /dev/null
@@ -1,18 +0,0 @@
-What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
-Date:      August 2008
-KernelVersion:	2.6.27
-Contact:	mark.langsdorf@amd.com
-Description:	These files exist in every cpu's cache index directories.
-		There are currently 2 cache_disable_# files in each
-		directory.  Reading from these files on a supported
-		processor will return that cache disable index value
-		for that processor and node.  Writing to one of these
-		files will cause the specificed cache index to be disabled.
-
-		Currently, only AMD Family 10h Processors support cache index
-		disable, and only for their L3 caches.  See the BIOS and
-		Kernel Developer's Guide at
-		http://www.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/31116-Public-GH-BKDG_3.20_2-4-09.pdf
-		for formatting information and other details on the
-		cache index disable.
-Users:    joachim.deguara@amd.com
diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
new file mode 100644
index 0000000..175bb4f
--- /dev/null
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -0,0 +1,18 @@
+What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
+Date:      August 2008
+KernelVersion:	2.6.27
+Contact:	mark.langsdorf@amd.com
+Description:	These files exist in every cpu's cache index directories.
+		There are currently 2 cache_disable_# files in each
+		directory.  Reading from these files on a supported
+		processor will return that cache disable index value
+		for that processor and node.  Writing to one of these
+		files will cause the specificed cache index to be disabled.
+
+		Currently, only AMD Family 10h Processors support cache index
+		disable, and only for their L3 caches.  See the BIOS and
+		Kernel Developer's Guide at
+		http://www.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/31116-Public-GH-BKDG_3.20_2-4-09.pdf
+		for formatting information and other details on the
+		cache index disable.
+Users:    joachim.deguara@amd.com

[PATCH 2/7] Documentation: ABI: document /sys/devices/system/cpu/

[Alex Chiang]

This interface has been around for a long time, but hasn't been
officially documented.

Document the top level sysfs directory for CPU attributes.

Signed-off-by: Alex Chiang <achiang@hp.com>
---

 Documentation/ABI/testing/sysfs-devices-system-cpu |   12 ++++++++++++
 1 files changed, 12 insertions(+), 0 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 175bb4f..86126b1 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -1,3 +1,15 @@
+What:		/sys/devices/system/cpu/
+Date:		pre-git history
+Contact:	Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:
+		A collection of both global and individual CPU attributes
+
+		Individual CPU attributes are contained in subdirectories
+		named by the kernel's logical CPU number, e.g.:
+
+		/sys/devices/system/cpu/cpu#/
+
+
 What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
 Date:      August 2008
 KernelVersion:	2.6.27

[PATCH 3/7] Documentation: ABI: /sys/devices/system/cpu/ topology files

[Alex Chiang]

Add brief descriptions for the following sysfs files:

	/sys/devices/system/cpu/kernel_max
	/sys/devices/system/cpu/offline
	/sys/devices/system/cpu/online
	/sys/devices/system/cpu/possible
	/sys/devices/system/cpu/present

Excerpted the relevant information from Documentation/cputopology.txt
and pointed back to cputopology.txt as the authoritative source of
information.

Cc: Mike Travis <travis@sgi.com>
Cc: Rusty Russell <rusty@rustcorp.com.au>
Signed-off-by: Alex Chiang <achiang@hp.com>
---

 Documentation/ABI/testing/sysfs-devices-system-cpu |   28 ++++++++++++++++++++
 1 files changed, 28 insertions(+), 0 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 86126b1..871acdb 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -10,6 +10,34 @@ Description:
 		/sys/devices/system/cpu/cpu#/
 
 
+What:		/sys/devices/system/cpu/kernel_max
+		/sys/devices/system/cpu/offline
+		/sys/devices/system/cpu/online
+		/sys/devices/system/cpu/possible
+		/sys/devices/system/cpu/present
+Date:		December 2008
+Contact:	Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:	CPU topology files that describe kernel limits related to
+		hotplug. Briefly:
+
+		kernel_max: the maximum cpu index allowed by the kernel
+		configuration.
+
+		offline: cpus that are not online because they have been
+		HOTPLUGGED off or exceed the limit of cpus allowed by the
+		kernel configuration (kernel_max above).
+
+		online: cpus that are online and being scheduled.
+
+		possible: cpus that have been allocated resources and can be
+		brought online if they are present.
+
+		present: cpus that have been identified as being present in
+		the system.
+
+		See Documentation/cputopology.txt for more information.
+
+
 What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
 Date:      August 2008
 KernelVersion:	2.6.27

[PATCH 4/7] Documentation: ABI: /sys/devices/system/cpu/cpu#/ topology files

[Alex Chiang]

Add brief descriptions for the following sysfs files:

	/sys/devices/system/cpu/cpu#/topology/core_id
	/sys/devices/system/cpu/cpu#/topology/core_siblings
	/sys/devices/system/cpu/cpu#/topology/core_siblings_list
	/sys/devices/system/cpu/cpu#/topology/physical_package_id
	/sys/devices/system/cpu/cpu#/topology/thread_siblings
	/sys/devices/system/cpu/cpu#/topology/thread_siblings_list

The descriptions in Documentation/cputopology.txt weren't very
informative, so I attempted a better description based on code
reading and hopeful guessing.

Updated Documentation/cputopology.txt with the better descriptions and
fixed some style issues.

Cc: Mike Travis <travis@sgi.com>
Cc: Rusty Russell <rusty@rustcorp.com.au>
Signed-off-by: Alex Chiang <achiang@hp.com>
---

 Documentation/ABI/testing/sysfs-devices-system-cpu |   39 +++++++++++++++++
 Documentation/cputopology.txt                      |   47 +++++++++++++-------
 2 files changed, 69 insertions(+), 17 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 871acdb..2ade5c0 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -38,6 +38,45 @@ Description:	CPU topology files that describe kernel limits related to
 		See Documentation/cputopology.txt for more information.
 
 
+What:		/sys/devices/system/cpu/cpu#/topology/core_id
+		/sys/devices/system/cpu/cpu#/topology/core_siblings
+		/sys/devices/system/cpu/cpu#/topology/core_siblings_list
+		/sys/devices/system/cpu/cpu#/topology/physical_package_id
+		/sys/devices/system/cpu/cpu#/topology/thread_siblings
+		/sys/devices/system/cpu/cpu#/topology/thread_siblings_list
+Date:		December 2008
+Contact:	Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:	CPU topology files that describe a logical CPU's relationship
+		to other cores and threads in the same physical package.
+
+		One cpu# directory is created per logical CPU in the system,
+		e.g. /sys/devices/system/cpu/cpu42/.
+
+		Briefly, the files above are:
+
+		core_id: the CPU core ID of cpu#. Typically it is the
+		hardware platform's identifier (rather than the kernel's).
+		The actual value is architecture and platform dependent.
+
+		core_siblings: internal kernel map of cpu#'s hardware threads
+		within the same physical_package_id.
+
+		core_siblings_list: human-readable list of the logical CPU
+		numbers within the same physical_package_id as cpu#.
+
+		physical_package_id: physical package id of cpu#. Typically
+		corresponds to a physical socket number, but the actual value
+		is architecture and platform dependent.
+
+		thread_siblings: internel kernel map of cpu#'s hardware
+		threads within the same core as cpu#
+
+		thread_siblings_list: human-readable list of cpu#'s hardware
+		threads within the same core as cpu#
+
+		See Documentation/cputopology.txt for more information.
+
+
 What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
 Date:      August 2008
 KernelVersion:	2.6.27
diff --git a/Documentation/cputopology.txt b/Documentation/cputopology.txt
index b41f3e5..f1c5c4b 100644
--- a/Documentation/cputopology.txt
+++ b/Documentation/cputopology.txt
@@ -1,15 +1,28 @@
 
-Export cpu topology info via sysfs. Items (attributes) are similar
+Export CPU topology info via sysfs. Items (attributes) are similar
 to /proc/cpuinfo.
 
 1) /sys/devices/system/cpu/cpuX/topology/physical_package_id:
-represent the physical package id of  cpu X;
+
+	physical package id of cpuX. Typically corresponds to a physical
+	socket number, but the actual value is architecture and platform
+	dependent.
+
 2) /sys/devices/system/cpu/cpuX/topology/core_id:
-represent the cpu core id to cpu X;
+
+	the CPU core ID of cpuX. Typically it is the hardware platform's
+	identifier (rather than the kernel's).  The actual value is
+	architecture and platform dependent.
+
 3) /sys/devices/system/cpu/cpuX/topology/thread_siblings:
-represent the thread siblings to cpu X in the same core;
+
+	internel kernel map of cpuX's hardware threads within the same
+	core as cpuX
+
 4) /sys/devices/system/cpu/cpuX/topology/core_siblings:
-represent the thread siblings to cpu X in the same physical package;
+
+	internal kernel map of cpuX's hardware threads within the same
+	physical_package_id.
 
 To implement it in an architecture-neutral way, a new source file,
 drivers/base/topology.c, is to export the 4 attributes.
@@ -32,32 +45,32 @@ not defined by include/asm-XXX/topology.h:
 3) thread_siblings: just the given CPU
 4) core_siblings: just the given CPU
 
-Additionally, cpu topology information is provided under
+Additionally, CPU topology information is provided under
 /sys/devices/system/cpu and includes these files.  The internal
 source for the output is in brackets ("[]").
 
-    kernel_max: the maximum cpu index allowed by the kernel configuration.
+    kernel_max: the maximum CPU index allowed by the kernel configuration.
 		[NR_CPUS-1]
 
-    offline:	cpus that are not online because they have been
+    offline:	CPUs that are not online because they have been
 		HOTPLUGGED off (see cpu-hotplug.txt) or exceed the limit
-		of cpus allowed by the kernel configuration (kernel_max
+		of CPUs allowed by the kernel configuration (kernel_max
 		above). [~cpu_online_mask + cpus >= NR_CPUS]
 
-    online:	cpus that are online and being scheduled [cpu_online_mask]
+    online:	CPUs that are online and being scheduled [cpu_online_mask]
 
-    possible:	cpus that have been allocated resources and can be
+    possible:	CPUs that have been allocated resources and can be
 		brought online if they are present. [cpu_possible_mask]
 
-    present:	cpus that have been identified as being present in the
+    present:	CPUs that have been identified as being present in the
 		system. [cpu_present_mask]
 
 The format for the above output is compatible with cpulist_parse()
 [see <linux/cpumask.h>].  Some examples follow.
 
-In this example, there are 64 cpus in the system but cpus 32-63 exceed
+In this example, there are 64 CPUs in the system but cpus 32-63 exceed
 the kernel max which is limited to 0..31 by the NR_CPUS config option
-being 32.  Note also that cpus 2 and 4-31 are not online but could be
+being 32.  Note also that CPUs 2 and 4-31 are not online but could be
 brought online as they are both present and possible.
 
      kernel_max: 31
@@ -67,8 +80,8 @@ brought online as they are both present and possible.
         present: 0-31
 
 In this example, the NR_CPUS config option is 128, but the kernel was
-started with possible_cpus=144.  There are 4 cpus in the system and cpu2
-was manually taken offline (and is the only cpu that can be brought
+started with possible_cpus=144.  There are 4 CPUs in the system and cpu2
+was manually taken offline (and is the only CPU that can be brought
 online.)
 
      kernel_max: 127
@@ -78,4 +91,4 @@ online.)
         present: 0-3
 
 See cpu-hotplug.txt for the possible_cpus=NUM kernel start parameter
-as well as more information on the various cpumask's.
+as well as more information on the various cpumasks.

[PATCH 5/7] Documentation: ABI: /sys/devices/system/cpu/sched_[mc|smt]_power_savings

[Alex Chiang]

Document sched_[mc|smt]_power_savings by reading existing code and
git logs.

Cc: Suresh Siddha <suresh.b.siddha@intel.com>
Cc: Ingo Molnar <mingo@elte.hu>
Signed-off-by: Alex Chiang <achiang@hp.com>
---

 Documentation/ABI/testing/sysfs-devices-system-cpu |   24 ++++++++++++++++++++
 1 files changed, 24 insertions(+), 0 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 2ade5c0..8cdda1c 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -9,6 +9,30 @@ Description:
 
 		/sys/devices/system/cpu/cpu#/
 
+What:		/sys/devices/system/cpu/sched_mc_power_savings
+		/sys/devices/system/cpu/sched_smt_power_savings
+Date:		June 2006
+Contact:	Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:	Discover and adjust the kernel's multi-core scheduler support.
+
+		Possible values are:
+
+		0 - No power saving load balance (default value)
+		1 - Fill one thread/core/package first for long running threads
+		2 - Also bias task wakeups to semi-idle cpu package for power
+		    savings
+
+		sched_mc_power_savings is dependent upon SCHED_MC, which is
+		itself architecture dependent.
+
+		sched_smt_power_savings is dependent upon SCHED_SMT, which
+		is itself architecture dependent.
+
+		The two files are independent of each other. It is possible
+		that one file may be present without the other.
+
+		Introduced by git commit 5c45bf27.
+
 
 What:		/sys/devices/system/cpu/kernel_max
 		/sys/devices/system/cpu/offline

[PATCH 6/7] Documentation: ABI: /sys/devices/system/cpu/cpuidle/

[Alex Chiang]

Document cpuidle sysfs attributes by reading code, Documentation/cpuidle/,
and git logs.

Cc: Venki Pallipadi <venkatesh.pallipadi@intel.com>
Cc: Len Brown <lenb@kernel.org>
Signed-off-by: Alex Chiang <achiang@hp.com>
---

 Documentation/ABI/testing/sysfs-devices-system-cpu |   20 ++++++++++++++++++++
 1 files changed, 20 insertions(+), 0 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 8cdda1c..968d8ba 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -101,6 +101,26 @@ Description:	CPU topology files that describe a logical CPU's relationship
 		See Documentation/cputopology.txt for more information.
 
 
+What:		/sys/devices/system/cpu/cpuidle/current_driver
+		/sys/devices/system/cpu/cpuidle/current_governer_ro
+Date:		September 2007
+Contact:	Linux kernel mailing list <linux-kernel@vger.kernel.org>
+Description:	Discover cpuidle policy and mechanism
+
+		Various CPUs today support multiple idle levels that are
+		differentiated by varying exit latencies and power
+		consumption during idle.
+
+		Idle policy (governor) is differentiated from idle mechanism
+		(driver)
+
+		current_driver: displays current idle mechanism
+
+		current_governor_ro: displays current idle policy
+
+		See files in Documentation/cpuidle/ for more information.
+
+
 What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
 Date:      August 2008
 KernelVersion:	2.6.27

[PATCH 7/7] Documentation: ABI: /sys/devices/system/cpu/cpu#/cpufreq/

[Alex Chiang]

This is a complex interface and is already described in
Documentation/cpu-freq/, especially in the user-guide.txt file.

No need to copy/paste all that information. Let's just alert the reader
to the presence of the user-guide.

Cc: Dave Jones <davej@redhat.com>
Signed-off-by: Alex Chiang <achiang@hp.com>
---

 Documentation/ABI/testing/sysfs-devices-system-cpu |   18 ++++++++++++++++++
 1 files changed, 18 insertions(+), 0 deletions(-)

diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
index 968d8ba..81e61f5 100644
--- a/Documentation/ABI/testing/sysfs-devices-system-cpu
+++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
@@ -121,6 +121,24 @@ Description:	Discover cpuidle policy and mechanism
 		See files in Documentation/cpuidle/ for more information.
 
 
+What:		/sys/devices/system/cpu/cpu#/cpufreq/*
+Date:		pre-git history
+Contact:	cpufreq@vger.kernel.org
+Description:	Discover and change clock speed of CPUs
+
+		Clock scaling allows you to change the clock speed of the
+		CPUs on the fly. This is a nice method to save battery
+		power, because the lower the clock speed, the less power
+		the CPU consumes.
+
+		There are many knobs to tweak in this directory.
+
+		See files in Documentation/cpu-freq/ for more information.
+
+		In particular, read Documentation/cpu-freq/user-guide.txt
+		to learn how to control the knobs.
+
+
 What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
 Date:      August 2008
 KernelVersion:	2.6.27

Re: [PATCH 0/7] Documentation: document /sys/devices/system/cpu/

[David Rientjes]

On Wed, 21 Oct 2009, Alex Chiang wrote:

> Hi Greg, Randy,
> 
> Not sure who actually maintains Documentation/ABI/; if it's not either of
> y'all then please point me at the correct maintainer.
> 
> Anyhow, I was proposing some patches to enhance the NUMA sysfs interface:
> 
> 	http://thread.gmane.org/gmane.linux.kernel.mm/40084/
> 
> I documented my changes, but David Rientjes suggested that I take this
> as an opportunity to do a more thorough job, so here is an attempt at
> doing so by documenting at least the files that I saw on my system. Maybe
> there are more that I didn't configure in, but I think this series covers
> a good amount.
> 

Fantastic, thanks Alex!

One thing I noticed in patches 3-6 of this series is you've attached 
multiple files to a single "What:" line.  That hasn't been done before 
(ignore the style violations of sysfs-firmware-*) and I think it would be 
better to seperate each file out into its own section.

I know it's long, but I think some automated scripts are eventually going 
to use this documentation and it's best to follow the guidelines in 
Documentation/ABI/README.

Thanks again!

Re: [PATCH 1/7] Documentation: ABI: rename sysfs-devices-cache_disable properly

[David Rientjes]

On Wed, 21 Oct 2009, Alex Chiang wrote:

> Rename sysfs-devices-cache_disable to sysfs-devices-system-cpu, in
> order to keep a stricter correlation between a sysfs directory and
> its documentation.
> 
> Reported-by: David Rientjes <rientjes@google.com>
> Signed-off-by: Alex Chiang <achiang@hp.com>

Adding Mark Langsdorf <mark.langsdorf@amd.com> to the cc since this is his 
file and Ingo since he pushed it to Linus.

Acked-by: David Rientjes <rientjes@google.com>

> ---
> 
>  .../ABI/testing/sysfs-devices-cache_disable        |   18 ------------------
>  Documentation/ABI/testing/sysfs-devices-system-cpu |   18 ++++++++++++++++++
>  2 files changed, 18 insertions(+), 18 deletions(-)
>  delete mode 100644 Documentation/ABI/testing/sysfs-devices-cache_disable
>  create mode 100644 Documentation/ABI/testing/sysfs-devices-system-cpu
> 
> diff --git a/Documentation/ABI/testing/sysfs-devices-cache_disable b/Documentation/ABI/testing/sysfs-devices-cache_disable
> deleted file mode 100644
> index 175bb4f..0000000
> --- a/Documentation/ABI/testing/sysfs-devices-cache_disable
> +++ /dev/null
> @@ -1,18 +0,0 @@
> -What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
> -Date:      August 2008
> -KernelVersion:	2.6.27
> -Contact:	mark.langsdorf@amd.com
> -Description:	These files exist in every cpu's cache index directories.
> -		There are currently 2 cache_disable_# files in each
> -		directory.  Reading from these files on a supported
> -		processor will return that cache disable index value
> -		for that processor and node.  Writing to one of these
> -		files will cause the specificed cache index to be disabled.
> -
> -		Currently, only AMD Family 10h Processors support cache index
> -		disable, and only for their L3 caches.  See the BIOS and
> -		Kernel Developer's Guide at
> -		http://www.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/31116-Public-GH-BKDG_3.20_2-4-09.pdf
> -		for formatting information and other details on the
> -		cache index disable.
> -Users:    joachim.deguara@amd.com
> diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
> new file mode 100644
> index 0000000..175bb4f
> --- /dev/null
> +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
> @@ -0,0 +1,18 @@
> +What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
> +Date:      August 2008
> +KernelVersion:	2.6.27
> +Contact:	mark.langsdorf@amd.com
> +Description:	These files exist in every cpu's cache index directories.
> +		There are currently 2 cache_disable_# files in each
> +		directory.  Reading from these files on a supported
> +		processor will return that cache disable index value
> +		for that processor and node.  Writing to one of these
> +		files will cause the specificed cache index to be disabled.
> +
> +		Currently, only AMD Family 10h Processors support cache index
> +		disable, and only for their L3 caches.  See the BIOS and
> +		Kernel Developer's Guide at
> +		http://www.amd.com/us-en/assets/content_type/white_papers_and_tech_docs/31116-Public-GH-BKDG_3.20_2-4-09.pdf
> +		for formatting information and other details on the
> +		cache index disable.
> +Users:    joachim.deguara@amd.com
> 
> 

Re: [PATCH 0/7] Documentation: document /sys/devices/system/cpu/

[Alex Chiang]

* David Rientjes <rientjes@google.com>:
> On Wed, 21 Oct 2009, Alex Chiang wrote:
> 
> > Hi Greg, Randy,
> > 
> > Not sure who actually maintains Documentation/ABI/; if it's not either of
> > y'all then please point me at the correct maintainer.
> > 
> > Anyhow, I was proposing some patches to enhance the NUMA sysfs interface:
> > 
> > 	http://thread.gmane.org/gmane.linux.kernel.mm/40084/
> > 
> > I documented my changes, but David Rientjes suggested that I take this
> > as an opportunity to do a more thorough job, so here is an attempt at
> > doing so by documenting at least the files that I saw on my system. Maybe
> > there are more that I didn't configure in, but I think this series covers
> > a good amount.
> > 
> 
> Fantastic, thanks Alex!
> 
> One thing I noticed in patches 3-6 of this series is you've attached 
> multiple files to a single "What:" line.  That hasn't been done before 
> (ignore the style violations of sysfs-firmware-*) and I think it would be 
> better to seperate each file out into its own section.

Ok, I can do that.

I was originally going for compactness, but I understand the
point you make below.

> I know it's long, but I think some automated scripts are eventually going 
> to use this documentation and it's best to follow the guidelines in 
> Documentation/ABI/README.

What do you think about keeping all the descriptions in the same
file, sysfs-devices-system-cpu vs. splitting them out into
separate files, sysfs-devices-system-cpu-topology, e.g.?

Will your tools be able to handle that?

Thanks.
/ac

Re: [PATCH 0/7] Documentation: document /sys/devices/system/cpu/

[David Rientjes]

On Thu, 22 Oct 2009, Alex Chiang wrote:

> > I know it's long, but I think some automated scripts are eventually going 
> > to use this documentation and it's best to follow the guidelines in 
> > Documentation/ABI/README.
> 
> What do you think about keeping all the descriptions in the same
> file, sysfs-devices-system-cpu vs. splitting them out into
> separate files, sysfs-devices-system-cpu-topology, e.g.?
> 

That's fine since the directories don't contain an egregious amount of 
files that sysfs-devices-system-cpu becomes overly long.

I suggest spliting the individual files into their own sections within 
sysfs-devices-system-cpu, though, so they each have their own What, Date, 
KernelVersion, Contact, and Description fields.

Re: [PATCH 0/7] Documentation: document /sys/devices/system/cpu/

[Randy Dunlap]

On Wed, 21 Oct 2009 21:45:10 -0600 Alex Chiang wrote:

> Hi Greg, Randy,
> 
> Not sure who actually maintains Documentation/ABI/; if it's not either of
> y'all then please point me at the correct maintainer.
> 
> Anyhow, I was proposing some patches to enhance the NUMA sysfs interface:
> 
> 	http://thread.gmane.org/gmane.linux.kernel.mm/40084/

Greg does, but he's in Japan or traveling this week...


> I documented my changes, but David Rientjes suggested that I take this
> as an opportunity to do a more thorough job, so here is an attempt at
> doing so by documenting at least the files that I saw on my system. Maybe
> there are more that I didn't configure in, but I think this series covers
> a good amount.

Thanks for doing this.

> One thing David suggested was following the sysfs hierarchy a bit more
> strictly wrt to the file name in Documentation/ABI. I renamed one existing
> file, and then stuck all the new stuff into the result.
> 
> I made the decision to keep the granularity at the top level sysfs
> CPU interface rather than break out each subdirectory into a separate
> file. If that's not ok or preferred, let me know and I can split it out
> (but I hope to avoid having to do that).
> 
> I split out each group of files into a separate patch, with my best
> guess at interested parties cc'ed. That way, they can each bike-shed
> me individually. ;)
> 
> Thanks,
> /ac
> 
> ---
> 
> Alex Chiang (7):
>       Documentation: ABI: rename sysfs-devices-cache_disable properly
>       Documentation: ABI: document /sys/devices/system/cpu/
>       Documentation: ABI: /sys/devices/system/cpu/ topology files
>       Documentation: ABI: /sys/devices/system/cpu/cpu#/ topology files
>       Documentation: ABI: /sys/devices/system/cpu/sched_[mc|smt]_power_savings
>       Documentation: ABI: /sys/devices/system/cpu/cpuidle/
>       Documentation: ABI: /sys/devices/system/cpu/cpu#/cpufreq/
> 
> 
>  .../ABI/testing/sysfs-devices-cache_disable        |   18 --
>  Documentation/ABI/testing/sysfs-devices-system-cpu |  159 ++++++++++++++++++++
>  Documentation/cputopology.txt                      |   47 ++++--
>  3 files changed, 189 insertions(+), 35 deletions(-)
>  delete mode 100644 Documentation/ABI/testing/sysfs-devices-cache_disable
>  create mode 100644 Documentation/ABI/testing/sysfs-devices-system-cpu


---
~Randy

Re: [PATCH 0/7] Documentation: document /sys/devices/system/cpu/

[Greg KH]

On Thu, Oct 22, 2009 at 01:42:34AM -0700, David Rientjes wrote:
> On Wed, 21 Oct 2009, Alex Chiang wrote:
> 
> > Hi Greg, Randy,
> > 
> > Not sure who actually maintains Documentation/ABI/; if it's not either of
> > y'all then please point me at the correct maintainer.
> > 
> > Anyhow, I was proposing some patches to enhance the NUMA sysfs interface:
> > 
> > 	http://thread.gmane.org/gmane.linux.kernel.mm/40084/
> > 
> > I documented my changes, but David Rientjes suggested that I take this
> > as an opportunity to do a more thorough job, so here is an attempt at
> > doing so by documenting at least the files that I saw on my system. Maybe
> > there are more that I didn't configure in, but I think this series covers
> > a good amount.
> > 
> 
> Fantastic, thanks Alex!
> 
> One thing I noticed in patches 3-6 of this series is you've attached 
> multiple files to a single "What:" line.  That hasn't been done before 
> (ignore the style violations of sysfs-firmware-*) and I think it would be 
> better to seperate each file out into its own section.
> 
> I know it's long, but I think some automated scripts are eventually going 
> to use this documentation and it's best to follow the guidelines in 
> Documentation/ABI/README.

They are?  I don't know of any such scripts anywhere, do you?

thanks,

greg k-h

Re: [PATCH 0/7] Documentation: document /sys/devices/system/cpu/

[Greg KH]

On Thu, Oct 22, 2009 at 02:45:30PM -0700, Randy Dunlap wrote:
> On Wed, 21 Oct 2009 21:45:10 -0600 Alex Chiang wrote:
> 
> > Hi Greg, Randy,
> > 
> > Not sure who actually maintains Documentation/ABI/; if it's not either of
> > y'all then please point me at the correct maintainer.
> > 
> > Anyhow, I was proposing some patches to enhance the NUMA sysfs interface:
> > 
> > 	http://thread.gmane.org/gmane.linux.kernel.mm/40084/
> 
> Greg does, but he's in Japan or traveling this week...

Yeah, I'm still in Japan.  I'll get to reviewing them next week, sorry
for the delay.

thanks,

greg k-h

Re: [PATCH 0/7] Documentation: document /sys/devices/system/cpu/

[David Rientjes]

On Thu, 22 Oct 2009, Greg KH wrote:

> > I know it's long, but I think some automated scripts are eventually going 
> > to use this documentation and it's best to follow the guidelines in 
> > Documentation/ABI/README.
> 
> They are?  I don't know of any such scripts anywhere, do you?
> 

I had assumed that there were guidelines for composing the ABI documents 
so that files could eventually be matched automatically with the 
documentation to provide insight into what it does.  The only thing I 
personally use is "grep ^What:.*file Documentation/ABI/*" to find if a 
sysfs file is documented and that's because I'm not interested in all 
occurrences, just the specific documentation of that file.

Re: [PATCH 3/7] Documentation: ABI: /sys/devices/system/cpu/ topology files

[David Rientjes]

On Wed, 21 Oct 2009, Alex Chiang wrote:

> diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
> index 86126b1..871acdb 100644
> --- a/Documentation/ABI/testing/sysfs-devices-system-cpu
> +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
> @@ -10,6 +10,34 @@ Description:
>  		/sys/devices/system/cpu/cpu#/
>  
>  
> +What:		/sys/devices/system/cpu/kernel_max
> +		/sys/devices/system/cpu/offline
> +		/sys/devices/system/cpu/online
> +		/sys/devices/system/cpu/possible
> +		/sys/devices/system/cpu/present
> +Date:		December 2008
> +Contact:	Linux kernel mailing list <linux-kernel@vger.kernel.org>
> +Description:	CPU topology files that describe kernel limits related to
> +		hotplug. Briefly:
> +
> +		kernel_max: the maximum cpu index allowed by the kernel
> +		configuration.
> +
> +		offline: cpus that are not online because they have been
> +		HOTPLUGGED off or exceed the limit of cpus allowed by the
> +		kernel configuration (kernel_max above).
> +
> +		online: cpus that are online and being scheduled.
> +
> +		possible: cpus that have been allocated resources and can be
> +		brought online if they are present.
> +
> +		present: cpus that have been identified as being present in
> +		the system.
> +
> +		See Documentation/cputopology.txt for more information.
> +
> +
>  What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
>  Date:      August 2008
>  KernelVersion:	2.6.27

I noticed that this and patches 4-6 were added to gregkh-2.6.  Alex, did 
you want to seperate these large multi-file sections into individual file 
sections so that it is consistent with the remainder of Documentation/ABI?

Re: [PATCH 3/7] Documentation: ABI: /sys/devices/system/cpu/ topology files

[Alex Chiang]

* David Rientjes <rientjes@google.com>:
> On Wed, 21 Oct 2009, Alex Chiang wrote:
> 
> > diff --git a/Documentation/ABI/testing/sysfs-devices-system-cpu b/Documentation/ABI/testing/sysfs-devices-system-cpu
> > index 86126b1..871acdb 100644
> > --- a/Documentation/ABI/testing/sysfs-devices-system-cpu
> > +++ b/Documentation/ABI/testing/sysfs-devices-system-cpu
> > @@ -10,6 +10,34 @@ Description:
> >  		/sys/devices/system/cpu/cpu#/
> >  
> >  
> > +What:		/sys/devices/system/cpu/kernel_max
> > +		/sys/devices/system/cpu/offline
> > +		/sys/devices/system/cpu/online
> > +		/sys/devices/system/cpu/possible
> > +		/sys/devices/system/cpu/present
> > +Date:		December 2008
> > +Contact:	Linux kernel mailing list <linux-kernel@vger.kernel.org>
> > +Description:	CPU topology files that describe kernel limits related to
> > +		hotplug. Briefly:
> > +
> > +		kernel_max: the maximum cpu index allowed by the kernel
> > +		configuration.
> > +
> > +		offline: cpus that are not online because they have been
> > +		HOTPLUGGED off or exceed the limit of cpus allowed by the
> > +		kernel configuration (kernel_max above).
> > +
> > +		online: cpus that are online and being scheduled.
> > +
> > +		possible: cpus that have been allocated resources and can be
> > +		brought online if they are present.
> > +
> > +		present: cpus that have been identified as being present in
> > +		the system.
> > +
> > +		See Documentation/cputopology.txt for more information.
> > +
> > +
> >  What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
> >  Date:      August 2008
> >  KernelVersion:	2.6.27
> 
> I noticed that this and patches 4-6 were added to gregkh-2.6.  Alex, did 
> you want to seperate these large multi-file sections into individual file 
> sections so that it is consistent with the remainder of Documentation/ABI?

That's one option. Here's another:

> > +What:		/sys/devices/system/cpu/kernel_max
> > +What:		/sys/devices/system/cpu/offline
> > +What:		/sys/devices/system/cpu/online
> > +What:		/sys/devices/system/cpu/possible
> > +What:		/sys/devices/system/cpu/present

That way, your grep that you displayed in another mail still
works.

I understand the point about consistency, but... I kinda like the
condensed format better, since imho, it's easier to read.

Dunno, I don't have very strong feelings really... Greg already
took them, so David, if you do have a strong feeling, let me know
and I'll ask Greg to drop and I'll do one last respin.

Thanks,
/ac

Re: [PATCH 3/7] Documentation: ABI: /sys/devices/system/cpu/ topology files

[David Rientjes]

On Wed, 28 Oct 2009, Alex Chiang wrote:

> > I noticed that this and patches 4-6 were added to gregkh-2.6.  Alex, did 
> > you want to seperate these large multi-file sections into individual file 
> > sections so that it is consistent with the remainder of Documentation/ABI?
> 
> That's one option. Here's another:
> 
> > > +What:		/sys/devices/system/cpu/kernel_max
> > > +What:		/sys/devices/system/cpu/offline
> > > +What:		/sys/devices/system/cpu/online
> > > +What:		/sys/devices/system/cpu/possible
> > > +What:		/sys/devices/system/cpu/present
> 
> That way, your grep that you displayed in another mail still
> works.
> 
> I understand the point about consistency, but... I kinda like the
> condensed format better, since imho, it's easier to read.
> 
> Dunno, I don't have very strong feelings really... Greg already
> took them, so David, if you do have a strong feeling, let me know
> and I'll ask Greg to drop and I'll do one last respin.
> 

When I originally saw the format that the Documentation/ABI files were 
written in, I had this premonition that someone would eventually write a 
gui application that allowed users to tune their sysfs files and that it 
would inevitably include commentary on what the file represented by using 
the documentation.  It was easily parsable and had a strict file naming 
scheme that this was possible.  It seems we've departed from that at a 
relatively late stage in its maturity with no real benefit, but I'll defer 
to the maintainer's preference.

Regardless, thanks a lot for documenting these files and going the extra 
mile!  I'm sure it will come in very useful.