Skip to contentSkip to conversation

Documentation: document /sys/devices/system/cpu/

PATCH In review Alex Chiang 4 participants 19 messages Oct 22, 2009 – Oct 29, 2009 Documentation

lore
Share & tools
lore
#0 lore raw

cover Documentation: document /sys/devices/system/cpu/

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
#1 lore raw

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

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

---

 .../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
Documentation/ABI/testing/sysfs-devices-cache_disable deleted +0 -18
deleted file mode 100644
index 175bb4f..0000000
@@ -1,18 +0,0 @@
-What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
-Date:      August 2008
-KernelVersion:	2.6.27
-Contact:	[email protected]
-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:    [email protected]
Documentation/ABI/testing/sysfs-devices-system-cpu new file +18 -0
new file mode 100644
index 0000000..175bb4f
@@ -0,0 +1,18 @@
+What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
+Date:      August 2008
+KernelVersion:	2.6.27
+Contact:	[email protected]
+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:    [email protected]
Acked-by on v1 1/7
#2 lore raw

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

Quoted 6 lines · 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.

Adding Mark Langsdorf <[email protected]> to the cc since this is his file and Ingo since he pushed it to Linus.

Quoted 58 lines

---

 .../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
Documentation/ABI/testing/sysfs-devices-cache_disable deleted +0 -18
deleted file mode 100644
index 175bb4f..0000000
@@ -1,18 +0,0 @@
-What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
-Date:      August 2008
-KernelVersion:	2.6.27
-Contact:	[email protected]
-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:    [email protected]
Documentation/ABI/testing/sysfs-devices-system-cpu new file +18 -0
new file mode 100644
index 0000000..175bb4f
@@ -0,0 +1,18 @@
+What:      /sys/devices/system/cpu/cpu*/cache/index*/cache_disable_X
+Date:      August 2008
+KernelVersion:	2.6.27
+Contact:	[email protected]
+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:    [email protected]
#3 lore raw

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

In reply to 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.

---

 Documentation/ABI/testing/sysfs-devices-system-cpu |   12 ++++++++++++
 1 files changed, 12 insertions(+), 0 deletions(-)
Documentation/ABI/testing/sysfs-devices-system-cpu +12 -0
index 175bb4f..86126b1 100644
@@ -1,3 +1,15 @@
+What:		/sys/devices/system/cpu/
+Date:		pre-git history
+Contact:	Linux kernel mailing list <[email protected]>
+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
#4 lore raw

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

In reply to 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 <[email protected]>
Cc Rusty Russell <[email protected]>

---

 Documentation/ABI/testing/sysfs-devices-system-cpu |   28 ++++++++++++++++++++
 1 files changed, 28 insertions(+), 0 deletions(-)
Documentation/ABI/testing/sysfs-devices-system-cpu +28 -0
index 86126b1..871acdb 100644
@@ -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 <[email protected]>
+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
#5 lore raw

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

Quoted 29 lines · Alex Chiang
Documentation/ABI/testing/sysfs-devices-system-cpu +21 -0
index 86126b1..871acdb 100644
@@ -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 <[email protected]>
+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.

Documentation/ABI/testing/sysfs-devices-system-cpu Description: · line 43

Quoted 10 lines
Documentation/ABI/testing/sysfs-devices-system-cpu +7 -0
+
+		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?

#6 lore raw

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

* David Rientjes <[email protected]>:

Quoted 37 lines · Alex Chiang
Quoted 36 lines
Documentation/ABI/testing/sysfs-devices-system-cpu +27 -0
index 86126b1..871acdb 100644
@@ -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 <[email protected]>
+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.
+
Quoted 8 lines

Documentation/ABI/testing/sysfs-devices-system-cpu Description: · line 43

Quoted 4 lines
Documentation/ABI/testing/sysfs-devices-system-cpu +1 -0
+
 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:

Quoted 5 lines

Documentation/ABI/testing/sysfs-devices-system-cpu

Quoted 5 lines
Documentation/ABI/testing/sysfs-devices-system-cpu +5 -0
+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

#7 lore raw

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

Quoted 15 lines · Alex Chiang
Quoted 3 lines

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:

Quoted 5 lines

Review

Quoted 5 lines
(quoted diff) +5 -0
+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.

Quoted 7 lines

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.

#8 lore raw

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

In reply to 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 <[email protected]>
Cc Rusty Russell <[email protected]>

---

 Documentation/ABI/testing/sysfs-devices-system-cpu |   39 +++++++++++++++++
 Documentation/cputopology.txt                      |   47 +++++++++++++-------
 2 files changed, 69 insertions(+), 17 deletions(-)
Documentation/ABI/testing/sysfs-devices-system-cpu +39 -0
index 871acdb..2ade5c0 100644
@@ -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 <[email protected]>
+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
Documentation/cputopology.txt +30 -17

89 lines not on this page · raw message

#9 lore raw

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

In reply to Alex Chiang

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

Cc Suresh Siddha <[email protected]>
Cc Ingo Molnar <[email protected]>

---

 Documentation/ABI/testing/sysfs-devices-system-cpu |   24 ++++++++++++++++++++
 1 files changed, 24 insertions(+), 0 deletions(-)
Documentation/ABI/testing/sysfs-devices-system-cpu +24 -0
index 2ade5c0..8cdda1c 100644
@@ -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 <[email protected]>
+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
#10 lore raw

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

In reply to Alex Chiang

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

Cc Venki Pallipadi <[email protected]>
Cc Len Brown <[email protected]>

---

 Documentation/ABI/testing/sysfs-devices-system-cpu |   20 ++++++++++++++++++++
 1 files changed, 20 insertions(+), 0 deletions(-)
Documentation/ABI/testing/sysfs-devices-system-cpu +20 -0
index 8cdda1c..968d8ba 100644
@@ -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 <[email protected]>
+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
#11 lore raw

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

In reply to 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.

---

 Documentation/ABI/testing/sysfs-devices-system-cpu |   18 ++++++++++++++++++
 1 files changed, 18 insertions(+), 0 deletions(-)
Documentation/ABI/testing/sysfs-devices-system-cpu +18 -0
index 968d8ba..81e61f5 100644
@@ -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:	[email protected]
+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
#12 lore raw
In reply to Alex Chiang
Quoted 7 lines · 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:

Quoted 8 lines
	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!

#13 lore raw

* David Rientjes <[email protected]>:

Quoted 18 lines · Alex Chiang
Quoted 8 lines

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:

Quoted 8 lines
	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.

Quoted 6 lines

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.

Quoted 3 lines

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

#14 lore raw
Quoted 8 lines · Alex Chiang
Quoted 3 lines

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.

#15 lore raw
In reply to David Rientjes
Quoted 20 lines · David Rientjes
Quoted 7 lines · 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:

Quoted 8 lines
	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!

Quoted 8 lines

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

#16 lore raw
Quoted 6 lines · Greg KH
Quoted 3 lines

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.

#17 lore raw
In reply to Alex Chiang
Quoted 8 lines · 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...

Quoted 5 lines

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.

Quoted 28 lines

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/

Quoted 6 lines
 .../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

#18 lore raw
Quoted 4 lines · Randy Dunlap
Quoted 2 lines · On Wed, 21 Oct 2009 21:45:10 -0600 Alex Chiang wrote:

Hi Greg, Randy,

Quoted 8 lines
Quoted 6 lines

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